diff --git a/courses/Recipes/Metrics/MeasuringJava/MeasuringJava.md b/courses/Recipes/Metrics/MeasuringJava/MeasuringJava.md index 7d5bb6c2c..9504e4569 100644 --- a/courses/Recipes/Metrics/MeasuringJava/MeasuringJava.md +++ b/courses/Recipes/Metrics/MeasuringJava/MeasuringJava.md @@ -71,7 +71,7 @@ You can use this code to extract a classpath if the project is a Maven project: ```rascal-shell,continue import util::Reflective; -cp = getProjectPathConfig(|tmp:///snakes-and-ladders|).javaCompilerPath; +cp = getProjectPathConfig(|tmp:///snakes-and-ladders|).libs; ``` and then pass it into the M3 extractor (this project does not have dependencies) diff --git a/courses/Tutor/API/API.md b/courses/Tutor/API/API.md new file mode 100644 index 000000000..c3880749b --- /dev/null +++ b/courses/Tutor/API/API.md @@ -0,0 +1,49 @@ +--- +title: API documentation +--- + +#### Synopsis + +The Tutor compiler reads Rascal source files and produces ((Concept)) markdown files +for each Rascal module. + +#### Description + +The compiler generates for every `Module.rsc` a markdown file with the following structure: + +`````` +--- +title: +--- + +// for each declaration (function, data, syntax, alias, import, extend) +## {#fully-qualified-declaration-name} + +#### Synopsis + +... +#### Description +... + +// etc. +`````` + +So, for all standard ((Concept)) headers, like `Synopsis` and `Benefits` there is a place at every declaration. + +The content of the header paragraphs is either directly derived from source code (like function signature and data definitions), or it is taken from the following tag definitions on each declaration: +* `@doc` may contain literally the headers of a ((Concept)), like `#### Synopsis`. This notation is deprecated in favor of the tags below. +* `@synopsis` is a single line description of the definition. +* `@description` is a multi-line explanantion of the definition. +* `@benefits`, `@pitfalls`, `@examples`, `@types`, `@name` and `@function` each follow the intent of the standard ((Concept)) headers. + +The documentation written for features without an explicit synopsis is not rendered. In other words it is obligatory to use at least a `@synopsis` tag or start with a `#### Synopsis` header.. + +#### Benefits + +* A (small) part of documentation writing is automated. The information about the name of a function, data or annotation declaration, or its signature is always consistent. +* You can write examples of the usage of each definition using ((Listing)) markup that is run and checked at documentation compile-time. + +#### Pitfalls + +* This approach requires that functions with the same name are grouped together in the source file. +* You need to run the tutor compiler before errors in the documentation tags are detected. diff --git a/courses/Tutor/Architecture/Architecture.md b/courses/Tutor/Architecture/Architecture.md new file mode 100644 index 000000000..168aadae4 --- /dev/null +++ b/courses/Tutor/Architecture/Architecture.md @@ -0,0 +1,62 @@ +--- +title: Architecture +--- + +#### Synopsis + +The global architecture of the Rascal Tutor + +#### Description + +The Rascal Tutor is a Markdown and Rascal source file pre-processor. As input it takes [Docusaurus Markdown](https://docusaurus.io/docs/markdown-features/) files organized in hierarchical folders, and Rascal modules organized in hierarchical packages. One root folder is called a "course". As output the pre-processor produces per course +a folder hierarchy again, where each folder has its own `index.md` file (generated or written). After the tutor +compiler has generated such a consistent folder of interconnected markdown files, other downstream processors can turn them into (static) html websites, pdf files or otherwise. The standard way of processing is to use the [Docusaurus](https://docusaurus.io) static website generator. + +The important features of the pre-processor, "compiler", are: + +1. The compiler is configured via `util::Reflective::PathConfig`, where: + * each entry in the `srcs` list is a single _course_ + * each entry in the `libs` list, be it a jar file or not, is searched for an `index.value` file to augment the current index. +1. Concept hierarchy - each folder `/X` has its own index file, called either `X/X.md` or `X/index.md`. Nested folders equal nested concepts. +1. Indexing - to help in easy cross-linking between concepts: + * Each concept of course `A` stored in `X/Y/Z/Z.md` may be linked via `Z`, `Y-Z`, `X-Y-Z`, `A:Z`, `A:Y-Z`, `A:X-Y-Z` + * Each Rascal module of course `A` named `a::b::C` may be linked via `C`, `b-C`, `a::b::C`, `module:a::b::C`, `A:C`, `A:b-C`, `A:a::b::C`, `A:module:a::b::C` + * Each Rascal package of course `A` named `a::b` may be linked via `b`, `a::b`, `package:a::b`, `A:b`, `A:a::b`, `A:module:a::b` + * Each image `x.{png,svg,jpg,jpeg}` stored in `X/Y/Z` may be linked as though it were a concept file. + * The index is a `rel[str,str]` from the above described links to the `index.md` files in the generated hierarchy. + * The compiler reports missing links and ambiguous links as errors. + * A single `index.value` file is written in the output folder for future reference by depending projects. +1. Code execution ensures lively demonstrations which are checked for correctness. + * Code blocks marked `rascal-shell` are executed line-by-line on the REPL prompt. Each prompt starts with a fresh environment. All error and standard output is captured and printed back. The `Content` module that serves HTML or any other file is also inlined in the output Markdown file. + * Code blocks marked `rascal-shell,continue` are executed in the previously constructed environment (from top to bottom in the Markdown file) and behave the same otherwise. + * Code blocks marked `rascal-prepare` with or without `continue` behave the same as above, except that no output or input is printed back into the output file. +1. Links written between `((` and `))` are resolved using the previously described index. +1. Table of contents are generated for the word TOC between three `(((` brackets `)))`; the content of each concept is the concept nested under it in the hierarchy. +1. Each Rascal file is indexed to list the declarations it contains and information is extracted: + * data declarations with their `doc`, `synopsis`, `examples` etc. tags + * (overloaded) function declarations with their `doc`, `synopsis`, `examples` etc. tags + * alias declarations with their `doc`, `synopsis`, `examples` etc. tags +1. Screenshots of interactive ((Library:module:Content) visualizations can be made by configuring the compiler to use selenium and chrome. + +Features on the TODO list are: +1. Interactive Questions (have to be revived) + + +To implement these features the following components are relevant: +* `lang::rascal::tutor::Indexer` implements indexing and lookup +* `lang::rascal::tutor::Compiler` implements linking, code execution, toc, and the generation of index files. +* `lang::rascal::tutor::apidoc::ExtractInfo` parses Rascal code and generates an intermediate overview +* `lang::rascal::tutor::apidoc::GenerateMarkdown` generates a single Markdown file for each Rascal module, and also reuses `Compiler` to process embedded markdown with code examples, links, etc. +* `lang::rascal::tutor::repl::TutorCommandExecutor` encapsulates a Rascal REPL as a set of closures (`eval`, `reset`, and `prompt`) + * for efficiency's sake a single executor is shared among all Markdown and Rascal files that are compiled in a single run. Between every file the executor is reset for a new environment, but previously loaded modules remain in the heap available for reuse. + +#### Benefits + +* Index creation is modular: an index is created per course and these indices are combined at runtime. +* Code execution is reasonably time efficient, although it may require quite some memory because eventually an entire course will be loaded. + +#### Pitfalls + +* Courses are compiled on a per-course basis. Support for incremental courses compilation is not yet available. +* Badly balanced code block quotes are not detected by this pre-processor but will fail HTML compilation downstream. +* Manual links are not checked at compile-time by this pre-processor but fill fail HTML compilation downstream. diff --git a/courses/Tutor/Authoring/Authoring.md b/courses/Tutor/Authoring/Authoring.md new file mode 100644 index 000000000..839f78f54 --- /dev/null +++ b/courses/Tutor/Authoring/Authoring.md @@ -0,0 +1,48 @@ +--- +title: Authoring +--- + +#### Synopsis + +Creating and writing a course for the Rascal Tutor. + +#### Syntax + +#### Types + +#### Function + +#### Description + +The life cycle of a course consists of the following steps: + +* A new course, say `MyCourse`, is created. This is achieved by: + * Creating a subdirectory named `MyCourse` in the `courses` directory of the current Rascal project. + * Creating a file `MyCourse/MyCourse.md`. This is the root concept of the new course. +* The contents of the course are created by populating the course with subconcepts of the root concept. +* A subconcept, say `CoolIdea` is created by: + * Creating a subdirectory `CoolIdea` of its parent concept. + * Creating a file `CoolIdea/CoolIdea.md` that describes the concept. + * Alternatively, a file `CoolIdea/index.md` works too. + * Renaming/moving/deleting concepts is done at the directory/file level. + +Concepts are represented as directories for the following reasons: + +* To represent subconcepts as subdirectories. +* To contain all figures and other files that are included in the concept. In this way: + * A complete concept can be easily moved or renamed as a single unit. + * Name clashes between included files per concept are avoided. + +#### Examples + +#### Benefits + +* You can use your favourite Markdown editor and standard system commands to author a course. +* The output of the Tutor compiler is Markdown/HTML that you can process further with any tool you like +* Links to other concepts are all _relative_ to a root directory with all the courses. So `../../Course/A/index.md` would be a link generated from a link to `A` in `/Course/Z/index.md`. This makes it easy to include courses in a website at any subfolder. +* The index that is generated for every project with several courses can be reused by other projects to generate consistent cross-referencing. For example a project `flybytes` which depends on the `rascal` project which contains the `Library` course, could use `Library:IO` to refer to the documentation about the `IO` module in the standard library of Rascal. + +#### Pitfalls + +* Special features like code execution and cross-referencing concepts are not implemented by generic Markdown editors, so you have to wait and see what happens until you compile the course. +* All images are referenced from `/assets/` so images have to be installed there on any website you want to include the documentation in. \ No newline at end of file diff --git a/courses/Tutor/Compilation/Compilation.md b/courses/Tutor/Compilation/Compilation.md new file mode 100644 index 000000000..999edb82d --- /dev/null +++ b/courses/Tutor/Compilation/Compilation.md @@ -0,0 +1,122 @@ +--- +title: Tutor Compilation +keywords: + - compilation + - compiler + - configuration + - maven + - deployment + - incremental + - dependency + - dependencies +--- + +After ((Authoring)) tutor files, they have to compiled down to plain docusaurus. The compiler implements features such as linking, screenshots, and executing code fragments. +Most importantly, when there are linking errors (missing or ambiguous) or code execution errors, the compiler reports them such that they can be fixed before releasing the documentation. + +## Configuration + +The way to execute the rascal tutor compiler is via [rascal-maven-plugin](http://github.com/usethesource/rascal-maven-plugin). First it +has to be configured for your project. + +Do configure the tutor, add the plugin to the pom.xml like so: + +```xml + + + org.rascalmpl + rascal-maven-plugin + 0.16.0 + + + default-cli + compile + + tutor + + + false + false + true + ${project.build.outputDirectory} + + ${project.basedir}/doc/Course1 + ${project.basedir}/doc/Course2 + ${project.basedir}/src/main/rascal + + + ${project.basedir}/src/main/rascal/experimental + + + + + + +``` + +1. `enableStandardLibrary` defines which library the links to standard library documentation refer to. Either the version of rascal that the rascal-maven-plugin depends on (`true`), or the version of rascal that the current project depends on (`false`). Also this defines which version of the library the code examples are executed against. +2. `errorsAsWarnings` and `warningsAsError` define failure modes for the compiler. Maven will not fail if `errorsAsWarnings` is set to `true` even if there are errors. +3. `isPackageCourse`, when set to `true` will nest all target documentation in `docs/Packages/projectName`, and rename `src/main/rascal` or `src` to `API`. All links will also be re-routed to these locations. Otherwise, when set to `false` all documentation ends up in `docs/Course1` and `docs/Course2`, etc. +4. `bin` points to the place that defines the root of the resulting `jar` file. All generated files will endup in `bin/docs` and `bin/docs/assets`. This has to be the outputDirectory and if you forget to configure this, it will be set automatically anyway. The compiler also writes `bin/index.value` file after it is done, to store the entire linking index for future usage. This future use can be either the next run of the compiler, or a depending project downstream. +5. `srcs` define root courses, some of which will be pure Concept hierarchies, and others could be the _root_ of Rascal source folders. Note that this also defines the search path for modules during code execution of `rascal-shell` blocks. +6. `ignores` defines files or folders which are to be ignore. These could be folder names inside of Rascal source folders, or files of Rascal modules, or course concept folders, or course concept files. When a folder is ignored, this works transitively for the contents of that folder. + +## Dependencies + +If the current Maven project has dependencies then the `index.value` files in these jar files are located +and imported in the current link index of the project. This allows you to refer to concepts in one of the +projects you depend on, provided that project was also using the `rascal-maven-plugin` to run the tutor compiler. + +The dependency feature depends on the assumption that the `/docs` folders in the jar of the current project and the jars of the +project it depends on are extracted into the `docs` folder of a Docusaurus project later, and that everything +under `/docs/assets` in the same jars is copied to `static/assets`. The `rascal-website` project +achieves this using the `resources` plugin `copy` commands. If you are running your own docusaurus site, +then this should be re-implemented. + +## Execution + +Simply run the maven `compile` or `package` or `install` command to trigger the rascal tutor compiler: + +```bash +$ mvn install +``` + +However, to exclusively run the tutor you can try this: + +```bash +$ mvn rascal:tutor +``` + +If there are screenshots in the documentation, then selenium must be configured with the location of `chrome` and `chromedriver`: + +```bash +$ mvn rascal:tutor -Dwebdriver.chrome.driver=`which chromedriver` -Dwebdriver.chrome.browser=`which chrome` +``` + +Here we have used the bash feature to splice in the location of chromedrive and chrome using the `which` command. This requires both to +be found on the system `PATH`. If this is not the case, provide the absolute path to the binaries of these two programs. Both on Mac +and Windows the path to `Google Chrome`, for example, may contain many spaces and it is wise to wrap the path in double quotes. + +The tutor compiler is **incremental** in a certain way. Running the compile twice in a row, only the markdown files and Rascal modules that have been modified will be compiled again. The compiler +reuses the output of the previous run, including error messages. All error messages and warnings, including those of unmodified files are +always presented at the end. + +Simple run the tutor twice to recompile only what has changed: + +```bash +mvn rascal:tutor +mvn rascal:tutor +``` + +:::warning +When folders or files are renamed, the old output files remain in the `bin` folder as well as the old links to those in the link index file. +This can lead to: +* spurious link ambiguity; for example when `A/B.md` has moved to `C/B.md` both versions of `B` will be present in the link administration. +* unreported missing links; for example when `A/B.md` has moved to A/C.md`, `B` will still be linked even though it is not present anymore. + +It is therefore always prudent to `mvn clean` such that the output directory including the `index.value` has been removed, when files or folder change name or location. +::: + +## Deployment of documentation + +* When `mvn install` or `mvn package` is run with the correct configuration for the `bin` folder, then all markdown files and other assets (screenshots) end up in the `jar` file of the current project. diff --git a/courses/Tutor/Concept/Benefits/Benefits.md b/courses/Tutor/Concept/Benefits/Benefits.md new file mode 100644 index 000000000..b93e111a5 --- /dev/null +++ b/courses/Tutor/Concept/Benefits/Benefits.md @@ -0,0 +1,32 @@ +--- +title: Benefits +--- + +#### Synopsis + +Briefly lists known advantages of the concept. + +#### Syntax + +``` +#### Benefits + +_MarkedText_ +``` + +#### Types + +#### Function + +#### Description + +#### Examples + +#### Benefits + +* Benefits allow a description of the, subjectively, positive aspects of a concept which is clearly delineated. This allows other sections to remain more factual and neutral. +* Benefits alert newcomers to possibilities they would not have thought of otherwise. + +#### Pitfalls + +* Benefits sections may grow into bragging lists. \ No newline at end of file diff --git a/courses/Tutor/Concept/Concept.md b/courses/Tutor/Concept/Concept.md new file mode 100644 index 000000000..e0b6dd1da --- /dev/null +++ b/courses/Tutor/Concept/Concept.md @@ -0,0 +1,61 @@ +--- +title: Concept +details: + - Title + - Keywords + - Synopsis + - Syntax + - Types + - Function + - Details + - Description + - Examples + - Benefits + - Pitfalls +--- + +#### Synopsis + +A _concept_ is the basic building block of a course. + +#### Syntax + +* `module a/b/Concept` in `a/b/Concept.rsc` +* Or a file `a/b/Concept/Concept.md`, `a/b/Concept/index.md`: + `````` + --- + title: Concept Title + keywords: + - keyword1 + - keyword2 + --- + + #### Synopsis + + This is the synopsis. + + #### Description + + #### Types + + #### Function + + #### Examples + + #### Benefits + + #### Pitfalls + `````` + +All sections are optional, but not the title header. It is always recommended to have at least a Synopsis and some Examples. Empty sections are removed by the preprocessor. + +#### Description + +A concept describes a separate entity (idea, artefact, function, rule) that is relevant in the scope of the course in which it appears. +It consists of the named sections above that are described separately. +Each section starts with a keyword that should appear at the begin of a line. + +Here is a brief summary of the sections of a concept: +(((TOC))) + + diff --git a/courses/Tutor/Concept/Description/Description.md b/courses/Tutor/Concept/Description/Description.md new file mode 100644 index 000000000..caa2e3786 --- /dev/null +++ b/courses/Tutor/Concept/Description/Description.md @@ -0,0 +1,41 @@ +--- +title: Description +--- + +#### Synopsis + +Gives a clear and concise explanation of a concept. + +#### Syntax + +``` +#### Description + +_MarkedText_ +``` + +#### Types + +#### Function + +#### Description + +The `Description` section gives a concise explanation of a concept. + +#### Examples + +The `Description` section of the concept `Description` (= the previous section) reads as follows: + +``` +#### Description + +The `Description` section gives a concise explanation of a concept. +``` + +#### Benefits + +#### Pitfalls + +* Avoid giving examples in the `Description` section but reserve these for the `Examples` section. +* Do not give explicit lists of subconcepts (details) since they are already included automatically in the `Details` section in the generated page. + diff --git a/courses/Tutor/Concept/Details/Details.md b/courses/Tutor/Concept/Details/Details.md new file mode 100644 index 000000000..e854e21fa --- /dev/null +++ b/courses/Tutor/Concept/Details/Details.md @@ -0,0 +1,65 @@ +--- +title: Details +--- + +#### Synopsis + +Explicitly list and _order_ the subconcepts of the current concept. + +#### Syntax + +Details are provided in the YAML header of the markdown file. + +``` +--- +details: + - Detail~1~ + - Detail~2~ + - ... +--- +``` + +#### Description + +To fully describe a concept, subconcepts (or details) are needed. +When the `details` meta-data header is empty, subconcepts will be listed +alphabetically in the (derived) outline of the documentation. + +This alphabetical order can be influenced by explicitly stating concepts in the details meta-data header.. +The effect is that the concepts listed there will be shown first, followed by the unmentioned subconcepts +in alphabetical order. + +The details declaration also influences the order and contents of the ((TableOfContents)) markup. + +#### Examples + +In ((Concept)) we want to order the details in the order as they appear in the concept description. +Its `Details` meta-data is therefore: + +`````` +--- +title: Concept +details: + - Name + - Details + - Syntax + - Types + - Function + - Synopsis + - Description + - Examples + - Benefits + - Pitfalls + - Questions +--- +`````` + +#### Benefits + +* With details you can choose an order for the subconcepts +* The Tutor compiler will warn about missing or additional elements in the details list. + +#### Pitfalls + +* You can forget to add a new concept to the list, or remove an old one from it. + diff --git a/courses/Tutor/Concept/Examples/Examples.md b/courses/Tutor/Concept/Examples/Examples.md new file mode 100644 index 000000000..e5e0a171f --- /dev/null +++ b/courses/Tutor/Concept/Examples/Examples.md @@ -0,0 +1,54 @@ +--- +title: Examples +--- + +#### Synopsis + +Examples to illustrate the concept. + +#### Syntax + +``` +#### Examples + +_MarkedText_ +``` + +#### Types + +#### Function + +#### Description + +Gives a number of simple but complete examples to illustrate the concepts and its variations. +Running examples are preferred. + +#### Examples + +Typically, examples would included executed code: + +`````` +```rascal-shell +import IO; +println("Hello World!") +``` +`````` + +to show this: + +```rascal-shell +import IO; +println("Hello World!") +``` + + +#### Benefits + +* Examples make documentation concrete and to the point. +* Examples can be copied by users and adapted for further exploratory learning. +* Code examples are checked by the tutor compiler for correctness (no exceptions or errors) + +#### Pitfalls + +* Code examples have to be maintained + diff --git a/courses/Tutor/Concept/Function/Function.md b/courses/Tutor/Concept/Function/Function.md new file mode 100644 index 000000000..617eb619e --- /dev/null +++ b/courses/Tutor/Concept/Function/Function.md @@ -0,0 +1,42 @@ +--- +title: Function +--- + +#### Synopsis + +Part of the synopsis that describes function signatures introduced by this concept. + +#### Syntax + +``` +#### Function + +_MarkedText_ +``` + +#### Types + +#### Function + +#### Description + +#### Examples + +Here is an example for the `readFile` function: + + +#### Syntax + +``` +#### Function + +str readFile(loc file) throws UnsupportedScheme(loc file), PathNotFound(loc file), IOError(str msg) +``` + +#### Benefits + +* These sections are usually generated from Rascal source code + +#### Pitfalls + +* The function signatures are not linked yet. diff --git a/courses/Tutor/Concept/Keywords/Keywords.md b/courses/Tutor/Concept/Keywords/Keywords.md new file mode 100644 index 000000000..605da7578 --- /dev/null +++ b/courses/Tutor/Concept/Keywords/Keywords.md @@ -0,0 +1,23 @@ +--- +title: Keywords +--- + +#### Synopsis + +Keywords are header meta-data to help search engines + +#### Syntax + +`````` +--- +title: Examples +keywords: + - '&' + - word + - "===" +--- +`````` + +#### Description + +A list of keywords is optional, but useful, for each concept. The list translates eventually to HTML meta-data that search engines may pick up. Also IDE features may use this to implement effective help facilities. \ No newline at end of file diff --git a/courses/Tutor/Concept/Pitfalls/Pitfalls.md b/courses/Tutor/Concept/Pitfalls/Pitfalls.md new file mode 100644 index 000000000..105129583 --- /dev/null +++ b/courses/Tutor/Concept/Pitfalls/Pitfalls.md @@ -0,0 +1,32 @@ +--- +title: Pitfalls +--- + +#### Synopsis + +Comprehensive list of known shortcomings or usage problems of the concept. + +#### Syntax + +``` +#### Pitfalls + +_MarkedText_ +``` + +#### Types + +#### Function + +#### Description + +#### Examples + +#### Benefits + +* Pitfalls allow a description of the, subjectively, negative aspects of a concept which is clearly delineated. This allows other sections to remain more factual and neutral. +* Pitfalls when described clearly can help newcomers to avoid the damage of well-known mistakes. + +#### Pitfalls + +* Too many pitfalls can scare newcomers away. If this happens a re-design should be considered. diff --git a/courses/Tutor/Concept/Synopsis/Synopsis.md b/courses/Tutor/Concept/Synopsis/Synopsis.md new file mode 100644 index 000000000..c72f1e4e4 --- /dev/null +++ b/courses/Tutor/Concept/Synopsis/Synopsis.md @@ -0,0 +1,33 @@ +--- +title: Synopsis +--- + +#### Synopsis + +One-line summary of the concept that is usable as a tool tip or table of contents entry + +#### Syntax + +``` +#### Synopsis + +_MarkedText_ +``` + +#### Types + +#### Function + +#### Description + +The full summary of a concept consists of the Synopsis and the optional elements +((Syntax)), ((Types)) and ((Function)). + +Synopsis is *mandatory* (this is not yet enforced). + +#### Examples + +#### Benefits + +#### Pitfalls + diff --git a/courses/Tutor/Concept/Syntax/Syntax.md b/courses/Tutor/Concept/Syntax/Syntax.md new file mode 100644 index 000000000..dd06bbef1 --- /dev/null +++ b/courses/Tutor/Concept/Syntax/Syntax.md @@ -0,0 +1,44 @@ +--- +title: Syntax +--- + +#### Synopsis + +Part of the synopsis that summarizes syntax introduced by this concept. + +#### Syntax + +``` +#### Syntax + +_MarkedText_ +``` + +#### Types + +#### Function + +#### Description + +The syntax section is intended to describe syntactic aspects of language constructs. +The contents of this section are arbitrary text. + + +#### Examples + +The syntax section for an if-then statement can be written as: + +``` +#### Syntax + +`if ( Exp ) Statement;` +``` + +#### Benefits + +* Syntax elements are usually "by example" such that you can immediately read what to write. + +#### Pitfalls + +* Syntax elements are not yet generated from actual syntax definitions + diff --git a/courses/Tutor/Concept/Title/Title.md b/courses/Tutor/Concept/Title/Title.md new file mode 100644 index 000000000..86b75490e --- /dev/null +++ b/courses/Tutor/Concept/Title/Title.md @@ -0,0 +1,42 @@ +--- +title: Title +--- + +#### Synopsis + +The display (presentation) name of a concept. + +#### Syntax + +`````` +--- +title: _ConceptName_ +--- +`````` + +#### Description + +A concept has actually three names: + +* Its file name, i.e., the name of the `.md` file in which the concept is described. +* Its _full_ name, the path name from the root concept to the current concept file. +* Its displayed title, its name as its appears as section heading and in the table of contents. + +The title metadata in the file header defines the presentation name of a concept and may be an arbitrary text. + +Concept names are used to refer to other concepts: when unambiguous its file name or display name can be used to refer to another concept, otherwise a sufficient part of its full name has to be given to make it unambiguous. + +The title is *mandatory* for every concept file. + +#### Examples + +The first line of this concept is: + +`````` +--- +title: What a title +--- +`````` + + + diff --git a/courses/Tutor/Concept/Types/Types.md b/courses/Tutor/Concept/Types/Types.md new file mode 100644 index 000000000..17424836c --- /dev/null +++ b/courses/Tutor/Concept/Types/Types.md @@ -0,0 +1,68 @@ +--- +title: Types +--- + +#### Synopsis + +Part of the synopsis that describes any types or typing rules introduced by this concept. + +#### Syntax + +``` +#### Types + +_MarkedText_ +``` + +#### Types + +#### Function + +#### Description + +The `Types` section describes any types that are involved in the concept that is described. +The description can be just text, but in many cases a table is useful to describe types. + + +#### Examples + +Here is a type description of an if-then-else statement: + +``` +#### Types + +| `Exp` | `if ( Exp ) Statement;` | +``` | +| `bool` | `void` | + + + +| `Exp` | `Statement~1~` | `Statement~2~` | `if ( Exp ) Statement~1~ else Statement~2~;` | +| --- | --- | --- | --- | +| `bool` | T~1~ | T~2~ | `lub(T~1~, T~2~)` | + +---- + +The result will be displayed as: + +#### Types + +| `Exp` | `if ( Exp ) Statement;` | +| --- | --- | +| `bool` | `void` | + + + +| `Exp` | `Statement~1~` | `Statement~2~` | `if ( Exp ) Statement~1~ else Statement~2~;` | +| --- | --- | --- | --- | +| `bool` | T~1~ | T~2~ | `lub(T~1~, T~2~)` | + + +#### Benefits + +* The reader gets an immediate overview of how to use an expression or a function + +#### Pitfalls + +* There may be many different ways of using an operator, combinatorially many, which can not be explored visually in a list or a table. +* These type signatures are written manually and not generated from source (yet) diff --git a/courses/Tutor/Maintenance/Adding/Adding.md b/courses/Tutor/Maintenance/Adding/Adding.md new file mode 100644 index 000000000..18f87b163 --- /dev/null +++ b/courses/Tutor/Maintenance/Adding/Adding.md @@ -0,0 +1,46 @@ +--- +title: Adding +--- + +#### Synopsis + +Add a concept to a course + +#### Syntax + +#### Types + +#### Function + +#### Usage + +#### Description + +There are basically two scenarios for adding a new concept, depending on where its contents come from. + +If the concept is part of a "course": + +* Select a concept that is suitable as parent for the new concept. +* Create a subdirectory, say `SubConcept` for the new subconcept. +* Create the file `SubConcept/SubConcept.md` or `SubConcept/index.md` using your favourite editor. +* Add the name and other information about the new concept. +* Save the file. + +If a concept is a Rascal source module: + +* Simply write the Rascal module in `folder/MyModule.rsc` +* Add @synopsis, @description, @examples, etc. tags to every notable declaration in the module +* Save the file. + +If a concept is a ((Concept)) or Rascal module container only: + +* Create the folder `MyConcept` +* Add new `SubConcept`s as above or new Rascal modules, as above. +* an `index.md` file will be generated for the folder + +#### Examples + +#### Benefits + +#### Pitfalls + diff --git a/courses/Tutor/Maintenance/Maintenance.md b/courses/Tutor/Maintenance/Maintenance.md new file mode 100644 index 000000000..e52ae2bdb --- /dev/null +++ b/courses/Tutor/Maintenance/Maintenance.md @@ -0,0 +1,28 @@ +--- +title: Maintenance +--- + +#### Synopsis + +How to maintain a course. + +#### Syntax + +#### Types + +#### Function + +#### Usage + +#### Description + +The following topics are discussed: + +(((TOC))) + +#### Examples + +#### Benefits + +#### Pitfalls + diff --git a/courses/Tutor/Maintenance/Removing/Removing.md b/courses/Tutor/Maintenance/Removing/Removing.md new file mode 100644 index 000000000..f6b080f4b --- /dev/null +++ b/courses/Tutor/Maintenance/Removing/Removing.md @@ -0,0 +1,31 @@ +--- +title: Removing +--- + +#### Synopsis + +Remove a concept from a course. + +#### Syntax + +#### Types + +#### Function + +#### Usage + +#### Description + +To remove a concept _C_: + +* Remove subdirectory _C_ (and its subdirectories) using standard commands. +* Recompile the course. + +#### Examples + +#### Benefits + +* If there are dangling links to the course, the compiler will produce an exact error for each reference. + +#### Pitfalls + diff --git a/courses/Tutor/Maintenance/Renaming/Renaming.md b/courses/Tutor/Maintenance/Renaming/Renaming.md new file mode 100644 index 000000000..1e3e46994 --- /dev/null +++ b/courses/Tutor/Maintenance/Renaming/Renaming.md @@ -0,0 +1,33 @@ +--- +title: Renaming +--- + +#### Synopsis + +How to rename a concept. + +#### Syntax + +#### Types + +#### Function + +#### Usage + +#### Description + +To rename a concept _C_ to _D_: + +* Rename _C_ to _D_ using the commands of the version control system. +* Rename `D/C.md` to `D/D.md` using the version control system, or keep `D/index.md` +* Open `D/D.md` in a text editor and change the title `title: Old Display Name` to `title: New Display Name`. +* Recompile the course. + +#### Examples + +#### Benefits + +* If there are dangling links to the course, the compiler will produce an exact error for each reference. + +#### Pitfalls + diff --git a/courses/Tutor/Markup/InlineMarkup/Bold/Bold.md b/courses/Tutor/Markup/InlineMarkup/Bold/Bold.md new file mode 100644 index 000000000..585e51b0c --- /dev/null +++ b/courses/Tutor/Markup/InlineMarkup/Bold/Bold.md @@ -0,0 +1,28 @@ +--- +title: Bold +--- + +#### Synopsis + +Create *bold* text. + +#### Syntax + +`````` +*Text* +`````` + +#### Types + +#### Function + +#### Description + +#### Examples + +`*bold*` gives *bold*. + +#### Benefits + +#### Pitfalls + diff --git a/courses/Tutor/Markup/InlineMarkup/Code/Code.md b/courses/Tutor/Markup/InlineMarkup/Code/Code.md new file mode 100644 index 000000000..907e993ec --- /dev/null +++ b/courses/Tutor/Markup/InlineMarkup/Code/Code.md @@ -0,0 +1,34 @@ +--- +title: Code +--- + +#### Synopsis + +Create inline code fragments. + +#### Syntax + +#### Syntax + +`````` +`MarkedText` +`````` + +#### Types + +#### Function + +#### Description + +Creates inline fragments of text that represent code. +Inside the _MarkedText_, other markup can be used. + +#### Examples + +* `` `if` `` gives `if`. +* to escape backquotes surround by more: ``` `` `if` `` ``` + +#### Benefits + +#### Pitfalls + diff --git a/courses/Tutor/Markup/InlineMarkup/Image/Image.md b/courses/Tutor/Markup/InlineMarkup/Image/Image.md new file mode 100644 index 000000000..556f322ca --- /dev/null +++ b/courses/Tutor/Markup/InlineMarkup/Image/Image.md @@ -0,0 +1,65 @@ +--- +title: Image +--- + +#### Synopsis + +Include an image. + +#### Syntax + +This is the general Markdown syntax: +`````` +![alt text](url) +`````` + +With the double brackets you can search for an image in the tutor index: +`````` +![alt text]((Link)) +`````` + +Or, if you need more configurability, like dimensions: +`````` + +`````` + + + +#### Types + +#### Function + +#### Description + +Tutor offers the simple Markdown image syntax plus referencing images in a course. +If you need more flexibility, use the HTML `` tag. + +#### Examples + +`````` +![alt]((dandelion.jpg)) +`````` + +will produce: + +![alt]((dandelion.jpg)) + +or we could use an `img` tag with a full path to the file in the assets folder: +`````` + +`````` + +which produces this: + + + + +(((TODO: uncomment the next link after bootstrapping +))) + +#### Benefits + +#### Pitfalls + +* Don't forget a sensible alt text. It makes the documentation much more accessible. diff --git a/courses/Tutor/Markup/InlineMarkup/Image/dandelion.jpg b/courses/Tutor/Markup/InlineMarkup/Image/dandelion.jpg new file mode 100644 index 000000000..5dbe2e76b Binary files /dev/null and b/courses/Tutor/Markup/InlineMarkup/Image/dandelion.jpg differ diff --git a/courses/Tutor/Markup/InlineMarkup/Image/example-image.odg b/courses/Tutor/Markup/InlineMarkup/Image/example-image.odg new file mode 100644 index 000000000..5e50d1a15 Binary files /dev/null and b/courses/Tutor/Markup/InlineMarkup/Image/example-image.odg differ diff --git a/courses/Tutor/Markup/InlineMarkup/Image/example-image.png b/courses/Tutor/Markup/InlineMarkup/Image/example-image.png new file mode 100644 index 000000000..9de3859d9 Binary files /dev/null and b/courses/Tutor/Markup/InlineMarkup/Image/example-image.png differ diff --git a/courses/Tutor/Markup/InlineMarkup/InlineMarkup.md b/courses/Tutor/Markup/InlineMarkup/InlineMarkup.md new file mode 100644 index 000000000..5c45d39d6 --- /dev/null +++ b/courses/Tutor/Markup/InlineMarkup/InlineMarkup.md @@ -0,0 +1,26 @@ +--- +title: Inline Markup +--- + +#### Synopsis + +Markup directives used in input text. + +#### Syntax + +#### Types + +#### Function + +#### Description + +For convenience we summarize the most common inline markup elements. See for all the supported features. + +(((TOC))) + +#### Examples + +#### Benefits + +#### Pitfalls + diff --git a/courses/Tutor/Markup/InlineMarkup/Italic/Italic.md b/courses/Tutor/Markup/InlineMarkup/Italic/Italic.md new file mode 100644 index 000000000..c6caf75ae --- /dev/null +++ b/courses/Tutor/Markup/InlineMarkup/Italic/Italic.md @@ -0,0 +1,28 @@ +--- +title: Italic +--- + +#### Synopsis + +Create _italic_ text. + +#### Syntax + +``` +_Text_ +``` + +#### Types + +#### Function + +#### Description + +#### Examples + +* `_italic_` gives _italic_. + +#### Benefits + +#### Pitfalls + diff --git a/courses/Tutor/Markup/InlineMarkup/LinkingConcepts/LinkingConcepts.md b/courses/Tutor/Markup/InlineMarkup/LinkingConcepts/LinkingConcepts.md new file mode 100644 index 000000000..0441153df --- /dev/null +++ b/courses/Tutor/Markup/InlineMarkup/LinkingConcepts/LinkingConcepts.md @@ -0,0 +1,74 @@ +--- +title: Linking to Concepts +keywords: + - reference + - referring + - linking + - link +--- + +#### Synopsis + +Refer to a concept in this course or another course. + +#### Syntax + +`````` +((ConceptName)) +((ParentConceptName-ConceptName)) +((FullDashSeparatedPathTo-ConceptName)) +((Course)) +((Course:ConceptName)) +((Course:ParentConceptName-ConceptName)) +((Course:FullDashSeparatedPathTo-ConceptName)) +((ModuleName)) +((a::b::ModuleName)) +((Course:a::b::ModuleName)) +((module:ModuleName)) +((module:a::b::ModuleName)) +((Course:module:a::b::ModuleName)) +((package:a::b)) +((Course:package:a::b)) +((data:ADTName)) +((syntax::SyntaxName)) +((function::functionName)) +`````` + +#### Types + +#### Function + +#### Description + +Above are all the ways a concept can be linked: +* The concept name, which is equal to its file name is leading. +* The parent concept name can be used to disambiguate +* Otherwise the full path to the root of the course can be used, where `/` is replaced by `-` +* Rascal modules can be referenced by name and by their fully qualified name +* To disambiguate modules from concept names, the `module` and `package` prefixes come in handy. + +#### Examples + +The concept name of this concept is `ReferenceToConcept` while its title is `Reference to Concept` (note the spaces). + +We can create a reference to the `InlineMarkup` concept in the current course in the following ways: + +* `((Inline Markup))` (using the display name) gives ((Inline Markup)). +* `((Markup-InlineMarkup))` (using its parent concept name and concept name) gives ((Markup-InlineMarkup)). +* `[see inline markup]((Tutor:Markup-InlineMarkup))` gives [see inline markup]((Tutor:Markup-InlineMarkup)) + +(((TODO: uncomment the reference +))) + +#### Benefits + +* Links are checked at compile-time +* Ambiguous links are first tried in the local course scope before an ambiguity is reported +* Ambiguous links have helpful error messages with the options to choose from + +#### Pitfalls + + + diff --git a/courses/Tutor/Markup/InlineMarkup/Listing/Listing.md b/courses/Tutor/Markup/InlineMarkup/Listing/Listing.md new file mode 100644 index 000000000..4c9e4872b --- /dev/null +++ b/courses/Tutor/Markup/InlineMarkup/Listing/Listing.md @@ -0,0 +1,235 @@ +--- +title: Listing +keywords: + - rascal-shell + - listing + - source + - rascal-prepare + - rascal-commands + - rascal-include + - include +--- + +#### Synopsis + +Include (executable) source code examples in the document. + +#### Syntax + +* Simple Rascal code, no execution: +`````` +```rascal +42 / 6 +``` +`````` +* Simple Rascal, with shell execution: +`````` +```rascal-shell +1 + 1 +``` +`````` +* Rascal shell execution with expected errors +`````` +```rascal-shell,errors +1 / 0 +``` +`````` +* Rascal shell execution with continued environment from previous code block +`````` +```rascal-shell,continue +a + b; // where a and b where declared in an earlier listing +``` +`````` +* Hidden Rascal shell execution without any output (no code, no values, no prints) +`````` +```rascal-prepare +int a = 0; +``` +`````` +* Visual shell execution with side-effects, but no value or printed output: +`````` +```rascal-commands +int f(int n) { + if (n <= 0) { + return 1; + } + + return n * f(n - 1); +} +``` +`````` +* Include the definition of a module in the documentation, and make it importable: +`````` +```rascal-include +demo::my::Example +``` +`````` + +#### Description + +* You can use the triple backquotes to encapsulate a piece of literal source text. The language name indicates +which syntax highlighter to use. You can use all the builtin languages of the downstream markdown processor, but there are some special ones. +* The special langauges start with `rascal-`: + * If you use `rascal-shell` as a language name, then the code is executed line-by-line by a Rascal shell and the output is collected. + * With `rascal-prepare` the code is executed in the current environment but no output is shown and the code is also hidden. + * With `rascal-commands` the code is executed in the current environment, and the code is printed to the documentation page. + * Finally using `rascal-include` you can include modules from disk that are on the current search path. +* Every rascal code block will start in a fresh environment, unless the `continue` label is used. With the `continue` label active, the _previous_ environment is continued. This is particularly useful with the use of `rascal-prepare` and `rascal-commands` as they allow to declare functions and syntax types before they are used in a shell. +* Either `rascal-shell`, `rascal-prepare`, `rascal-commands` or `rascal-include` code with an unexpected error in it will _fail_ the documentation build and an error message will be reported. The build will continue to find other issues and compile all the other files. +* Using the `error` label to a code block, an error will be expected and printed back to the user. This is to demonstrate error messages to the reader. + * If no error is produced by the code block, but the error label is used, an error will be printed and the compilation will fail. + * If an error is produced by a code block, but the error label is not used, an error will be printed and the compilation will fail. +* The "magic comments" `highlight-next-line`, `highlight-start`, and `highlight-end` give you a way to highlight +selected lines in the code. Also you can use ranges like this `{1,4--6,9}`. +* If a `rascal-shell`, `rascal-commands` or `rascal-prepare` produces an interactive `Content` value, then the compiler will wait one second and try to make a [screenshot]((Screenshots)) of the browser's visual content. That [screenshot]((Screenshots)) is immediately included in the current document at that place. +* Use `showLineNumbers` to render line numbers in the code examples. +* If you use `rascal` as a language, no checking occurs. There is only syntax highlighting. + +#### Examples + +`````` +```rascal-shell +x = 1 + 1; +``` +`````` + +Would produce: + +```rascal-shell +x = 1 + 1; +``` + +Using `continue` you can continue where you've left off: + +`````` +```rascal-shell,continue +x + 1 +``` +`````` + +Which results in: + +```rascal-shell,continue +x + 1 +``` + +With `error` you can show an error message without the build failing: +`````` +```rascal-shell,error +int x = 1; +y + y; +``` +`````` + +```rascal-shell,error +int x = 1; +y + y; +``` + +Or you could prepare something in "secretly": +`````` +```rascal-prepare +int x = 1; +``` +`````` + +```rascal-prepare +int y = 1; +``` + +Nothing is shown; the `prepare` block is executed but hidden from view. Then use the context it created later. This is nice for generating example data in files or modules to import +without bothering the reader with the details. Watch out: it is not smart to +hide essential notions from the user. This feature is only for preparing a lesson, not to destroy it... + +`````` +```rascal-shell,continue +y + y +``` +`````` + +```rascal-shell,continue +y + y +``` + +Simply using `rascal` as a language does not have all these effects: + +`````` +```rascal +int fac(0) = 1; +default int fac(int n) = n * fac(n - 1); +``` +`````` + +That block simply produces this: + +```rascal +int fac(0) = 1; +default int fac(int n) = n * fac(n - 1); +``` + +Now we demonstrate line highlighting: + +`````` +```rascal {2--7} showLineNumbers +int fac(int n) { + if (n <= 0) { + return 1; + } + else { + return n * fac(n-1); + } +} +``` +`````` + +```rascal {2-7} showLineNumbers +int fac(int n) { + if (n <= 0) { + return 1; + } + else { + return n * fac(n-1); + } +} +``` + +`````` +```rascal showLineNumbers +int fac(int n) { + // highlight-next-line + if (n <= 0) { + return 1; + } + else { + // highlight-start + return n * fac(n-1); + // highlight-end + } +} +``` +`````` + +```rascal showLineNumbers +int fac(int n) { + // highlight-next-line + if (n <= 0) { + return 1; + } + else { + // highlight-start + return n * fac(n-1); + // highlight-end + } +} +``` + +#### Benefits + +* Code examples that run at documentation compile-time are "always" tested and correct when deployed. +* Screenshots are always up-to-date with the latest look-and-feel of the example + +#### Pitfalls + +* Screenshots are only taken when the compiler is properly configured to link selenium and chrome + + diff --git a/courses/Tutor/Markup/InlineMarkup/Listing/Screenshots/Screenshots.md b/courses/Tutor/Markup/InlineMarkup/Listing/Screenshots/Screenshots.md new file mode 100644 index 000000000..f7cf68ade --- /dev/null +++ b/courses/Tutor/Markup/InlineMarkup/Listing/Screenshots/Screenshots.md @@ -0,0 +1,60 @@ +--- +title: Screenshots +--- + +### Synopsis + +Take screenshots of (interactive) webcontent produced by Rascal code examples. + +### Description + +The `rascal-shell` feature offers the option to take screenshots of interative content. + +Every time the shell detects content that is not strictly plaintext: +* a headless browser is used to display the content. +* a screenshot is taking every second until the visual content stabilizes. +* the screenshot is saved as a PNG image with the markdown content. + +This behavior simulates the effect that users have on the REPL when they produce +visual content. For them normally a browser is started in their development environment to +show the content and to interact with it. + +### Examples + +Any function that produces an http content server, like below, leads to a screenshot: +`````` +```rascal-shell +import vis::Charts; +barChart({<"bike",80>, <"car", 20>}) +``` +`````` + +This produces: +```rascal-shell +import vis::Charts; +barChart({<"bike",80>, <"car", 20>}) +``` + +However, we can also hide the commands and only look at the image, using a prepare shell: + +`````` +```rascal-prepare +import vis::Charts; +barChart({<"bike",20>, <"car", 80>}) +``` +`````` + +This produces: + +```rascal-prepare +import vis::Charts; +barChart({<"bike",20>, <"car", 80>}) +``` + +#### Benefits + +* Screenshots don't lie; you always see it in the documentation as the user will see it in their browser. + +#### Pitfalls + +* The screenshot feature automatically turns off when the tutor startup code can not link a browser and a selenium driver to control that browser. A warning is printed with hints on how to configure `mvn` to fix this. diff --git a/courses/Tutor/Markup/InlineMarkup/Variable/Variable.md b/courses/Tutor/Markup/InlineMarkup/Variable/Variable.md new file mode 100644 index 000000000..fed49af76 --- /dev/null +++ b/courses/Tutor/Markup/InlineMarkup/Variable/Variable.md @@ -0,0 +1,38 @@ +--- +title: Variable +--- + +#### Synopsis + +Markup for a variable. + +#### Syntax + +We use subscript syntax for variable indices. + +* `\VarName` +* `\VarName\~a~` + +Watch out, only characters in this class are supported `[aeh-pr-vx0-9()+-]`. + +#### Types + +#### Function + +#### Description + +Variables in text and code are represented by ((Italic)) markup. +They may be followed by one or more subscripts (enclosed by tildes). + +#### Examples + +* `\Var` gives _Var_. + +* `\Var\~1~` gives _Var_~1~. + +#### Benefits + +#### Pitfalls + +* This feature is broken currently. The italics do not work in code fragments and subscripts are broken as well. +* We only support a limited set of characters currently: `[aeh-pr-vx0-9()+-]` \ No newline at end of file diff --git a/courses/Tutor/Markup/Markup.md b/courses/Tutor/Markup/Markup.md new file mode 100644 index 000000000..d55f94645 --- /dev/null +++ b/courses/Tutor/Markup/Markup.md @@ -0,0 +1,33 @@ +--- +title: Markup +--- + +#### Synopsis + +Markup directives for creating concept pages. + +#### Syntax + +#### Types + +#### Function + +#### Description + +The _MarkedText_ in each section of a concept is plain text. +Some characters or text strings are used to influence the markup of the text +and follow the conventions of +We distinguish: + +* ((StructureMarkup)) influences the structure of the text. +* ((InlineMarkup)) influences the markup for characters or words. +* ((SourceCodeMarkup)) to define concepts in Rascal source code. +* ((QuestionMarkup)) defines interactive tutorial questions. + + +#### Examples + +#### Benefits + +#### Pitfalls + diff --git a/courses/Tutor/Markup/QuestionMarkup/Choice/Choice.md b/courses/Tutor/Markup/QuestionMarkup/Choice/Choice.md new file mode 100644 index 000000000..e6c1b4dc0 --- /dev/null +++ b/courses/Tutor/Markup/QuestionMarkup/Choice/Choice.md @@ -0,0 +1,51 @@ +--- +title: Choice +--- + +#### Synopsis + +Multiple-choice question. + +#### Syntax + +``` +QChoice _OptName_: _MarkedText_ +_GoodOrBad_~1~: _Choice_~1~ +_GoodOrBad_~2~: _Choice_~2~ +... +``` + +#### Types + +#### Function + +#### Description + +Asks a multiple-choice questions described by _MarkedText_. +_OptName_ is an optional name of the question (enclosed between `[` and `]`). +If _OptName_ is missing, the question gets a unique number as name. + +Each possible _Choice_ is preceded by a good (`g`) or bad (`b`) marker. +When generating a question 3 choices (including one good answer) are presented in random order. + +Providing more good and bad answers will therefore create more variation in the generated questions. + +#### Examples + +```rascal +QChoice[Faster]: Which means of transportation is faster: +b: Apache Helicopter +g: High-speed train +b: Ferrari F430 +b: Hovercraft +``` +will produce the question `Faster` in the questions section below. + +And, by the way, the [High-speed train](http://en.wikipedia.org/wiki/High-speed_rail) wins with over 570 km/hour compared to +[Ferrari](http://en.wikipedia.org/wiki/Ferrari_F430) (315 km/hour), [Apache](http://en.wikipedia.org/wiki/Boeing_AH-64_Apache) (293 km/hour) +and [Hovercraft](http://en.wikipedia.org/wiki/Hovercraft) (137 km/hour). + +#### Benefits + +#### Pitfalls + diff --git a/courses/Tutor/Markup/QuestionMarkup/Choice/Choice.quest b/courses/Tutor/Markup/QuestionMarkup/Choice/Choice.quest new file mode 100644 index 000000000..7a99c46ce --- /dev/null +++ b/courses/Tutor/Markup/QuestionMarkup/Choice/Choice.quest @@ -0,0 +1 @@ +[choiceQuestion("Tutor/Markup/QuestionMarkup/Choice","Faster"," Which means of transportation is faster?\n",[good("High speed train"),bad("Apache Helicopter"),bad("Ferrari F430"),bad("Hovercraft")])] \ No newline at end of file diff --git a/courses/Tutor/Markup/QuestionMarkup/Question.odg b/courses/Tutor/Markup/QuestionMarkup/Question.odg new file mode 100644 index 000000000..6da697aa4 Binary files /dev/null and b/courses/Tutor/Markup/QuestionMarkup/Question.odg differ diff --git a/courses/Tutor/Markup/QuestionMarkup/Question.png b/courses/Tutor/Markup/QuestionMarkup/Question.png new file mode 100644 index 000000000..4cb7e7dd7 Binary files /dev/null and b/courses/Tutor/Markup/QuestionMarkup/Question.png differ diff --git a/courses/Tutor/Markup/QuestionMarkup/QuestionMarkup.md b/courses/Tutor/Markup/QuestionMarkup/QuestionMarkup.md new file mode 100644 index 000000000..05bd73be1 --- /dev/null +++ b/courses/Tutor/Markup/QuestionMarkup/QuestionMarkup.md @@ -0,0 +1,68 @@ +--- +title: QuestionMarkup +--- + +#### Synopsis + +Mark up for interactive questions. + +#### Syntax + +#### Types + +#### Function + +#### Description + +:::danger +The specification of questions is being redesigned; The information provided here is outdated. +::: + +The following types of questions are supported: + +* _Text_: a text question with a free format answer. +* _Choice_: a multiple choice question. +* _Type_: question about the _type_ of a Rascal expression. +* _Value_: question about the _value_ of a Rascal expression. + + +((Text)) gives the question text and lists all possible good answers. + +((Choice)) is a straightforward listing of good and bad answers. + +((Type)) and ((Value)) questions are based on a template that consists of an optional _listing_ and an _equality_: + +![]((Question.png)) + + +There should be exactly one _hole_ (indicated by ``) in this template that is to be filled in by the student; it may occur in the listing +or in one of the sides of the equality. The general structure is therefore: _fill in the hole such that the equality holds_. +Given that the listing is optional, this template represents 5 different question styles. + +((Type)) and ((Value)) questions use ((TypeDescriptor))s to describe desired values and share certain common steps (_QSteps_): + +* `prep: RascalCommand` describes preparatory steps needed to execute the question. Typically, required + imports can be listed here. +* `make: Var = TypeDescriptor`: makes a new value generated according to _TypeDescriptor_ and assigns it to a new variable _Var_. + _Var_ can be used in later steps in the same question. +* `expr: Var = Expr`: introduces a new variable _Var_ and assigns to it the result of evaluating _Expr_. + _Expr_ may contain references to previously introduced variables using `<`Var`>`. +* `type: TypeDescriptor` +* `hint: Text`: a hint to be given to the student in response to a wrong answer. _Text_ may contain references to previously introduced variables. +* `test: Expr~1~ == Expr~2~`: the equality that should hold. The expressions may contain references to variables. One side may contain a hole (``). +* `list: Text`: a listing that runs until the next question or the end of the concept. It may contain a hole. + +#### Examples + +* `prep: import List;` imports the List module before executing the following steps. +* `make: A = set[arb[int,str]]` introduces `A` and assigns it a value of the indicated type. +* `make: B = same[A]` introduces `B` and assigns it a value of the same type as `A`. +* `expr: C = + `: inserts the values of `A` and `B`, performs the addition, and assigns the result to `C`. +* `type: set[int]`: the required type is `set[int]`. +* `hint: One or more integers separated by comma's`. +* `test: + == `: the student has to replace `` by an answwer that makes the equality true. + +#### Benefits + +#### Pitfalls + diff --git a/courses/Tutor/Markup/QuestionMarkup/Text/Text.md b/courses/Tutor/Markup/QuestionMarkup/Text/Text.md new file mode 100644 index 000000000..4e5a0e3eb --- /dev/null +++ b/courses/Tutor/Markup/QuestionMarkup/Text/Text.md @@ -0,0 +1,44 @@ +--- +title: Text +--- + +#### Synopsis + +A text question with a free-format answer. + +#### Syntax + +``` +QText _OptName_: _Text_ +a: _Answer_~1~ +a: _Answer_~2~ +... +``` + +#### Types + +#### Function + +#### Description + +Presents a text questions consisting of _Text_. +_OptName_ is an optional name of the question (enclosed between `[` and `]`). +If _OptName_ is missing, the question gets a unique number as name. + +The user can give a free format answer, and that is accepted if it contains one of the given answers _answer_~1~, _Answer_~2~ as substring. + +#### Examples + +The markup +```rascal +QText[Taller]: Which is taller, the Eiffel Tower or the Empire State Building? +a: Empire +``` +Will generate question `Tall` in the questions section below. +The answer is obvious: the [Empire State Building](http://en.wikipedia.org/wiki/Empire_State_Building) is 443.2 meters tall while the [Eifel Tower](http://en.wikipedia.org/wiki/Eiffel_Tower) is 324 meters tall. +Any answer that contains `Empire` will be accepted. + +#### Benefits + +#### Pitfalls + diff --git a/courses/Tutor/Markup/QuestionMarkup/Text/Text.quest b/courses/Tutor/Markup/QuestionMarkup/Text/Text.quest new file mode 100644 index 000000000..836649fbe --- /dev/null +++ b/courses/Tutor/Markup/QuestionMarkup/Text/Text.quest @@ -0,0 +1 @@ +[textQuestion("Tutor/Markup/QuestionMarkup/Text","Taller"," What is taller, the Eiffel Tower or the Empire State Building?\n",{"empire"})] \ No newline at end of file diff --git a/courses/Tutor/Markup/QuestionMarkup/Type/Type.md b/courses/Tutor/Markup/QuestionMarkup/Type/Type.md new file mode 100644 index 000000000..0faffa6a6 --- /dev/null +++ b/courses/Tutor/Markup/QuestionMarkup/Type/Type.md @@ -0,0 +1,53 @@ +--- +title: Type +--- + +#### Synopsis + +A question about a Rascal type. + +#### Syntax + +* `QType OptName : TypeDescriptor` +* `QType OptName : QSteps Test Listing` + +#### Types + +#### Function + +#### Description + +A type question presents a Rascal expressions and poses a question about its type. + +_OptName_ is an optional name of the question (enclosed between `[` and `]`). +If _OptName_ is missing, the question gets a unique number as name. + +The desired type is given by a ((TypeDescriptor)). + +The first form presents the value generated for the _TypeDescriptor_ and asks about its type. + +The second form allows more preparatory steps and also allows adding a listing to the question. + +#### Examples + +See the effect of the following type questions in the Questions section below. + +## Question 1 + +The following question can be paraphrased as: _I give you an arbitrary set of integers, what is its type?_ +```rascal +QType: +``` + +## Question 2 + + +The following question can be paraphrased as: _I give you an addition of a set of integers, strings or reals and another set of the same type; what is the type of the result?_ +```rascal +QType: + +``` + +#### Benefits + +#### Pitfalls + diff --git a/courses/Tutor/Markup/QuestionMarkup/Type/Type.quest b/courses/Tutor/Markup/QuestionMarkup/Type/Type.quest new file mode 100644 index 000000000..ff0dcabb6 --- /dev/null +++ b/courses/Tutor/Markup/QuestionMarkup/Type/Type.quest @@ -0,0 +1 @@ +[tvQuestion("Tutor/Markup/QuestionMarkup/Type","1",typeOfExpr(),details(" ",[],"","","\","",false,false,[<"A",set(int(-20,20),1,5)>],[],void(),"")),tvQuestion("Tutor/Markup/QuestionMarkup/Type","2",typeOfExpr(),details(" ",[],"","","\ + \","",false,false,[<"A",set(arb(0,[int(-20,20),str(),real(-20,20)]),1,5)>,<"B",same("A")>],[],void(),""))] \ No newline at end of file diff --git a/courses/Tutor/Markup/QuestionMarkup/TypeDescriptor/TypeDescriptor.md b/courses/Tutor/Markup/QuestionMarkup/TypeDescriptor/TypeDescriptor.md new file mode 100644 index 000000000..402f4c68b --- /dev/null +++ b/courses/Tutor/Markup/QuestionMarkup/TypeDescriptor/TypeDescriptor.md @@ -0,0 +1,72 @@ +--- +title: TypeDescriptor +--- + +#### Synopsis + +Description of a Rascal type used in type and value questions. + +#### Syntax + +A _TypeDescriptor_ is one of + +* `bool` +* `int` +* `int[Max]` +* `int[Min,Max]` +* `real` +* `real[Max]` +* `real[Min,Max]` +* `num` +* `num[Max]` +* `num[Min,Max]` +* `str` +* `loc` +* `datetime` +* `list[TypeDescriptor]` +* `set[TypeDescriptor]` +* `map[TypeDescriptor,TypeDescriptor]` +* `tuple[TypeDescriptor~1~, TypeDescriptor~2~, ...]` +* `void` +* `value` +* `arb` +* `arb[Int]` +* `arb[Int, TypeDescriptor~1~, TypeDescriptor~2~]` +* `arb[TypeDescriptor~1~, TypeDescriptor~2~]` +* `same[TypeName]` + +#### Types + +#### Function + +#### Description + +A TypeDescriptor is used to describe Rascal types and values in questions and are used to automatically generate +values of the described type. TypeDescriptors largely follow the types as available in Rascal, with the following +extensions that are helpfull when generating values: + +* `int`, `real` and `num` may specify a minimal and maximal value for the values to be generated. +* `arb` describes an arbitrary type. The choice can be restricted by: + * given an integer that defines the maximal depth of the type. + * given an explicit list of types to choose from. +* `same[Name]` refers back to a type that was used earlier on in the same question. + +#### Examples + +| TypeDescriptor | Generated value | +| --- | --- | +| `int` | Arbitrary integer | +| `int[-5,10]` | An integer between -5 and 10 | +| `arb[int,bool,str]` | An arbitrary integer, boolean or string | +| `list[int]` | A list of integers | +| `set[int[0,10]]` | A set of integers between 0 and 10 | + + +#### Benefits + +#### Pitfalls + +* There is currently an arbitrary built-in limit that restricts generated lists, sets, + maps and relations to at most 5 elements. +* There is no support for labeled tuples. + diff --git a/courses/Tutor/Markup/QuestionMarkup/Value/Value.md b/courses/Tutor/Markup/QuestionMarkup/Value/Value.md new file mode 100644 index 000000000..89eb3fb74 --- /dev/null +++ b/courses/Tutor/Markup/QuestionMarkup/Value/Value.md @@ -0,0 +1,107 @@ +--- +title: Value +--- + +#### Synopsis + +Question about the value of a Rascal expression or program. + +#### Syntax + +* `QValue OptName: TypeDescriptor` +* `QValue OptName: QSteps Test Listing` + +#### Types + +#### Function + +#### Description + +A value question presents a Rascal expression and poses a question about its value. + +_OptName_ is an optional name of the question (enclosed between `[` and `]`). +If _OptName_ is missing, the question gets a unique number as name. + +The desired type of the expression is given by a ((TypeDescriptor)). + +The first form presents the value generated for the _TypeDescriptor_ and asks about its value. + +The second form allows more preparatory steps and also allows adding a listing to the question. +The following steps are defined: + +* `prep: Cmd`: execute _Cmd_ as preparatory step. Mostly used to import necessary libraries. +* `make: Var = TypeDescriptor`: create a new variable and use _TypeDescriptor_ to generate its value. +* `expr: Var = Exp`: evaluate the Rascal expression _Exp_ and assign its value to the new variable _Var_. +* `list: Lines`: lines that will be displayed as a listing. The listing may contain a placeholder in the form of `` and + ends where a new step begins. +* `test: Exp~1~ == Exp~2~`: the equality is evaluated as Rascal expression. The outcome determines the success or failure to answer this question. +* `hint: Text`: a hint that will be shown when the user enters a wrong answer. + +The following restrictions apply: + +* Each step starts at the beginning of a new line. +* Every _Exp_ or _Cmd_ or listing may contain one or more variable references of the form `<` Var `>`. +* Each variable reference `<` Var `>` is first replaced by the value of _Var_. + _Var_ should have received a value in a preceeding `make` or `expr` step. +* The listing, and the expressions in the test may contain at most one placeholder ``. + +#### Examples + +See the effect of the following value questions in the Questions section below. + +## Question 1 + +The following question can be paraphrased as: _I give you a union of two sets of integers, what is its value?_ +```rascal +QValue: + +``` + +## Question 2 + +The following question can be paraphrased as: _What is the size of a given list of integers?_ +```rascal +QValue: +prep: import List; +test: size() == +``` +Note that the `List` module is imported as a preparatory step. + +## Question 3 + +The following question can be paraphrased as: +_I give you a union of integers or strings and an unknown set and the result of the union; what is the value of the unknown set?_ +```rascal +QValue: +make: A = set[arb[int,str]] +make: B = same[A] +expr: C = + +hint: +test: + == +``` + +Observe that we generate values for `A` and `B` and compute the value of `C`. +The value of `B` is the answer we are looking for, and we replace it by `` in the posed test. +When the student gives a wrong answer, we show the value of `B` as hint. + +### Question 4 + +The following question can be paraphrased as: +_Fill in the hole in the definition of funcion find to ensure that it returns all strings that contain "o"._ +```rascal +QValue: +desc: Return the strings that contain "o". +list: +text = ["andra", "moi", "ennepe", "Mousa", "polutropon"]; +public list[str] find(list[str] text){ + return + for(s <- text) + if(/o/ := s) + ; +} +test: find(text) == ["moi", "Mousa", "polutropon"]; +``` + +#### Benefits + +#### Pitfalls + diff --git a/courses/Tutor/Markup/QuestionMarkup/Value/Value.quest b/courses/Tutor/Markup/QuestionMarkup/Value/Value.quest new file mode 100644 index 000000000..12c817465 --- /dev/null +++ b/courses/Tutor/Markup/QuestionMarkup/Value/Value.quest @@ -0,0 +1 @@ +[tvQuestion("Tutor/Markup/QuestionMarkup/Value","1",valueOfExpr(),details(" ",[],"","","\ + \","",false,false,[<"A",set(int(-20,20),1,5)>,<"B",same("A")>],[],void(),"")),tvQuestion("Tutor/Markup/QuestionMarkup/Value","2",valueOfExpr(),details(" ",["import List;"],"","","size(\) == ","",false,true,[<"A",list(int(-20,20),1,5)>],[],void(),"")),tvQuestion("Tutor/Markup/QuestionMarkup/Value","3",valueOfExpr(),details(" ",[],"","","\ + "," == \",false,true,[<"A",set(arb(0,[int(-20,20),str()]),1,5)>,<"B",same("A")>],[<"C","\ + \">],void(),"\")),tvQuestion("Tutor/Markup/QuestionMarkup/Value","4",valueOfExpr(),details(" Return the strings that contain \"o\".\n",[],"text = [\"andra\", \"moi\", \"ennepe\", \"Mousa\", \"polutropon\"];\npublic list[str] find(list[str] text){\n return \n for(s \<- text)\n if(/o/ := s)\n ",";\n}\n","find(text) == [\"moi\", \"Mousa\", \"polutropon\"];","",true,false,[],[],void(),""))] \ No newline at end of file diff --git a/courses/Tutor/Markup/SourceCodeMarkup/SourceCodeMarkup.md b/courses/Tutor/Markup/SourceCodeMarkup/SourceCodeMarkup.md new file mode 100644 index 000000000..533e12ae4 --- /dev/null +++ b/courses/Tutor/Markup/SourceCodeMarkup/SourceCodeMarkup.md @@ -0,0 +1,160 @@ +--- +title: Source Code Markup +--- + +#### Synopsis + +Documentation tags attach an inline concept description to any Rascal declaration. Inside the tag you can use an entire structure of a tutor concept. + +:::info +Previously there was a single `@doc` tag with all the sections +of a concept internally. Now we use different tags for each concept. +The old notation is deprecated but still supported for backward compatibility. +::: + +These tags will be used by the tutor compiler to document any Rascal declaration: +* `@synopsis` +* `@description` +* `@examples` +* `@benefits` +* `@pitfalls` + +The `@synopsis` tag is not optional. The others are optional. + +#### Description + +All Rascal declarations can be preceeded by annotation of the form `@synopsis{ ... }` where ... may be arbitrary text, +provided that `{` and `}` characters are balanced and that unbalanced braces are escaped like `\{` or `\}`. +This text is expanded to a full concept definition when the concept is processed. + +The Tutor supports and expands inline concept descriptions for the following declarations types. + +## Module Declaration + +The name of this module is extracted. +The header of the concept definition is automatically generated and consists of: + +``` +--- +title: _Module name_ +--- +#### Usage + +_Import declaration needed to use this module_ +``` + +## Function Declaration + +The signatures of this function and of all directly following functions with the same name are collected. +The signatures are placed in an itemized list (unless there is only one). +The header of the concept definition is automatically generated and consists of: + +`````` +--- +title: _Function name_ +--- + +#### Function + +```rascal +_Function signature_ +``` + +#### +Usage +_Import declaration needed to use this module_ +`````` + +## Data Declaration + +The signatures of this data declaration and of all directly following data declarations without their own `@doc` annotation are collected. +The header of the concept definition is automatically generated and consists of: + +`````` +# _Data declaration name_ + +#### Type + +```rascal +_Data declarations_ +``` + +#### Usage +_Import declaration needed to use this module_ +`````` + +## Annotation Declaration + +The signature of this annotation declaration is collected. +The header of the concept definition is automatically generated and consists of: + +`````` +# _Annotation declaration name_ + +#### Type + +```rascal +_Annotation declarations_ +``` + +#### Usage +_Import declaration needed to use this module_ +`````` + +#### Examples + +We only give an example of documenting a simple function. Read the source code of Rascal library files for other ones. + +Consider the source code of the now function in the `DateTime` library. + +`````` +@synopsis{Get the current datetime.} +@examples{ +```rascal-shell + import DateTime; + now(); +``` +} +@javaClass{org.rascalmpl.library.DateTime} +public java datetime now(); +`````` + +This will be expanded to + +`````` + # now + #### Function + + ```rascal + datetime now(); + ``` + + #### Usage + + ```rascal + import DateTime; + ``` + + #### Synopsis + + Get the current datetime. + + #### Examples + +```rascal-shell + import DateTime; + now(); +``` +`````` + +#### Benefits + +* A (small) part of documentation writing is automated. +* The information about the name of a function, data or annotation declaration, or its signature is always consistent. +* Examples of how to use functions are maintained close to the definitions of those functions +* API documentation for Rascal modules is easily presented online or in an IDE. + +#### Pitfalls + +* This approach requires that functions with the same name are grouped together in the source file. +* Editor support for markdown inside @doc tags is usually limited. diff --git a/courses/Tutor/Markup/StructureMarkup/Admonition/Admonition.md b/courses/Tutor/Markup/StructureMarkup/Admonition/Admonition.md new file mode 100644 index 000000000..0942b7151 --- /dev/null +++ b/courses/Tutor/Markup/StructureMarkup/Admonition/Admonition.md @@ -0,0 +1,91 @@ +--- +title: Admonition +--- + +#### Synopsis + +Mark up for admonitions. + +#### Syntax + +The general scheme is: +* `:::label␤ MarkedText ␤:::`, where `␤` represents a newline character and label is one of: + * `note` + * `tip` + * `info` + * `caution` + * `danger` + + +#### Types + +#### Function + +#### Description + +An admonition is remark that should draw the reader's attention. + +#### Examples + +`````` +:::note +This is a note +::: +`````` + +:::note +This is a note +::: + +`````` +:::tip +MarkedText +::: +`````` + +:::tip +what a great tip! +::: + +`````` +:::info +MarkedText +::: +`````` + +:::info +Some more information here. +::: + +`````` +:::caution +MarkedText +::: +`````` + +:::caution +Careful now.. +::: + + +`````` +:::danger +MarkedText +::: +`````` + +`````` +:::danger +alarm! +::: +`````` + +#### Benefits + +* If used sparingly admonitions can draw the user's attention to important parts in your documentation. +* The tutor compiler uses admonitions to mark problems (errors and warnings) with the links or the code contents of the documentations. + +#### Pitfalls + +* Too many admonitions clutters the documentation and inspires "alarm fatique" +* Better use the `#### Pitfalls` and `#### Benefits` sections to group information that is meant to alert the reader to positive/negative information. diff --git a/courses/Tutor/Markup/StructureMarkup/BulletLists/BulletLists.md b/courses/Tutor/Markup/StructureMarkup/BulletLists/BulletLists.md new file mode 100644 index 000000000..5c32e297d --- /dev/null +++ b/courses/Tutor/Markup/StructureMarkup/BulletLists/BulletLists.md @@ -0,0 +1,72 @@ +--- +title: Bullet Lists +--- + +#### Synopsis + +A (possible nested) list of bullet points. + +#### Syntax + +Here `␠` is used to mark a space character: + +* `* MarkedText` +* `␠␠␠* MarkedText` +* `␠␠␠␠␠␠* MarkedText` +* ... + +#### Types + +#### Function + +#### Description + +Bullet lists create, possibly nested, lists of points. +The number of `*` characters determines the nesting level of a (sub)list. + +A list item ends with: + +* the start of a new list item. +* an empty line. + + + +#### Examples + +The input + +``` +* First item. +* Second item. +``` + +will produce: + +* First item. +* Second item. + + +The input + +``` +* First item. + * First subitem. + * Second subitem. +* Second item. +``` + +will produce: + +* First item. + * First subitem. + * Second subitem. +* Second item. + +#### Benefits + +* ((BulletLists)) and ((NumberedLists)) can be nested under eachother. + +#### Pitfalls + +* An empty line is required _after_ ((BulletLists)). + diff --git a/courses/Tutor/Markup/StructureMarkup/NamedParagraph/NamedParagraph.md b/courses/Tutor/Markup/StructureMarkup/NamedParagraph/NamedParagraph.md new file mode 100644 index 000000000..496d546d5 --- /dev/null +++ b/courses/Tutor/Markup/StructureMarkup/NamedParagraph/NamedParagraph.md @@ -0,0 +1,39 @@ +--- +title: NamedParagraph +--- + +#### Synopsis + +Mark up for a named paragraph. + +#### Syntax + +* `## ParagraphName` +* `\### ParagraphName` +* ... + +#### Types + +#### Function + +#### Description + +A NamedParagraph produces a named paragraph of a level that is determined by the number of `#` characters preceding the _ParagraphName_. + +#### Examples + +The input: + +`## Paragraph` + +will give + +## Paragraph + +#### Benefits + +#### Pitfalls + +* NamedParagraphs have at least two hash signs (`##`). A single hash is reserved for the Concept level. +* A NamedParagraph should start at the start of a line. + diff --git a/courses/Tutor/Markup/StructureMarkup/NewParagraph/NewParagraph.md b/courses/Tutor/Markup/StructureMarkup/NewParagraph/NewParagraph.md new file mode 100644 index 000000000..21ef408eb --- /dev/null +++ b/courses/Tutor/Markup/StructureMarkup/NewParagraph/NewParagraph.md @@ -0,0 +1,41 @@ +--- +title: NewParagraph +--- + +#### Synopsis + +Introduce a new paragraph. + +#### Syntax + +#### Types + +#### Function + +#### Description + +A new paragraph is created by a single empty line. + +#### Examples + +The input: +``` +line1 +line2 + +line3 +line4 +``` + +will produce: + +line1 +line2 + +line3 +line4 + +#### Benefits + +#### Pitfalls + diff --git a/courses/Tutor/Markup/StructureMarkup/NumberedLists/NumberedLists.md b/courses/Tutor/Markup/StructureMarkup/NumberedLists/NumberedLists.md new file mode 100644 index 000000000..3aa9a3d86 --- /dev/null +++ b/courses/Tutor/Markup/StructureMarkup/NumberedLists/NumberedLists.md @@ -0,0 +1,67 @@ +--- +title: Numbered Lists +--- + +#### Synopsis + +A (possibly nested) list of numbered points. + +#### Syntax + +Here `␠` is used to represent a visible space: +* ``1. MarkedText`` +* ``␠␠␠1. MarkedText`` +* ``␠␠␠␠␠␠1. MarkedText`` + +#### Types + +#### Function + +#### Description + +Numbered Lists create, possibly nested, lists of numbered points. +They start with a number followed by a period (`1.`). The number of spaces indicates the nesting level, every 3 spaces represents one level. + +A list item ends with: + +* the start of a new list item. +* an empty line. + +((BulletLists)) and ((NumberedLists)) can be mixed. + +#### Examples + +The input + +``` +1. First item. +1. Second item. +``` + +will produce: + +1. First item. +1. Second item. + +The input + +``` +1. First item. + 1. First subitem. + 1. Second subitem. +1. Second item +``` + +will produce: + +1. First item. + 1. First subitem. + 1. Second subitem. +1. Second item + +#### Benefits + +#### Pitfalls + +* An empty line is required _after_ a NumberedList + diff --git a/courses/Tutor/Markup/StructureMarkup/StructureMarkup.md b/courses/Tutor/Markup/StructureMarkup/StructureMarkup.md new file mode 100644 index 000000000..b5cc8d526 --- /dev/null +++ b/courses/Tutor/Markup/StructureMarkup/StructureMarkup.md @@ -0,0 +1,26 @@ +--- +title: Structure Markup +--- + +#### Synopsis + +Markup for structured text entities. + +#### Syntax + +#### Types + +#### Function + +#### Description + +The following structured markup is supported: + +(((TOC))) + +#### Examples + +#### Benefits + +#### Pitfalls + diff --git a/courses/Tutor/Markup/StructureMarkup/Table/Table.md b/courses/Tutor/Markup/StructureMarkup/Table/Table.md new file mode 100644 index 000000000..1f5a711db --- /dev/null +++ b/courses/Tutor/Markup/StructureMarkup/Table/Table.md @@ -0,0 +1,97 @@ +--- +title: Table +--- + +#### Synopsis + +Mark up for tables. + +#### Syntax + +`````` +| _Header_~1~ | _Header_~2~ | ... | +| ---- | --- | --- | +| _Entry_~11~ | _Entry_~12~ | ... | +| _Entry_~21~ | _Entry_~22~ | ... | +`````` + +The "column specification", that's the line with the dashes, may also contain hints for +left, right and centered aligment: + +`````` +| _Header_~1~ | _Header_~2~ | ... | +| :---- | :---: | ---: | +| _Entry_~11~ | _Entry_~12~ | ... | +| _Entry_~21~ | _Entry_~22~ | ... | +`````` +---- + +#### Types + +#### Function + +#### Description + +Tables follow the [standard markdown syntax](https://www.markdownguide.org/extended-syntax/#tables) for tables. + +#### Examples + +##### Example 1 + +`````` +| A | B | C | +| --- | --- | --- | +| 11 | 12 | 13 | +| 21 | 22 | 23 | +`````` + +gives: + +| A | B | C | +| --- | --- | --- | +| 11 | 12 | 13 | +| 21 | 22 | 23 | + + +##### Example 2 + + +`````` +| A | B | C | +|:--- | ---:|:---:| +| 1111 | 1221 | 1331 | +| 21 | 22 | 23 | +`````` + +gives (with column B centered): + +| A | B | C | +|:--- | ---:|:---:| +| 1111 | 1221 | 1331 | +| 21 | 22 | 23 | + + +##### Example 3 + +`````` +| Operator | Description | +| --- | --- | +| `A | B` | Or operator | +| A | B | Or operator | +`````` + +gives (note the escaped `|` character in one table entry): + +| Operator | Description | +| --- | --- | +| `A | B` | Or operator | +| A | B | Or operator | + + +#### Benefits + +* Standard markdown syntax for tables + +#### Pitfalls + +* Watch out for escaping that `|` character! diff --git a/courses/Tutor/Markup/StructureMarkup/TableOfContents/TableOfContents.md b/courses/Tutor/Markup/StructureMarkup/TableOfContents/TableOfContents.md new file mode 100644 index 000000000..60a4eb1ba --- /dev/null +++ b/courses/Tutor/Markup/StructureMarkup/TableOfContents/TableOfContents.md @@ -0,0 +1,35 @@ +--- +title: Table of Contents +--- + +#### Synopsis + +Generate a local table of contents of current concept. + +#### Syntax + +`````` +(((TOC))) +`````` + +#### Types + +#### Function + +#### Description + +Generate a local table of contents for all subconcepts of the current concept. +This is useful for summary (index) pages. + +#### Examples + +A table of contents of 1 level deep is generated by + +`````` +(((TOC))) +`````` + +#### Benefits + +#### Pitfalls + diff --git a/courses/Tutor/Tutor.md b/courses/Tutor/Tutor.md new file mode 100644 index 000000000..73b59165d --- /dev/null +++ b/courses/Tutor/Tutor.md @@ -0,0 +1,75 @@ +--- +title: Tutor +sidebar_position: 11 +--- + +#### Synopsis + +The Rascal Tutor compiler can be used to create, maintain and follow (interactive) documentation. + +#### Syntax + +#### Types + +#### Function + +#### Description + +The RascalTutor is an interactive ((Authoring)) and learning environment intended to create and follow interactive courses related to the Rascal language. +It is based on the following principles and ideas: + +* [Write]((Authoring)) standard Markdown in normal files and folders that can be edited using any Markdown editor. +* Generates Docusaurus Markdown files in a file hierarchy that can be included easily in a static markdown website. +* The basic notion is a ((Concept)). Each concept has a _name_ and contains a fixed set of subsections that describe it. +* A course is a _concept tree_: + The central subject of the course is the root of the concept tree, and all subtrees further explain their parent concept. +* A Rascal code module is a ((Concept)) to the Tutor compiler as well, in order to provide ((API)) documentation for every Rascal module. The declarations it contains are not sub-concepts but rather sub-sections of that concept. +* A folder with Rascal modules is also a ((Concept)). +If it has an `index.md` file this is used to document it, otherwise an `index.md` file is generated. +* Concepts, as described above, can easily be [linked by short names]((LinkingConcepts)), and disambiguated with longer names when necessary. + +A _student_ using a course can: + +* Browse through the table of contents of the concept tree of the course. +* Search for concepts and specific terms using a search box. +* Read individual concepts. +* Follow links to other concepts. + +An _author_ of a course can: + +* Create a new course. +* Create a new concept in a course. +* Edit a concept directly using a standard text editor. +* Add code examples that are actually executed at "compile time" of the course. The code examples either simulate the interaction with the Rascal REPL, or they are just highlighted code. +* Recompile the course. +* Inspect the warnings that are generated for the whole course in order to + control the quality of the concept descriptions. +* Create [links]((LinkingConcepts)) between concepts (in different courses) +* Inline images in the same folder/directory as the concept +* Use Rascal code to create (static) visuals + +The actual markup used is an extension of Docusaurus, see https://docusaurus.io/ and +in most cases we directly refer to + +* https://docusaurus.io/docs/markdown-features for the "commonmark" compliant features of Docusaurus +* https://docusaurus.io/docs/markdown-features/react for the MDX/React extensibility features of Docusaurus + +The following topics will be described here: + +(((TOC))) + +#### Examples + +#### Benefits + +* The tutor compiler generates docusaurus-compatible markdown, which is general Markdown unless people write text that depends on docusaurus-specific extensions. This means that downstream processing can be done by many different Markdown tools. +* The input syntax is also very close to standard Markdown, so typical Markdown editors will do a good job in helping you write documentation. We also selected the `.md` extension for this purpose. +* The tutor compiler allows to include runnable code examples that must succeed in order for to the documentation to be released. This makes the documentation another source of valuable tests for the documented Rascal code, and it guarantees that users can copy paste from the examples without hazard. +* **privacy** Tutor does not send or retain information about the user at the server side. Even interactive question answering and the progress that is measured are stored client-side only. + +#### Pitfalls + +* We have to run the tutor compiler manually to find out about possible errors. There is no IDE support yet. +* The Tutor compiler is not incremental yet. It will re-compile everything from scratch even if nothing has changed. +* Downstream tools, such as Docusaurus, may detect issues that the tutor compiler does not detect. For example broken links that are not ((Concept)) links will not be detected early. This means you may have to go back and fix the documentation, release it in a `jar` and then try the downstream tool again. +* The interactive ((QuestionMarkup)) part of the compiler is currently under maintenance and therefore unavailable. diff --git a/pom.xml b/pom.xml index 4b2bbd8f7..d621700d2 100644 --- a/pom.xml +++ b/pom.xml @@ -26,7 +26,6 @@ 0.24.0 0.34.0 - 0.18.4 0.12.0 0.1.14 0.2.3 @@ -101,15 +100,6 @@ docs/**/*.* docs/index.value - - org.rascalmpl - rascal-tutor - ${rascal-tutor.version} - ${project.basedir} - docs/**/*.* - **/examples/,**/questions/ - docs/index.value - org.rascalmpl clair @@ -196,6 +186,7 @@ ${project.basedir}/courses/GettingStarted ${project.basedir}/courses/Rascalopedia ${project.basedir}/courses/Bibliography + ${project.basedir}/courses/Tutor ${project.basedir}/courses/Packages @@ -265,11 +256,6 @@ clair ${clair.version} - - org.rascalmpl - rascal-tutor - ${rascal-tutor.version} - org.rascalmpl salix-core