[syslinux] Syslinux docs for core variants and installers

[Ady]

Date sent:      	Sun, 28 Oct 2012 17:19:59 -0400
Subject:        	Re: [syslinux] Syslinux docs for core variants and 
installers

> 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

Hello Gene,

New common users get to know Syslinux first by the simple menu. So 
when a user is trying to know and understand Syslinux, 
./doc/syslinux.txt (and the equivalents in the wiki) is too long and 
touches many different matters.

IMO, it should have references to other more-specialized docs, and 
the relevant info should be moved to those other docs; sub-items or 
sub-sections if you'd like.

The installers could have their own document(s), possibly separated 
by versions when the installers changed too much. The MBR is a 
separate doc already, but it needs corrections / improvements and it 
could be referenced (linked) from the installers' documentation.

Then the Syslinux boot prompt and commands usage could go in a 
separated doc. The prompt usage is _almost_ independent of cfg files 
or menu system.

Then a doc for basic cfg files. IMHO (and for the sake of newbies), 
it should be clear that the basic directives are interpreted with 
independence of the menu system. For newbie users, the simple menu 
"is" Syslinux, so for such new user it is easy to confuse the basic 
directives with the "menu" directives. Appropriate comments and 
references would help clarify them.

IMO, the directives that are related to serial consoles could be 
separated into a new doc, with a reference in syslinux.txt.

Another subsection that might need a separated document could be the 
DISPLAY format, options, files... When a new user - who probably 
knows Syslinux first for the simple menu system - reads about the 
DISPLAY format and files in the current syslinux.txt (or in the 
equivalent wiki pages), it is easy to get confused (as when first 
reading about SAY, for example). If a more clear explanation of the 
different ways to "use" Syslinux is included into syslinux.txt (with 
appropriate references to other docs), then the user can navigate to 
whichever method he wants to learn about: boot prompt command line, 
DISPLAY (msg) files and SAY directives, the simple menu system, the 
complex menu system, the serial console...

By separating syslinux.txt into different documents with respective 
subsections, the main documents would be easier to read and to 
follow, specially by new users but also for advance users and 
developers, allowing to build in knowledge according to the 
necessities. Of course cross-references between documents are 
crucial.

HTH,
Ady.