man pages and help topics

Mads Kiilerich mads at kiilerich.com
Tue Oct 19 08:23:46 CDT 2010


On 10/19/2010 02:44 PM, Martin Geisler wrote:
> Mads Kiilerich<mads at kiilerich.com>  writes:
>> 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

Now we have to use inexact and verbose descriptions for "linking" to 
hgrc, such as what Erik is fighting:

"merge-tools section - see hgrc(1)"

"See merge tools and ui section of configuration help on setting the
merge tools"

"See the merge-tools and ui sections of |hgrc(5)|_ for details
on configuration of merge tools."

Semantic markup like :hgrc:`merge-tools` and :hgrc:`ui.merge` would be 
much more helpful.

> 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.

Fine. HTML pages can be big too - and because we can link to anchors 
that wouldn't be big a problem, even though short pages often is faster 
and more convenient.

The opposite - creating a separate man page for each sub-command or 
topic (like some other p-language or DVCS does) - is however not an 
option, IMHO. But it could be done, and it would make it easier to 
reference to man pages...

> 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

Yes, very nice, more of that, please - especially to and from hgrc ... 
which would be a lot easier if hgrc was a help topic ;-)

(btw: http://www.selenic.com/mercurial/hgrc.5.html is pre-a86fd45c1911 
and thus more than 3 months old.)

/Mads


More information about the Mercurial-devel mailing list