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

[Gene Cumm]

On Sun, Sep 2, 2012 at 3:16 PM, Ady Ady <ady-sf at hotmail.com> wrote:
>
>
>> 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.

Depends on output format but for text, that should be true.  HTML
should not be limited however.

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

It's "-w" not "-W" (case matters).

>  misinterpreted as part of the command line option itself. By using

Yeah, that's a part of the contemplation.

>  AsciiDoc, you could always make the letter "W" of "Wait" be bolder or
>  brighter than the normal text.

It already is.

Unfortunately, I can't figure out how to get this to cooperate to be a
clean link:

https://sites.google.com/site/genecsyslinux/pxechn.html

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

This is more up to date and also includes portions that will be hidden
after transformation as they're planned or works in progress.

https://github.com/geneC/syslinux/blob/pxechn-fix-news-for-hpa/doc/pxechn.txt

-- 
-Gene