Docs and the :manpage: tag

[Nicola Nye]

Delicious victory is mine!

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.

Now, to look at updating all the references in our existing docs so that
it uses the new tag...


On Fri, Aug 7, 2015, at 03:03 PM, Nicola Nye wrote:
> 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                             nic at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.andrew.cmu.edu/pipermail/cyrus-devel/attachments/20150813/bafbef4e/attachment.html