amforth-devel — Development discussion and user support

[Amforth] List of Supported Device Features in Amforth Documentation?

[<fr...@fr...>]

Hi!


Summary: I believe you could greatly increase the
number of Amforth users with little effort providing
one Wiki page per hardware device. There you would
provide fuse settings, name of a suitable binary,
parameters for the flasher etc. in order to reduce the
frustration of a rookie to see the first Forth prompt.
It's only 20-50 devices, that's not much compared to
the list of devices in Arch Linux for example (I found
my specific laptop model there...).
SourceForge offers a Wiki very suitable for that!


In Detail:

I'm a fellow open source guy, running a project
here on SourceForge for a living:
https://sourceforge.net/projects/project-open/
Also, 30 years ago I wrote a Forth for Inmos
Transputers...


So: Congratulations to your work on Amforth!
I managed to get it running on a barebone AtMega
328 for a hobby project (a tracked robot with my
son...).

I implemented drivers for both stepper motors
and DC motors with angle coders without too much
trouble and to send Forth commands over SPI.

However, I got some trouble trying to connect
multiple 328s to a single RasPi and finally serious
trouble with spikes from the DC motors affecting
the SPI bus :-(

For the next iteration I'd like to decouple the
various I/O subsystems electrically and use UART
over USB for communication in order to address the
issues both with multiple devices (USB hub as PI
HAT) and noise (USB has differential signaling...)

So, I'd like to use a 32U4 or Mega 2560 or similar
for each subsystem and a RasPi Zero W as a base,
but I haven't yet purchased anything.
Here some information on the supported features
would come in handy. I've spent several hours
trying to understand if/how Amforth supports
USB/UART in these model. 6.9 doesn't seem to
support it at all, correct?


There isn't much space in a robot, and USB cables
are surprisingly bulky. And now imagine that I'd
somehow need to have 2x USB for each Atmega...

I wonder if I'm the only one trying to build a more
complex system using Amforth or if others had
similar problems...

I have also found very few postings in the Internet
from people connecting multiple Arduinos to
a RasPI or to build bigger projects in general.
That's precisely where I see the value of Amforth,
because it introduces a protocol layer that is
easy to debug and decouples the subsystems.


Cheers, and keep up the good work!
Frank

Re: [Amforth] [ANN] release 6.9 is available

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

Hello Jim,

Jim Tittsler writes:

> On Mon, Oct 19, 2020 at 2:46 AM Erich Wälde <ew....@na...> wrote:
>> One thing remains: the "download the latest release" Button still
>> points to 6.8 --- I have no idea, where to look. Oh well.
>
> As project administrator, visit
> https://sourceforge.net/projects/amforth/files/amforth/6.9/ then click
> the 'i' (information) button for the desired file.  In addition to the
> normal file details, an administrator can specify a "default download"
> (by platform).

With sufficient thrust, äh javascript and 3rd party connections
and reloading ... yes there are (i) buttons showing up. :)

Thank you very much for pointing me to the correct place!

Cheers,
Erich

-- 
May the Forth be with you ...

Re: [Amforth] [ANN] release 6.9 is available

[Jim T. <jti...@gm...>]

On Mon, Oct 19, 2020 at 2:46 AM Erich Wälde <ew....@na...> wrote:
> One thing remains: the "download the latest release" Button still
> points to 6.8 --- I have no idea, where to look. Oh well.

As project administrator, visit
https://sourceforge.net/projects/amforth/files/amforth/6.9/ then click
the 'i' (information) button for the desired file.  In addition to the
normal file details, an administrator can specify a "default download"
(by platform).

Jim

[Amforth] [ANN] release 6.9 is available

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

Dear AmForthers,

today I called it "release 6.9".

The "commits" part is quite simple.

- r2452 -- only doc/source/index.rst
- r2453 -- copy of trunk as release/6.9
- r2454 -- in trunk increment version strings (3 files)

There is some more work in creating the tar balls.

I have decided to remove the doc/Projects folder from the release
tarballs, because it increases their size from <10 MB to >100 MB.
This is probably the reason why Matthias had the Projects not included
in the archives either.

One thing remains: the "download the latest release" Button still
points to 6.8 --- I have no idea, where to look. Oh well.

This release rolls up everything that had been committed since
2019-01-07.

The website is updated, too.

Happy Forthing!

Erich

-- 
May the Forth be with you ...

Re: [Amforth] Ref Card Generation quo vadis?

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

Dear AmForthers,

I tend to disagree on some of this ...

What you argue for is a "architecture and project-specific"
"reduced" refcard. At least this is, what I understand.


I have used the refcard extensively in the beginnings of my
AmForth journey. And I would argue any time, that the refcard
should please include /all/ /available/ things --- whether or
not they are in my build. This is akin to the "Complete
Instruction Set Summary" found in the document describing the
AVR assembly instructions.

Whether or not a given word is /in my build/ ... " words " to
rescue. Or just trying this /interactively/ on the serial
prompt. Or reading the .lst file from the build (for .asm
definitions).


The examples by Tristan
>> https://tjnw.co.uk//amforth-6.92/appl/arduino/uno.html
>> https://tjnw.co.uk//amforth-6.92/appl/arduino/custom.html
look nice and clean.

However, /I/ did not notice, the words are actually links ---
only after Marks comment. For me attributes like this are pretty
much /invisible/, although they are quite common (They can be
topped by buttons that appear only /after/ I have selected
something -- sigh).


IMHO a worthwhile extension of the refcard would include a
pointer to the source (in readable form), something like

> WORD  ( stack -- effect )
> - one-line-description
> - colon definition equivalent, if the word is in .asm
> - .../path/to/file.frt -- one entry if this is a /common/ .frt file
> - .../path/to/arch/file.asm -- several entries (one per line) if
>   this is a target-specific .asm file

This way it is clear, where to look, if the word is missing in
my build. It even indirectly tells you, on what targets this
WORD is available. And all this information should be visible on
a printed version of the refcard, too.


The pre-made .hex files for the arduino targets are a double
edged sword imho: On one hand they considerably lower the bar to
get to your first AmForth-prompt. On the other hand, they do not
teach users about fuses, about .lst and .map and include files,
etc. This is where the "can we please include words X and Y"-
wishlist comes from. But with pre-made files, users give up
control over their project --- to some extent. I would encourage
everyone get on top of the complete tool chain immediately after
the first pre-made file runs successfully.


But lets assume for this paragraph we want these "target and
build specific" refcards (which formats is another question
imho). How are we going about them? Is their production included
in the project Makefile? Are they produced by /every/ build? How
long does that take and what would be an acceptable time? And
how much tools do we add as a dependency?

The minimal toolchain is already substantial (from my Linux
centric point of view):

- the sources (via tarball, subversion/git, ...)
- the assembler (AvrAsm2 plus wine, unfortunately)
- an editor (/any!/)
- make to help with the build (could be done with shell commands
  in principle)
- a programmer (hardware)
- a program to talk to the programmer (avrdude or similar)
- a serial cable of some sort (hardware)
- a program to talk to the serial interface (minicom et al.,
  amforth-upload.py, amforth-shell.py)
- possibly some programm (evince, xpdf, ...) to read the
  documentation offline.

Even if we produce the refcard using an upgraded perl script,
imho this is going the wrong way.



One other thing I find interesting to note in this lengthy
thread: So far we have only looked at

"How to generate the documentation from the sources?"

But there is another option:

"How to generate the source from a (large) description of the
whole system?"

This is called "literate programming", as everyone and their dog
knows, of course :-)

I envision something like "every word has a description,
including any reasoning why it is implemented in such a way,
plus a description of the source code in some form. From this
description a .frt and/or .asm (variable asm formats)" is
generated, along with the Technical Handbook, the RefCard and
what not.

HOWEVER! I have tried to produce code like this. This is a not
so modest pain up the backside for a project, which is on the
move, which is not fully implemented. Literate Programming alone
is unable to track the evolution of the code, unless you rewrite
the description every time. I still think there is value to this
idea, but it is not the one answer to rule all questions.

I will not even try to convert AmForth to such a structure,
because it requires a lot of work PLUS an even larger tool
chain. :-)


Too Long; Didn't Read:

- I argue for a full refcard, not a reduced one
- I argue for a bit more information on the refcard
- I argue against pre-made .hex files
- I argue for less dependencies
- I do not argue for "produce the code from documentation" :-)

- my current priority is "how to make a release". And I'm not
  there yet.

- I'm willing to accept patches fixing the headers of .asm
  files.

- I'm willing to rewrite the refcard scripts, since I still use
  perl for my own stuff, too.


