Various typos

[aanastasiou]

Hello.

My previous experience with meta-programming has been with Racket and I had to go through Rascal's documentation quite a few times to improve my understanding of its constructs and way of thinking.

Because of this, I came across a number of typos or other "issues" with the text that made comprehension a bit difficult.

I decided to start noting down alternate suggestions for improvement and these few commits cover the material up to "Rascalopedia" and a few entries within the "Rascal Language Reference".

This PR contains notes from this first pass after the amount of "issues" I was coming across dropped significantly in the later files (the Standard Library docs seem to be in a very good state).

Finally, an "issue" that was tackled in a separate commit (the last one) was the definition of multi-level lists using multiple * characters. This causes multi-level lists to be rendered as one solid block of text and require a bit of untangling while reading. Characteristic examples are here (The third bullet point is supposed to have a nested list which is rendered as a set of bold characters), here (The list is rendered with visible double asterisks in front of every list item), here (third bullet point...) and elsewhere. The exhaustive list is found in docs/files_with_list_revisions.md.

I hope this helps.

Thank you for Rascal.

[jurgenvinju]

@aanastasiou this is great! Thanks for taking the time and I'll have a look tomorrow at your contributions

[jurgenvinju]

Ok I reviewed the changes and they are all good. What a nice X-mas present :-)

Now the merge is going to be somewhat of a challenge. @JJWTimmer @DavyLandman I can use your help here. The challenges are:

• the edits in the PR are on the generated output markdown files of the tutor that we copied temporarily into the docs folder manually (while bootstrapping the new documentation system);
• the input files for docs/Rascal are still in the rascal project
• the input files for RascalConcepts, RascalShell, Recipes and Rascalopedia are now in this project in the courses folder.
• file names do not correspond: all ConceptName/index.md are ConceptFolder/ConceptName.md in the course
• path names do not correspond: docs => courses
• line numbers do not correspond. The YAML headers in particular are different between source and target, and also some files have expanded rascal-shell blocks with output in them that shifts the offsets.

My current conclusion is that I should go through each diff manually and apply manually, but I'm open to suggestions :-) W.r.t to filenames I can edit patch files manually, but with respect to line offsets I don't know how to fix that issue. Can git merge this somehow?

[jurgenvinju]

For clarity's sake: @aanastasiou could not have known we were in the middle of this migration.

[aanastasiou]

@jurgenvinju I am both glad to hear my edits were received positively and kind of terrified to realise that all along I was probably editing the intermediate representation :/

Can still lend a hand if there is anything I can do.

Just two questions:

1. What is the right place (directory) to apply the changes?
2. I wonder if we can get the diffs from git, where changes are presented in context and then match that context in the "new" files to quickly pin-point where a given change is to be applied. From that, we can probably generate diff files that when applied en masse, they can edit the "new" locations in place. It is not without effort but at least it would be focused on generating the diffs correctly.

[jurgenvinju]

Don't worry, we'll figure out a way. I think your suggestion comes very close to what I had in mind too. Just need to find some time.. but if you have the spirit, please do take the initiative. Having said this: I believe we all deserve a gitless holiday 😁

At 1. The Rascal course source files are in the rascal project at src/org/rascalmpl/courses/Rascal. That doc remained in that project for it's tight connection with the interpreter and parser.

The other courses are in the website project under the courses folder. The mvn rascal:tutor command generates the intermediate files in the docs directory and in static/assets. mvn package additionally copies the other intermediate files from the Rascal jar file, and that's necessary to be able you resolve links between the different courses.

[JJWTimmer]

Hi all, hope you had wonderful days. Given filenames and locations changed and it are many small improvements, I'd say let's do it manually. I can start doing it but I'd like to make sure nobody else it doing that at the same time.

[jurgenvinju]

that's probably the safest way. one github merge hack can introduce more issues than we can fix :-) You have the baton @JJWTimmer Thanks!

[JJWTimmer]

Ok, I've gone through the changes and applied them at the right files manually and added you as a co-author @aanastasiou! Thanks for your efforts! Please keep 'm coming! This website and docs rework lately was mainly because I felt it was too hard to contribute, so I am very glad we got our first contribution so soon. I'm going to close the PR 'unmerged' but we included your changes.

[jurgenvinju]

Thanks @JJWTimmer !

[aanastasiou]

Thank you @JJWTimmer , @jurgenvinju .

Jasper, I took Jurgen's suggestion for a gitless holiday I am afraid, glad to see it probably did not take too long for the changes to be transcribed. Will be more careful in the future.

All the best