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

[Martin Geisler]

Benoit Boissinot <bboissin at gmail.com> writes:

> On Fri, Apr 29, 2011 at 3:08 PM, yun lee <yun.lee.bj at gmail.com> wrote:
>> 2011/4/29 Martin Geisler <mg at lazybytes.net>:
>>>
>>> Yeah, I don't think we should just move the help text into help
>>> topics like this -- we'll get a lot of small help topics with little
>>> structure.
>>
>> Am, I agree with you, it will be better. Then, what are others'
>> opinions, please?
>
> What do you think we should do to move things from doc/ to
> mercurial/help/? Only move self-contained topics, is there a minimum
> topic size? What is the long term goal we want to achieve there (sorry
> I haven't followed all the discussions).

The short-term goal is pretty clear: make all help available as 'hg help
<something>' and so also available in the hgweb help section.

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?

  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.

As for help topics shadowing commands with the same name, then I suggest
we try to avoid it but also add a --topic/-t switch to the help command
so that you can do 'hg help -t tags' and get a (hypothetical) help topic
about tags. That would probably explain how tags are stored.

There has been patches for making 'hg help --extension relink' show the
relink module docstring instead of the docstring for the relink command.
I just looked and I see that our extensions now intentionally have
little information in the module docstring. The patchbomb extension is
an exception, but it cleverly defines a command with the name email so
that both 'hg help patchbomb' and 'hg help email' works.


-- 
Martin Geisler

aragost Trifork
Professional Mercurial support
http://aragost.com/mercurial/