On Mon, Mar 25, 2024 at 11:40 AM Peter Eisentraut <pe...@eisentraut.org> wrote: > I think a possible problem we need to consider with these proposals to > combine chapters is that they could make the chapters themselves too > deep and harder to navigate.
I looked into various options for further combining chapters and/or appendixes and found that this is indeed a huge problem. For example, I had thought of creating a Developer Information chapter in the appendix and moving various existing chapters and appendixes inside of it, but that means that the <sect1> elements in those chapters get demoted to <sect2>, and what used to be a whole chapter or appendix becomes a <sect1>. And since you get one HTML page per <sect1>, that means that instead of a bunch of individual HTML pages of very pleasant length, you suddenly get one very long HTML page that is, exactly as you say, hard to navigate. > The rendering can be adjusted to some degree, but then we also need to > make sure any new chunking makes sense in other chapters. (And it might > also change a bunch of externally known HTML links.) I looked into this and I'm unclear how much customization is possible. I gather that the current scheme comes from having chunk.section.depth of 1, and I guess you can change that to 2 to get an HTML page per <sect2>, but it seems like it would take a LOT of restructuring to make that work. It would be much easier if you could vary this across different parts of the documentation; for instance, if you could say, well, in this particular chapter or appendix, I want chunk.section.depth of 2, but elsewhere 1, that would be quite handy, but after several hours reading various things about DocBook on the Internet, I was still unable to determine conclusively whether this was possible. There's an interesting comment in stylesheet-speedup-xhtml.xsl that says "Since we set a fixed $chunk.section.depth, we can do away with a bunch of complicated XPath searches for the previous and next sections at various levels." That sounds like it's suggesting that it is in fact possible for this setting to vary, but I don't know if that's true, or how to do it, and it sounds like there might be performance consequences, too. > I think maybe more could also be done at the top-level structure, too. > Right now, we have <book> -> <part> -> <chapter>. We could add <set> on > top of that. Does this let you create structures of non-uniform depth? i.e. is there a way that we can group some chapters into sets while leaving others as standalone chapters, or somesuch? I'm not 100% confident that non-uniform depth (either via <set> or via chunk.section.depth or via some other mechanism) is a good idea. There's a sort of uniformity to our navigation right now that does have some real appeal. The downside, though, is that if you want something to be a single HTML page, it's got to either be a chapter (or appendix) by itself with no sections inside of it, or it's got to be a <sect1> inside of a chapter, and so anything that's long enough that it should be an HTML page by itself can never be more than one level below the index. And that seems to make it quite difficult to keep the index small. Without some kind of variable-depth structure, the only other ways that I can see to improve things are: 1. Make chunk.section.depth 2 and restructure the entire documentation until the results look reasonable. This might be possible but I bet it's difficult. We have, at present, chapters of *wildly* varying length, from a few sentences to many, many pages. That is perhaps a bad thing; you most likely wouldn't do that in a printed book. But fixing it is a huge project. We don't necessarily have the same amount of content about each topic, and there isn't necessarily a way of grouping related topics together that produces units of relatively uniform length. I think it's sensible to try to make improvements where we can, by pushing stuff down that's short and not that important, but finding our way to a chunk.section.depth=2 world that feels good to most people compared to what we have today seems like it's going to be challening. 2. Replace the current index with a custom index or landing page of some kind. Or keep the current index and add a new landing page alongside it. Something that isn't derived automatically from the documentation structure but is created by hand. -- Robert Haas EDB: http://www.enterprisedb.com
