Re: [Boost-gil] Section anchors and inter-section links

Subject: Re: [Boost-gil] Section anchors and inter-section links
From: Stefan Seefeld (stefan_at_[hidden])
Date: 2018-04-06 14:45:44

On 06.04.2018 10:37, Mateusz Loskot wrote:
> On 6 April 2018 at 15:47, Stefan Seefeld <stefan_at_[hidden]> wrote:
>> On 04.04.2018 12:30, Mateusz Loskot wrote:
>>> On 4 April 2018 at 17:33, Stefan Seefeld <stefan_at_[hidden] <mailto:stefan_at_[hidden]>> wrote:
>>>> On 04.04.2018 09:49, Mateusz Loskot wrote:
>>>>> On 4 April 2018 at 13:50, Stefan Seefeld <stefan_at_[hidden] <mailto:stefan_at_[hidden]>> wrote:
>>>>> It seems the mechanism we want is
>>>> Do you mind if we enable and use it?
>>> Looking into it.
>>> (I enabled it and now get warnings, as certain section titles
>>> appear multiple times, even in the same document: e.g. "related",
>>> "models". I need to think how to handle that.)
>> I still haven't acted upon this. The code of the extension is rather
>> trivial
>> (
>> The `design_guide.rst` document contains multiple (sub-)sections called
>> "Models" (as well as "Related Concepts"), which cause warnings. Here are
>> a few ways to deal with this:
>> 1) ignore the warnings (and not use references to those sub-sections)
>> 2) not use the auto-labeling feature, and instead insert explicit
>> anchors
>> (
>> 3) clone the `autosectionlabel` extension and adjust it to ignore those
>> duplicate sections
>> I'm somewhat split between option 1) and 2).
> I guess, technically feasible solution may be splitting the large
> design_guide.rst into design/point.rst, design/channel.rst, etc.

Oh, good point ! We may restructure the documentation, so this may no
longer be an issue. OK, one more reason to go with the simplest solution
for now. I'll thus enable the auto-label generation, and then we can
revisit this once we talk about documentation refactorization..



      ...ich hab' noch einen Koffer in Berlin...

This archive was generated by hypermail 2.1.7 : 2018-04-12 20:05:06 UTC