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

[yun lee]

2011/5/5 Martin Geisler <mg at aragost.com>:
> 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 = {
>      "children":
>          (children,
>           [('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.
>
I have spent some days to consumed your advice and think it's great,
Martin! I have realised a simple version of that feature, please check
my patch on issue 2804. Thanks!

> --
> Martin Geisler
>
> aragost Trifork
> Professional Mercurial support
> http://mercurial.aragost.com/kick-start/
>



-- 
Yun Lee