[syslinux] RFC:documents for new modules; Interest in rewriting exiting documentation

Ady Ady ady-sf at hotmail.com
Sun Sep 2 07:20:49 PDT 2012



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



More information about the Syslinux mailing list