Docs and the :manpage: tag

Nic Bernstein nic at
Fri Aug 7 00:43:37 EDT 2015

As you've no doubt learnt by now, the tool which provides this 
functionality, for example, to the RFC links, is sphinx.ext.extlinks 
Unfortunately, it can only provide a simple, single, substitution within 
a static link string, like so (from cyrus-docs/sources/

    extlinks = {
             'rfc':('', 'RFC '),
             'task':('', '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':('', 'RFC '),
             'task':('', 'Task #'),
             'manpage':('%s.html', ''),

but that renders a link like this:
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):


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.


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)
>     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                             nic at
Onlight llc.                    
219 N. Milwaukee St., Ste. 2A	          v. 414.272.4477
Milwaukee, Wisconsin  53202		  f. 414.290.0335

-------------- next part --------------
An HTML attachment was scrubbed...

More information about the Cyrus-devel mailing list