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