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

[Peter Krempa]

On Mon, Jul 27, 2020 at 11:02:10 -0400, Laine Stump wrote:
> 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.

I've hacked up something to show how it would look. Please note that
I've didn't fix links yet and only the two linked documents are prepped.

I want to have some feedback before converting everything.

Main document:

https://pipo.sk.gitlab.io/-/libvirt/-/jobs/661894123/artifacts/website/formatdomain.html#supported-devices

Split off disk:
https://pipo.sk.gitlab.io/-/libvirt/-/jobs/661894123/artifacts/website/formatdomain-devices-disk.html

Split off interface:
https://pipo.sk.gitlab.io/-/libvirt/-/jobs/661894123/artifacts/website/formatdomain-devices-interface.html