Thank you for your precious time!

Happy häcking!
Erich

PS: I'm very uneasy about the "answer above the thread text"
format. But I didn't see a convincing "merged form".

Mark Roth writes:

> Hello Tristan, Erich and AmForthers around the world.
>
> Tristan, I really like the direction you have gone in. Coupling the build
> process with the local refcard really is a solution that I can put my
> support behind. When push comes to shove what really matters to the end
> user? The words that have been installed into their system. From what I can
> see, it just works. AHHH and I just noticed that you linked the names to
> the source file. That is the solution to having the info you might need
> easy to find. Super.
>
> Since the build process would create individual refcards, it would just be
> a matter of making group of refcards based on the builds. But that begs
> the question of what other platforms is AmForth being used on? Is it enough
> to just make a project that loads every single common and avr8 file and use
> that for the website. I think maybe yes. Sort of the one refcard to rule
> them all.
>
> In any case, I really like what you've done so far Tristan. It is a big
> improvement upon the oundated version. Cleaning up the source to give a
> better card will be a minor issue in the long run since it will only have
> to be done once. When it is done locally during the build, the created html
> file should be dumped somewhere convenient, perhaps even in the build
> directory so one could just click on it to load it into a browser.
>
> All the best,
> Mark
>
> On Sat, Sep 19, 2020 at 6:30 PM Tristan Williams <ho...@tj...> wrote:
>
>> Hello Mark, Erich, AmForthers,
>>
>> I made some more modifications to the perl reference card script so
>> that it will write out an AVR8 build specific reference card in
>> html. Below are example outputs for the stock UNO build and
>> a custom build
>>
>> https://tjnw.co.uk//amforth-6.92/appl/arduino/uno.html
>> https://tjnw.co.uk//amforth-6.92/appl/arduino/custom.html
>>
>> The issues relating to the presence and correctness of the
>> documentation in the .asm files still remain.
>>
>> Best wishes,
>> Tristan
>>
>> On 09Sep20 08:38, Tristan Williams wrote:
>> > Hello Mark, Erich, AmForthers,
>> >
>> > Yes, I completely agree the format of my refcard excerpt has some
>> > issues. I just wanted to show that, with the hard work done by the
>> > perl script, all of the documentation data fields for AVR8 built-in
>> > words with compliant doc headers are readily available for
>> > output using the .lst file. That data could be formatted as desired
>> > and then written out in html, rst, LaTeX, Lout, etc.
>> >
>> > For the above to be useful, the .asm source files need to have
>> > compliant (and correct) doc headers. Lots of files are, but sufficient
>> > are not that some coordinated way of doing this is needed.
>> >
>> > How is this best done?
>> >
>> > Part of my motivation for pursuing this is that I think there is some
>> > value in having "fuller" pre-built AVR8 hex files in the distribution
>> > and giving them greater prominence in the documentation[1]. A build
>> > specific reference card would be helpful in such cases and it ought to
>> > be created by the same process that creates the hex files. Whilst I
>> > agree with [2] that it would be impractical to build hex files for an
>> > extensive combinations of clock frequency/mcu/baud rate, appl/arduino
>> > already exists and caters for arguably the most popular AVR8
>> > development boards plus a few other interesting ones - perhaps ~6
>> > pairs of hex files in total. Adding assembler words such as bm-set,
>> > bm-clear, bm-toggle, sleep, spirw, store-wdc etc. to the default build
>> > for these larger flash devices would just make the default build more
>> > useful.
>> >
>> > > 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.
>> >
>> > It does not have to be a replacement, just something that I think fits
>> > well with "fuller" pre-built AVR8 hex files and I see as achievable.
>> >
>> > > For the website there would have to be cards generated for different
>> > > architectures and perhaps even NWWR sizes. So, what to do?
>> >
>> > Limiting this to AVR8 and those boards that already are in
>> > appl/arduino (or perhaps should be) etc. makes it simpler.
>> >
>> > For existing non AVR8 pre-built hex/binary then having a matching
>> > refcard would make sense. However, I don't know enough about the details
>> > of the non AVR8 build process to say whether the same approach would
>> > work. Also risc-v/words/1-minus.s does not use the same doc headers as
>> > avr8/words/1minus.asm which suggests problems.
>> >
>> > > 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.
>> >
>> > Yes, I would agree - with board level customisation in uno.asm etc as
>> > it is currently. A refcard reflecting the built-in words of hex file
>> > created, be that built locally or pre-built on the website.
>> >
>> > With the current AmForth and AVR8 it is likely the built-in refcards for
>> > appl/arduino boards would be very similar - if not identical.
>> >
>> > So for an AVR8 builtin-ref card I think this is needed
>> >
>> > 1. Compliant doc headers for all the .asm files
>> > 2. Modify the perl script to write out refcard as desired in the desired
>> formats
>> > 3. Connect this to the build system
>> > 4. Connect the pre-built hex files and their refcards to the main
>> documentation
>> >
>> > All can be done for a local build setup, but most value would be with
>> > 1 and 4 done at the distribution/website level.
>> >
>> > Best wishes,
>> > Tristan
>> >
>> > [1] https://sourceforge.net/p/amforth/mailman/message/37054617/
>> > [2]
>> http://amforth.sourceforge.net/faq.html#there-are-no-hexfiles-in-the-distribution-archive
>> >
>> >
>> > On 08Sep20 13:14, Mark Roth wrote:
>> > > 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 <ho...@tj...>
>> 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
>> > > >
>> > > > ....
>> > > >
>> > > >
>> > > >
>> > > >


-- 
May the Forth be with you ...

Re: [Amforth] [Solved] @ vs c@ (was: rshift not zero padded)

[Mark R. <cab...@gm...>]

Hello Erich,

so you found the subtle difference between @ and c@, congrats! :-)
>
> Mark Roth writes:
> > So because of grabbing a word it seems that I was bringing in the PINB
> > register as well that had a value in it. So that is where the extra bits
> > came from.
>

Yeah that was just a rookie error there. I had it so stuck in my head that
the port register was 8 bits, where could the rest possibly be coming from?
Of course it grabbed it's neighbor. That was what I told it to do. It was a
good lesson about words though.

Numbers: Over time I have adopted the style to prefix each and
> every number except for 0 and 1. I have been in the situation
> too often, that base was not 10 like expected but rather 16.
>
> >: cylon
> >     $ff ddra c! 1 porta c!
> >     begin #40 ms
> >         #7 0 do porta c@ 2* porta c! #40 ms loop
> >         #7 0 do porta c@ 2/ porta c! #40 ms loop
> >     key? until ;
>
>
This is good advice and serves to document in place just what you wanted
for when you have to come back to it. I'll have to try that from now on.
Thanks! I was going to add that perhaps I'll only do it with 2 digit
numbers, but it occured to me that you do it with anything higher than 1 so
that if the base is set to BIN your code could never accidentally choke.

>

> Cheers,
> Erich
> --
> May the Forth be with you ...
>

Slowly, ever so slowly it is. Since my son was playing along as well and
wanted to change the speeds we made a few modifications. With your other
advice and an added safety catch so we wouldn't have to reset so often. The
binary representations of the port values were to show him exactly what we
were doing. All in all a bit of learning all around.

: cy-delay    ( n -- n )
    dup ms
;

: cylon    ( n -- )
    depth if
        %11111111 ddra c!  %00000001 porta c!
        begin
            #7 0 do porta c@ 2* porta c! cy-delay loop
            #7 0 do porta c@ 2/  porta c! cy-delay loop
        key? until drop %00000000 porta c!
    then
;

Now to make it smarter so it reverses when it hits the endstops. We are
following along with the Junk Box Arduino stuff since the projects are
pretty simple and make a nice bridge from C to Forth.

All the best,
Mark

[Amforth] [Solved] @ vs c@ (was: rshift not zero padded)

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

Hello Mark,

so you found the subtle difference between @ and c@, congrats! :-)

Mark Roth writes:

> So because of grabbing a word it seems that I was bringing in the PINB
> register as well that had a value in it. So that is where the extra bits
> came from.
>
> : cylon
>>     $ff ddra c! 1 porta c!
>>     begin 40 ms
>>         7 0 do porta c@ 2* porta c! 40 ms loop
>>         7 0 do porta c@ 2/ porta c! 40 ms loop
>>     key? until ;
>
>
> So this works exactly as I wanted it to. I am really starting to understand
> the value of interactive debugging by just running each line to see what is
> going on. Once I looked at the stack while stepping it made
> perfect sense.


