Re: [Boost-build] B2 documentation..

Subject: Re: [Boost-build] B2 documentation..
From: Raffi Enficiaud (raffi.enficiaud_at_[hidden])
Date: 2017-08-08 11:27:46

Le 08.08.17 à 11:55, Daniel James via Boost-build a écrit :
> On 8 August 2017 at 10:18, Raffi Enficiaud via Boost-build
> <boost-build_at_[hidden]> wrote:
>>
>>   * can you generate an index easily, and play with the structure of the
>> documentation? Can you easily change the structure? For instance, in
>> Quickbook, restructuring breaks the URLS if you link to eg. section by the
>> name in the documentation tree. In Sphinx, you have commands like
>> :py:class:`` that references a global object, wherever it is in the
>> documentation.
>
> I have no interest in a debate about which is the bestest
> documentation system,

Good, me neither :)

> but to answer the question, in quickbook you can
> use anchors (e.g [#link.something]), which can be moved around and
> survive restructuring.

Yes I know, but I have found it hard to maintain and I prefer having the 
section implicit links directly (that I can just see by opening the 
browser and clicking on the section).

The links in Sphinx carry some semantics as well, like :py:class:`some 
class`, a bit a la [classref ] , with the difference that the referenced 
entity is living in the same documentation system (and not in eg Doxygen).

Do not get me wrong, I like the simplicity/expressivity of Quickbook, 
just I have found a bit poor the "reference like" documentation support 
(link to externally managed documentation).

Raffi