man pages and help topics

[Martin Geisler]

Mads Kiilerich <mads at kiilerich.com> writes:

> On 10/19/2010 09:48 AM, Martin Geisler wrote:
>> Erik and I debated a bit if this would make better sense as a hgext.1
>> manpage and we also discussed how this fits with the new hgweb help
>> system. My take is that generating a manpage for the extensions is a
>> nice low-hanging fruit and so we should just do it and then worry
>> about the overlap with the hgweb help later (the hgweb help obviously
>> already overlaps with the current hg.1.html file).
>
> That could be nice, but I think the opposite is more important.
>
> Man pages are unix only and they are hard to reference and navigate
> (especially because our pages are so long).

Hmm, I have no problem referencing them and I like to get one big man
page since I can search through it easily compared to a bunch of HTML
pages each with a fragment of the documentation.

The HTML version should also be nice for printing, even on Windows.

> Man pages have some advantages: "All" unix tools have man pages, so
> that is the place to go when a brief summary of a unix tool is needed,
> but I am not sure we should put _all_ our help there. The main
> advantage "man" has to "hg help" is that the pager is built-in ;-)
>
> So I would rather see the man pages hgrc.5 and hgignore.1 (and perhaps
> the last pieces of hg.1 if any) as help topics. These help topics
> could be the canonical location (used when other help mentions
> configuration and its documentation) and it would probably be possible
> to make cross references in the html version and in the "hg serve"
> help.

Agreed, I also think we should concentrate our help in the help topics
and then build man and HTML pages based on it. The HTML version of the
manpages already has nice links for cross references, such as this
example where 'hg add' links to 'hg forget':

  http://www.selenic.com/mercurial/hg.1.html#add

These links are created with the hg role: you can do :hg:`help whatever`
to get a link to "whatever" in the help topics. When I get minirst
beefed up to produce HTML output I'll make it produce links like that.

-- 
Martin Geisler

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