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

Gene Cumm gene.cumm at gmail.com
Sun Sep 2 09:04:10 PDT 2012


On Sun, Sep 2, 2012 at 10:20 AM, Ady Ady <ady-sf at hotmail.com> wrote:
>
>
>> 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).

Noted already.

> Change from:
> == NAME ==
> pxechn.c32 - Chainboot to new NBP
> to:
> == NAME ==
> pxechn.c32 - Chainboot to new Network Boot Program (NBP)

I debated this one as the that becomes the HTML title also.  If I were
to change this one, I'd lean towards:

pxechn.c32 - Chainboot to new NBP (Network Boot Program)

> Change from:
> == DESCRIPTION ==
> Chainboot to a new NBP (Network Boot Program) 'FILE'
> to:
> == DESCRIPTION ==
> Chainboot to a new NBP 'FILE'

Dependent on above.

> Change from:
> *-w*::
>     wait after loading before booting for user input.
> to:
> *-w*::
>     after loading and before booting, wait for user input.

This wording was because I wanted it clear what word the letter stood for.

*-w*::
    (wait) after loading and before booting, wait for user input.

OR

*-w* (wait)::
    after loading and before booting, wait for user input.

would likely make it clearer for both which word and the statement.
I'd want to test the output of each with AsciiDoc also.

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

I guess I'm missing why the above could be misinterpreted with a
4-digit prefix, clearly indicating the year.  This date format is the
RFC 3339 format, YYYY-mm-dd.  I know of no other format that utilizes
a 4-digit prefix.

-- 
-Gene



More information about the Syslinux mailing list