[PATCH 2 of 2 STABLE] Consistent help text formatting (indentation)

[Olav Reinert]

On 10. jan 2012, at 03.45, Matt Mackall wrote:

> On Mon, 2012-01-09 at 17:31 +0100, Olav Reinert wrote:
>> # HG changeset patch
>> # User Olav Reinert <seroton10 at gmail.com>
>> # Date 1326126555 -3600
>> # Node ID dcd680d8410b6a1b4c9f6ef67271ec4789f5e34c
>> # Parent  c9f8671b5081abd8891dd8d78ded241ae1c491db
>> Consistent help text formatting (indentation)
> 
> (FYI, I think it's great that you're furthering the job I started of
> doiing more RSTification of the built-in help)

Thanks - good to know.

> Spaces around operators, please.

OK

> 
>> +                topics.append('     '+h[f])
>>             else:
>> -                ui.write('%s\n' % (util.wrap(h[f], textwidth,
>> -                                             initindent=' %-*s   ' % (m, f),
>> -                                             hangindent=' ' * (m + 4))))
>> +                topics.append(":%s: %s" % (f, h[f]))
>> +        rstopt = { 'fieldshrink':False, 'fieldwidth':13, 'definitionmargin':False }
> 
> Where did 13 come from?
> 
> What's wrong with the output without these formatting hints?

The 'fieldshrink' option applies to field lists, and setting it to False stops minirst from shrinking the width of the left column to fit the content. This makes it possible to write multiple field lists that are column-aligned, independent of content.

The 'fieldwidth' option overrides the default maximum width of the left column of field lists. Currently, the default width in minirst is 12. However, this is too narrow, as it will produce output like this:

[quote]
additional help topics:

 config      Configuration Files
 dates       Date Formats
 diffs       Diff Formats
 environment
             Environment Variables
 extensions  Using additional features
 filesets    Specifying File Sets
[endquote]

rst2html uses a default field list width of 14 - see <http://docutils.sourceforge.net/docs/user/config.html#field-name-limit>. I considered changing minirst to also use 14 as a default, but didn't feel brave enough for that. Instead I added the 'fieldwidth' option to allow overriding the default. 13 is the smallest field width that avoids unnecessary line breaks in the help text, and the output resembles the original  closely.

Finally, when formatting the command list using RST, if 'definitionmargin':False is omitted, the output of "hg help -v" will look like this:

[quote]
14:51:11 ~/Code/mercurial $ ./hg help -v
Mercurial Distributed SCM

list of commands:

 add:
      add the specified files on the next commit

 addremove:
      add all new files, delete all missing files

 annotate, blame:
      show changeset information by line for each file

 archive:
      create an unversioned archive of a repository revision
[endquote]

The 'definitionmargin':False option suppresses the empty line between definitions, thus making the output appear as before using RST.

> Ideally we generate the output by generating one large RST text and
> doing one large format + write. That way when we finally implement 'hg
> help --html/--rst', it just works. Also, this is what the web interface
> will eventually want.

OK, I will rework the patch to align with this goal.