Syslinux - Oct 2012 - Syslinux docs for core variants and installers

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.

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
- Config file syntax in subsections (global, label-specifc,
dual-purpose as global or label-specific, and kernel-like directives)
- Non-Linux kernel formats and detection (should this still be
specified outside the config file syntax?)
- Display file format
- Boot prompt command line keystrokes
- Reference to docs covering other variants/sections (pxelinux.txt,
isolinux.txt, comboot.txt; perhaps add menu.txt due to popularity)
- DOS boot (for SYSLINUX on a FAT* file system)(perhaps group with
installer command line)
- Novice protection
- "NOTES ON BOOTABLE CD-ROMS" (perhaps move to isolinux.txt; for the
deprecated FDIMAGE directive / .img floppy image format)
- Hardware compatibility list reference
- (not present) Common problems list reference
- MBR install (bad cat) (perhaps group with installer command line)
- Boot loader IDs
- Bug reports/contact info

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.

--
-Gene

On Sun, Oct 28, 2012 at 1:32 PM, Gene Cumm <gene.cumm at gmail.com> wrote:
> 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.
In summary:
1) Should the content doc/syslinux.txt be split into multiple
documents, since the documents I'm editing are targeting to replace
doc/syslinux.txt, man/syslinux.1 and the page on the website.
2) If split, how should it be split?  IMO, the info for the command
line of the installers would be the first to be separated.

-- 
-Gene

(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