[syslinux] correct "--help' options

[Gene Cumm]

On Sat, Sep 1, 2012 at 5:56 AM, Ady Ady <ady-sf at hotmail.com> wrote:
>> Date: Fri, 31 Aug 2012 22:32:18 -0400
>> From: gene.cumm at gmail.com
>> To: syslinux at zytor.com
>> Subject: Re: [syslinux] correct "--help' options
>>
>> On Fri, Aug 31, 2012 at 8:46 PM, Ady Ady <ady-sf at hotmail.com> wrote:
>> >
>> > Hello hpa,
>> >
>> > When running each ldlinux.sys installer:
>> > extlinux
>> > syslinux
>> > syslinux[64].exe
>> > syslinux.com
>> >
>> > with the "--help" argument, the results are different, depending on
>> > the specific installer.
>>
>> As each accepts different options.
>>
> Yes; I'm referring to the ones in common, such as those in the examples.
>
>
>> > Under the Linux-based installer(s):
>> > --once=... Execute a command once upon boot
>> >
>> > while for the others:
>> > --once=... -o Execute a command once upon boot
>> >
>> > Note that the "-o" is missing under Linux.
>>
>> It should not show under the syslinux installers (linux/syslinux and
>> mtools/syslinux). I believe this is historical as it could also be
>> used for --offset.
>>
>  Sorry, that makes no much sense to me. It can only lead to confusions.
>  "--offset" is "-t", and the "short" common options shouldn't be used

Yes, that's what it is currently.  My first sentence refers to current
behaviors observed on 4.05.

>  differently in each installer. Also "--offset" doesn't appear for EXTLINUX.

It should not.

Digression for clarity:
Syslinux is the name of the project.
EXTLINUX is the name of the now-defunct (as of 4.00) boot loader for
ext* whose functionality was rolled into SYSLINUX.
SYSLINUX is the name of the disk-based boot loader for FAT* and (as of
4.00) ext* and btrfs.
extlinux is the installer for mounted file systems which previously
didn't work with FAT*.
syslinux (as linux/syslinux and mtools/syslinux) is the installer for
unmounted FAT* file systems

CamelCase for the project; ALL_CAPS for the boot loaders; lower_case
for the installers.

extlinux uses the kernel to find where the beginning of the file
system is.  --offset is used with syslinux to instruct it where the
beginning of the file system is, if the offset is not 0.

>  All this makes it more difficult for the final user and for documentation,
>  and easier to mess up when developing. It also makes the statement "EXTLINUX
>  is like SYSLINUX but for mounted fs" more inaccurate.
>
>  The only reason would be if "-o" was actually used for "--offset" in
>  "recent" stable versions of (the installer of) syslinux, in case it was
>  used in some script. Other than that possibility, not using "-o" for one

Historically, only short options existed.  -o was used up to 3.86 for
the offset.

>  installer just invites for problems. The alternative would be not to use
>  "-o" in none of the installers.

This probably would help prevent confusion.

>> > I haven't tested whether "-o" is actually working or not in any of the
>> > installers. It would be convenient to test and unify both:
>> > _ the actual behavior of "<installer> -o", and;
>> > _ the "--help" screen.
>> >
>> > A similar example is
>> > --directory -d Directory for installation target
>> >
>> > which appears after "syslinux --help" but not after "extlinux --help".
>> > Does extlinux support "--directory"?
>>
>> It doesn't need to. That's what the path parameter for extlinux is for.
>  I guess I need to experiment with EXTLINUX more, because I don't exactly
>  understand the meaning of that.

>From the man page:
  extlinux [options] directory

This directory is where ldlinux.sys is dropped.  It's also the first
directory search for a config file.  It also dictates the file system
into which the first sector boot code is installed.

>> > In addition to those requests, I'd like to know if there is any specific
>> > "logic" for the order of appearance of the options when running
>> > "<installer> --help".
>>
>> Perhaps libinstaller/syslxopt.c:usage() needs to have the common
>> options resorted.
>>
>> --
>> -Gene
>  At least "some" kind of logic would make it easier for the final user (who
>  needs the "--help" screen). For example (and I also have in mind other
>  different possible sorting orders, not just this one, so this is just one
>  idea among several), first the options that are common to the different
>  installers, and then the specific ones, alphabetically sorted.
>  But before re-sorting, the common options should be really common.

If sorted, the most logical decision is to use the long option within
each category.  With regards to common options first, specific options
first or just mix them, that's a wide debate.  There are some apps
where I see the specific first while others the common first.

-- 
-Gene