Hello Tristan, Erich and fellow lurking AmForthers (I really do like this intro Tristan) :)
It really does seem that you may have caught the tiger by the tail Tristan. For better or for worse even! For the better (hey, you caught the tiger) : I think your layout really goes a long way toward documenting the used words. The last few days before I saw your mail I had been thinking of this very thing, to use the local build for the refcard. I hadn't, however, seen the obvious which was to use the list file. I used it when I was trying to find what was compiled into the base system and then finding useful assembly files to build into my hex. It's funny how a new set of eyes sees the obvious. Well played indeed. A few things of note from your examples. Since the items will most likely be listed by category the "category:" would be redundant. It also would seem pretty trivial to remove the "C:" or "R:" from the stack effects if they were to be listed in the way you have. It makes it very clear what is going on as well as being consistent. Having the location of the asm file is super. Too many times I'm searching my local system for just that very thing. Of course it is listed in the lst file which makes perfect sense to show it. It could even open the door to having a location to forth source files there as well. It would just be a matter of putting the location in the comments in some way. I know you have shown interest in having that easy to find as well Erich. Perhaps something like that could be a good compromise? I have a file in my appl directory that I use to upload everything I add after burning a new hex into the controller. It is just a list of locations for files that get added after the fact. It would seem that something like this could even be added into the documentation process. Say perhaps, to give an upload file name to the script before running so it could parse out the frt files that will be added after. Of course, that would mean they would have to have some consistent system of comments as well... In any case, it does open that door. And for the worse: This does drastically change what the current refcard is. That is to say, right now it was just a dump of the base system without regard to usage, more to availability. For the website there would have to be cards generated for different architectures and perhaps even NWWR sizes. So, what to do? Maybe the easiest would be to have some generic setups in the appl dir (most likely many already exist) and run the refcard script against them while building for the website (or perhaps even locally, it won't take much time) then using that to create an array of refcards that could be grouped together as web pages. The point is, that amforth.asm will dictate what a more or less default system will be and that can be used for the site. Overall, I really like the direction of this proposal from Tristan. I think it does capture what the refcard should do for the end user. All the best, Mark On Mon, Sep 7, 2020 at 3:00 PM Tristan Williams <h...@tjnw.co.uk> wrote: > Hello Mark, Erich, AmForthers, > > I agreed with Mark's comment below > > >> It seems that the intent of the refcard was to document the things that > >> are compiled into the system. > > and commented > > > 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. > > For AVR8, the .lst file produced as part of the build process lists > all the .asm files used in building the hex files. Modifying Mark's > perl script from > > https://sourceforge.net/p/amforth/mailman/message/37060541/ > > so that it uses only the included files listed in the .lst file, a > list of words with the their documentation fields can output. These > are specific to the individual build, rather than to the general > assembly source tree. Giving something like this (see end of > message). As Mark pointed out > > >> There is still the issue of files that don't have the 3 lines at the top > >> of stack effects, category and description. > > Making these (assembly) files compliant would require some coordinated > effort - some of which has been already done I believe, but after that > a build specific ref card documenting built-in words could just > be another automated part of the hex build process. > > Not perhaps the perfect ref card - whatever that is, but achievable > and with a clearly defined scope. Certainly something I would make use > of. > > Best wishes, > Tristan > > Edited example (text) output of the modified script for uno.lst > > .... > > Arithmetics > ----------- > > VOC : 1- > DSTACK : ( n1 -- n2 ) > RSTACK : > CSTACK : > DESC : optimized decrement > CATEGORY : Arithmetics > ASM_FILE : amforth-6.92/avr8/words/1minus.asm > > VOC : 1+ > DSTACK : ( n1|u1 -- n2|u2 ) > RSTACK : > CSTACK : > DESC : optimized increment > CATEGORY : Arithmetics > ASM_FILE : amforth-6.92/avr8/words/1plus.asm > > VOC : 2/ > DSTACK : ( n1 -- n2 ) > RSTACK : > CSTACK : > DESC : arithmetic shift right > CATEGORY : Arithmetics > ASM_FILE : amforth-6.92/avr8/words/2slash.asm > > > Compiler > -------- > > VOC : 2literal > DSTACK : ( -- x1 x2 ) > RSTACK : > CSTACK : (C: x1 x2 -- ) > DESC : compile a cell pair literal in colon definitions > CATEGORY : Compiler > ASM_FILE : amforth-6.92/common/words/2literal.asm > > VOC : again > DSTACK : ( -- ) > RSTACK : > CSTACK : (C: dest -- ) > DESC : compile a jump back to dest > CATEGORY : Compiler > ASM_FILE : amforth-6.92/common/words/again.asm > > VOC : ahead > DSTACK : ( f -- ) > RSTACK : > CSTACK : (C: -- orig ) > DESC : do a unconditional branch > CATEGORY : Compiler > ASM_FILE : amforth-6.92/common/words/ahead.asm > > .... > > > > > _______________________________________________ > 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
