Initial rearranging of documentation #116
Conversation
|
That all sounds great - lmk if you want a second pair of eyes to review anything. |
| @@ -38,27 +36,44 @@ include::ch_installing.adoc[] | |||
| == Running Tali Forth | |||
| include::ch_running.adoc[] | |||
|
|
|||
| == Major Components | |||
| = Tutorials for Major Components | |||
There was a problem hiding this comment.
Perhaps even just "Introduction to major components"?
It the TOC some of the subsections here have headings like "Tutorial: Working with Blocks" and others don't have the "Tutorial:", like "The Assembler". I slightly prefer the latter but either way I think they should all be the same.
There was a problem hiding this comment.
I was trying to mark the ones that were "walkthrough" style as tutorials, where the others are more descriptions of how it works. Perhaps there is a better way to do this? or perhaps its not necessary?
I would like to have a way to find the "hands on things to try" for someone who wants to try things out even if they don't understand everything that is happening.
| @@ -8,6 +8,10 @@ go and read Leo Brodie's excellent "Starting Forth", available for | |||
| free online, before continuing through this manual. You can use Tali | |||
| Forth 2 to run the examples given in the book. | |||
|
|
|||
| You will also want to refer to Tali's <<Glossary>> for the list of words that | |||
There was a problem hiding this comment.
It wasn't clear to me in the TOC that "Glossary" referred to forth words, rather than (say) a glossary of concepts in the manual. What about calling it "Glossary of Built in Forth Words" or some such?
There was a problem hiding this comment.
That's a good point (and another one where I was blind to the issue - if I'm working with a new forth, it's glossary is the first thing I look for). I hadn't even thought about the fact that the word glossary has multiple meanings here, and that either type could be expected in a document like this.
| built-in RAM drive that can be accessed by running: | ||
| hardware or are running Tali in a simulator, fear not! Tali has a | ||
| built-in RAM drive that can be used on any hardware or simulator. If using the | ||
| c65 simulator that comes with Tali, persistant storage can be simulated using |
There was a problem hiding this comment.
Thanks - flag any of those that you find (I'm sure there are more in there). I re-read everything when I'm done, but don't always catch them all.
| The following tutorial walks through some examples using |
There was a problem hiding this comment.
I rearranged that section a bunch and ended up removing a couple of the sections, but I haven't deleted the files yet because I still want their contents for shuffling things around. ch_blocks.adoc and ch_editor_block.adoc will no longer be included as their content was moved into the tutorial itself (ch_tutorial_blocks.adoc). I suspect this is leftovers of me trying to piece things together. I'll be deleting those other files soon, as I think it's better with all of the material in the tutorial section.
| The addresses (xt) of these routines need to be placed in the existing variables | ||
| `BLOCK-READ-VECTOR` and `BLOCK-WRITE-VECTOR`, respectively. | ||
| If you had written routines named `mybockreader` and `myblockwriter`, That might |
|
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. |
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.
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. |
|
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 |
|
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. |
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 |
|
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 |
|
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 :) |
|
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 |
|
I started writing a hardware tutorial with the LCD, and it's long - especially with the LCD in 4-bit mode, which is the configuration a BenEater computer uses in the schematic with the serial port (oddly enough, it's wired in 8-bit mode in the schematic without the serial port). I think it makes more sense to start with just buttons and lights on a 65C22 VIA. I'm not sure if I will use the LCD example or not. Perhaps I can simplify it as I won't need to re-explain how the VIA ports work. |
|
awesome - i'll pull the branch and have a read. the beneater lcd video which I followed (https://www.youtube.com/watch?v=FY3zTUaykVo) jump right to 8-bit mode since it's much simpler to code. i'd definitely stick with that if you do write up anything for LCD since 4-bit is super-painful. i originally just hooked up a bar-graph LED to 8 via output pins instead of the LCD, and got my "moment of joy" when I was able to roll a bit backward and forward across the bar-graph, knight-rider style 😂 if it's of any use I collected all the asm code for my beneater build which followed the videos fairly closely. e.g. via.asm, lcd.asm and so forth. I did skip all the serial acia stuff and used simple bit-banging from a smart keyboard for input. but no doubt you have your own version of all of it |
|
I agree - the 8-bit LCD would be much better/simpler. I'm spending way too much time explaining the initialization and nybble transfer. The 8-bit transfers don't need the masking and shifting of the data - only masking for the control lines is needed. The LCD section is commented out in the .adoc file for now - I'll probably give it another go with 8-bit data. If I put the LCD example after the buttons/lights example, then I also don't need to re-explain how the VIA ports work. I, of course, also built some knight-rider LEDs and was thoroughly amused. That was some of the first Forth I stored in blocks in an EEPROM so I could easily load it later. I'll put some hardware together and actually run the code examples and make sure they work as expected. You're welcome to flag anything you see that is wrong. |
|
Buttons/LEDs and LCD examples tested on real hardware. |
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.