[syslinux] Some documentation suggestions as of v.5.10

Ady ady-sf at hotmail.com
Sat Jun 8 15:58:11 PDT 2013


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.


More information about the Syslinux mailing list