Initial rearranging of documentation

[SamCoVT]

Initial work on #33 to rearrange the manual. I've already merged the block chapter and block editor chapter into the tutorial, as the tutorial already covered almost everything and that reduces a lot of the duplication.

I'd like to add some more tutorials showing a sample simulation run (including editing code in an editor on the PC), one on native compiling, and one on working with hardware (perhaps using a beneater LCD+65C22 circuit as an example). I'm keeping a todo list in #33.

[patricksurry]

That all sounds great - lmk if you want a second pair of eyes to review anything.

[SamCoVT]

Thanks for taking a look.

I'm currently getting frustrated by the inflexibility of the tags used to show forth code - they only allow very minor markup (like footnotes). In the tutorials, I'd like to make it clear what the user is typing for input and what Tali is typing back, but there is no easy way to adjust the typeface in those sections.

Tali's documentation was originally in LaTeX, and I'm thinking it might be a good idea to go back. Scot had changed to the adoc format to try to make it easier to work on for people who don't know LaTeX, but I honestly don't think LaTeX is that difficult to learn and I'm missing features that I think would be very useful.

How do you normally read the documentation? Do you have a preference for the PDF vs HTML vs .md versions? The PDF is currently a second class output, as there is no control of page breaks and other formatting.

I'll finish this effort up first to get things to a reasonable spot before I investigate if moving back to LaTeX would be worth the effort, but I think the tutorial sections, specifically, could benefit.

[patricksurry]

How do you normally read the documentation?

Interesting question. I like the HTML layout a little better but often fall back to the PDF version since I find the sidebar thumbnails help me navigate and the search seems better somehow. The markdown is hard to use as a single huge page without sidebar nav. Overall I don't love the single monolithic doc.

Tali's documentation was originally in LaTeX, and I'm thinking it might be a good idea to go back

I've used LaTeX a bunch and it seems well suited for a book-style output esp with complex math etc. I'd never come across adoc before Tali. For this kind of software project my own preference would be mkdocs. ie. source in markdown with html extensions where needed, and served directly from github pages. I've used mkdocs material before which is nice for organization and search. I like the doc style used by fastapi and friends. Particularly the rich animated termynal they use to show user interaction.

mkdocs-material has a lot of support for including and annotating code blocks (https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#usage), and apparently its default syntax highlighter pygments even supports forth(!)

I could try a quick stab at a skeleton like that some time if you're interested.

[patricksurry]

having just updated a few of them, another thing that would be great with documentation would be to have the code snippets extracted so we could test/update the output automatically whenever the binary changes

[SamCoVT]

I'm not sure if it's worth the effort to automate the code snippets for the docs, but the thought had crossed my mind. I would like to improve the code snippets, though, either in visibility of what the user is supposed to type, or perhaps having a codeblock to go along with an example session that is only the user input, so it could be copy/pasted to hardware or a simulator.

[SamCoVT]

I'm currently getting frustrated by the inflexibility of the tags used to show forth code - they only allow very minor markup (like footnotes). In the tutorials, I'd like to make it clear what the user is typing for input and what Tali is typing back, but there is no easy way to adjust the typeface in those sections.

For input vs output, I was thinking it might be good to show sample input (in a way that can be copy/pasted into a working Tali, be that on hardware or in simulator) and then separately show an actual session. In order to help show what is input and what is output, I made a Tali branch that colorizes the output with ANSI codes (it changes the text color at the beginning of accept and then puts it back at the end) and would up with this: I'm not a huge fan of images of text, but I think that's going to be the best option and I have less objection if a copy/paste version of the text is available right nearby.

[patricksurry]

nice! i've wrestled with the same thing on some other projects. tho text images might end up pretty painful to maintain?

I like animated/colored text markup in html/css like this https://github.com/termynal/termynal.py which comes from here https://github.com/ines/termynal it claims to have pure html/css fallback but maybe that's problematic if you want to keep targeting PDF? i'm not sure how the conversion works

[SamCoVT]

I agree that the images might be a pain to maintain, but this method should work for md, html, and PDF outputs. I also don't see most of the tutorial content changing all that much once it's written. It might be worth adding a note that output may be slightly different on newer versions of Tali.

The termynal output is cute, but I'm too impatient to wait for it to play :)

[SamCoVT]

I'm actually super-enjoying this "input and output are visually different" - I might make it less hacky and add it as an option that's off by default. I've pushed my colorize_output branch if you want to try it out yourself (and promise not to laugh too hard, as I totally kludged it in there with emit_a over and over - I'll make optional strings if I decide to make it an option). The only change is to accept, so you can modify the ANSI code if you want a different color.