Numbers: Over time I have adopted the style to prefix each and
every number except for 0 and 1. I have been in the situation
too often, that base was not 10 like expected but rather 16.

>: cylon
>     $ff ddra c! 1 porta c!
>     begin #40 ms
>         #7 0 do porta c@ 2* porta c! #40 ms loop
>         #7 0 do porta c@ 2/ porta c! #40 ms loop
>     key? until ;


Number output

>> It's a common display situation in Forth. Leading zeros aren't display,
>> even when they exist.

/Very often/ I use " u0.r " for exactly this reason.


Cheers,
Erich



-- 
May the Forth be with you ...

Re: [Amforth] Ref Card Generation quo vadis?

[Mark R. <cab...@gm...>]

Hello Tristan, Erich and AmForthers around the world.

Tristan, I really like the direction you have gone in. Coupling the build
process with the local refcard really is a solution that I can put my
support behind. When push comes to shove what really matters to the end
user? The words that have been installed into their system. From what I can
see, it just works. AHHH and I just noticed that you linked the names to
the source file. That is the solution to having the info you might need
easy to find. Super.

Since the build process would create individual refcards, it would just be
a matter of making group of refcards based on the builds. But that begs
the question of what other platforms is AmForth being used on? Is it enough
to just make a project that loads every single common and avr8 file and use
that for the website. I think maybe yes. Sort of the one refcard to rule
them all.

In any case, I really like what you've done so far Tristan. It is a big
improvement upon the oundated version. Cleaning up the source to give a
better card will be a minor issue in the long run since it will only have
to be done once. When it is done locally during the build, the created html
file should be dumped somewhere convenient, perhaps even in the build
directory so one could just click on it to load it into a browser.

All the best,
Mark

On Sat, Sep 19, 2020 at 6:30 PM Tristan Williams <ho...@tj...> wrote:

> Hello Mark, Erich, AmForthers,
>
> I made some more modifications to the perl reference card script so
> that it will write out an AVR8 build specific reference card in
> html. Below are example outputs for the stock UNO build and
> a custom build
>
> https://tjnw.co.uk//amforth-6.92/appl/arduino/uno.html
> https://tjnw.co.uk//amforth-6.92/appl/arduino/custom.html
>
> The issues relating to the presence and correctness of the
> documentation in the .asm files still remain.
>
> Best wishes,
> Tristan
>
> On 09Sep20 08:38, Tristan Williams wrote:
> > Hello Mark, Erich, AmForthers,
> >
> > Yes, I completely agree the format of my refcard excerpt has some
> > issues. I just wanted to show that, with the hard work done by the
> > perl script, all of the documentation data fields for AVR8 built-in
> > words with compliant doc headers are readily available for
> > output using the .lst file. That data could be formatted as desired
> > and then written out in html, rst, LaTeX, Lout, etc.
> >
> > For the above to be useful, the .asm source files need to have
> > compliant (and correct) doc headers. Lots of files are, but sufficient
> > are not that some coordinated way of doing this is needed.
> >
> > How is this best done?
> >
> > Part of my motivation for pursuing this is that I think there is some
> > value in having "fuller" pre-built AVR8 hex files in the distribution
> > and giving them greater prominence in the documentation[1]. A build
> > specific reference card would be helpful in such cases and it ought to
> > be created by the same process that creates the hex files. Whilst I
> > agree with [2] that it would be impractical to build hex files for an
> > extensive combinations of clock frequency/mcu/baud rate, appl/arduino
> > already exists and caters for arguably the most popular AVR8
> > development boards plus a few other interesting ones - perhaps ~6
> > pairs of hex files in total. Adding assembler words such as bm-set,
> > bm-clear, bm-toggle, sleep, spirw, store-wdc etc. to the default build
> > for these larger flash devices would just make the default build more
> > useful.
> >
> > > 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.
> >
> > It does not have to be a replacement, just something that I think fits
> > well with "fuller" pre-built AVR8 hex files and I see as achievable.
> >
> > > For the website there would have to be cards generated for different
> > > architectures and perhaps even NWWR sizes. So, what to do?
> >
> > Limiting this to AVR8 and those boards that already are in
> > appl/arduino (or perhaps should be) etc. makes it simpler.
> >
> > For existing non AVR8 pre-built hex/binary then having a matching
> > refcard would make sense. However, I don't know enough about the details
> > of the non AVR8 build process to say whether the same approach would
> > work. Also risc-v/words/1-minus.s does not use the same doc headers as
> > avr8/words/1minus.asm which suggests problems.
> >
> > > 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.
> >
> > Yes, I would agree - with board level customisation in uno.asm etc as
> > it is currently. A refcard reflecting the built-in words of hex file
> > created, be that built locally or pre-built on the website.
> >
> > With the current AmForth and AVR8 it is likely the built-in refcards for
> > appl/arduino boards would be very similar - if not identical.
> >
> > So for an AVR8 builtin-ref card I think this is needed
> >
> > 1. Compliant doc headers for all the .asm files
> > 2. Modify the perl script to write out refcard as desired in the desired
> formats
> > 3. Connect this to the build system
> > 4. Connect the pre-built hex files and their refcards to the main
> documentation
> >
> > All can be done for a local build setup, but most value would be with
> > 1 and 4 done at the distribution/website level.
> >
> > Best wishes,
> > Tristan
> >
> > [1] https://sourceforge.net/p/amforth/mailman/message/37054617/
> > [2]
> http://amforth.sourceforge.net/faq.html#there-are-no-hexfiles-in-the-distribution-archive
> >
> >
> > On 08Sep20 13:14, Mark Roth wrote:
> > > 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 <ho...@tj...>
> 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/
> > > > Amf...@li...
> > > > https://lists.sourceforge.net/lists/listinfo/amforth-devel
> > > >
> > >
> > > _______________________________________________
> > > Amforth-devel mailing list for http://amforth.sf.net/
> > > Amf...@li...
> > > https://lists.sourceforge.net/lists/listinfo/amforth-devel
> > >
> >
> >
> > _______________________________________________
> > Amforth-devel mailing list for http://amforth.sf.net/
> > Amf...@li...
> > https://lists.sourceforge.net/lists/listinfo/amforth-devel
> >
>
>
> _______________________________________________
> Amforth-devel mailing list for http://amforth.sf.net/
> Amf...@li...
> https://lists.sourceforge.net/lists/listinfo/amforth-devel
>

Re: [Amforth] Ref Card Generation quo vadis?

[Tristan W. <ho...@tj...>]

Hello Mark, Erich, AmForthers,

I made some more modifications to the perl reference card script so
that it will write out an AVR8 build specific reference card in
html. Below are example outputs for the stock UNO build and
a custom build

https://tjnw.co.uk//amforth-6.92/appl/arduino/uno.html
https://tjnw.co.uk//amforth-6.92/appl/arduino/custom.html

The issues relating to the presence and correctness of the
documentation in the .asm files still remain. 

Best wishes,
Tristan

