gforth
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [gforth] gforth documentation


From: Bernd Paysan
Subject: Re: [gforth] gforth documentation
Date: Mon, 20 Oct 2014 00:57:25 +0200
User-agent: KMail/4.11.5 (Linux/3.11.10-21-desktop; KDE/4.11.5; x86_64; ; )

Am Sonntag, 19. Oktober 2014, 14:22:35 schrieb Jerry DeLisle:
> Hi all,
> 
> Since I have been getting up to speed using gforth by using the manual, I
> see some things I would like to fix.  Before I start into it I want to make
> sure we have agreement:
> 
> I am using the on-line manual rather than the pdf or info versions.  I
> assume they are similar and generated from the same source files.

Yes.  The source file is doc/gforth.ds, and it takes glossary entries and 
stack comments from the actual source - i.e. the gforth.ds contains the 
structure of the overall document, and the explanatory text for each section, 
but not the actual glossary entry for each word.

> When I
> built the latest trunk from a snapshot I grabbed, I noticed an error in the
> documentation build.  I am not sure what that is, but will explore further.
> 
> I would like to adjust the fonts and font sizes to be more readable.  The
> Forth words need to stand out a bit better.  I will submit examples of what
> I come up with before doing this.
> 
> Stack comments need to have the familiar   (   --   ) format and spacing
> between items in those comments adjusted.  Right now the forth words sort
> of run right into the stack comments without much space.  Its hard to tell
> where the stack comment begins and ends.
> 
> Are the stack comments being pulled directly from the Forth source? That
> might be useful.

Yes, it is.

> Some paragraph alignments might help with readability.
> 
> As I go through each file, I will be looking for readability and
> understanding. I will edit if I think it needs it.  What review approval
> process do you want followed here?  Can I get write access to the
> repository assuming I have earned some trust?

Yes.

> Folks on the gfortran team
> can probably vouch for me.  I do have gcc write after approval access.

The Gforth team isn't that big, we don't have much bureaucrazy.

> What areas do you think need attention?  Are there missing sections in the
> documentation?

I'm sure there are. E.g. the entire unix/serial.fs is completely undocumented, 
as are other parts.  I don't expect from you that you document this stuff ;-).

> This is enough to get started, so feed back will be appreciated.

If you want to show us experiments without officially checking them into the 
savannah repository, feel free to fork my github repository first - it is in 
sync with the savannah repository.

> BTW I am successfully writing data to my USB serial port using serial.fs.

-- 
Bernd Paysan
"If you want it done right, you have to do it yourself"
http://bernd-paysan.de/

Attachment: signature.asc
Description: This is a digitally signed message part.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]