[Amforth] Ref Card Generation quo vadis?

[Erich W. <ew....@na...>]

thread hijacked intentionally.

Hello Mark,
dear AmForthers,

today I spent some time trying to understand the "make-refcard*"
scripts in some detail.

The script works roughly like this:

- it reads the .asm files in "one" "hard coded" directory
  ("../common/words").

- for every file the function "readASM" goes to some length to digest
  the content.

- the first three lines are comments expected to produce
  1. the stack effects (data, return, compile stacks)
  2. the category to which this word belongs
  3. a one line description, what this word is supposed to do.

- the name of the word is searched for in the '^VE_...' to '^XT_...'
  section of the code (^ being the beginning of the line).

- the strings found during this procedure are stored into several
  hash-tables, where the XT_LABEL of the word is used as the key into
  these tables.

- after all files are digested and the hash-tables are filled
  accordingly, the function printLaTeX will walk through these tables
  and print their content accordingly.

Mark has spent some time to fix the comment headers and make the
script work again. Thank you for your time!

See thread starting here:
https://sourceforge.net/p/amforth/mailman/message/37060533/
and especially here:
https://sourceforge.net/p/amforth/mailman/message/37063662/


------

Now I could commit Marks patches and not look further. However, there
are several shortcomings with the current state.

- The script will currently only digest AVR style .asm files, whereas
  we have different asm styles (see next point).

- The script will currently only read "one" directory, whereas we have
  several directories with /different/ asm styles!
  - arm/words/    -- gnu asm style
  - avr8/words/   -- avr asm style
  - common/words/ -- avr, msp430 asm style with .if directives
  - msp430/words/ -- msp430 asm style
  - risc-v/words/ -- riscv asm style
  - shared/words/ -- looks like some macro style for generators

- The generated output (LaTeX, ReST) is done with two different
  scripts.

- The generated output does currently not have any indication, on
  which ports a particular word is available.

- The script will currently not read any forth code. And words like
  "value" or "c," should show up in the refcard as well, shouldn't
  they? And should the refcard not have the information that you have
  to include one of these files:
  :    avr8/lib/forth2012/core/c-comma.frt
  : msp430/lib/forth-2012/core/c-comma.frt

  I kind of remember that Matthias decided to move some code from the
  pre-assembled form /back/ to pure Forth. This was in order to help
  dealing with the new, additional architectures.

- in the .asm files I would also like to see a pure Forth equivalent
  as a comment. I have missed this in the past already.


Apart from that the perl scripts are somewhat clunky and would deserve
some more modern style upgrade. Perl style i.e. I have no interest in
moving anything to Python, as you might guess.

So. Things are a whee bit muddy, unfortunately.

I currently do not see, where we would want to go. What would a good
"Reference Card" look like? Once that becomes clearer, I'm sure there
are ways to get there.


Happy forthing!
Erich,
still undecided on this



-- 
May the Forth be with you ...