On 09Sep20 08:38, Tristan Williams wrote:
> Hello Mark, Erich, AmForthers,
> 
> Yes, I completely agree the format of my refcard excerpt has some
> issues. I just wanted to show that, with the hard work done by the
> perl script, all of the documentation data fields for AVR8 built-in
> words with compliant doc headers are readily available for
> output using the .lst file. That data could be formatted as desired
> and then written out in html, rst, LaTeX, Lout, etc. 
> 
> For the above to be useful, the .asm source files need to have
> compliant (and correct) doc headers. Lots of files are, but sufficient
> are not that some coordinated way of doing this is needed.
> 
> How is this best done?
> 
> Part of my motivation for pursuing this is that I think there is some
> value in having "fuller" pre-built AVR8 hex files in the distribution
> and giving them greater prominence in the documentation[1]. A build
> specific reference card would be helpful in such cases and it ought to
> be created by the same process that creates the hex files. Whilst I
> agree with [2] that it would be impractical to build hex files for an
> extensive combinations of clock frequency/mcu/baud rate, appl/arduino
> already exists and caters for arguably the most popular AVR8
> development boards plus a few other interesting ones - perhaps ~6
> pairs of hex files in total. Adding assembler words such as bm-set,
> bm-clear, bm-toggle, sleep, spirw, store-wdc etc. to the default build
> for these larger flash devices would just make the default build more
> useful. 
> 
> > 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.
> 
> It does not have to be a replacement, just something that I think fits
> well with "fuller" pre-built AVR8 hex files and I see as achievable. 
> 
> > For the website there would have to be cards generated for different
> > architectures and perhaps even NWWR sizes. So, what to do?
> 
> Limiting this to AVR8 and those boards that already are in
> appl/arduino (or perhaps should be) etc. makes it simpler. 
> 
> For existing non AVR8 pre-built hex/binary then having a matching
> refcard would make sense. However, I don't know enough about the details
> of the non AVR8 build process to say whether the same approach would
> work. Also risc-v/words/1-minus.s does not use the same doc headers as
> avr8/words/1minus.asm which suggests problems.
> 
> > 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.
> 
> Yes, I would agree - with board level customisation in uno.asm etc as
> it is currently. A refcard reflecting the built-in words of hex file
> created, be that built locally or pre-built on the website.
> 
> With the current AmForth and AVR8 it is likely the built-in refcards for
> appl/arduino boards would be very similar - if not identical. 
> 
> So for an AVR8 builtin-ref card I think this is needed
> 
> 1. Compliant doc headers for all the .asm files
> 2. Modify the perl script to write out refcard as desired in the desired formats
> 3. Connect this to the build system
> 4. Connect the pre-built hex files and their refcards to the main documentation
> 
> All can be done for a local build setup, but most value would be with
> 1 and 4 done at the distribution/website level.  
> 
> Best wishes,
> Tristan
> 
> [1] https://sourceforge.net/p/amforth/mailman/message/37054617/
> [2] http://amforth.sourceforge.net/faq.html#there-are-no-hexfiles-in-the-distribution-archive
> 
> 
> On 08Sep20 13:14, Mark Roth wrote:
> > 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 <ho...@tj...> 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/
> > > Amf...@li...
> > > https://lists.sourceforge.net/lists/listinfo/amforth-devel
> > >
> > 
> > _______________________________________________
> > Amforth-devel mailing list for http://amforth.sf.net/
> > Amf...@li...
> > https://lists.sourceforge.net/lists/listinfo/amforth-devel
> > 
> 
> 
> _______________________________________________
> Amforth-devel mailing list for http://amforth.sf.net/
> Amf...@li...
> https://lists.sourceforge.net/lists/listinfo/amforth-devel
> 

Re: [Amforth] rshift not zero padded

[Mark R. <cab...@gm...>]

So because of grabbing a word it seems that I was bringing in the PINB
register as well that had a value in it. So that is where the extra bits
came from.

: cylon
>     $ff ddra c! 1 porta c!
>     begin 40 ms
>         7 0 do porta c@ 2* porta c! 40 ms loop
>         7 0 do porta c@ 2/ porta c! 40 ms loop
>     key? until ;


So this works exactly as I wanted it to. I am really starting to understand
the value of interactive debugging by just running each line to see what is
going on. Once I looked at the stack while stepping it made perfect sense.

All the best,
Mark

On Sat, Sep 19, 2020 at 9:55 AM George Herzog <jac...@gm...>
wrote:

> It's a common display situation in Forth. Leading zeros aren't display,
> even when they exist.
>
> On Sat, Sep 19, 2020, 2:24 AM Mark Roth <cab...@gm...> wrote:
>
> > Is there a reason that when using rshift or 2/ the most significant bit
> > isn't zero padded? lshift and 2* do this correctly. I was trying to
> > implement a simple back and forth led on a port by starting with a value
> of
> > 1 in the the port. Moving from right to left in the port works perfectly
> > but when moving from left to right using either rshift or 2/ every other
> > bit is set high so after a couple of back and forths the port is filled
> > with 1s.
> >
> > I can see that the lshift says it is zero padded but the rshift doesn't
> say
> > that it is. Is there a reason for this? The 2012 specs seem to say that
> > rshift is zero padded as well.
> > http://lars.nocrew.org/forth2012/core/RSHIFT.html
> >
> > Perhaps it's just my noob code that is the problem.
> >
> > : cylon
> > >     $ff ddra ! 1 porta !
> > >     begin 40 ms
> > >         8 0 do porta @ 2* porta ! 40 ms loop
> > >         8 0 do porta @ 2/ porta ! 40 ms loop
> > >     key? until ;
> >
> >
> > It appears to work correctly in one direction but not the other.
> >
> > Thanks,
> > Mark
> >
> > _______________________________________________
> > Amforth-devel mailing list for http://amforth.sf.net/
> > Amf...@li...
> > https://lists.sourceforge.net/lists/listinfo/amforth-devel
> >
>
> _______________________________________________
> Amforth-devel mailing list for http://amforth.sf.net/
> Amf...@li...
> https://lists.sourceforge.net/lists/listinfo/amforth-devel
>

Re: [Amforth] rshift not zero padded

[Mark R. <cab...@gm...>]

Okay, hmm. It seems to be because even when I store a value of $80 in
PORTA, if I read it right back like that I'm getting a word. Which is
actually what I'm asking it for by using @. So I would read back $ED80.
Changing it to use the byte size  c* and c! was the problem there.

Thanks,
Mark

On Sat, Sep 19, 2020 at 9:55 AM George Herzog <jac...@gm...>
wrote:

> It's a common display situation in Forth. Leading zeros aren't display,
> even when they exist.
>
> On Sat, Sep 19, 2020, 2:24 AM Mark Roth <cab...@gm...> wrote:
>
> > Is there a reason that when using rshift or 2/ the most significant bit
> > isn't zero padded? lshift and 2* do this correctly. I was trying to
> > implement a simple back and forth led on a port by starting with a value
> of
> > 1 in the the port. Moving from right to left in the port works perfectly
> > but when moving from left to right using either rshift or 2/ every other
> > bit is set high so after a couple of back and forths the port is filled
> > with 1s.
> >
> > I can see that the lshift says it is zero padded but the rshift doesn't
> say
> > that it is. Is there a reason for this? The 2012 specs seem to say that
> > rshift is zero padded as well.
> > http://lars.nocrew.org/forth2012/core/RSHIFT.html
> >
> > Perhaps it's just my noob code that is the problem.
> >
> > : cylon
> > >     $ff ddra ! 1 porta !
> > >     begin 40 ms
> > >         8 0 do porta @ 2* porta ! 40 ms loop
> > >         8 0 do porta @ 2/ porta ! 40 ms loop
> > >     key? until ;
> >
> >
> > It appears to work correctly in one direction but not the other.
> >
> > Thanks,
> > Mark
> >
> > _______________________________________________
> > Amforth-devel mailing list for http://amforth.sf.net/
> > Amf...@li...
> > https://lists.sourceforge.net/lists/listinfo/amforth-devel
> >
>
> _______________________________________________
> Amforth-devel mailing list for http://amforth.sf.net/
> Amf...@li...
> https://lists.sourceforge.net/lists/listinfo/amforth-devel
>

Re: [Amforth] rshift not zero padded

[George H. <jac...@gm...>]

It's a common display situation in Forth. Leading zeros aren't display,
even when they exist.

On Sat, Sep 19, 2020, 2:24 AM Mark Roth <cab...@gm...> wrote:

> Is there a reason that when using rshift or 2/ the most significant bit
> isn't zero padded? lshift and 2* do this correctly. I was trying to
> implement a simple back and forth led on a port by starting with a value of
> 1 in the the port. Moving from right to left in the port works perfectly
> but when moving from left to right using either rshift or 2/ every other
> bit is set high so after a couple of back and forths the port is filled
> with 1s.
>
> I can see that the lshift says it is zero padded but the rshift doesn't say
> that it is. Is there a reason for this? The 2012 specs seem to say that
> rshift is zero padded as well.
> http://lars.nocrew.org/forth2012/core/RSHIFT.html
>
> Perhaps it's just my noob code that is the problem.
>
> : cylon
> >     $ff ddra ! 1 porta !
> >     begin 40 ms
> >         8 0 do porta @ 2* porta ! 40 ms loop
> >         8 0 do porta @ 2/ porta ! 40 ms loop
> >     key? until ;
>
>
> It appears to work correctly in one direction but not the other.
>
> Thanks,
> Mark
>
> _______________________________________________
> Amforth-devel mailing list for http://amforth.sf.net/
> Amf...@li...
> https://lists.sourceforge.net/lists/listinfo/amforth-devel
>

Re: [Amforth] rshift not zero padded

[tur b. <mai...@gm...>]

If you are trying to make a led version of a cylons eyes a delay shift or
using pwm will always result in a led coming on when not wanted. To
overcome this you need to use Mirror Imaged Bit Angle Modulation to get the
fading and reverse direction to run smoothly

On Fri, 18 Sep 2020 19:24 Mark Roth, <cab...@gm...> wrote:

