documentation suggestions from a forth newbie

[patricksurry]

I've played with taliforth a few times, and have been spending a lot of time with it recently working on porting a big chunk of old C code as a learning exercise. a while back i went through the right of passage of writing my own 6502 forth (an ITC implementation based on jonesforth) and benchmarked it as about 3x slower (and much less functional) than tali :). so my view might be slightly weird since I know a fair bit about how forth works, but less about how to write forth code.

Sam suggested writing down some thoughts about the docs. apologies this is a bit of a braindump.

• i felt a bit lost in initial "getting started writing some actual forth". I would have loved a mini tutorial on the concrete mechanics of writing forth code using taliforth in pymon. for example:
  • introduce bye, quit, abort, cold, dump, here, .s etc;
  • how you can jump back into pymon,
  • how to reset from pymon back into forth rather than just launch pymon and immediately reset into forth.
  • what's the best way to experiment with defining some new words in forth? I can paste stuff from a scratchpad in my fave editor into pymon, and can type things directly in the simulator. should i have a habit of just copy/pasting back to my scratchpad when something works, and then pasting my chunk of currently working code into the sim once I start it up?
  • do the accept buffers work in pymon with ctrl-n, ctrl-p? (i only discovered this feature reading the dev guide later)
  • adding a simple console log with some tali interaction in pymon to the 'dude ...' section in the README would be cool too

i now use a different c-based simulator that mimics pymon getc/putc but also has a magic block r/w address so you can read/write from an external file; i'll make a PR with that since it would give an alternative to the ram disk to play with block words

• the docs have a lot of front matter before you get to a hands on "getting started" section, especially for someone wanting to use forth rather than modify / understand the internals. e.g. the design considerations section feels like it could happily live in the developer section rather than up front where I probably don't care yet about which implementation model it uses

• the organization of user guide / developer guide / tutorials was odd to me; especially as the user guide has a kind of mini version of several of the later tutorial sections so I kept getting a sort of deja vu feeling. i wonder if the tutorials should be separate docs, or at least moved before the developer part, perhaps keeping the mini versions even shorter

• after a long time I discovered that the appendix / glossary is a reference for all the built-in words (beforehand I'd been spending a lot of time in native_words.asm reading the comments). this is super handy and would love more callout earlier, or at least renamed/linked to make it more discoverable. would also love a one-page(?) cheat sheet or standalone markdown doc with one line per word / signature / short desc. i thought words.md might be the thing but that is more of a symbol table/wordsize rather than how to use the words

• there is a lot of content about the assembler/disassembler in the user guide. while these are great tools, it seems tangential to getting on with forth, so i would be tempted to just intro and then move the bulk of their detailed content to a tutorial/appendix

• because the documentation is so big I often resorted to searching for specific things I wanted to know about rather than reading linearly. this compounds the deja vu feeling when there is some duplication in different sections.

• (minor) i ran into a gotcha with evaluate in that it eats everything beyond a backslash. also (iirc) paren comments only work on a single line. this would be great to note in the docs when you talk about comments. is there a standard multi-line comment?

• as a developer i was confused about how to integrate taliforth with my own kernel. the 'installing on your own hardware' is great as is the top-level config management to customize for your h/w. but if I need to get it to play nice with my own code, how do i do that? for a while i was put off even trying since tali is currently tied to a different assembler than I've been using and I didn't want to port either way. ultimately it's not too difficult to configure and make tali, and then .incbin the tali code when I build my own kernel, or vice versa perhaps modify the tali build to insert my own kernel code. (that felt harder since tali's make structure initially seemed "complicated" until I spent some time with it)

• in fact for a long time i was confused that the 'kernel' shown in yellow in the zero page and parts of rom referred to space not used by tali where I could put my own kernel routines and vars, rather than part of some tali kernel that was already spoken for. for example I started by trying to put my own kernel zero page values at the (already used) bottom of page 0 instead of the (free) top.

[SamCoVT]

There is a lot to digest here. Thanks for taking the time to write it all down. For the items that I want to take action on, I'll probably split some of these out into separate issues. For things that don't have a super clear path to resolve, I think to think about them for a while before I take action.

I'll recommend opening a separate issue for \ for strings with line endings, as that may require some additional digging into details like what a line ending even is (LF vs CR vs CR+LF) and how to handle the fact that they might be different on different systems (have already run into this on #27). I expect that parenthesis comments will work if you are EVALUATING a string that contains line ending characters, but it's true that they are not multiline in general and that's because REFILL only reads one line at a time from the keyboard. The forth standard doesn't require them to be multiline, but it also doesn't prohibit them from being multiline. I, personally, would like \ to work in blocks, so I'm likely to be editing that word anyway.

I think some of this is simply organizational, but some will require adding new material or rewriting some sections. You are welcome to help as little or as much as you are interested in. An intro that handholds all the way through a "My First Forth Session" seems like a reasonable place to start.

I do now see that the glossary is indeed not mentioned at all, and there are multiple places where it could or should be mentioned, including the aforementioned "My First Forth Session".

Do you know how to jump back into py65mon (other than using bye or executing a BRK instruction)? On Linux, CTRL-C breaks all the way out of Tali and py65mon. I usually set breakpoints before starting Tali if I want to be in the monitor at a certain point.

A separate issue on how to integrate Tali with other (possibly already existing) code is also welcome, and I'd love to hear your thoughts. Tali is set up for you to put all of your code in the platform file (or include it from there), but that's certainly not the only option. Tali is also set up in the py65mon platform file to have the kernel code after Tali, but it certainly can be the other way around (see the neo6502 or sorbus platform files, which have kernel_init first and then Tali). The good news is that Tali is generally pretty agnostic about where exactly things get put (by design), but I'm not sure what the documentation for that might look like.

