Nicola,
As you've no doubt learnt by now, the tool which provides this
functionality, for example, to the RFC links, is sphinx.ext.extlinks
<http://sphinx-doc.org/ext/extlinks.html#module-sphinx.ext.extlinks>.
Unfortunately, it can only provide a simple, single, substitution within
a static link string, like so (from cyrus-docs/sources/conf.py):
extlinks = {
'rfc':('http://tools.ietf.org/html/rfc%s', 'RFC '),
'task':('https://git.cyrus.foundation/T%s', 'Task #'),
}
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.
I tried the obvious solution:
extlinks = {
'rfc':('http://tools.ietf.org/html/rfc%s', 'RFC '),
'task':('https://git.cyrus.foundation/T%s', 'Task #'),
'manpage':('%s.html', ''),
}
but that renders a link like this:
file:///home/nic/Checkouts/cyrus.foundation/cyrus-docs/build/html/imap/admin/commands/imapd.conf(5).html
where that damnable (5) gets in the way. :-(
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):
/manpage:`(\S)(\(\S\))`/manpage:`$1`*$2*/
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.
Cheers,
-nic
On 08/06/2015 11:03 PM, Nicola Nye wrote:
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)
https://git.cyrus.foundation/T213
Nicola
On Thu, Aug 6, 2015, at 11:21 AM, Nicola Nye wrote:
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
--
Nic Bernstein n...@onlight.com
Onlight llc. www.onlight.com
219 N. Milwaukee St., Ste. 2A v. 414.272.4477
Milwaukee, Wisconsin 53202 f. 414.290.0335
