60265 - command line -help needs formatting help

Status: RESOLVED INCOMPLETE

(Core Graveyard :: Cmd-line Features, defect, P3)

Description

[sairuh (rarely reading bugmail)]

thx to Andrew Phillips for pointing this out. the output for -help needs some
formatting, since the [tabbed] distances are inconsitent btwn the parameters and
their corresponding descriptions. below is an example from a linux build
[2000.11.15.08 mozilla trunk] --i assume this is also an issue on win32, but
cannot verify presently due to bug 26761.

this is cosmetic. but if we could tighten up on the whitespace and make the
wording pithier, that would ameliorate things here.

./mozilla -help
<-- snipped out startup stuff -->
Usage: ./mozilla-bin [ options ... ] [URL]
       where options include:

        -height <value>         Set height of startup window to <value>.
        -h or -help             Print this message.
        -installer              Start with 4.x migration window.
        -width <value>          Set width of startup window to <value>.
        -v or -version          Print ./mozilla-bin version.
        -CreateProfile <profile>                Create and start with <profile>.
        -P <profile>            Start with <profile>.
        -ProfileWizard          Start with profile wizard.
        -ProfileManager         Start with profile manager.
        -SelectProfile          Start with profile selection dialog.
        -splash         Enable splash screen.
        -compose <url>          Start with messenger compose.
        -edit <url>             Start with editor.
        -mail           Start with mail.
        -chrome <url>           Start with browser.
        -addressbook            Start with the addressbook.
        -chat           Start with an IRC chat client
        -jsconsole              Start with Javascript Console
        -news           Start with news.

Comment 1

[sairuh (rarely reading bugmail)]

forgot to add: there appears to be a fixed number a tabs btwn the parameters and
their descriptions.

Comment 2

[verah (gone)]

Copying Steve Rudman.

Comment 3

[André Dahlqvist]

Yes, their position is decided by the defines HELP_SPACER_1 and HELP_SPACER_2
which are set to "\t" and "\t\t". Would it perhaps be better to use just a few
spaces? With tabs a lot of screenspace is lost. I can volunteer to fix this if
you guys have more important things to worry about. Right now I'm adding a help
text for -remote anyway, so I'm in this part of the code right now.

Comment 4

[André Dahlqvist]

Attachment: Patch which aligns the description of -splash and -quiet correctly

Comment 5

[timeless]

 #define HELP_SPACER_2   "\t\t"
