trac-admin --help falsely advertises extra initenv parameter

[Dave Abrahams <dave@…>]

console.py

@@ -447 +447 @@
     ## Initenv
     _help_initenv = [('initenv',
                       'Create and initialize a new environment interactively'),
-                     ('initenv <projectname> <db> <repostype> <repospath> <templatepath>',
+                     ('initenv <projectname> <db> <repostype> <repospath>',
                       'Create and initialize a new environment from arguments')]
 
     def do_initdb(self, line):

Fixes it.

While you're in there, it would be good to document these parameters more completely in the —help; you can't get it right without running it interactively to find out, e.g. what a legal database descriptor looks like. And even then, you won't really know your available options.

[osimons <simon-code@…>]

Verified - I found that today as well when upgrading some of my code from 0.10 to 0.11.

It is there for 0.10, but the argument and supporting code has been removed from the 0.11 do_initenv() method in trac.admin.console.

[Christian Boos]

Wasn't that fixed in r5790?

[Eli Carter]

Replying to cboos:

Wasn't that fixed in r5790?

It was. The unittests were improved in r5791 and r5792. The help text itself wasn't improved with more information though.

I'm going to close this ticket since the main issue is addressed. Improving the help text should be a separate issue.

[Dave Abrahams <dave@…>]

Replying to ecarter:

I'm going to close this ticket since the main issue is addressed. Improving the help text should be a separate issue.

What main issue? The whole point of my report was the help text! Are you asking me to enter another ticket with some rephrasing of the content? How could I possibly make the point of my report clearer?

[Eli Carter]

Replying to Dave Abrahams <dave@boost-consulting.com>:

Replying to ecarter:

I'm going to close this ticket since the main issue is addressed. Improving the help text should be a separate issue.

What main issue? The whole point of my report was the help text! Are you asking me to enter another ticket with some rephrasing of the content? How could I possibly make the point of my report clearer?

No, you're right. I should not have closed the ticket, and I apologize.

[Christian Boos]

To the specifics of this request:

While you're in there, it would be good to document these parameters more completely in the —help; you can't get it right without running it interactively to find out, e.g. what a legal database descriptor looks like. And even then, you won't really know your available options.

In general, I'd say that the command line is not the place for detailed documentation. For complex topics (like the format of a database descriptor), it should simply point to the appropriate wiki page describing it (TracEnvironment in this case).

Now of course here we have a special case, as this is the command for creating the Trac instance, so we can't tell the user to look for detailed documentation in Trac ;-)

I see several options:

1. point to the raw trac/wiki/default-page/TracEnvironment file which is mostly readable as plain text if we reformat it a bit (perhaps not easily doable - egg installations and such)
2. point to the INSTALL file where this information is duplicated (probably same issue as above for the location of the file)
3. point to t.e.o. ​http://trac.edgewall.org/wiki/0.11/TracEnvironment - but what about people installing Trac and not connected to the net? (well, if you want my opinion, they're in trouble anyway)
4. add an installation guide (e.g. the TracGuide converted to PDF), as this was requested a few times already. But remark 1. applies here as well.

Thoughts?

[Eli Carter]

Replying to cboos:

In general, I'd say that the command line is not the place for detailed documentation. For complex topics (like the format of a database descriptor), it should simply point to the appropriate wiki page describing it (TracEnvironment in this case).

When running interactively, there's a default listed. I think we should support those defaults on the commandline, and we should list those defaults in the help. That should address a large chunk of the issue.

Now of course here we have a special case, as this is the command for creating the Trac instance, so we can't tell the user to look for detailed documentation in Trac ;-)

I see several options:

1. point to the raw trac/wiki/default-page/TracEnvironment file which is mostly readable as plain text if we reformat it a bit (perhaps not easily doable - egg installations and such)
2. point to the INSTALL file where this information is duplicated (probably same issue as above for the location of the file)
3. point to t.e.o. ​http://trac.edgewall.org/wiki/0.11/TracEnvironment - but what about people installing Trac and not connected to the net? (well, if you want my opinion, they're in trouble anyway)
4. add an installation guide (e.g. the TracGuide converted to PDF), as this was requested a few times already. But remark 1. applies here as well.

Thoughts?

Other possibilities:

5. add a man page for 'trac' (intro), 'trac-admin', and 'tracd' (though I don't know how that works with an egg.)
6. add an option to trac-admin to output detailed info to a file? (pdf, html, or…)

I think that providing an html rendering of TracEnvironment would be preferable to the raw form.

As for egg installs; if we marked the egg as 'not zip safe' (IIRC) won't the files then be accessible after an install? At that point, we should be able to reference a supplied documentation file. I'm not sure what the tradeoffs would be for that.

[Eli Carter]

Hmmm…. I'm starting to think that the initenv command's help needs to provide a bit more functionality. I think that having trac-admin help give a very brief overview is nice, but trac-admin help <command> should give more information.

So, the output of trac-admin help should change to drop the blank lines and the lines starting with '—'. Then, trac-admin help permission would give the full help text for all the permission sub-commands. Then, trac-admin help initenv could be changed to list the supported version control types, with a help text for those, and the same for the supported database types.

We're going to be making a lot of first-impressions with trac-admin, so I think that for this tool, the commandline is the place for detailed documentation.

Thoughts?

[Emmanuel Blot]

Replying to ecarter:

Thoughts?

+1. Something like the output of the 'svn' help system seems fair.

[anonymous]

Replying to ecarter:

Thoughts?

+1 …since I'm fighting with an initenv command line as we speak :/

[gt4329b]

The correct non-interactive command line (as of today, anyway):

trac-admin <PATH TO NEW TRAC ENV> initenv <NAME> sqlite:db/trac.db svn <PATH TO SVN REPOSITORY>

This assumes, of course, that you want to use the initenv defaults (sqlite and svn) — if not, hunt through the docs and substitute your changes.

(I was anonymous/comment 10, FWIW)

[ThurnerRupert]

wouldn't the small fix proposed by dave be sufficient for 0.11, maybe extended with "run it interactively for the first time" at the bottom of the help text?

[ThurnerRupert]

nobody with appropriate rights seems to apply it, its not a bug, so it seems to block 0.11 unecessarily …

[Noah Kantrowitz]

This is clearly a bug.

[ThurnerRupert]

you have commit right, could you please apply the original fix then?

[techtonik <techtonik@…>]

Replying to ThurnerRupert: Original fix is already applied in r5790 I suggest closing this bug report about "false advertisement" and opening a new one about "Need detailed help information about commands in trac-admin". It becomes harder to to figure out what the talk is about.

[Christian Boos]

As eli said in comment:3, the false advertising part was fixed.

We can keep that ticket for the topic of improving the interactive help for the command line tool, but that's a 0.12 topic.

[Christian Boos]

Replying to cboos:

We can keep that ticket for the topic of improving the interactive help for the command line tool, but that's a 0.12 topic.

… and indeed the infrastructure for providing more detailed help for TracAdmin commands is now on trunk, see r7681 and #7788.