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

[Matt Mackall]

On Tue, 2012-01-10 at 15:41 +0100, Olav Reinert wrote:
> 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.

I see. I think I'd actually lean towards turning shrinking off entirely
then in the interest of simplicity.

> 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:

Changing the default here is also acceptable, in terms of keeping the
mini in minirst.

> [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

Yeah, I've never liked that. We waste 55 lines in stock hg just to tell
you about a few boring or trivial aliases:

 annotate, blame:
 commit, ci:
 copy, cp:
 identify, id:
 import, patch:
 incoming, in:
 log, history:
 outgoing, out:
 remove, rm:
 rename, move, mv:
 showconfig, debugconfig:
 status, st:
 summary, sum:
 update, up, checkout, co:

Some of these (like history) we shouldn't even be advertising. The rest
can easily be discovered just by running 'hg help <command I don't
know>' or 'hg help <command I want aliases for>'. I'm fine with dropping
this version of the list entirely though maybe other people disagree.

> [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.

-- 
Mathematics is the supreme nostalgia of our time.