External document links (was Re: Add Formal Verification chapter v4)

[Chris Johns]

On 6/10/2023 1:02 am, Gedare Bloom wrote:
> On Fri, Sep 22, 2023 at 4:50 AM Andrew.Butterfield at scss.tcd.ie
> <Andrew.Butterfield at scss.tcd.ie> wrote:
>> Also, I'm not sure the best way to refer to a sub-section of another document
>> I used something like (See Host Tools in the RTEMS User Manual)
>> I guessed the URL might be less robust
> Yes this is basically correct. We don't want explicit links between
> documents. It's a bit challenging at the moment to validate
> cross-document references and we don't have a great solution or
> standard approach for how to do it.

There are a few issues having external links between our documents:

1. The links reference the `master` branch so branching for a release breaks the
documentation in a releases and that is something we cannot have.

2. PDF documents do not know how to link to the other PDF documents. A PDF is
not web resource.

3. Localised builds for internal use, for example on a disk or local server
still link externally back to `master`. If you need to work on a site that does
not have internet access the documentation breaks.

With the current documentation structure these issue are beyond the scope for us
to deal with in sphinx. We develop an RTOS.

A single book of all our documents would resolve this but that would slow the
documentation builds down unless someone knows how to build partial pieces.

Chris