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

FUJIWARA Katsunori foozy at lares.dti.ne.jp
Thu Jul 12 07:36:46 CDT 2012


At Thu, 12 Jul 2012 11:49:37 +0200,
Martin Geisler wrote:
> 
> 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

Thank you for your comments, Martin.
 
> 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.

Yes, as you guessed, I think "detailed description is omitted..."
should be placed just after description, at least not after 'use "hg
-v help add" to show more info' at the end of help output.


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

It can be assumed that "minirst.format() twice" is not so acute
because users don't so mind about response of "hg help", can't it ?

OK, I'll re-post the patch using this way.

----------------------------------------------------------------------
[FUJIWARA Katsunori]                             foozy at lares.dti.ne.jp


More information about the Mercurial-devel mailing list