[PATCH] help: indicate help omitting if help document is not fully displayed

[Martin Geisler]

FUJIWARA Katsunori <foozy at lares.dti.ne.jp> writes:

> # HG changeset patch
> # User FUJIWARA Katsunori <foozy at lares.dti.ne.jp>
> # Date 1342015589 -32400
> # Node ID c9dc22b313bf3ed8d8f81709568cf31230b1b8db
> # Parent  2e13c1bd34dc6afda8fc7cfa22a8cd658276724f
> help: indicate help omitting if help document is not fully displayed

This is a good feature! Infact I thought we already had some logic to
detect when stuff was pruned and so show the "use hg help -v" message.
Seems we don't have that after all...

> +def indicateomitted(rst, name, verbose):
> +    if not verbose:
> +        for text in rst:
> +            if '.. container:: verbose' in text:
> +                msg = _("(detailed description is omitted."
> +                        " use :hg:`help -v %s` to show detail.)") % name
> +                rst.append('\n%s\n\n' % msg)
> +                return

You should not parse the reStructuredText like that, it should only be
minirst that parses it. For example, the above will fail if you have

  starting a literal block::

    .. container:: verbose

       not really verbose text after all

You should instead look at the pruned list retuned by minirst.format:

    keep = ui.verbose and ['verbose'] or []
    formatted, pruned = minirst.format(''.join(rst), textwidth, keep=keep)

That is the one place that encapsulates the logic about when to keep the
verbose sections based on ui.verbose (it's important not to spread the
logic all over since we might want to keep more sections later, such as
'detailed' or 'expert' sections). The pruned list contains the types of
sections that were pruned.

Using

    if pruned:
        ui.write(_("(detailed help was omitted")))

kind of works, but it puts the note right after the

  use "hg -v help add" to show more info

text. I guess that's why you springled the help.indicateomitted calls
throughout commands.help.

I think we'll need to parse the text twice to insert the right text at
the right spot. We could even have

  normal text

  .. container:: verbose

     verbose text

  .. container:: omitted

     (verbose help text omitted)

as the source text and then do

  keep = ui.verbose and ['verbose'] or []
  formatted, pruned = minirst.format(rst, keep=keep)
  if 'verbose' in pruned:
      keep.append('omitted')
      formatted, pruned = minirst.format(rst, keep=keep)

That will allow us to build the rst source text incrementally.

-- 
Martin Geisler

aragost Trifork
Commercial Mercurial support
http://aragost.com/mercurial/