On 6/10/2023 1:02 am, Gedare Bloom wrote: > On Fri, Sep 22, 2023 at 4:50 AM andrew.butterfi...@scss.tcd.ie > <andrew.butterfi...@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 _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
