[syslinux] Syslinux docs for core variants and installers

[Matt Fleming]

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

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.

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

> - 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?

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

> - Display file format

doc/config.txt ?

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

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

> - "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?

> - (not present) Common problems list reference

This should exist on the wiki with a reference in README?

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

-- 
Matt Fleming, Intel Open Source Technology Center