> Is there a reason that when using rshift or 2/ the most significant bit
> isn't zero padded? lshift and 2* do this correctly. I was trying to
> implement a simple back and forth led on a port by starting with a value of
> 1 in the the port. Moving from right to left in the port works perfectly
> but when moving from left to right using either rshift or 2/ every other
> bit is set high so after a couple of back and forths the port is filled
> with 1s.
>
> I can see that the lshift says it is zero padded but the rshift doesn't say
> that it is. Is there a reason for this? The 2012 specs seem to say that
> rshift is zero padded as well.
> http://lars.nocrew.org/forth2012/core/RSHIFT.html
>
> Perhaps it's just my noob code that is the problem.
>
> : cylon
> >     $ff ddra ! 1 porta !
> >     begin 40 ms
> >         8 0 do porta @ 2* porta ! 40 ms loop
> >         8 0 do porta @ 2/ porta ! 40 ms loop
> >     key? until ;
>
>
> It appears to work correctly in one direction but not the other.
>
> Thanks,
> Mark
>
> _______________________________________________
> Amforth-devel mailing list for http://amforth.sf.net/
> Amf...@li...
> https://lists.sourceforge.net/lists/listinfo/amforth-devel
>

[Amforth] rshift not zero padded

[Mark R. <cab...@gm...>]

Is there a reason that when using rshift or 2/ the most significant bit
isn't zero padded? lshift and 2* do this correctly. I was trying to
implement a simple back and forth led on a port by starting with a value of
1 in the the port. Moving from right to left in the port works perfectly
but when moving from left to right using either rshift or 2/ every other
bit is set high so after a couple of back and forths the port is filled
with 1s.

I can see that the lshift says it is zero padded but the rshift doesn't say
that it is. Is there a reason for this? The 2012 specs seem to say that
rshift is zero padded as well.
http://lars.nocrew.org/forth2012/core/RSHIFT.html

Perhaps it's just my noob code that is the problem.

: cylon
>     $ff ddra ! 1 porta !
>     begin 40 ms
>         8 0 do porta @ 2* porta ! 40 ms loop
>         8 0 do porta @ 2/ porta ! 40 ms loop
>     key? until ;


It appears to work correctly in one direction but not the other.

Thanks,
Mark

Re: [Amforth] Ref Card Generation quo vadis?

[Tristan W. <ho...@tj...>]

Hello Mark, Erich, AmForthers,

Yes, I completely agree the format of my refcard excerpt has some
issues. I just wanted to show that, with the hard work done by the
perl script, all of the documentation data fields for AVR8 built-in
words with compliant doc headers are readily available for
output using the .lst file. That data could be formatted as desired
and then written out in html, rst, LaTeX, Lout, etc. 

For the above to be useful, the .asm source files need to have
compliant (and correct) doc headers. Lots of files are, but sufficient
are not that some coordinated way of doing this is needed.

How is this best done?

Part of my motivation for pursuing this is that I think there is some
value in having "fuller" pre-built AVR8 hex files in the distribution
and giving them greater prominence in the documentation[1]. A build
specific reference card would be helpful in such cases and it ought to
be created by the same process that creates the hex files. Whilst I
agree with [2] that it would be impractical to build hex files for an
extensive combinations of clock frequency/mcu/baud rate, appl/arduino
already exists and caters for arguably the most popular AVR8
development boards plus a few other interesting ones - perhaps ~6
pairs of hex files in total. Adding assembler words such as bm-set,
bm-clear, bm-toggle, sleep, spirw, store-wdc etc. to the default build
for these larger flash devices would just make the default build more
useful. 

> 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.

It does not have to be a replacement, just something that I think fits
well with "fuller" pre-built AVR8 hex files and I see as achievable. 

> For the website there would have to be cards generated for different
> architectures and perhaps even NWWR sizes. So, what to do?

Limiting this to AVR8 and those boards that already are in
appl/arduino (or perhaps should be) etc. makes it simpler. 

For existing non AVR8 pre-built hex/binary then having a matching
refcard would make sense. However, I don't know enough about the details
of the non AVR8 build process to say whether the same approach would
work. Also risc-v/words/1-minus.s does not use the same doc headers as
avr8/words/1minus.asm which suggests problems.

> 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.

Yes, I would agree - with board level customisation in uno.asm etc as
it is currently. A refcard reflecting the built-in words of hex file
created, be that built locally or pre-built on the website.

With the current AmForth and AVR8 it is likely the built-in refcards for
appl/arduino boards would be very similar - if not identical. 

So for an AVR8 builtin-ref card I think this is needed

1. Compliant doc headers for all the .asm files
2. Modify the perl script to write out refcard as desired in the desired formats
3. Connect this to the build system
4. Connect the pre-built hex files and their refcards to the main documentation

All can be done for a local build setup, but most value would be with
1 and 4 done at the distribution/website level.  

Best wishes,
Tristan

[1] https://sourceforge.net/p/amforth/mailman/message/37054617/
[2] http://amforth.sourceforge.net/faq.html#there-are-no-hexfiles-in-the-distribution-archive


On 08Sep20 13:14, Mark Roth wrote:
> 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 <ho...@tj...> 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/
> > Amf...@li...
> > https://lists.sourceforge.net/lists/listinfo/amforth-devel
> >
> 
> _______________________________________________
> Amforth-devel mailing list for http://amforth.sf.net/
> Amf...@li...
> https://lists.sourceforge.net/lists/listinfo/amforth-devel
> 

Re: [Amforth] Ref Card Generation quo vadis?

[Mark R. <cab...@gm...>]

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 <ho...@tj...> 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/
> Amf...@li...
> https://lists.sourceforge.net/lists/listinfo/amforth-devel
>

Re: [Amforth] Ref Card Generation quo vadis?

[Tristan W. <ho...@tj...>]

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

....

Re: [Amforth] AmForth Weekend 3 + Leonardo

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

resend to list.

Hello Tristan,

thank you indeed for pointing this out!


> Erich Wälde writes:
>> Tristan Williams writes:
>>> Erich Wälde writes:
>>> After that all the remaining hex files could be built.
>>> ONLY arduino/leonardo.hex is missing.
>>
>> I am not sure if the Leonardo was excluded because AmForth cannot make
>> use the of the Leonardo's USB connection, but it builds without error
>> on r2450.
> Aha, good to know. I admit that I did not read all error
> messages. Something in my environment could /easily/ be ...
> well, /customized/ :-)
>
> I'll have another look.

This is funny, but highly unobvious:

