trac-admin help is illegible due to long lines

[mdaniel@…]

On an 80x25 xterm, the output from trac-admin help is not very legible because the "help text" spills over into the next line where one would expect a command to be.

initenv                                                -- Create and initialize 
a new environment interactively
initenv <projectname> <db> <repospath> <templatepath>  -- Create and initialize 
a new environment from arguments

See?

One suggestion would be to employ newlines and indenting spaces:

initenv
    * Create and initialize lorem ipsum donet ipsum
initenv <projectname> <db> <foo> <bar>
    * Does other cool thing lorem ipsum

[adeason@…]

I attached an example patch. It introduces a new parameter to print_listing() called maxw, which I set to 80 in print_doc(). Right now the patch doesn't really make sure that the text keeps to 80 chars, but none of the help text is over 80 characters in length, so it works now. If someone would like to make it wrap the text to maxw chars, that would probably be better. And also examining the environment for the actual number of columns that should be used would be better.

[adeason@…]

Preliminary patch, puts help descriptions on different lines.

[Christopher Lenz]

The plan for trac-admin is to get rid of those required arguments for initenv and provide an option-based interface instead. This means that the help text would be reorganized a bit: the listing would just contain [options], and the detailled help for initenv would then list the options.

[Christopher Lenz]

#2579 has been marked as duplicate of this ticket.

[Christian Boos]

Maybe we can do a simpler fix for now, which would solve that issue without having to wait for a larger refactoring…

[Christian Boos]

Fix committed in r3367 (simply bypass the print_listing method and print command and description on separate lines).

[Christopher Lenz]

Hmm, why all the extra empty lines?

[Christian Boos]

Readability? I found it was too compact.

Anyway, a better fix would be to have for each command a short and a longer help. The first line will be used in a compact, global, help. The second will be used when asking for help on that specific command.

That's how Mercurial does it, and it's a good model, I think.

e.g. the global help:

$ hg help
Mercurial Distributed SCM

list of commands (use "hg help -v" to show aliases and global options):

 add        add the specified files on the next commit
 annotate   show changeset information per file line
 archive    create unversioned archive of a repository revision
 backout    reverse effect of earlier changeset
 bundle     create a changegroup file
 cat        output the latest or given revisions of files
 clone      make a copy of an existing repository
...

the specific help:

hg add [OPTION]... [FILE]...

add the specified files on the next commit

    Schedule files to be version controlled and added to the repository.

    The files will be added to the repository at the next commit.

    If no names are given, add all files in the repository.

options:

 -I --include  include names matching the given patterns
 -X --exclude  exclude names matching the given patterns

and the corresponding bits of source code:

def add(ui, repo, *pats, **opts):
    """add the specified files on the next commit

    Schedule files to be version controlled and added to the repository.

    The files will be added to the repository at the next commit.

    If no names are given, add all files in the repository.
    """

the options doc come from another data structure:

    ...
    "^add":
        (add,
         [('I', 'include', [], _('include names matching the given patterns')),
          ('X', 'exclude', [], _('exclude names matching the given patterns'))],
         _('hg add [OPTION]... [FILE]...')),
     ...

[Emmanuel Blot]

Readability? I found it was too compact.

-1, it makes the help message hard to read on a small terminal (vertical scrolling…)

Anyway, a better fix would be to have for each command a short and a longer help.

+1 (without the extra spaces from the add example).