[syslinux] Syslinux docs for core variants and installers

[Gene Cumm]

On Oct 28, 2012 6:21 PM, "Ady" <ady-sf at hotmail.com> wrote:
>
>
> 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

Please note first and foremost that I have an opinion with what I feel
are fair reasons for such and seeking feedback from others in the
community and a more definitive decision.

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

Agreed.  This is another consideration of why and how to split/resort.
 The top sections should contain the most basic/relevant information
needed by the most users.

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

Agreed.

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

IMO, all installers (except the isohybrid installers) deserve to be
addressed together since you'd otherwise end up listing items 4 times.

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

It is certainly independent of the menu.

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

A statement that they are considered comments and reference menu.txt
for use in (vesa)menu.c32 should suffice.

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

Since they are a part of the core's config processing and don't feel
like they take up that much space, I feel they should stay with the
other core config directives in one contiguous block BUT serve a lower
priority and should be in a later subsection of config directives.  At
the moment, this is how I've broken the config section up.

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

This one does seem longer and less used.

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

Splitting and resorting.  I'm also trying to think in terms of
manpages, ie having a syslinux.cfg.5 manpage.

--
-Gene