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