[PATCH 06/32] docs: formatdomain: Split out <devices>
pkrempa at redhat.com
Wed Jul 29 15:00:27 UTC 2020
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
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.
Split off disk:
Split off interface:
More information about the libvir-list