Turns out that my collection of Atmel/AvrAssembler2/Appnotes/*
files was so stone-age outdated, that the file for atmega32u4
was there but not good enough!

I replaced them with the content of the Archive found at
https://sourceforge.net/projects/amforth/files/Atmel-AVR8-Assembler/Atmel-Assembler.tgz/download
and hey presto! leonardo builds now without a hitch!


So, I have to inspect the box with the arduino boards ... no,
unfortunately no leonardo in the box. But I did find the
butterfly.

Off to new time sinking adventures!

Cheers,
Erich

PS: so yes, I'm able to build the hexfiles found in the release
archives. One off the list.

Re: [Amforth] Gory Details: How to properly create a release?

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

Hello Brian,

after the stunt getting leonardo to build a similar stunt makes
the butterfly building again :-)

> Erich Wälde writes:
>> Brian writes:
>> I am running the latest version of amforth on an avrbutterfly.
>
> Oh, cool! You made me curious. This is a atmega169 controller
> featuring 16k flash, so it is possible. I still have such a
> thing in a box, so I should be able to recreate it.

In my /outdated/ version of the Atmel files, there is
the file "m169def.inc".

In the /new/ version of the Atmel files from the archive found
here
https://sourceforge.net/projects/amforth/files/Atmel-AVR8-Assembler/Atmel-Assembler.tgz/download
this file is unfortunately missing! So I just copied

m169def.inc (note there is no A P PA in this game!)

over to the new tree and the file for the butterfly can be
built! Yay! I have not yet tried to run it on the board.

If it works, I'm going to
- add "m169def.inc" to Atmel-Assembler.tgz (provided I can
  figure out how to place this file in the correct location)
- add avr-butterfly back to appl/
- fix the Makefile in there


This still applies:
>
> Would you care to share your application? Something like a
> nametag maybe???

I'm aware that there is a description, how to use the LCDisplay
in Vierte Dimension 2007/1 (german text)
https://forth-ev.de/wiki/res/lib/exe/fetch.php/vd-archiv:4d2007-01.pdf


Thank you very much for pointing this out!

Cheers,
Erich

>snip<


-- 
May the Forth be with you ...

Re: [Amforth] AmForth Weekend 3 + Leonardo

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

Hello Tristan,

thanks for your message.

Tristan Williams writes:

> Hello Erich, AmForthers,
>
>> After that all the remaining hex files could be built.
>> ONLY arduino/leonardo.hex is missing.
>
> I am not sure if the Leonardo was excluded because AmForth cannot make
> use the of the Leonardo's USB connection, but it builds without error
> on r2450.
Aha, good to know. I admit that I did not read all error
messages. Something in my environment could /easily/ be ...
well, /customized/ :-)

I'll have another look.

Cheers,
Erich

> I have not tested r2450 on a device as I don't have my Leonardo
> to hand, but for reference, it ran on a Leonardo with AmForth 6.8
>
> https://sourceforge.net/p/amforth/mailman/message/36608525/
>
> Best wishes,
> Tristan
>
>
> _______________________________________________
> Amforth-devel mailing list for http://amforth.sf.net/
> Amf...@li...
> https://lists.sourceforge.net/lists/listinfo/amforth-devel


-- 
May the Forth be with you ...

Re: [Amforth] AmForth Weekend 3 + Leonardo

[Tristan W. <ho...@tj...>]

Hello Erich, AmForthers,

> After that all the remaining hex files could be built.
> ONLY arduino/leonardo.hex is missing.

I am not sure if the Leonardo was excluded because AmForth cannot make
use the of the Leonardo's USB connection, but it builds without error
on r2450. I have not tested r2450 on a device as I don't have my Leonardo
to hand, but for reference, it ran on a Leonardo with AmForth 6.8

https://sourceforge.net/p/amforth/mailman/message/36608525/

Best wishes,
Tristan

Re: [Amforth] Gory Details: How to properly create a release?

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

Hello Brian,

thanks for your message!

Brian writes:

> I am running the latest version of amforth on an avrbutterfly.

Oh, cool! You made me curious. This is a atmega169 controller
featuring 16k flash, so it is possible. I still have such a
thing in a box, so I should be able to recreate it.

Would you care to share your application? Something like a
nametag maybe???

Cheers,
Erich


>
> Brian
>
> On 8/30/20 1:09 PM, Erich =?utf-8?Q?W=C3=A4lde?= wrote:
>> More details on Point 4 (see below).
>> Cheers,
>> Erich
>>
>> Erich Wälde writes:
>>
>>> Dear AmForthers,
>>>
>>> I asked:
>>>>   - How do I actually create a new release? Copying the files is
>>>>     one thing, but where do I need to change the version? There
>>>>     is more than one place, I'm afraid. I also happen to know
>>>>     that after 6.9 there cannot be 6.10 due to a limitation
>>>>     created very early. Matthias told me that, otherwise I would
>>>>     be clueless.
>>> see https://sourceforge.net/p/amforth/mailman/message/37048278/
>>>
>>>
>>>
>>> How to create an official release?
>>>
>snip<

>>>
>>> 4. create all .hex files for target boards in appl/
>>>     arduino,atmega2561,eval-pollin,hifive1,launchpad-arm,launchpad430,
>>>     template
>>>
>>>     I had forgotten that these exsisted. They are in the release archive
>>>     only, not in the source tree. Now I understand, why people
>>>     sometimes ask about them.
>>>
>>>     This step is detailed in a few .xml files. Matthias used ant to
>>>     build them. I have not built these before, but this looks doable,
>>>     provided I get all relevant toolchains up and running.
>> Digging through the ./appl/ subdirectory I think I understand the
>> following:
>>
>> - There are currently 8 target directories.
>>
>> - all of them have either build.xml or Makefile files
>>
>> - of the AVR8 targets all can be build with the exception of
>>    "arduino/leonardo" --- this runs into the "8k is too small"
>>    limitation. There used to be an avr-butterfly target (up to
>>    6.4), which suffers from the same limitation, iirc.
wrong. see above.

>snip<

-- 
May the Forth be with you ...

Re: [Amforth] Gory Details: How to properly create a release?

[Brian <bkn...@gm...>]

I am running the latest version of amforth on an avrbutterfly.

Brian

On 8/30/20 1:09 PM, Erich =?utf-8?Q?W=C3=A4lde?= wrote:
> More details on Point 4 (see below).
> Cheers,
> Erich
>
> Erich Wälde writes:
>
>> Dear AmForthers,
>>
>> I asked:
>>>   - How do I actually create a new release? Copying the files is
>>>     one thing, but where do I need to change the version? There
>>>     is more than one place, I'm afraid. I also happen to know
>>>     that after 6.9 there cannot be 6.10 due to a limitation
>>>     created very early. Matthias told me that, otherwise I would
>>>     be clueless.
>> see https://sourceforge.net/p/amforth/mailman/message/37048278/
>>
>>
>>
>> How to create an official release?
>>
>> I spent some time to do some code archeology. I still do not know,
>> how to properly make a release. This is, what I currently
>> see/expect:
>>
>> 1. check all version numbers in trunk
>>
>>     - doc/Makefile being one place. This seems to be used in all
>>       generated documentation, which is nice.
>>     - common/words/env-forthversion.asm is another place with different
>>       syntax!
>>     Judging by commit r2271, these are all places indeed. Yay!
>>
>> 2. update doc/source/index.rst and optionally history.rst in
>>     trunk and commit
>>
>> 3. "svn copy" trunk to releases/$VERSION; commit message collects
>>     the accumulated one line change descriptions
>>     This is the most visible change in the source tree
>>     e.g. see commit r2244 (rel 6.5)
>>
>> 4. create all .hex files for target boards in appl/
>>     arduino,atmega2561,eval-pollin,hifive1,launchpad-arm,launchpad430,
>>     template
>>
>>     I had forgotten that these exsisted. They are in the release archive
>>     only, not in the source tree. Now I understand, why people
>>     sometimes ask about them.
>>
>>     This step is detailed in a few .xml files. Matthias used ant to
>>     build them. I have not built these before, but this looks doable,
>>     provided I get all relevant toolchains up and running.
> Digging through the ./appl/ subdirectory I think I understand the
> following:
>
> - There are currently 8 target directories.
>
> - all of them have either build.xml or Makefile files
>
> - of the AVR8 targets all can be build with the exception of
>    "arduino/leonardo" --- this runs into the "8k is too small"
>    limitation. There used to be an avr-butterfly target (up to
>    6.4), which suffers from the same limitation, iirc.
>
>    AVR needs the wine/avrasm2.exe toolchain.
>
> - the remaining targets need different toolchains, which I have not
>    installed at this moment.
>
>    - hifive1         riscv64-linux-gnu-as
>      In the download section Matthias has provided a toolchain, see:
>      https://sourceforge.net/projects/amforth/files/Risc-V-Tools/
>      However, this toolchain is very hip today, so it is available
>      at den Debian repositories as well: gcc-riscv64-linux-gnu/stable
>
>      I actually have such a board collecting dust in the corner :-/
>
>    - launchpad-arm   arm-none-eabi-as
>      This toolchain is available at the debian repositories as well:
>      gcc-arm-none-eabi/stable
>
>    - launchpad430    naken_asm
>      This tool is available, maintained and probably quite mature:
>      http://www.mikekohn.net/micro/naken_asm.php
>      In 2015 I have made experiments with this toolchain, so this
>      part is probably doable.
>
>    - inux-arm        arm-linux-gnueabi-as
>      This toolchain is available at the debian repositories as well:
>      gcc-arm-linux-gnueabi/stable
>
>    I do not have any msp430 or arm boards any more. I have given
>    them away.
>
>    So all in all, the toolchains are available. Matthias has
>    probably built a bunch of docker containers to run them :-)
>
>
> A little while later:
>
> Installing the missing toolchains on Debian turns out to be
> fairly simple (thank you, Debianistas!):
>
> # apt install binutils-riscv64-linux-gnu \
>    binutils-arm-linux-gnueabi \
>    binutils-arm-none-eabi
>
> I had a copy of naken_asm (from 201(5) in some corner and with
> that executable on the PATH, I could build launchpad430
>
> So with the exception of arduino/leonardo.* I managed to build
> everything that shows up in the release archive.
>
>
>> ew@ceres:~/Forth/amforth/trunk/appl 119 > ls -l */*.hex */amforth
>> -rw-r----- 1 ew ew   239 2020-08-30 11:28 arduino/duemilanove.eep.hex
>> -rw-r----- 1 ew ew 26843 2020-08-30 11:28 arduino/duemilanove.hex
>> -rw-r----- 1 ew ew   239 2020-08-30 11:28 arduino/mega128.eep.hex
>> -rw-r----- 1 ew ew 27959 2020-08-30 11:28 arduino/mega128.hex
>> -rw-r----- 1 ew ew   239 2020-08-30 11:28 arduino/uno.eep.hex
>> -rw-r----- 1 ew ew 27157 2020-08-30 11:28 arduino/uno.hex
>>
>> -rw-r----- 1 ew ew   239 2020-08-30 11:31 atmega2561/atmega256.eep.hex
>> -rw-r----- 1 ew ew 27481 2020-08-30 11:31 atmega2561/atmega256.hex
>>
>> -rw-r----- 1 ew ew   239 2020-08-30 11:27 eval-pollin/p1284-16.eep.hex
>> -rw-r----- 1 ew ew 28096 2020-08-30 11:27 eval-pollin/p1284-16.hex
>> -rw-r----- 1 ew ew   239 2020-08-30 11:27 eval-pollin/p16-8.eep.hex
>> -rw-r----- 1 ew ew 27518 2020-08-30 11:27 eval-pollin/p16-8.hex
>> -rw-r----- 1 ew ew   239 2020-08-30 11:27 eval-pollin/p32-8.eep.hex
>> -rw-r----- 1 ew ew 27682 2020-08-30 11:27 eval-pollin/p32-8.hex
>> -rw-r----- 1 ew ew   239 2020-08-30 11:27 eval-pollin/p328-16.eep.hex
>> -rw-r----- 1 ew ew 27771 2020-08-30 11:27 eval-pollin/p328-16.hex
>> -rw-r----- 1 ew ew   239 2020-08-30 11:27 eval-pollin/p644-16.eep.hex
>> -rw-r----- 1 ew ew 27796 2020-08-30 11:27 eval-pollin/p644-16.hex
>>
>> -rw-r----- 1 ew ew 47833 2020-08-30 13:17 hifive1/hifive1.hex
>>
>> -rw-r----- 1 ew ew 44449 2020-08-30 13:23 launchpad-arm/lp-stellaris.hex
>> -rw-r----- 1 ew ew 23068 2020-08-30 13:12 launchpad430/lp-2553.hex
>> -rw-r----- 1 ew ew 23132 2020-08-30 13:12 launchpad430/lp-5529.hex
>> -rw-r----- 1 ew ew 22568 2020-08-30 13:12 launchpad430/lp-5969.hex
>>
>> -rwxr-x--- 1 ew ew 68528 2020-08-30 13:20 linux-arm/amforth*
>>
>> -rw-r----- 1 ew ew   239 2020-08-30 11:34 template/template.eep.hex
>> -rw-r----- 1 ew ew 27475 2020-08-30 11:34 template/template.hex
> This pretty much solves point 4
>
>
>
> So the whole thing more "shell script like"
>
> cd /path/to/../amforth/trunk
> ( cd avr8; ln -s /path/to/AvrAssembler2 ./Atmel )
>
> cd appl
> # these are avr targets
> # arduino fails on leonardo (8k too small problem)
> for DIR in arduino atmega2561 eval-pollin template
> do
>      ( cd $DIR; ant compile )
> done
>
> sudo apt install binutils-riscv64-linux-gnu \
>      binutils-arm-linux-gnueabi \
>      binutils-arm-none-eabi
>
> for DIR in hifive1 launchpad-arm linux-arm
> do
>      ( cd $DIR; make )
> done
>
> # remove the "git-info" dependency from launchpad430/build.xml
> ( cd launchpad430; make lp-2553.hex lp-5529.hex lp-5969.hex )
>
>
>> 5. create the documentation
>>     - htdocs, the web page
>>     - books, did you know that all the content of the webpage shows up
>>       in amforth.pdf (made with pdflatex) and AmForth.epub (made with
>>       sphinx-build)? Amazing! These books are part of the download .zip
>>       archive.
>>
>>       This step is a "cd doc; make all" --- provided sphinx pdflatex
>>       and all the good stuff is installed.
>>
>> 6. create a new temporary tree to collect everything, that goes into
>>     the release archive:
>>     - sources
>>     - some of the scripts, tools, meta-files
>>     - the generated documentation from releases/$VERSION, without the
>>       document sources, but including the "books"
>>
>>     I have not found anything that looks like doing this.
>>
>> 7. create the .zip and .tar.gz archives (the easy part), and upload
>>     them to their correct location in the sourceforge.net file tree
>>     (the not so obvious part).
>>
>>     I found out that these release archives were built by Matthias.
>>     The files for 6.8 are about 7 MB in size.
>>
>>     Whereas if you download "the latest sources", sourceforge will
>>     generate a snapshot of "trunk". This is a plain copy, without all
>>     the niceties included in the archives mentioned here. This archive
>>     is currently 35 MB in size.
>>
>> 8. sync the generated documentation with the online website
>>
>>     I have done this a few times now, but I'm still asking myself, if I
>>     see all relevant pieces or not.
>>
>> 9. Increment the version numbers in trunk and commit
>>
>>
>> So nine easy steps to code nirvana? Hmmm.
>>
>> If anyone has some insight or detail I'm missing, I would be
>> happy to hear about it. I propose to rework this into a .rst
>> document and add it to the source tree, once missing bits have
>> emerged (points 4, 6, 7).
>>
>> Cheers,
>> Erich
>
>
> _______________________________________________
> Amforth-devel mailing list for http://amforth.sf.net/
> Amf...@li...
> https://lists.sourceforge.net/lists/listinfo/amforth-devel

