[PATCH 06/32] docs: formatdomain: Split out <devices>

[Laine Stump]

On 7/27/20 2:58 AM, Peter Krempa wrote:
> On Fri, Jul 24, 2020 at 11:23:58 -0500, Jonathon Jongsma wrote:
>> On Thu, 2020-07-23 at 15:21 +0200, Peter Krempa wrote:
>>> Start splitting the massive document into smaller pieces using the
>>> .. include:: directive.
>>>
>>> Signed-off-by: Peter Krempa <pkrempa at redhat.com>
>>> ---
>>>   docs/formatdomain-devices.rst | 5053
>>> ++++++++++++++++++++++++++++++++
>>>   docs/formatdomain.rst         | 5054 +----------------------------
>>> ----
>>>   docs/meson.build              |    5 +-
>>>   3 files changed, 5058 insertions(+), 5054 deletions(-)
>>>   create mode 100644 docs/formatdomain-devices.rst
>>>
>> So, this is already a nice improvement for maintenance, but I wonder if
>> it wouldn't be good to go even farther and split up the giant document
>> for the website as well? For instance, the other day, I was looking up
>> some information in this document about the XML format of network
>> interfaces. I was looking for a particular word (can't remember what it
>> was now) so I tried a Ctrl+F to search for the word on the page. Of
>> course it gave me results from thousands of lines away that were
>> relevant to e.g. CPU allocation instead of network interfaces.
>>
>> In addition, some of the sections are so long, with so many sub-
>> headings (that all look similar to the main headings) that it can be
>> really cumbersome to navigate and difficult to notice where one section
>> ends and the next begins.
>>
>> I understand that there are advantages to having it all on one page as
>> well, but I'm not sure whether they outweigh the disadvantages.
> I think there's only one disadvantage of doing so. It's breaking
> existing links.


There are so many broken links in blog posts, product reviews, news 
articles, and even the direct results of google searches these days that 
I think it's a losing battle.


Would it be possible to create a nearly-empty shell of the original 
document that just contained redirects to the new locations of the 
content, then use a different name for the base page of the new version 
to avoid conflict?


>   I opted to keep the otput identical including keeping
> existing links to prevent any risks of additional bikeshedding on the
> series as it's already attracting conflicts.
>
> I'm all for splitting up the docs and removing all the anchor points I
> had to add to keep links working.
>

Anything to avoid having to type all those < > gets a vote from 
me! Better readability in raw form and organization are further icing on 
the cake.