[syslinux] submenus and menu title

[Gene Cumm]

On Tue, Sep 18, 2012 at 8:32 PM, Ady <ady-sf at hotmail.com> wrote:
> Hello Gene,
>
> I think that submenus involve many details that are not necessary for
> all users. Currently almost no information about submenus is
> documented, except the mention of the existence of a few directives.

Aside from cleaning up and ensuring items like the fallbacks are
documented, I'm not sure what else there is other than examples.

> In my case, it took me "too much" time to understand the "oddities" I
> was seeing. Even a developer as yourself, with experience in
> Syslinux, was unaware of some of those fallback rules we are
> covering.

I typically consider myself a contributor.  I normally avoid the menu
system except to use "MENU LABEL"s for pretty names.  As I result, I
was using doc/menu.txt but that's a bit dated.  However, the fallback
rules are very straight forward to add.

> To mention just some points to be documented, the potential
> restrictions for "tagname", or its equivalent use as "label", or
> examples for
>  [MENU] INCLUDE filename.cfg [tagname]
> in addition to the sample cases I presented here in this thread, or
> even multiple levels of submenus, or using other alternatives
> methods. I think it's too much to add to menu.txt.

I'd say the rules/syntax should be clearly but concisely explained in
menu.txt and should list the directive and its required and optional
arguments, the valid context (LABEL, top menu, submenu or both top and
sub menus), and an explanation of its functions and rules, including
fallback rules.

> This is not the only matter that needs more documentation for the
> user (author of cfg files). IMHO, adding references (whether in text
> files as "read some_file.txt for more info about submenus", or in the
> wiki as internal links) generates a main (already "long") menu.txt
> that is easier to read and follow, specially for newcomers. A
> separate document would provide more info for those users
> specifically interested. The reader not interested in using submenus
> would continue reading the main document about the configuration of
> [vesa]menu.c32 with a more natural flow.

I'd say this falls more into the idea of example configs.  menu.txt
should explain it all however, yes, there are some circumstances where
it's easier to go into more detail with examples.

> In any case, after 2 months of presenting here my request /
> suggestion, I have no indication whether it is going to be
> implemented some time in the foreseeable future, even after
> summarizing it in one email.

I'm will admit that I misunderstood some of what you were trying to
explain and what was going on.

> Please don't misunderstand me. I'm not complaining, at all. I just
> would rather have an indication that I'm not wasting my (and yours,
> and probably others') time with this issue.
>
> I have already prepared a "media wiki table" with the fallback rules,
> and I can easily convert it to a text-only table for inclusion in a

This seems quite unnecessary.  It's just two straight forward
prioritized lists.  About 1 line each.

> text file (to be displayed in some mono-space font, for better
> clarity). This is _almost_ independent of the improvements I am
> suggesting. If the improvements are implemented, I'll gladly test
> them again (not only with the 8 cases I presented here but also with
> all the others I have seen in live CDs, and whichever other case I
> can think about), so to present accurate and updated documentation
> and feedback.
>
> I can help with documentation, but I cannot implement my suggestion
> by myself.
>
> TIA,
> Ady.