[syslinux] Patching doc/syslinux.txt, partialy because #647603 on Debian

[Ferenc Wagner]

Regid Ichira <regid23 at yahoo.com> writes:

> On Sat, 12/10/11, Gene Cumm <gene cumm gmail com> wrote:
>
>> On Thu, Dec 8, 2011 at 20:06, Regid Ichira <regid23 at yahoo.com> wrote:
>>
>>> My reason for patching circa line 225 is that I think it is
>>> clearer.
>> 
>> I'm not sure why "default" doesn't appear clear.
>
> To me it wasn't clear what is the context in which the word "default"
> is required.  Actually, while writing this response, I am still
> confused.  By the the next few lines it appears to be tied to the file
> name extension. Yet, if I write a LINUX command then what will be
> taken as a default? Is it that the label will be taken as a linux
> image? Why is a default required with a LINUX command?

You are truly confused, and not without a reason, I have to say.  It may
be because we aren't native English speakers, but I agree that the
wording of this section is unfortunate.  Let me quote it:

    The following commands are available after a LABEL statement:

    LINUX image                 - Linux kernel image (default)
    BOOT image                  - Bootstrap program (.bs, .bin)
    BSS image                   - BSS image (.bss)
    PXE image                   - PXE Network Bootstrap Program (.0)
    FDIMAGE image               - Floppy disk image (.img)
    COMBOOT image               - COMBOOT program (.com, .cbt)
    COM32 image                 - COM32 program (.c32)
    CONFIG image                - New configuration file
        Using one of these keywords instead of KERNEL forces the
        filetype, regardless of the filename.

What the heck does (default) mean at the end of the first line?  The
other lines (except the last?) contain extensions, which "default"
isn't.  So it should be "none of the below", which sounds awkward.  I'd
put it at the end of the list with (none of the above).  On the other
hand, mentioning extensions here, where they explicitly don't matter,
may not be the best practice, even if they make sense in hindsight,
after reading the whole document.

The confusion stems from the fact that KERNEL and DEFAULT set the
command line, which then deduces the image type from its filename
extension (as described later in syslinux.txt).  The command line even
adds various extensions if the specified file can't be found, but only
when given interactively (if I read the documentation right).

It's a pity that this functionality isn't optional on the command line,
ie. that LINUX, BOOT, BSS etc. aren't regular Syslinux commands.  That
would make documenting them much simpler.  And also, what if in a
recovery situation you're stuck at the command line with a vmlinuz-3.0
waiting to be booted?  (OK, this particular extension shouldn't be a
problem, but you get the idea.)

> I think the documentation should describe accurately the current
> actions of the software.

In such a world there would be no software errors by definition. :)
-- 
Regards,
Feri.