<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
Nicola,<br>
As you've no doubt learnt by now, the tool which provides this
functionality, for example, to the RFC links, is <a
href="http://sphinx-doc.org/ext/extlinks.html#module-sphinx.ext.extlinks">sphinx.ext.extlinks</a>.
Unfortunately, it can only provide a simple, single, substitution
within a static link string, like so (from
cyrus-docs/sources/conf.py):<br>
<blockquote>
<pre>extlinks = {
'rfc':('<a class="moz-txt-link-freetext" href="http://tools.ietf.org/html/rfc%s">http://tools.ietf.org/html/rfc%s</a>', 'RFC '),
'task':('<a class="moz-txt-link-freetext" href="https://git.cyrus.foundation/T%s">https://git.cyrus.foundation/T%s</a>', 'Task #'),
}
</pre>
</blockquote>
This doesn't work, however, for the manpage identifiers, since they
look like this: 'imapd.conf(5)' but the pages to which one would
wish to link don't have the '(5)' part on them.<br>
<br>
I tried the obvious solution:<br>
<blockquote>
<pre>extlinks = {
'rfc':('<a class="moz-txt-link-freetext" href="http://tools.ietf.org/html/rfc%s">http://tools.ietf.org/html/rfc%s</a>', 'RFC '),
'task':('<a class="moz-txt-link-freetext" href="https://git.cyrus.foundation/T%s">https://git.cyrus.foundation/T%s</a>', 'Task #'),
'manpage':('%s.html', ''),
}
</pre>
</blockquote>
but that renders a link like this:<br>
<a class="moz-txt-link-freetext" href="file:///home/nic/Checkouts/cyrus.foundation/cyrus-docs/build/html/imap/admin/commands/imapd.conf(5).html">file:///home/nic/Checkouts/cyrus.foundation/cyrus-docs/build/html/imap/admin/commands/imapd.conf(5).html</a><br>
where that damnable (5) gets in the way. :-(<br>
<br>
I will try to give this more attention as time permits. The one
option I can see would be to do a mass search/replace operation with
(poorly written, most likely, pseudo-code):<br>
<blockquote>
<pre>/manpage:`(\S)(\(\S\))`/manpage:`$1`*$2*/
</pre>
</blockquote>
That, I think, would do what we wish. We'd have to decide which
modifier rendered most properly for the parenthetical part, in both
the man and html versions.<br>
<br>
Cheers,<br>
-nic<br>
<br>
<div class="moz-cite-prefix">On 08/06/2015 11:03 PM, Nicola Nye
wrote:<br>
</div>
<blockquote
cite="mid:1438920227.1999039.350001657.39C9D110@webmail.messagingengine.com"
type="cite">
<pre wrap="">Hiya,
An update...
I took a look and after some wild flailing, rapidly came to the
conclusion that this is beyond my skillset. I've created a task for it
in case anyone's feeling in the mood for a task. (I found an extension
someone else had written which is similar to what we need, so it's not
an entirely undefined job)
<a class="moz-txt-link-freetext" href="https://git.cyrus.foundation/T213">https://git.cyrus.foundation/T213</a>
Nicola
On Thu, Aug 6, 2015, at 11:21 AM, Nicola Nye wrote:
</pre>
<blockquote type="cite">
<pre wrap="">G'day,
Nic B and Jeroen, I think this is mostly something you'll have some
thoughts about...
Currently the rst docs make use of a :manpage: tag. This does little
more than change the formatting of the affected text.
For the html docs, it makes far more sense for it to convert it to the
link for the relevant man page. (while not affecting any other output
format generation such as the actual man pages)
Anyone have any objections before I just go ahead and do it?
Nicola
</pre>
</blockquote>
</blockquote>
<br>
<pre class="moz-signature" cols="72">--
Nic Bernstein <a class="moz-txt-link-abbreviated" href="mailto:nic@onlight.com">nic@onlight.com</a>
Onlight llc. <a class="moz-txt-link-abbreviated" href="http://www.onlight.com">www.onlight.com</a>
219 N. Milwaukee St., Ste. 2A v. 414.272.4477
Milwaukee, Wisconsin 53202 f. 414.290.0335
</pre>
</body>
</html>