The Makefile system also isn't fully explained anywhere. There's a "make sim" target, for example, that will reassemble Tali (if it needs it) and then load it in the (py65mon) simulator.

I think a lot of your other points may be things that can be more clear, and this is where it's super handy to have someone experiencing Tali for the first time.

[patricksurry]

I'll add an issue for the comment discussion.

Might take a stab at writing a little intro session.

how to jump back into py65mon (other than using bye or executing a BRK instruction)

just that, using bye to get back to pymon perhaps after collecting some xt locations, and then resuming at quit e.g.

: foo ." hi" ;  ok
foo hi ok
hex ' quit u. 8083  ok
bye 
65C02: PC=f02b A=85 X=78 Y=01 SP=f9 FLAGS=<N0 V0 B1 D0 I1 Z0 C0>
.g 8083
foo hi ok

[SamCoVT]

That's handy - much better then starting at COLD. It also leaves the stack intact.

[SamCoVT]

The "User Variables" have been updated in both platform/platform-py65mon.asm as well as the diagram in the user manual. I still have to read through the text in the manual to see if anything else needs to be updated, but hopefully that will make it clearer. If you can take a look at docs/pics/memory_map.png , does that help clear up some of the confusion? I also marked the yellow sections as AVAILABLE.

[patricksurry]

coming back to this looking at the block intro. Currently the doc structure looks like:

• Dedication
• Intro
  • But why
  • Overview of TF
• User Guide
  • Installing
  • Running
  • Major components
• Developer Guide
  • ...
• Tutorials
  • ...

With a novice user in mind, I think the intro>overview section would fit better at the start of the developer guide, and would merge 'major components' into tutorials and move it before the developer guide. i.e.

• Dedication
• Intro (but why?)
• User Guide
  • Installing
  • Running
• Tutorials (merging major components text)
• Developer Guide
  • Overview of TF
  • ...

[SamCoVT]

I agree that the beginner stuff should be closer to the front of the manual without a need to know much about Forth (or 65C02 for that matter) to get started.

I do think this will be a bit more involved than just rearranging the sections, but getting the order of the sections down first should make it clearer what info should be in each section. I'm pretty busy until the summer, but I should have some time then to take a deeper look and get started on this. If you think you have time (and are interested) to start with the rearranging earlier than that, let me know.

[SamCoVT]

I'm getting ready to get started on this - initially just a rearranging of the material that already exists, then pulling out the tutorials and reducing duplication in user guide/tutorial sections, and I expect to be adding some tutorials as well. I think I'd like the tutorials to be walkthrough type exercises with the basics, some stuff to try, and the results explained; the user/developer guide can have more of the "how it works" information.

I just wanted to send out a heads-up that the docs would be being rearranged as that may affect PRs (edit: PRs that update the docs) for a while.

[SamCoVT]

Notes: Removing block editor chapter as the tutorial covers it completely

TODO (will update as I go along):

• [X] In Developer Guide, it says c65 lacks debugging and monitor capabilities - that is no longer true.
• [X] Mention Glossary - Words section of Running Tali Forth, at least - recommend mentioning multiple times.
• [X] merge the block section into the tutorial
• [X] Investigate making the text the user types in different (eg bold) in examples, if possible.
  • Does not appear to be easily possible in asciidoctor format.
• [X] Remove statement that Tali only supports parenthesis comments in blocks - it now supports \ as well
• [X] Add link to wordlist tutorial in wordlist section of Running Tali Forth.
  • [ ] Consider merging wordlist tutorial and Running Tali Forth section.
• [X] In "Running the Binary" section, there is a sentence fragment "If you have make installed"
• [X] Add a tutorial for working with hardware (perhaps Ben Eater LCD on 65C22), or buttons and LEDs on 65C22 ---------------------------------------- merged to master up to this point
• [ ] Add tutorial on native compiling
• [X] Fix error in glossary (at the very top) about KEY? (probably a formatting error in the assembly)
• [ ] Add tutorial (place first), perhaps in Running Tali Forth, with a quick walkthrough starting the simulator, writing a word (perhaps with copy/paste from an editor), showing the use of CTRL-N and CTRL-P, and exiting the simulator (note that py65mon needs an extra "q" to quit the simulator)
• [ ] Move Testing Tali Forth into Developer Guide
• [ ] In Installing section, the "If you have GNU Make" is repeated twice - looks like a leftover sentence fragment.
• [ ] In the Native Compiler section of How Tali Works in the Developer Guide chapter, there is a source listing of words&sizes that needs to be updated (it was modified to support the new header structure). The correct code can be located in forth_code/user_words.fs (as noted just above the listing).
• [ ] spelling/grammar
  • [X] persistant -> persistent
  • [X] mybockreader -> myblockreader

Long Term TODO

• [ ] Consider switching back to LaTeX (the full docs toolchain is getting difficult to manage, and LaTeX is required for generating the PDF anyway) as this may allow tutorial examples that have user input rendered differently than Tali output. Pandoc would still be used to generate .md and html versions.

[patricksurry]

The updated TOC looks great! I might move the "Testing TaliForth2" section from the appendix into the developer guide since it feels like it should be a key part of the workflow for anyone making changes to check they haven't broken everything :)

[SamCoVT]

That's a good point - in fact, it might be good near the beginning of the developer section.