[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