<!DOCTYPE html>
<html>
<head>
<title></title>
</head>
<body><div>Delicious victory is mine!<br></div>
<div> </div>
<div>We now have a :cyrusman: sphinx option which generates urls into our docs.cyrus.foundation tree, performing string munging magic to match the generated url to our directory and filename structure.<br></div>
<div> </div>
<div>Now, to look at updating all the references in our existing docs so that it uses the new tag...</div>
<div> </div>
<div> </div>
<div>On Fri, Aug 7, 2015, at 03:03 PM, Nicola Nye wrote:<br></div>
<blockquote type="cite"><div>Hi Nic,<br></div>
<div> <br></div>
<div>I like your thinking, but as you've noted, it doesn't really handle what we after.<br></div>
<div> <br></div>
<div>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.<br></div>
<div> <br></div>
<div>When I come up with a wishlist item, I do it with all the bells and whistles. :)<br></div>
<div> <br></div>
<div>I'm hoping that chunk of python script referenced in the Maniphest task is on the right path.<br></div>
<div> <br></div>
<div> <br></div>
<div>On Fri, Aug 7, 2015, at 02:43 PM, Nic Bernstein wrote:<br></div>
<blockquote type="cite"><div>Nicola,<br></div>
<div>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></div>
<div> <br></div>
<blockquote><pre>extlinks = {
'rfc':('<a href="http://tools.ietf.org/html/rfc%s">http://tools.ietf.org/html/rfc%s</a>', 'RFC '),
'task':('<a href="https://git.cyrus.foundation/T%s">https://git.cyrus.foundation/T%s</a>', 'Task #'),
}
<br></pre></blockquote><div>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></div>
<div> <br></div>
<div>I tried the obvious solution:<br></div>
<div> <br></div>
<blockquote><pre>extlinks = {
'rfc':('<a href="http://tools.ietf.org/html/rfc%s">http://tools.ietf.org/html/rfc%s</a>', 'RFC '),
'task':('<a href="https://git.cyrus.foundation/T%s">https://git.cyrus.foundation/T%s</a>', 'Task #'),
'manpage':('%s.html', ''),
}
<br></pre></blockquote><div>but that renders a link like this:<br></div>
<div><a 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></div>
<div>where that damnable (5) gets in the way. :-(<br></div>
<div> <br></div>
<div>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></div>
<div> <br></div>
<blockquote><pre>/manpage:`(\S)(\(\S\))`/manpage:`$1`*$2*/
<br></pre></blockquote><div>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></div>
<div> <br></div>
<div>Cheers,<br></div>
<div>-nic<br></div>
<div> <br></div>
<div> <br></div>
<div>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>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 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:
<br></pre><blockquote type="cite"><pre>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
<br></pre></blockquote></blockquote><div> <br></div>
<pre>--
Nic Bernstein <a href="mailto:nic@onlight.com">nic@onlight.com</a>
Onlight llc. <a 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
<br></pre></blockquote><div> <br></div>
</blockquote><div> </div>
</body>
</html>