[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