[Amforth] AmForth Weekend 3 (2020-08-29/30)

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

Dear AmForthers,

as previously announced I made this weekend the official

    AmForth Weekend 3 / 2020-08-29,30

So what happened?

- Commits

  r2450: one line whitespace fix in amforth-shell.py (2020-08-04)
         https://sourceforge.net/p/amforth/code/2450/

  r2451: one line python2->3 fix provided by Tristan Williams. Thanks!
         https://sourceforge.net/p/amforth/code/2451/


- Progress

  - I did some code archeology about how to create an official
    release. see separate email
    https://sourceforge.net/p/amforth/mailman/message/37096517/

  - some more digging on how to create all the .hex files (point 4)
    https://sourceforge.net/p/amforth/mailman/message/37097180/

  - turns out that installing the toolchains is not difficult (on Debian)
    : apt install binutils-riscv64-linux-gnu binutils-arm-linux-gnueabi binutils-arm-none-eabi
    and naken_asm I still had around in some obscure directory.

    After that all the remaining hex files could be built.
    ONLY arduino/leonardo.hex is missing.
    Not bad for a rainy afternoon :-)

  While working on this, sourceforge went into "disaster recovery
  mode" --- not for the first time. :/

  So, this weekend was not as busy from the point of this project, I
  think. However, I spent countless hours in the past weeks to find a
  bug in my data collection system. It makes the communication die for
  no apparent reason, but it still has evaded my attempts to uncover
  it. Such is life.


- Open Issues

  as far as I'm aware:

  - WDT (Martin Nicholas) patch

    Martin has provided a small patch (.asm) regarding the
    startup of the WDT (watch dog timer) on atmega2560
    controllers. I have honestly no idea, whether or not this
    will break something else, and under which conditions exactly
    this is needed.
    link to email archive (Martin Nicholas, June 2019)
    https://sourceforge.net/p/amforth/mailman/message/36682958/

  - Multitasker documentation

    This needs to be tested and enhanced in a few ways. It might
    be that the current example in the Cookbook section is simply
    broken. There have been questions about how to better
    populate the task local user area. Maybe this could be
    answered by a more complex example. There has been the
    question about producing output from a task (not the cmd
    loop), its collision with the shared HLD/TAB area, and
    possible ways to solve this (semaphores, task local HLD/TAB).
    link to email archive (Jan Kromhout Feb 2019)
    https://sourceforge.net/p/amforth/mailman/message/36596842/

  - " du< " is missing
    link to email archive (Martin Nicholas August 2019)
    https://sourceforge.net/p/amforth/mailman/message/36748496/



- AmForth Weekend 4

  Shall take place in October, I think, but I hesitate to fix a date.


Thank you very much for your precious time!

Take care and happy hacking,

Erich

-- 
May the Forth be with you ...

Re: [Amforth] Gory Details: How to properly create a release?

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

More details on Point 4 (see below).
Cheers,
Erich

Erich Wälde writes:

> Dear AmForthers,
>
> I asked:
>>  - How do I actually create a new release? Copying the files is
>>    one thing, but where do I need to change the version? There
>>    is more than one place, I'm afraid. I also happen to know
>>    that after 6.9 there cannot be 6.10 due to a limitation
>>    created very early. Matthias told me that, otherwise I would
>>    be clueless.
> see https://sourceforge.net/p/amforth/mailman/message/37048278/
>
>
>
> How to create an official release?
>
> I spent some time to do some code archeology. I still do not know,
> how to properly make a release. This is, what I currently
> see/expect:
>
> 1. check all version numbers in trunk
>
>    - doc/Makefile being one place. This seems to be used in all
>      generated documentation, which is nice.
>    - common/words/env-forthversion.asm is another place with different
>      syntax!
>    Judging by commit r2271, these are all places indeed. Yay!
>
> 2. update doc/source/index.rst and optionally history.rst in
>    trunk and commit
>
> 3. "svn copy" trunk to releases/$VERSION; commit message collects
>    the accumulated one line change descriptions
>    This is the most visible change in the source tree
>    e.g. see commit r2244 (rel 6.5)
>
> 4. create all .hex files for target boards in appl/
>    arduino,atmega2561,eval-pollin,hifive1,launchpad-arm,launchpad430,
>    template
>
>    I had forgotten that these exsisted. They are in the release archive
>    only, not in the source tree. Now I understand, why people
>    sometimes ask about them.
>
>    This step is detailed in a few .xml files. Matthias used ant to
>    build them. I have not built these before, but this looks doable,
>    provided I get all relevant toolchains up and running.

Digging through the ./appl/ subdirectory I think I understand the
following:

- There are currently 8 target directories.

- all of them have either build.xml or Makefile files

- of the AVR8 targets all can be build with the exception of
  "arduino/leonardo" --- this runs into the "8k is too small"
  limitation. There used to be an avr-butterfly target (up to
  6.4), which suffers from the same limitation, iirc.

  AVR needs the wine/avrasm2.exe toolchain.

- the remaining targets need different toolchains, which I have not
  installed at this moment.

  - hifive1         riscv64-linux-gnu-as
    In the download section Matthias has provided a toolchain, see:
    https://sourceforge.net/projects/amforth/files/Risc-V-Tools/
    However, this toolchain is very hip today, so it is available
    at den Debian repositories as well: gcc-riscv64-linux-gnu/stable

    I actually have such a board collecting dust in the corner :-/

  - launchpad-arm   arm-none-eabi-as
    This toolchain is available at the debian repositories as well:
    gcc-arm-none-eabi/stable

  - launchpad430    naken_asm
    This tool is available, maintained and probably quite mature:
    http://www.mikekohn.net/micro/naken_asm.php
    In 2015 I have made experiments with this toolchain, so this
    part is probably doable.

  - inux-arm        arm-linux-gnueabi-as
    This toolchain is available at the debian repositories as well:
    gcc-arm-linux-gnueabi/stable

  I do not have any msp430 or arm boards any more. I have given
  them away.

  So all in all, the toolchains are available. Matthias has
  probably built a bunch of docker containers to run them :-)


A little while later:

Installing the missing toolchains on Debian turns out to be
fairly simple (thank you, Debianistas!):

# apt install binutils-riscv64-linux-gnu \
  binutils-arm-linux-gnueabi \
  binutils-arm-none-eabi

I had a copy of naken_asm (from 201(5) in some corner and with
that executable on the PATH, I could build launchpad430

So with the exception of arduino/leonardo.* I managed to build
everything that shows up in the release archive.


> ew@ceres:~/Forth/amforth/trunk/appl 119 > ls -l */*.hex */amforth
> -rw-r----- 1 ew ew   239 2020-08-30 11:28 arduino/duemilanove.eep.hex
> -rw-r----- 1 ew ew 26843 2020-08-30 11:28 arduino/duemilanove.hex
> -rw-r----- 1 ew ew   239 2020-08-30 11:28 arduino/mega128.eep.hex
> -rw-r----- 1 ew ew 27959 2020-08-30 11:28 arduino/mega128.hex
> -rw-r----- 1 ew ew   239 2020-08-30 11:28 arduino/uno.eep.hex
> -rw-r----- 1 ew ew 27157 2020-08-30 11:28 arduino/uno.hex
> 
> -rw-r----- 1 ew ew   239 2020-08-30 11:31 atmega2561/atmega256.eep.hex
> -rw-r----- 1 ew ew 27481 2020-08-30 11:31 atmega2561/atmega256.hex
> 
> -rw-r----- 1 ew ew   239 2020-08-30 11:27 eval-pollin/p1284-16.eep.hex
> -rw-r----- 1 ew ew 28096 2020-08-30 11:27 eval-pollin/p1284-16.hex
> -rw-r----- 1 ew ew   239 2020-08-30 11:27 eval-pollin/p16-8.eep.hex
> -rw-r----- 1 ew ew 27518 2020-08-30 11:27 eval-pollin/p16-8.hex
> -rw-r----- 1 ew ew   239 2020-08-30 11:27 eval-pollin/p32-8.eep.hex
> -rw-r----- 1 ew ew 27682 2020-08-30 11:27 eval-pollin/p32-8.hex
> -rw-r----- 1 ew ew   239 2020-08-30 11:27 eval-pollin/p328-16.eep.hex
> -rw-r----- 1 ew ew 27771 2020-08-30 11:27 eval-pollin/p328-16.hex
> -rw-r----- 1 ew ew   239 2020-08-30 11:27 eval-pollin/p644-16.eep.hex
> -rw-r----- 1 ew ew 27796 2020-08-30 11:27 eval-pollin/p644-16.hex
> 
> -rw-r----- 1 ew ew 47833 2020-08-30 13:17 hifive1/hifive1.hex
> 
> -rw-r----- 1 ew ew 44449 2020-08-30 13:23 launchpad-arm/lp-stellaris.hex
> -rw-r----- 1 ew ew 23068 2020-08-30 13:12 launchpad430/lp-2553.hex
> -rw-r----- 1 ew ew 23132 2020-08-30 13:12 launchpad430/lp-5529.hex
> -rw-r----- 1 ew ew 22568 2020-08-30 13:12 launchpad430/lp-5969.hex
> 
> -rwxr-x--- 1 ew ew 68528 2020-08-30 13:20 linux-arm/amforth*
> 
> -rw-r----- 1 ew ew   239 2020-08-30 11:34 template/template.eep.hex
> -rw-r----- 1 ew ew 27475 2020-08-30 11:34 template/template.hex

This pretty much solves point 4



So the whole thing more "shell script like"

cd /path/to/../amforth/trunk
( cd avr8; ln -s /path/to/AvrAssembler2 ./Atmel )

cd appl
# these are avr targets
# arduino fails on leonardo (8k too small problem)
for DIR in arduino atmega2561 eval-pollin template
do
    ( cd $DIR; ant compile )
done

sudo apt install binutils-riscv64-linux-gnu \
    binutils-arm-linux-gnueabi \
    binutils-arm-none-eabi

for DIR in hifive1 launchpad-arm linux-arm
do
    ( cd $DIR; make )
done

# remove the "git-info" dependency from launchpad430/build.xml
( cd launchpad430; make lp-2553.hex lp-5529.hex lp-5969.hex )


> 5. create the documentation
>    - htdocs, the web page
>    - books, did you know that all the content of the webpage shows up
>      in amforth.pdf (made with pdflatex) and AmForth.epub (made with
>      sphinx-build)? Amazing! These books are part of the download .zip
>      archive.
>
>      This step is a "cd doc; make all" --- provided sphinx pdflatex
>      and all the good stuff is installed.
>
> 6. create a new temporary tree to collect everything, that goes into
>    the release archive:
>    - sources
>    - some of the scripts, tools, meta-files
>    - the generated documentation from releases/$VERSION, without the
>      document sources, but including the "books"
>
>    I have not found anything that looks like doing this.
>
> 7. create the .zip and .tar.gz archives (the easy part), and upload
>    them to their correct location in the sourceforge.net file tree
>    (the not so obvious part).
>
>    I found out that these release archives were built by Matthias.
>    The files for 6.8 are about 7 MB in size.
>
>    Whereas if you download "the latest sources", sourceforge will
>    generate a snapshot of "trunk". This is a plain copy, without all
>    the niceties included in the archives mentioned here. This archive
>    is currently 35 MB in size.
>
> 8. sync the generated documentation with the online website
>
>    I have done this a few times now, but I'm still asking myself, if I
>    see all relevant pieces or not.
>
> 9. Increment the version numbers in trunk and commit
>
>
> So nine easy steps to code nirvana? Hmmm.
>
> If anyone has some insight or detail I'm missing, I would be
> happy to hear about it. I propose to rework this into a .rst
> document and add it to the source tree, once missing bits have
> emerged (points 4, 6, 7).
>
> Cheers,
> Erich