60085 - about:commandline

Status: RESOLVED WONTFIX

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

Description

[timeless]

We need a way to output a long list of command line options with detailed 
descriptions (possibly in some way that different types of style sheets would 
display more or less granularity).  This became apparent wrt -compose.

Comment 1

[sairuh (rarely reading bugmail)]

seth has suggested adding a url to the -help content --ie, it could point to
this.

Comment 2

[(not reading, please use [e-mail] instead)]

having about:commandline is a neat idea.

adding alecf to the cc list.

Comment 3

[verah (gone)]

Copying Steve Rudman. We're thinking about creating a document that describes 
the command line options, so we should combine efforts here.

Comment 4

[Viswanath Ramachandran]

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

Comment 5

[verah (gone)]

I'm attaching a first draft of a document listing the command line options that
I know about. Please take a look and let me know:

- what I've left out
- what I've gotten wrong
- where I've written incorrect syntax (missing quotation marks? spaces?)

Thanks!

Comment 6

[verah (gone)]

Attachment: First draft of a summary of command line options

Comment 7

[timeless]

s/Windows (95, 98, and NT) and Linux/most/
s/Netscape 6/Mozilla and derivatives/g <if you don't mind>
empty parameter fields should not have cells
s#or#<i>or</i>#g
<I think I want italic, but i might be wrong. Maybe we want all switches in bold?>

We need to be able to show that parameters are required or optional.

Defined terms should be <a id> and <a href="#">

Command before Result, don't put the cart before the horse ;-)

[Profile Name] [File_Name] either use spaces or use underscores.

Print the ./mozilla-bin version that's too unixy. If we do that now for xp
please file a bug.

JavaScript console should be after chrome.
Editor should be after JavaScript Console (before MailNews)
Version after Help
Splash after version
Installer After Splash
width after Installer, height after width

there's also a -nosplash, and a -quiet.

Someone else will list what you're missing. However, the goal of this bug is for
mozilla to be able to generate a page similar to this, so I guess we'll use your
page as a style guide.

Comment 8

[Alec Flett]

verah - we're not putting a document in the product like this.. your document
looks more like something that belongs on a web site (like www.mozilla.org) -
about:commandline is going to be a runtime-generated document which describes
all commandline options that have been registered with the currently running
mozilla, it's for developers...

Comment 9

[verah (gone)]

Yes, see my original comment above -- we (info design) are creating a document
similar to what this bug is requesting, so I wanted to combine efforts. (Our
document will be posted at DevEdge or other appropriate location.)

Comment 10

[verah (gone)]

Timeless -- thanks for your input; I'll do a second draft soon. I'm thinking
that for my version (as opposed to the about:commandline version) I should list
the desired action ("Start with the Profile Wizard") first, and then the method
of achieving the result. My version is more of a "how to" document;
about:commandline is more of a reference.

I dunno, though... I started out with it the other way around, as you recommend,
and would easily go back to that if people think it looks funny with the cart
before the horse.

Comment 11

[Alec Flett]

verah - all I mean is that this bug is for making something similar to
about:plugins (try it) - not a how-to document or anything.. if you want to
start a new bug for that, or just start the document, feel free.

Comment 12

[verah (gone)]

