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

[Ady Ady]

> Date: Sun, 2 Sep 2012 12:04:10 -0400
> From: gene.cumm at gmail.com
> To: syslinux at zytor.com
> Subject: Re: [syslinux] RFC:documents for new modules; Interest in rewriting exiting documentation
> 
> On Sun, Sep 2, 2012 at 10:20 AM, Ady Ady <ady-sf at hotmail.com> wrote:
> >
> > For doc/pxechn.txt:
> >
> > Whenever possible, use shorter line lengths (less than 78 characters).
> 
> Noted already.
> 
 
For the AsciiDoc compatibility, you have 80 columns and immediately you get
 to the next line (when the file is displayed) even if in the file itself
 you keep writing. So by using less than 80 columns (for the "real text to
 be displayed") and "forcing" a line feed (press <enter>) you waste at most
 1 column for each text line, but you also get a "content" that is similar
 to the displayed text (plus the formatting characters, of course). Thus,
 the lines in the text file are not so long.
  
 
> > 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)
> 
 
Or, you could choose to set the == NAME == (HTML title) to use the full
 name only, no extra "(NBP)". Then in the description you explain it as
 stated, so anyone reading the document will know what the NBP is already.
 IMHO, titles shouldn't be using "shortcuts" if they are not "universally
 clear to the target user".
 
 
> > 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.
 
Just be sure that the "(wait)" in the same line as "-W" won't be
 misinterpreted as part of the command line option itself. By using
 AsciiDoc, you could always make the letter "W" of "Wait" be bolder or
 brighter than the normal text.
 
  
> > 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
 
Yes, I know about the RFC, but not every reader will. In my example,
 YYYYMMMDD, each section uses a different and unique number of places
 (Y=4; M=3; D=2), and using MMM saves the two separator characters ("-")
 too. But this is probably not critical, so if you'd rather use RFC
 standards, it is also a good decision.
 
Best Regards,
Ady.