+#define HELP_SPACER_3  "\t\t\t"
:-( almost perfect. Can you fix this so they line up? [i suspect there's a tab 
in the file...]

Comment 6

[André Dahlqvist]

Attachment: A second version of the patch which fixes the error timeless pointed out

Comment 7

[André Dahlqvist]

How about this:

What if we change the first TAB to 2 spaces instead, and add another tab to the
descriptions that need it? The whitespace on the left isn't doing any good, and
is better used between the options and their descriptions. Since we are removing
stuff from the left side we can still keep well inside the 80 column limit too.

Using this we could easily get help output that would look like this:

Usage: ./mozilla-bin [ options ... ] [URL]
where options include:

  -height <value> 		Set height of startup window to <value>.
  -h or -help             	Print this message.
  -installer              	Start with 4.x migration window.
  -width <value> 		Set width of startup window to <value>.
  -v or -version          	Print ./mozilla-bin version.
  -CreateProfile <profile> 	Create and start with <profile>.
  -P <profile> 			Start with <profile>.
  -ProfileWizard          	Start with profile wizard.
  -ProfileManager         	Start with profile manager.
  -SelectProfile          	Start with profile selection dialog.
  -splash         		Enable splash screen.
  -compose <url> 		Start with messenger compose.
  -edit <url> 			Start with editor.
  -mail           		Start with mail.
  -chrome <url> 		Start with browser.
  -addressbook            	Start with the addressbook.
  -chat           		Start with an IRC chat client
  -jsconsole              	Start with Javascript Console
  -news           		Start with news.

[Lets hope that will come out the way I typed it in this textwindow]

If this sound insteresting to you I can provide a patch which does this.

Comment 8

[sairuh (rarely reading bugmail)]

andre, that looks good!

Comment 9

[timeless]

Yes two spaces makes sense to me, but let's quickly compare w/ other silly 
apps. <offtopic context="application/x-others">
wget uses two spaces:

Usage: wget [OPTION]... [URL]...

Mandatory arguments to long options are mandatory for short options too.

Startup:
  -V,  --version           display the version of Wget and exit.
  -h,  --help              print this help.
  -b,  --background        go to background after startup.
  -e,  --execute=COMMAND   execute a `.wgetrc' command.

Logging and input file:
  -o,  --output-file=FILE     log messages to FILE.
  -a,  --append-output=FILE   append messages to FILE.
  -d,  --debug                print debug output.
  -q,  --quiet                quiet (no output).
  -v,  --verbose              be verbose (this is the default).

Actually, it also groups output. We should consider that.
pico uses "\t", gmake uses "  ".

bash-2.03$ gzip --help
gzip 1.2.4 (18 Aug 93)
usage: gzip [-cdfhlLnNrtvV19] [-S suffix] [file ...]
 -c --stdout      write on standard output, keep original files unchanged
...
 -r --recursive   operate recursively on directories
 -S .suf  --suffix .suf     use suffix .suf on compressed files
 -t --test        test compressed file integrity

" " with bad allignment for suffix.
wget avoided this by "Mandatory arguments to long options are mandatory for 
short options too."
Windows.
dir /? uses "  " but with a twist:

[cmd.exe] dir /?
Displays a list of files and subdirectories in a directory.

DIR [drive:][path][filename] [/A[[:]attributes]] [/B] [/C] [/D] [/L] [/N]
  [/O[[:]sortorder]] [/P] [/Q] [/S] [/T[[:]timefield]] [/W] [/X] [/4]

  [drive:][path][filename]
              Specifies drive, directory, and/or files to list.

  /A          Displays files with specified attributes.
  attributes   D  Directories                R  Read-only files
               H  Hidden files               A  Files ready for archiving
...
  /B          Uses bare format (no heading information or summary).
  /C          Display the thousand separator in file sizes.  This is the
              default.  Use /-C to disable display of separator.

Here, params are on lower lines and help for a switch can have multiple lines.

D:\CVS\sbh\mozilla>edit /?

MS-DOS Editor   Version 2.0.026   Copyright (c) Microsoft Corp 1995.

EDIT [/B] [/H] [/R] [/S] [/<nnn>] [/?] [file(s)]

  /B       - Forces monochrome mode.
...
  /<nnn>   - Load binary file(s), wrapping lines to <nnn> characters wide.
  /?       - Displays this help screen.
The dash isn't needed.
</offtopic>
Now to your proposal. Overall, it's great. We might later consider segmenting 
the help, but since it's already kind of grouped that's just adding extra print 
statements.

Please include:
  -chrome <url>                 Start with specified chrome.
Let's be consistent:
  -jsconsole                    Start with Javascript Console*
Always use a period at the end of a statement. or the other way. [3/4 of my 
examples use periods]

Do you need someone to check your patches in when they're r+sr'd?

Comment 10

[André Dahlqvist]

> Do you need someone to check your patches in when they're r+sr'd?

Yes, I will be needing that.

And thanks for your comments, they will be helpful when I create the patch.
Expect a patch tomorrow.

Comment 11

[Viswanath Ramachandran]

Since Don has left, Vishy is taking his bugs in bulk, pending reassignment.
thanks,
	Vishy

Comment 12

[sairuh (rarely reading bugmail)]

here's the -help output i get from 2000.12.11.12 [linux verif comm build]. for
some reason [known?] my debug build from today doesn't display all the [mozilla]
options...

Usage: ./mozilla-bin [ options ... ] [URL]
       where options include:

        -height <value>         Set height of startup window to <value>.
        -h or -help             Print this message.
        -installer              Start with 4.x migration window.
        -width <value>          Set width of startup window to <value>.
        -v or -version          Print ./mozilla-bin version.
        -CreateProfile <profile>                Create and start with <profile>.
        -P <profile>            Start with <profile>.
        -ProfileWizard          Start with profile wizard.
        -ProfileManager         Start with profile manager.
        -SelectProfile          Start with profile selection dialog.
        -remote <command>       Execute <command> in an already running
                                Mozilla process.  For more info, see:

                http://home.netscape.com/newsref/std/x-remote.html

        -splash         Enable splash screen.
        -compose <url>          Start with messenger compose.
        -edit <url>             Start with editor.
        -mail           Start with mail.
        -chrome <url>           Load the specified chrome.
        -addressbook            Start with the addressbook.
        -jsconsole              Start with Javascript Console
        -news           Start with news.
        -aim            Start with Instant Messenger

Comment 13

[sairuh (rarely reading bugmail)]

ooops: forgot to say that the above info was requested by verah... methinks
she's also seeking the current -help output for win32 bits [blocked by bug
26761].

Comment 14

[verah (gone)]

I learned from Bill Law that the Linux cmd. line options are identical to the
ones for Windows, though there are a couple of additional ones for Windows (and
he's going to let me know what they are RSN).

Comment 15

[Bill Law]

Windows also supports "-quiet" (same as -nosplash) and "-console" (dynamically
creates a Windows console that will show debugging info messages while the
program runs).

BTW, check out the other bugs against this component.  It seems -width and
-height don't work (if that matters).

Comment 16

[Marcia Knous [:marcia]]

Netscape Nav triage team: this is not a Netscape beta stopper.

Comment 17

[sairuh (rarely reading bugmail)]

bill, did you want to take this? if not, feel free to reassign...

Comment 18

[André Dahlqvist]

[sorry for the long delay with this patch]

Below is a first stab at a patch to format the helptext correctly. This is the
output I get for 'mozilla --help' (on Linux) with this patch applied:

Usage: ./mozilla-bin [ options ... ] [URL]

Options:
  -height <value>               Set height of startup window to <value>.
  -h or -help                   Print this message.
  -installer                    Start with 4.x migration window.
  -width <value>                Set width of startup window to <value>.
  -v or -version                Print ./mozilla-bin version.
  -CreateProfile <profile>      Create <profile>.
  -P <profile>                  Start with <profile>.
  -ProfileWizard                Start with profile wizard.
  -ProfileManager               Start with profile manager.
  -SelectProfile                Start with profile selection dialog.
  -remote <command>             Execute <command> in an already running
                                Mozilla process.  For more info, see:

                        http://home.netscape.com/newsref/std/x-remote.html

  -splash                       Enable splash screen.
  -compose <url>                        Start with messenger compose.
  -edit <url>                   Start with editor.
  -mail                 Start with mail.
  -chrome <url>                 Load the specified chrome.
  -addressbook                  Start with the addressbook.
  -jsconsole                    Start with Javascript Console
  -news                 Start with news.

The URL can't be aligned with the rest of the descriptions without crossing the
80-column barrier.

As you can see, the descriptions for '-mail' and '-news' are not aligned
correctly. The reason for this is that these command line switches are shorter
than 6 characters, and would therefore require four tabs after them to get their
descriptions aliged with the other ones.

All of the options before '-compose <url>' are printed from the DumpHelp()
function in nsAppRunner.cpp. The rest of them (like '-mail', '-news' and '-edit
<url>') are printed in this piece of code from DumpArbitraryHelp() in
nsAppRunner.cpp:

 if ((const char *)helpText) {
   printf("%s%s\n",HELP_SPACER_2,(const char *)helpText);
 }

This makes it harder to align them individually like I did in nsAppRunner.cpp.
My patch changes HELP_SPACER_2 to HELP_SPACER_3, which was necessary since much
whitespace has been removed from the left side. But in order to get '-mail' and
'-news' (and other short command line switches that might be added) aligned
correctly we need to check if the command line switch is longer than 6
characters. Pseudo code:

if "Command line switch is smaller than 6 chars":
  printf("%s%s\n",HELP_SPACER_4,(const char *)helpText);
else:
  printf("%s%s\n",HELP_SPACER_3,(const char *)helpText);

This is of course easy to add to my patch, but the problem is that I don't know
how I can access the string that holds the command line switch. Can I access it
in nsAppRunner.cpp just like I can access helpText? Some grepping revealed that
the description for -news is set on mailnews/news/src/nsNntpService.cpp:1519:

CMDLINEHANDLER3_IMPL(nsNntpService,"-news","general.startup.news","Start with
news.",NS_NEWSSTARTUPHANDLER_CONTRACTID,"News Cmd Line Handler", PR_FALSE,"",
PR_TRUE)

But how do I access the '-news' string in nsAppRunner.cpp?

[Sorry for the babbling]

Comment 19

[André Dahlqvist]

Attachment: First stab at a patch to align the help text

Comment 20

[Paul Chen]

Marking nsbeta1- bugs as future to get off the radar

Comment 21

[André Dahlqvist]

Attachment: Patch that aligns everything printed from nsAppRunner.cpp

Comment 22

[Brian 'netdragon' Bober]

I fixed this issue in bug: http://bugzilla.mozilla.org/show_bug.cgi?id=26761
Please don't check in the patch above because its obsolete.

Comment 23

[Wayne Mery (:wsmwk)]

(In reply to comment #22)
> I fixed this issue in bug 26761
> Please don't check in the patch above because its obsolete.

so what is left to be done in this bug - nothing/