PicForth doco etc (was: Re: [PicForth] Re: A smarter disassembly utility)

[David McNab]

Samuel Tardieu wrote:
> David> I never knew PicForth had an integrated disassembler.
> I shall document it.

that'll be great

> If you have any suggestion on things that ought to be documented, do
> not hesitate to tell me (or better, supply patches to the
> documentation :-)

A couple of ideas for making low-level PicForth more accessible:

* More comments in picforth.fs to help out newbies like myself
    - 1 (or n-) line descriptive comments for as many words as
      practicable, including stack effects
    - stack-effect commentaries within word definitions. For a
      silly and exaggerated example of forth aimed at readability:

      \ performs rot13 encoding on a char
      : rot13                       ( c -- c' )

         \ make an uppercase copy (ie, with bit 5 reset)
         dup $df and                              ( ch chU )

         \ is it A-M ?
         dup [char] A >= over [char] M <= and     ( ch chU f )
         if                                       ( ch chU )
             \ yes, map to M-Z
             drop
             $d +                                 ( chR )
         else                                     ( ch chU )
             \ is it M-Z?
             dup [char] N >= over [char] Z <= and ( ch chU f )
             if                                   ( ch chU )
                 \ yes, map to A-M
                 drop
                 $d -                             ( chR )
             else                                 ( ch chU )
                 drop                             ( ch )
             then
         then
      ;

        (yeah, I know, the algo could be greatly simplified)

* A healthy suite of example programs, working from the simplest through
   to the more involved. I tend to believe that in the Forth 'reality',
   learning happens faster from studying clean demonstrative source code
   than trying to read doco aiming at general explanation.

> Do you mind me including your Python disassembler in PicForth with the
> same license as PicForth? It is currently GPL, but I may switch to a
> BSD-like license (without attribution clause) to further use reuse.

I'm happy for the disassembler to go out under a BSD-like license.

> By the way, are you by chance familiar with GNU Arch? This is the
> revision control system I use for PicForth -- if you used it as well,
> you could easily keep track of your chances even accross PicForth
> versions.

I use a bit of CVS, and even less of Subversion, but wouldn't know GNU 
Arch if it slapped me with a 10-pound trout. Is GnuArch similar to CVS 
and Subversion in its concept, or is it a different thing altogether?

Do you have your PicForth dev tree set up on a CVS-like remotely 
accessible server? If so, I'd be happy to accept write access and to 
submit patches/additions - which you can always change/veto if they 
don't quite fit the grain.

-- 
Cheers
David