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

[Peter Krempa]

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. 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.