[syslinux] Some documentation suggestions as of v.5.10

Gene Cumm gene.cumm at gmail.com
Mon Jun 10 05:03:42 PDT 2013


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


More information about the Syslinux mailing list