OK, that' fine... so it seems like you're saying that you don't want the
information I collect about the command line options. Fine, I'll keep it to
myself! (Removing myself from the list of cc's.)

Comment 13

[Dawn Endico]

I don't get it.

Why wouldn't you build this from vera's docs? Why do you want this
as an about: url? Are you going to build the page by querying the dom?

Putting this info into an about url seems fairly useless. Who would ever
think of typing "about:commandline"?

I think it would be a lot more useful as  "mozilla -h" and/or as a help menu
item. Come to think of it, it would be nice to make about:plugins available
from the help menu as well.

Comment 14

[timeless]

The Help menu is very much broken architecture wise. I do have Help>About 
Plugins. But that's _ALL_ I have because we put the about menu into the wrong 
overlay.

about:commandline is an about because we expect it to be dynamic, like plugins, 
the components you have could match features that will never be included in 
netscape6 online help.

The other reason I want it as about: is that the commandline text is really too 
long for -h, there are too many options people might use and there is too much 
information about those options that people might need.

Once we get a good menu overlay architecture (and I think jag is working on xbl 
for it, hyatt and ben know what is needed) hooking up about:plugins, 
about:commandline, and others will be easy. But until then it's a mess.  Maybe 
i'll dig up my javascript that emulates the future XBL so people can try to 
build the menu architecture now.

Comment 15

[Marcia Knous [:marcia]]

Netscape Nav triage team: this is not a Netscape beta stopper.  Info design 
should go ahead and create this document for the website for DevEdge, but not 
prior to putting it in the product.

Comment 16

[Paul Chen]

Marking nsbeta1- bugs as future to get off the radar.

Comment 17

[Brian 'netdragon' Bober]

This would be a good way to solve bug 26761 which is about -version and -help
not working.
-help would bring up about:commandline
-version would bring up about:

The summary of commandline options could be dynamically generated in the future,
but for now I think we should just get it in there. Perhaps there could be a
link on the page to a more detailed description in the help system.

Comment 18

[Ian Pottinger]

adding self to cc list

Comment 19

[Brian 'netdragon' Bober]

Attachment: patch.zip

the zip file contains the path of the locations where the files that are new to
the tree are going, then apply the zip.

After that, run mozilla and try about:commandline and about:sink - That is Bug
122411 - Mozilla does not have a kitchen sink that I included in this patch
since they overlap and therefore, it would be extra work to fix the other
later.

Comment 20

[Brian 'netdragon' Bober]

Sorry, I meant apply the diff, not apply the zip. It's a diff -u.

Comment 21

[Christian :Biesinger (don't email me, ping me on IRC)]

what do we need this for? use "mozilla -help". true, it doesn't work on windows,
but that's bug 26761.

if you really _need_ to implement this, generate it in C++ code and share the
data between nsAppRunner.cpp and this code. Else this _will_ get out of sync.

Comment 22

[Brian 'netdragon' Bober]

Attachment: The about:commandline page - only for viewing

Comment 23

[Brian 'netdragon' Bober]

Some people mentioned that it might be better to have the commandline options on
mozilla.org. For a second, I thought that was a good idea - but after thinking
about it, I realized that it might not be consistant with the version that
people are running. Therefore, having it in the code would be better.

I'll look into what Chris mentioned about sharing it with the C++ code.

Comment 24

[Brian 'netdragon' Bober]

Ignore the the current patch. I am going to make the page dynamically created by
C++.

about:commandline could be brought up for mozilla -help on windows versions
other than windows xp (which seemed to have fixed the problem in bug 26761).

Also, people were mentioning putting commandline options in the help menu, or in
the help system. It could just internally load about:commandline.

Some people say we don't need this, but I would much rather type
about:commandline than type mozilla -help. I imagine many people are like me
(and remember - not everyone using Mozilla prefers using Linux over Windows).
Windows users generally would much rather do it this way since mozilla probably
isn't in their path like it is on linux.

Comment 25

[Alex Bishop]

Someone should look over the wording for this - cc'ing MPT.

I can see a few obvious things myself:

* 'Commandline' (in the heading) should be 'Command Line'.

* It's 'Mac OS X' and not 'Mac OSX'.

* Similarly, it's 'BeOS' not 'Beos'.

Comment 26

[Christian :Biesinger (don't email me, ping me on IRC)]

Why is the font at the bottom different from the rest of the file?

Comment 27

[Blake Ross]

Reassigning to a real person.

Comment 28

[Brian 'netdragon' Bober]

Biesi: Are you still in favor of a dymaically created file? The only issue I
have with that is that it shouldn't be piped directly to the window, but should
be parsed and be placed within an attractive web page to look professional.

Comment 29

[Christian :Biesinger (don't email me, ping me on IRC)]

>Biesi: Are you still in favor of a dymaically created file? 

well, yeah, I am; but I'm not the module owner or anything, and I wouldn't try
to hold up a non-dynamic patch...

Comment 30

[Brian 'netdragon' Bober]

Attachment: mozilla/xpfe/global/resources/content/nsAboutCommandline.html

Let's get this puppy moving. Here is the newest copy of the about:commandline
please make comments on what needs to be changed...

Comment 31

[Brian 'netdragon' Bober]

Attachment: mozilla/xpfe/global/resources/content/nsAboutCommandline.html

The first part of the patch, place in
mozilla/xpfe/global/resources/content/nsAboutCommandline.html

Comments please.

Comment 32

[Brian 'netdragon' Bober]

Attachment: Here is the patch, make sure you put the html file in too.

Please review this regardless of the comments on the html file.

Comment 33

[Henrik Gemal]

Please change "Communicator 4.x" to "Netscape 4.x"

Comment 34

[Henrik Gemal]

And also spell JavaScript correct. It's "JavaScript" not "Javascript"

Comment 35

[Christian :Biesinger (don't email me, ping me on IRC)]

please mention on the page that to use -chat, Chatzilla must be installed. same
for other parameters which require an optional component.

and I don't think you should point to a bugzilla bug in this file. I'd just say
"This is a known bug."

Comment 36

[Henrik Gemal]

"Print the ./mozilla-bin version" should say:
"Prints the Mozilla version. Only available on non Windows platforms."

"Print the information in this table" should say:
"Print the information in this table. Only available on non Windows platforms."

Comment 37

[Alex Bishop]

First paragraph: the order the Windows versions are listed in ("95, 98, ME,
2000, XP and NT") seems strange. "95, 98, ME, NT, 2000 and XP" would make more
sense. And it should be "Mac OS", not "Macintosh", as that's the name of the
operating system. The Unix variants should be listed before BeOS as they're more
common.

The next paragraph gives way too much detail. The important information is that
-help and -version don't work on Windows, not why. Just remove it and place
explainations next to the relevant commands, as Henrik said:

> "Print the ./mozilla-bin version" should say:
> "Prints the Mozilla version. Only available on non Windows platforms."
>
> "Print the information in this table" should say:
> "Print the information in this table. Only available on non Windows
> platforms."

Personally, I would phrase these a little differently though:

"Display the Mozilla version (not available on Windows)."
"Display the information in this table (not available on Windows)."

Use "Display" not "Print". To most people, "Print" involves paper. :-)

Aren't there some command line options missing (e.g. -quiet)?

Finally, some examples of complete commands would be good.

Comment 38

[Brian 'netdragon' Bober]

This is a summary of the command line options from linux

(~/programming/netscape/mozilla/obj-i686-pc-linux-gnu/dist/bin)> mozilla -help
Usage: /usr/lib/mozilla/mozilla-bin [ options ... ] [URL]
       where options include:

GTK options
	--gdk-debug=FLAGS		Gdk debugging flags to set
	--gdk-no-debug=FLAGS		Gdk debugging flags to unset
	--gtk-debug=FLAGS		Gtk+ debugging flags to set
	--gtk-no-debug=FLAGS		Gtk+ debugging flags to unset
	--gtk-module=MODULE		Load an additional Gtk module
X11 options
	--display=DISPLAY		X display to use
	--sync		Make X calls synchronous
	--no-xshm		Don't use X shared memory extension
	--xim-preedit=STYLE
	--xim-status=STYLE
	--g-fatal-warnings		Make all warnings fatal

Mozilla 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 /usr/lib/mozilla/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.
	-UILocale <locale>		Start with <locale> resources as UI Loca
le.
	-contentLocale <locale>		Start with <locale> resources as content
 Locale.
	-remote <command>	Execute <command> in an already running
				Mozilla process.  For more info, see:

		http://www.mozilla.org/unix/remote.html

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

Comment 39

[Brian 'netdragon' Bober]

Attachment: mozilla/xpfe/global/resources/content/nsAboutCommandline.html

This can be used as a placeholder until we hook up the dynamic handler, which
isn't as trivial a task.

Comment 40

[Brian 'netdragon' Bober]

Attachment: New Validated HTML 4.0 Transitional mozilla/xpfe/global/resources/content/nsAboutCommandline.html

Comment 41

[Christian :Biesinger (don't email me, ping me on IRC)]

Comment on attachment 108857 [details]
New Validated HTML 4.0 Transitional mozilla/xpfe/global/resources/content/nsAboutCommandline.html

some comments:
-news: you should mention here as well that mail & newsgroups must be
installed; same for addressbook. but maybe you should rather group them somehow
and mention it above the group.

Note that composer is not optional, so no need to mention that it must be
installed for -edit.

o The hyphen (-) delimits an action type.

what is an action type?


Also, you must get module owner review for this.

Comment 42

[Christian :Biesinger (don't email me, ping me on IRC)]

Comment on attachment 108722 [details] [diff] [review]
Here is the patch, make sure you put the html file in too.

+static const int kRedirTotal = 5; // sizeof(kRedirMap)/sizeof(*kRedirMap)

note, this line of the patch will be rotted as soon as the tree unfreezes.

the patch looks ok to me, but as I said above, get module-owner review (from
law I think)

Comment 43

[Brian 'netdragon' Bober]

I haven't gotten a chance to look at the commandline service, but the service 
needs to hold more information than just the command and its results so we can 
do context-senstive help. (i.e. -help quiet) which displays a lot of 
information. Also the data structures use to store this need to be such that 
the data can be easily extracted to format within tables on web pages, etc.

If you look at attachment 108857 [details], we need the service to have examples, 
information about quirks, listing of parameters with key values that are 
mapped to commands, etc etc.

You can get an idea of what I mean by trying CVS.

Comment 44

[Brian 'netdragon' Bober]

Would a command line parser that also could hold examples, context-senstive 
information, etc be too high-level for nspr?

Comment 45

[Brian 'netdragon' Bober]

Or would it be for XPCOM? We need a better command line service if we want 
other people to use Mozilla technologies to build their apps.

Comment 46

[Brian 'netdragon' Bober]

I added bug 184788 about dynamic processing about:commandline so we can put 
this one in for the moment and mark it fix once the patch is approved.

Comment 47

[Brian 'netdragon' Bober]

Removing helpwanted keyword.
Asking timeless for review.

Comment 48

[timeless]

Comment on attachment 108722 [details] [diff] [review]
Here is the patch, make sure you put the html file in too.

the filename doesn't match most of the other about filenames. get law's r= if
you can, i'll review a dynamic patch but have no interest in a static patch.

Comment 49

[Daniel Wang]

re attachment 108857 [details]
* -p is not case sensitive
* -chrome should be used for chrome loading, url loading should be done
   simply by "mozilla url"
* I hate the [table of contents] links, can we get rid of 'em?
* We should add info on -compose parameters
* We should link -remote to the remote command page

see bug 58313 attachment 122708 [details]

Comment 50

[Justin Wood (:Callek)]

Ben, is this easier or harder after the commandline work you have done (or started?)

I also assume you would [as well] like it dynamically populated rather than
any-sort-of static page.