[PATCH] help: 'hg help' supports subtopics (issue2804)

Martin Geisler mg at lazybytes.net
Fri May 13 11:54:23 CDT 2011


yun lee <yun.lee.bj at gmail.com> writes:

> Thanks for your patient reply, I have understood better.
>
> I think it's OK to insert the help into comment, but I still have some
> questions:
> 1) Do we need create new method to extract information from the comments?

Yes, there is no code that can extract such comments right now.

>>>> Maybe it would be better to use a specially formatted comment. That
>>>> comment could then be put directly where it is needed! Like this
>>>>
>>>> diff --git a/mercurial/url.py b/mercurial/url.py
>>>> --- a/mercurial/url.py
>>>> +++ b/mercurial/url.py
>>>> @@ -425,6 +425,9 @@
>>>>     construct an opener suitable for urllib2
>>>>     authinfo will be added to the password manager
>>>>     '''
>>>> +    ## ui.usehttp2: bool, False
>>>> +    ##
>>>> +    ## Use new experimental HTTP client?
>>>>     if ui.configbool('ui', 'usehttp2', False):
>>>>         handlers = [httpconnectionmod.http2handler(ui, passwordmgr(ui))]
>>>>     else:
>
> 2) I have seen just "Use new experimental HTTP client?" for
> 'ui.usehttp2', however how to deal with more detailed information for
> it? Could we just add them together like below?
>
> diff --git a/mercurial/url.py b/mercurial/url.py
> --- a/mercurial/url.py
> +++ b/mercurial/url.py
> @@ -425,6 +425,9 @@
>     construct an opener suitable for urllib2
>     authinfo will be added to the password manager
>     '''
> +    ## ui.usehttp2: bool, False
> +    ##
> +    ## Use new experimental HTTP client?
> +    ##
> +    ## Detailed information is here...
>     if ui.configbool('ui', 'usehttp2', False):
>         handlers = [httpconnectionmod.http2handler(ui, passwordmgr(ui))]
>     else:

Yes, the idea is that we can have as much documentation as we want for
each configuration value.

But let us backtrack a little: let us start by making

  $ hg help alias

show what you see on

  http://www.selenic.com/mercurial/hgrc.5.html#alias

In other words, let us take the parts of your patch that adds the
sub-topic functionality. That will be patch nr 1.

A second patch can then move the [alias] section from doc/hgrc.5.txt to
doc/mercurial/help/alias.txt, a third patch can move [auth], etc.

Some of the sections (e.g., [diff]) overlap with names of existing
commands -- what can we do with those? You suggested that we put things
into a config "namespace" so that one must use

  hg help config.diff

to get the help for the [diff] section. I would prefer if we in the next
step could write just

  hg help diff.git

and not

  hg help config.diff.git

since we've tried to teach ourselves and users to talk about config
settings as "section.name", not "config.section.name". So we could add a
flag to 'hg help', just like it now has flags to show the module help
string when a command exist with the same name as an extension. I cannot
come up with a good name for such a flag, any ideas?

So let's start by getting a patch nr 1 that just adds the subtopic
functionality.

-- 
Martin Geisler

Mercurial links: http://mercurial.ch/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: not available
URL: <http://selenic.com/pipermail/mercurial-devel/attachments/20110513/390c61e9/attachment.pgp>


More information about the Mercurial-devel mailing list