Docs and the :manpage: tag

[Nic Bernstein]

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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.andrew.cmu.edu/pipermail/cyrus-devel/attachments/20150806/2f28a577/attachment-0001.html