Syslinux - Sep 2012 - RFC:documents for new modules; Interest in rewriting exiting documentation

I'm interested in redoing doc/syslinux.txt into 2 AsciiDoc documents,
splitting configuration from command.

First, however, I'm requesting comments on my recent documentation of
several modules I have written.  My goal is to be clear, concise, and
complete.  Acknowledgements and constructive comments are welcome.  If
it would help to also post converted copies of these documents (HTML,
man, etc.), please let me know.

Below are links to my git repo on github for the documents in question:

https://github.com/geneC/syslinux/blob/master/doc/pxechn.txt
https://github.com/geneC/syslinux/blob/lwip/doc/cptime.txt

--
-Gene

Op 2-9-2012 13:39, Gene Cumm schreef:
> https://github.com/geneC/syslinux/blob/master/doc/pxechn.txt
Line width might be an issue (seeing scrollbars in browser) and possibly 
unclear which GPL version(s) are meant (at bottom of doc).

As for cptime:
- replace 'file' by 'single file' ? (if that's a limitation)
- (absolute/relative) path support or only current dir?
- how does CHMOD or ACLs influence if cptime can find/read a file?

Documentation looks pretty clear, including the format/flow you've used.
Something like MEMDISK documentation would be the real challenge to see 
if you're happy with used document style.

with best regards,

Bernd Blaauw

> Date: Sun, 2 Sep 2012 07:39:33 -0400
> From: gene.cumm at gmail.com
> To: syslinux at zytor.com
> Subject: [syslinux] RFC:documents for new modules; Interest in rewriting
exiting documentation
> 
> I'm interested in redoing doc/syslinux.txt into 2 AsciiDoc documents,
> splitting configuration from command.
> 
> First, however, I'm requesting comments on my recent documentation of
> several modules I have written. My goal is to be clear, concise, and
> complete. Acknowledgements and constructive comments are welcome. If
> it would help to also post converted copies of these documents (HTML,
> man, etc.), please let me know.
> 
> Below are links to my git repo on github for the documents in question:
> 
> https://github.com/geneC/syslinux/blob/master/doc/pxechn.txt
> https://github.com/geneC/syslinux/blob/lwip/doc/cptime.txt
> 
> --
 
Some suggestions:
For doc/syslinux.txt, instead of just making editions, you could make first
 a copy with an appropriate file name, so it would be still available for
 users of older versions (3.xx). This would avoid the need to permanently
 make references to old releases where some command might have been
 different than in current versions. Thus, the new doc/syslinux.txt would
 include a minimum version number for which the content is valid and current.
 
For doc/pxechn.txt:
 
Whenever possible, use shorter line lengths (less than 78 characters).
 
Change from:
== NAME =pxechn.c32 - Chainboot to new NBP
to:
== NAME =pxechn.c32 - Chainboot to new Network Boot Program (NBP)
 
Change from:
== DESCRIPTION =Chainboot to a new NBP (Network Boot Program) 'FILE' 
to:
== DESCRIPTION =Chainboot to a new NBP 'FILE' 
 
Change from:
*-w*::
    wait after loading before booting for user input.
to:
*-w*::
    after loading and before booting, wait for user input.
 
Whenever possible, write dates in a "unique" way, so it can be
understandable
 with no doubts at all, no matter the reader's country.
So instead of:
The non-space constraint is due to how Syslinux variants parse the command line
as of 2012-01-12.
you could use, for example:
The non-space constraint is due to how Syslinux variants parse the command line
as of 2012JAN12.
HTH,
Ady.