man pages and help topics

[Martin Geisler]

Mads Kiilerich <mads at kiilerich.com> writes:

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

Ah, now I see what you mean. That would be a nice syntax!

>> 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 ;-)

Yes and no... there are already some anchors in the hgrc.5.html file:

  http://www.selenic.com/mercurial/hgrc.5.html#patch

But there is no way to link to a specific setting such as patch.eol.
Turning the whole file into a single help topic will not really change
that -- creating more headers will.

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

Strange, I'm sure Matt said he had made a crontab that would refresh it
every couple of hours.

-- 
Martin Geisler

Mercurial links: http://mercurial.ch/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: not available
URL: <http://selenic.com/pipermail/mercurial-devel/attachments/20101019/77d791fa/attachment.pgp>