[syslinux] Syslinux docs for core variants and installers

Gene Cumm gene.cumm at gmail.com
Wed Nov 7 13:58:03 PST 2012


On Nov 7, 2012 4:28 AM, "Matt Fleming" <matt at console-pimps.org> wrote:
>
> (Cc'ing Peter for historical context)
>
> On Sun, 2012-10-28 at 13:32 -0400, Gene Cumm wrote:
> > I'm currently in the process of trying to convert the existing core
> > documentation (doc/syslinux.txt for starters) to AsciiDoc which can be
> > used to generate man pages for installed systems, HTML for the website
> > and possibly cleaner text file output (along with various other
> > possibilities).  I'm also doing a bit of editing as I go with the
> > goals of being correct, complete, clear and concise, including new and
> > deprecated behavior with version numbers noted as there is quite the
> > wide variation in versions used (although I've never heard of someone
> > using Syslinx older than 3.00).  My thought here is that if someone is
> > accustomed to older behavior, this would facilitate them updating to
> > the new behavior.
>
> Before you start down the road of documenting old behaviour, do you know
> of people running into issues because of the differences between
> versions? If so then I agree that documenting them is an excellent idea,
> but don't create unnecessary work for yourself.

Nothing in particular but items like the changes to config filename
searches for SYSLINUX/ISOLINUX could be worthwhile.

> Cleaning up the documentation, however, is a fantastic idea. If
> possible, I'd prefer it if you wrote your patches against the 5.00
> branch for reasons that will become clear below.

Understandable.

> > Looking at doc/syslinux.txt, there are numerous basic sections.  My
> > main question is: Should any of these be regrouped into different
> > documents?  Aspects specific to the installers don't necessarily
> > concern those using PXELINUX/ISOLINUX.
> >
> > Aside from the information specific to the command line of the
> > installers, I see the following sections:
> >
> > - Name convention
>
> I honestly think the naming convention should be in the README in the
> top-level directory. Likewise the section about bug reports and the
> mailing list.

Should the man pages include some of this?  AsciiDoc has facilities
for an include which probably be useful here which can also have
conditions. If not, references for at least bugs and the list should
likely be included in the bottom

> > - Config file syntax in subsections (global, label-specifc,
> > dual-purpose as global or label-specific, and kernel-like directives)
>
> Put this in a new doc/config.txt file?

For now, txt/.  I was thinking this should generate the manpage file
syslinux.cfg.5.

> > - Non-Linux kernel formats and detection (should this still be
> > specified outside the config file syntax?)
>
> Are you referring to COMBOOT IMAGES AND OTHER OPERATING SYSTEMS? This
> should probably be in doc/config.txt too.

Yes.  I'm also uncertain that needs its own section since some of it
is duplicated.  The CLI behavior is probably better off with the CLI
docs.  I've already made a subsection just for the kernel-like
directives.

> > - Display file format
>
> doc/config.txt ?

Either that or display.txt (=> syslinux.dsp.5).

> > - Boot prompt command line keystrokes
>
> OK, the reason I asked for patches against 5.00 is because the command
> line code gets way more interesting in that version. For instance, it's
> got bash-like command history, e.g. you can search backwards through the
> commands you've typed with Ctrl + R foo. The command line code in 5.00
> is much more hackable (it's all written in C) and I suspect new features
> will be added. Having a separate command line doc file will make it
> easier for people to update the documentation.

Also moving the filename append rule here (cli.txt?) would likely be
appropriate.

> > - Reference to docs covering other variants/sections (pxelinux.txt,
> > isolinux.txt, comboot.txt; perhaps add menu.txt due to popularity)
>
> These files are already described in README.
>
> > - DOS boot (for SYSLINUX on a FAT* file system)(perhaps group with
> > installer command line)
>
> Yes, group this with the installer documentation.
>
> > - Novice protection
>
> Hmm.. I genuinely can't think of where to move this.

Something with common documentation.

> > - "NOTES ON BOOTABLE CD-ROMS" (perhaps move to isolinux.txt; for the
> > deprecated FDIMAGE directive / .img floppy image format)
>
> Yes.
>
> > - Hardware compatibility list reference
>
> Move to README or the installers file?

I'd say wherever bugs go.

> > - (not present) Common problems list reference
>
> This should exist on the wiki with a reference in README?

Same with bugs.

> > - MBR install (bad cat) (perhaps group with installer command line)
>
> Yep.
>
> > - Boot loader IDs
> > - Bug reports/contact info
>
> README?
>
> > I'd think keeping all of the information specific to the command line
> > of the installers grouped together (covering all installers) would be
> > useful for people moving between installers.
>
> Yes, I think there's merit in keeping all the installer documentation in
> its own file.

I'm glad we're on a similar page.

--Gene



More information about the Syslinux mailing list