diff --git a/docs/02-getting-started.md b/docs/02-getting-started.md index f11ff6b..a43a99b 100644 --- a/docs/02-getting-started.md +++ b/docs/02-getting-started.md @@ -1,132 +1,45 @@ -# Getting started +# Getting Started -Much like [Mermaid](https://mermaid.js.org/), the project uses a special scripting language. +Welcome to our Nassi–Shneiderman diagram builder – the easiest way to visualize your code! +If you're new to programming or just getting started with our tool, follow these simple steps to create your first diagram. -I designed the langauge to be permissive and mimicked its syntax after the [C programming language](). -I expect users who are experienced with coding should have no issue with the project. -As for users with less experience, I hope to provide a risk-free playground to experiment. +## Hello World -At the time of writing, the project supports [process blocks](#process-block), [testing loops](#testing-loop), [branching blocks](#branching-block), [functions](#function), and [comments](#comment). +Let's begin with the classic "Hello World" example. -There are multiple interactive examples on this section, but live preview is shown by default, so press "Show code" to hide the preview. +First, click on the "SHOW CODE" button to bring up the editor. +In the code editor, type "Hello World;" -## Process block + -From [Wikipedia](https://en.wikipedia.org/wiki/Nassi%E2%80%93Shneiderman_diagram#Diagrams): +If you click on the "HIDE CODE" button, you should see a diagram with "Hello World" message. -> "The process block represents the simplest of steps and requires no analysis. -> When a process block is encountered, the action inside the block is performed and we move onto the next block. " +Now, let's turn it into a something more useful. -Process blocks are flexible by design. -A piece of text is "essentially" copied from the code and pasted onto the diagram with no modification. +## Loops - +Loops allow a set of processes to be repeated. +Although our "Hello World" is a single statement, let's introduce a loop for practice: -I have included three ways to convey variable assignment. -The project does not enforce a particular style, but if you are an ELTE student, you might want to use the following: + - +## Branches -I have seen some Wikipedia articles, for example, an article on [Insertion sort](https://en.wikipedia.org/wiki/Insertion_sort#Algorithm), uses the "<-" operator. +Branches help in decision-making. +Consider this example: - + -Even better, you can describe what you want in the process. +Illustrate the decision-making process with a branch structure around the "Hello World" and "Greetings, Universe!" lines. - +## Functions -## Testing loop +Functions allow you to organize your code. +For instance: -From [Wikipedia](https://en.wikipedia.org/wiki/Nassi%E2%80%93Shneiderman_diagram#Diagrams): + -> "The testing loop allows the program to loop one or a set of processes until a particular condition is fulfilled. -> The process blocks covered by each loop are subset with a side-bar extending out from the condition." +## Export Your Diagram -There are two types of testing loops, test first and test last blocks. The difference is the order in which the steps involved are completed. - -In test-first loops, the condition is tested before the processes, while in test-last loops, the condition is tested after the processes. - -Both testing loops have two components. - -Elements enclosed by a pair of parentheses "(...)" belong to the "condition" component. -Such elements are copied from the code and pasted onto the diagram. - -Elements enclosed by a pair of curly braces "{...}" belong to the "body" component. - -### Test-first loop - - - -Nesting loops is possible, but you can only nest so deep before the diagram becomes unreadable. - - - -Alternatively, a test-first loop may be invoked with "while" keyword, instead of "for." -The project produces the same diagram and does not distinguish between "for" and "while" keyword. - - - -I have included a few ways to write a test-first loop. -If you are an ELTE student, you might want to use the following syntax. - - - -Some pseudocode uses "<-" to signifies each iteration. - - - -The property of the double dots can be confusing, so we can also write a description. - - - -### Test-last loops - - - -Here is an example with nested test-last loops. - - - -## Branching block - -From [Wikipedia](https://en.wikipedia.org/wiki/Nassi%E2%80%93Shneiderman_diagram#Diagrams): - -> "The simple True/False or Yes/No branching block which offers the program two paths to take depending on whether or not a condition has been fulfilled." - -Branching blocks have two components. -Elements enclosed by a pair of parentheses "(...)" belong to the "condition" component. -Elements enclosed by a pair of curly braces "{...}" belong to the "body" component. - - - -To access the other path, use "else" keyword. - - - -## Function - -Functions and procedures have four components. - -The first element represents the [return type](https://en.wikipedia.org/wiki/Return_type). -It is required, even for procedures. - -The second element represents the name of the function or procedure. - -Elements enclosed by a pair of parentheses "(...)" belong to the "Parameter" component. -They are copied from the code and pasted on the diagram. - -Elements enclosed by a pair of curly braces "{...}" belong to the "body" component. - - - -A procedure is conveyed with a few methods, but I found "void" to be the most elegant. - - - -## Comment - -Comments are invoked with two forward slashes "//", similar to the C-programming language, the entire line is excluded from the diagram. - -When sharing diagram through links, comments are preserved. - - +Once you've created your "Hello World" diagram, you can export it as an image or share it as a link. +Explore the options in the toolbar to save and share your work. diff --git a/docs/03-syntax.md b/docs/03-syntax.md new file mode 100644 index 0000000..30df662 --- /dev/null +++ b/docs/03-syntax.md @@ -0,0 +1,96 @@ +# Syntax + +The syntax draws inspiration from the [C progamming language]() with more flexibility to suit the dynamic nature of our project. + +The project delivers a comprehensive syntax for various programming constructs, including process blocks, for and while loops, do-while loops, if-else blocks, functions, and comments. + +It's worth noting that two structures from the [orignal diagram design](https://www.cs.umd.edu/hcil/members/bshneiderman/nsd/Yoder-Schrag-nassi_schart.pdf) are currently not supported: parallel blocks and switch blocks, the latter being if-else blocks with more than two branches. + +## Process block + +From [Wikipedia's article on Nassi–Shneiderman diagram](https://en.wikipedia.org/wiki/Nassi%E2%80%93Shneiderman_diagram): + +> "A process represents the simplest of steps and requires no analysis. +> When a process block is encountered, the action described is performed before moving onto the next." + +A process is a sequence of words and symbols separated by spaces and terminates by a semicolon. + + + +A process can contain any number of words and symbols, but it must contain at least one word or symbol. + + + +## Loop + +From Wikipedia's article on Nassi–Shneiderman diagram: + +> "The loop allows the program to loop one or a set of processes until a particular condition is fulfilled. + +The project supports two types of loops: test-first loops and test-last loops, each differing in the sequence of executed steps. + +- **Test-First Loops**: In these loops, the condition is assessed before the execution of processes, aligning with the behavior of for loops and while loops. +- **Test-Last Loops**: Conversely, test-last loops evaluate the condition after the processes have been executed, mirroring the behavior of do-while loops. + +Both types of loops consist of two components: + +- **Condition Component**: Enclosed within parentheses, this component comprises elements directly derived from the code, and pasted onto the diagram. +- **Body Component**: Enclosed within curly braces, this component defines the actions to be iteratively performed. + +### For loop + + + +Nested for loops: + + + +Additionally, it's worth noting that a test-first loop can be invoked with either "for" or "while." +The project generates the same diagram for both variations, making no distinction between the keywords. + + + +### Do-while loop + + + +Nested do-while loop: + + + +## If-else block + +From Wikipedia's article on Nassi–Shneiderman diagram: + +> "The simple True/False branching block offers the program two paths to take depending on whether or not a condition has been fulfilled." + +If-else blocks consist of two components: + +- **Condition Component**: Enclosed within parentheses, this component comprises elements directly derived from the code, and pasted onto the diagram. +- **Body Component**: Enclosed within curly braces, this component defines the actions to be performed when the condition is fulfilled. + + + +The "else" keyword is used to access the other branch. + + + +## Function + +Functions and procedures within the project are characterized by four essential components: + +- **Return Type Element**: The first element denotes the return type, a mandatory specification even for procedures. +- **Name Element**: The second element designates the name of the function or procedure. +- **Parameter Component**: Enclosed within parentheses, this component comprises elements directly derived from the code, faithfully pasted onto the diagram. +- **Body Component**: Enclosed within curly braces, this component encapsulates the procedural elements of the function or procedure, defining the actions to be executed. + + + +## Comment + +Comments within the project are invoked with two forward slashes (//). When a line is commented, the remainder of the line is excluded from the diagram. + +Importantly, comments are preserved when a diagram is shared through a link. +This ensures that the explanatory remarks remain intact, contributing to the collaborative and communicative nature of the shared diagrams. + + diff --git a/docs/03-examples.md b/docs/04-examples.md similarity index 100% rename from docs/03-examples.md rename to docs/04-examples.md