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@xxxxxxxxxx> > > > > --- > > > > 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
