Hi Nic,
I like your thinking, but as you've noted, it doesn't really handle
what we after.
We need something which can interrogate the (8) vs (5) and interpret
that in the link to the commands vs configs subdirectories. And know
that an imap manpage link is under image/admin while a sasl manpage link
is under (well, nowhere right now). And be able to not convert regular
manpage links should we refer folks to cron, say.
When I come up with a wishlist item, I do it with all the bells and
whistles. :)
I'm hoping that chunk of python script referenced in the Maniphest task
is on the right path.
On Fri, Aug 7, 2015, at 02:43 PM, Nic Bernstein wrote:
> 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[1]. 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/T213Nicola
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.com219 N. Milwaukee St., Ste. 2A v. 414.272.4477
Milwaukee, Wisconsin 53202 f. 414.290.0335
>
Links:
1. http://sphinx-doc.org/ext/extlinks.html#module-sphinx.ext.extlinks
