On Sat, Aug 1, 2020 at 10:50 PM Erich Wälde <ew.fo...@nassur.net> wrote:
> thread hijacked intentionally. > 'Thar be pirates! > > today I spent some time trying to understand the "make-refcard*" > scripts in some detail. > > The script works roughly like this: > > <snip> > - 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. > > Indeed. It also happens to be the reason the perl script works so well, as well as being so easy to break. It's just too rigid. One thing that the original has as well is that the 4th line needs to be the "VE" or "XT" part. If it isn't it will fail. That was the reason for poking around with the 3 prior lines part of the the script and hardwiring it for the first 3 lines. > > Now I could commit Marks patches and not look further. However, there > are several shortcomings with the current state. > > Yeah, don't do that. I really just put up the diff as a reference for someone that knows Perl. At best right now I would say you could replace the very outdated refcard.html with the one my changes generate. It is an improvement just because of the age difference (5.5 to 6.8). For the long term however, this tool needs to either be fixed entirely or replaced with something that the build system can use. Having a refcard generated directly from the source tree is fantastic IMHO. > > - 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. > > This gets to the guts of how to march from here (Google's rendition of the Latin in the title). Each of the flavors could be determined from their location in the source tree. The additional information would have to be added to the hash tables and the generation end would have to be made aware of all this of course. But in those cases it would seem that you would just end up with a mess of duplication. The script would need to determine if something exists already then act accordingly. However, what would be appropriate? How do you deal with differences in the stack effects because of the platform? It seems that the end user would be better served if they could just pull up their flavor of refcard and be done with it. As you mentioned, right now it is the AVR8 refcard. I don't know how different each platform is since I am personally only concerned with the AVR one. But there is of course a wider audience out there and each needs to be dealt with equally. Having individual refcards would seem to align with the way that the website documents already work for the different platforms (sections for linux and windows etc) so that is where I'd cast my vote. > - 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. > > It seems that the intent of the refcard was to document the things that are compiled into the system. Since the Forth source code could be nearly anything AND has to be uploaded after the hex files are uploaded to the device you are now entering into the realm of full generated documentation. In that case it may be better to look into something like Doxygen (or whatever the kids are using these days) and properly generate all that. Of course that would take a one time scouring of all the sources to align with something of that nature. As for the Forth source in the asm file I'm not sure about that. I think I'd rather see the .frt file alongside the .asm file. That is just personal preference though and I can see the value in having them together. It does seem like it could complicate the build and/or uploading process. ;tldnr Perl script needs to be updated entirely by someone fluent. Sources need to be properly commented for the refcard/doc generation. Maybe define the style to be used (indentation, tabs, spaces etc) for the sources. Forth source for all the asm files and maybe even some docs for the rules that go along with that. I did read some things about that in the mailing list like how the first .dw value is created. Is there somewhere that explains the asm file format in more detail or is it just a Forth standard thing? That is probably more than enough for now. I'm willing to help where I can but I think that we will really need a roadmap to head for v6.9 and more importantly v7.0. Otherwise these talks are just coffee before heading back to our own private repos. I guess one can't march until one knows which direction to march in... I'm going swimming now. :) All the best. Mark _______________________________________________ Amforth-devel mailing list for http://amforth.sf.net/ Amforth-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/amforth-devel
