Syslinux - Jun 2013 - Some documentation suggestions as of v.5.10

Hello,

Here are some humble suggestions for 'doc/menu.txt' and 
'doc/syslinux.txt'. They might be relevant for other documentation 
sources too.

Unfortunately, I don't know how to prepare adequate patches.


For 'menu.txt':

_ Line 8:
"located in the menu/ subdirectly."

Suggestion:
"located in the 'com32/cmenu' subdirectory."


_ Line 10:
"It requires that the menu is compiled from a
simple C file, see menu/simple.c and menu/complex.c for examples."

Suggestion:
"It requires [for] the menu to be compiled from a
simple C file, see 'com32/cmenu/simple.c' and
'com32/cmenu/complex.c'
for examples."


_ Line 15:
Suggestion:
"See 'com32/cmenu/README' "

_ Line 302:
IMHO, the 'DEFAULT label' directive under [vesa]menu.c32 (in 
./doc/menu.txt) needs some better explanation regarding its behavior.

For example, the following phrase, as of v.5.10, seems inaccurate to 
me:
"For backwards compatibility with earlier versions of Syslinux,
 this directive is ignored unless the configuration file also
 contains a UI directive."

_ Line 375:
Suggestion:
"Takes the place of the TABMSG message if option-editing is"

_ Line 527:
Suggestion:
"Additionally, an optional"


*****
For 'syslinux.txt':

_ Line 21 to Line 24 (and more):
Suggestion (this particular one might be of lower priority):
Perhaps it could be helpful to introduce a "more accurate" 
description or definition of SYSLINUX / EXTLINUX for current 
versions.
The current difference between them is not supposed to be about the 
fs (in the relevant storage media), but about whether it is mounted 
or not.
I would tend to keep the "older" description or definition too, valid 
for older versions still in use.
The 'options' for each Syslinux installer are not updated in this 
document; so maybe a reference to the wiki (which is at least 
partially updated regarding "potential" and available options) or to 
other sources of relevant and current information could perhaps be 
helpful for newcomers (?).
Mentioning the '--help' and '--version' options for installers
could
be useful too.

_ Line 135:
Suggestion:
Mention the (semi-alternative) 'DEFAULT label' syntax, which is 
compatible with the UI directive too. Although 'label' is a 
particular sub-case of 'kernel' for this directive, explicitly 
mentioning this particular case might help newcomers for 
troubleshooting situations (with or without the UI directive).

_ Line 147:
Suggestion:
The statement:
"directive that overrides the DEFAULT and PROMPT directives."
seems to be not clear enough for some users, as it gives the sense 
that the remaining 'DEFAULT' directive has no effect, which would be, 
generally speaking, inaccurate.

_ Line 206:
Suggestion:
"higher.)  The following CPU features"

_ Line 237:
Suggestion:
"If these strings contain white-space characters, they are replaced 
with underscores (_)."

_ Line 370:
Suggestion:
IIRC, the statement:
"Note: all files except the last one are zero-padded to a
 4K page boundary.  This should not affect initramfs."
is not accurate. I think the original value (4K) was actually 
reduced.

_ Line 383:
Suggestion:
Document the "special" case for the restart of the timer (for 
[TOTAL]TIMEOUT) when changing from one interface to another, for 
example from [vesa]menu.c32 to CLI (by pressing ESC, for example). 
This behavior might be evident to developers, but not to users.

_ Line 406:
Suggestion:
Similarly to the suggestion for 'Line 135' above, explicitly 
mentioning the particular case of 'ONTIMEOUT label' might be helpful 
for newcomers.

_ Line 429:
Suggestion:
Correct
"SERIAL port [[baudrate] flowcontrol]"
to
"SERIAL port [baudrate [flowcontrol]]"

