Hello Mark, Erich, AmForthers, Mark - I have chopped and reordered selected parts of your message to form my reply. I hope this is OK.
> It seems that the intent of the refcard was to document the things that > are compiled into the system. +1 For me, the scope of the/each refcard is defined by the distribution build for each architecture (AVR8, msp430, etc.). If the refcard script were part of the hex build process then a custom refcard could be a product of the build process also. > 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. +1 I think AmForth's documentation is very good, but as Mark's draft 6.8+ refcard pointed out to me, there are words I did not know existed. There is more to AmForth than made it to the existing documentation. Complete, exhaustive and automated documentation would clearly be great, but as has already been noted, doing this across AVR8/msp430/risc-v/arm + various assembler formats + common/uncommon Forth is challenging. As previously mentioned, part of the challenge being agreeing on what a refcard should be. My vote would be to 1. Limit the refcard to the words written in assembler that contribute to the distribution build of the hex files. 2. Limit the refcard improvements for AmForth 6.9 to AVR8 only 3. Take this as an opportunity to review the distribution builds for AVR8 (which words to include) and make the existence and location of the hex files more prominent in the documentation. > I think that we will really need a roadmap to head for v6.9 and more > importantly v7.0. I think the distinction between 6.9 and 7.0 is a very helpful one. My opinion is that AVR8 has been and currently is the core platform for AmForth. From the from the mailing list archive it is certainly the one that generates the most activity. Whilst I probably have more than enough AVR8 development boards in the parts box to see out my list of projects, I think Matthias saw a longer term future for AmForth beyond AVR8. Perhaps answers to these two questions go someway towards defining a roadmap for 7.0 1) which, if any, of the other mcus AmForth can run on do AmForthers think is the one to focus on? 2) is there a desire/will for AmForth on AVR8 to be extended to run on newer AVR8 such as the ATMEGA4809[1] ? Best wishes, Tristan [1] http://ww1.microchip.com/downloads/en/DeviceDoc/ATmega4808-09-DataSheet-DS40002173B.pdf On 02Aug20 09:53, Mark Roth wrote: > 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 _______________________________________________ Amforth-devel mailing list for http://amforth.sf.net/ Amforth-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/amforth-devel
