[PATCH] help: move topic "files" from /doc/hg.1.txt to /mercurial/help/ (issue2760)

Martin Geisler mg at aragost.com
Thu May 5 09:45:34 CDT 2011

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

>> As for the long-term goal, then I'm a bit more unsure: we haven't
>> made a plan for which topics we should have. For the man pages:
>> * The hg(1) man page is mostly empty -- done!
>> * The hgignore(5) man page was moved yesterday -- great!
>> * The hgrc(5) man page should be moved into mercurial/help too since
>>  people don't know about this manpage on Windows.
>>  Maybe it could be merged with the config help topic?
> Yes, I agree on merging hgrc(5) . And I think it's not necessary to
> modify the hg.1.txt, as it just contains some simple descriptions, and
> the rich content has been contained in concrete files such as hg(1),
> hgignore(5) and hgrc(5).

Yeah, exactly.

>>  Later, we should see if we could generate the help for each config
>>  setting programmatically so that we are sure it will be complete, in
>>  the same was as we do it for commands and command line options.
> I don't understand, do you mean sections in hgrc by  "each config
> setting", and what do you mean by "commands and command line options"?

The command line options are stored in a table like this

  cmdtable = {
           [('r', 'rev', '',
             _('show children of the specified revision'), _('REV')),
           ] + templateopts,
           _('hg children [-r REV] [FILE]')),

from the children extension. This means that we can output nice command
line tables automatically in 'hg help children'.

We've talked a little about doing something similar for the
configuration options. They are currently spread out through code: if a
piece of code needs a config value, then it just does

  val = ui.config('section', 'name')

to get it. There is no central list of all configuration values used by
the code. We only have the hgrc.5.txt file which is maintained manually.

I cannot find the relevant thread right now, but last time we talked
about it, Matt said that it would be good if the options were defined
close to where they are used. That of course makes it difficult to find
the definitions...

Anyway, if we had such a list of options, then users could do

  $ hg help ui.username

and get the relevant help for that setting -- I think that would be a
great step forward.

Martin Geisler

aragost Trifork
Professional Mercurial support

More information about the Mercurial-devel mailing list