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

[Jeffrey Hutzelman]

On Sun, 2012-09-02 at 12:04 -0400, Gene Cumm wrote:
> > 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)

Personally, I'm partially to spelling it out and putting the
abbreviation in parentheses.


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

Not really.  Personally, I wouldn't make this change at all, though I
would be consistent about whether it's the abbreviation or the expanded
form that is parenthesized.  The abbreviation can be used alone after
the first usage, but I don't think the NAME section (which is
essentially the document title) should be counted as a "usage" for this
purpose.


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

Agree - with the year first, its unambiguous that month and day follow
in that order.  On the other hand, in prose, one could simply write it
out, as "January 12, 2012".

-- Jeff