_ Line 598:
This comment is not about documentation (so it's off-topic here), but 
about a request / reminder to fix the 'ASCII24+LSS16+newline' issue 
still present in Syslinux 5.10 (since 5.00).

_ Line 825:
Suggestion:
The wiki (in the MBR page) mentions a safer method, instead of using 
"cat mbr.bin > /dev/XXX".


That's enough for now :). Hopefully, someone with the necessary 
knowledge might 
also be willing to patch these two documentation files.

TIA,
Ady.

On Jun 8, 2013 7:32 PM, "Ady" <ady-sf at hotmail.com>
wrote:
>
> Hello,
>
> Here are some humble suggestions for 'doc/menu.txt' and
> 'doc/syslinux.txt'. They might be relevant for other documentation
> sources too.
I'm pretty sure Matt Fleming has been considering moving to my AsciiDoc
rewrite which may render these moot.
--Gene

> On Jun 8, 2013 7:32 PM, "Ady" <ady-sf at hotmail.com>
wrote:
> >
> > Hello,
> >
> > Here are some humble suggestions for 'doc/menu.txt' and
> > 'doc/syslinux.txt'. They might be relevant for other
documentation
> > sources too.
> 
> I'm pretty sure Matt Fleming has been considering moving to my AsciiDoc
> rewrite which may render these moot.
> --Gene
It is still not "moot", considering that:
_ the ./doc/*.txt files are still included and are still read by 
users.
_ Matt is still adding information to ./doc/*.txt as of 5.xx, and 
part of my comments are in reference to those recent additions.
_ disregarding the specific line numbers and specific file names, the 
content of the suggested corrections / improvements is still relevant 
to other sources of information such as the man pages and the 
AsciiDoc files. The exact location in each set of files might differ, 
but the main concept in most of those suggestions is still relevant 
for all those sources of information.

Regards,
Ady.

On Sat, Jun 8, 2013 at 6:58 PM, Ady <ady-sf at hotmail.com>
wrote:
> Hello,
>
> Here are some humble suggestions for 'doc/menu.txt' and
> 'doc/syslinux.txt'. They might be relevant for other documentation
> sources too.
>
> Unfortunately, I don't know how to prepare adequate patches.
Here's a breakdown relative to txt/
> For 'menu.txt':
Not yet present in txt/
> *****
> For 'syslinux.txt':
>
> _ Line 21 to Line 24 (and more):
> Suggestion (this particular one might be of lower priority):
> Perhaps it could be helpful to introduce a "more accurate"
> description or definition of SYSLINUX / EXTLINUX for current
> versions.
> The current difference between them is not supposed to be about the
> fs (in the relevant storage media), but about whether it is mounted
> or not.
> I would tend to keep the "older" description or definition too,
valid
> for older versions still in use.
> The 'options' for each Syslinux installer are not updated in this
> document; so maybe a reference to the wiki (which is at least
> partially updated regarding "potential" and available options) or
to
> other sources of relevant and current information could perhaps be
> helpful for newcomers (?).
> Mentioning the '--help' and '--version' options for
installers could
> be useful too.
No, as of 4.00, EXTLINUX's functionality is merged into SYSLINUX.  The
installers extlinux and syslinux are what you're considering.  This in
part still needs to be included.
> _ Line 135:
> Suggestion:
> Mention the (semi-alternative) 'DEFAULT label' syntax, which is
> compatible with the UI directive too. Although 'label' is a
> particular sub-case of 'kernel' for this directive, explicitly
> mentioning this particular case might help newcomers for
> troubleshooting situations (with or without the UI directive).
Perhaps worth clarifying centrally in txt/syslinux.cfg.txt with more
info in txt/syslinux-cli.txt.
> _ Line 147:
> Suggestion:
> The statement:
> "directive that overrides the DEFAULT and PROMPT directives."
> seems to be not clear enough for some users, as it gives the sense
> that the remaining 'DEFAULT' directive has no effect, which would
be,
> generally speaking, inaccurate.
Actually, it is accurate as the core now ignores these options.  It
may be worth mentioning briefly that modules like (vesa)menu.c32 may
still utilize this directive.  "but these options may still be
utilized by modules parsing the config".
> _ Line 206:
> Suggestion:
> "higher.)  The following CPU features"
s/feature/features/ was a little hard to spot at first and SYSAPPEND
needs to get into txt/syslinux.cfg.txt.
> _ Line 237:
> Suggestion:
> "If these strings contain white-space characters, they are replaced
> with underscores (_)."
Looks good.
> _ Line 370:
> Suggestion:
> IIRC, the statement:
> "Note: all files except the last one are zero-padded to a
>  4K page boundary.  This should not affect initramfs."
> is not accurate. I think the original value (4K) was actually
> reduced.
Should be verified.  Not yet included.
> _ Line 383:
> Suggestion:
> Document the "special" case for the restart of the timer (for
> [TOTAL]TIMEOUT) when changing from one interface to another, for
> example from [vesa]menu.c32 to CLI (by pressing ESC, for example).
> This behavior might be evident to developers, but not to users.
It's not changing interfaces.  It's successfully booting a kernel (a
COM32 module) and returning.  However, worth noting.
> _ Line 406:
> Suggestion:
> Similarly to the suggestion for 'Line 135' above, explicitly
> mentioning the particular case of 'ONTIMEOUT label' might be
helpful
> for newcomers.
repeat.
> _ Line 429:
> Suggestion:
> Correct
> "SERIAL port [[baudrate] flowcontrol]"
> to
> "SERIAL port [baudrate [flowcontrol]]"
Yes.
> _ Line 825:
> Suggestion:
> The wiki (in the MBR page) mentions a safer method, instead of using
> "cat mbr.bin > /dev/XXX".
Moot.

--
-Gene