Niels Thykier <ni...@thykier.net> writes: > Russ Allbery: >> Ooo, this is a great framing of the problem. I have a lot of thoughts >> about this. Unfortunately, I'm not sure if they're actionable thoughts >> since my grand vision requires someone to sit down and do some serious >> Policy restructuring and produce a radically different document. But >> maybe if I write them all down and enough people feel similarly, it >> would be worth doing. I would love to work on this, I am just afraid >> that it is the sort of project that I would start and never finish and >> thus never accomplish anything of use.
> Indeed, it is definitely the thing I would personally prefer to > pre-align on before adventuring on something of this scale myself (were > I in your shoes), so I totally feel your concern about actionability. I do to some extent want people to encourage me to work on this if they think it would be awesome, since people being happy with it would be what would make all the work worthwhile (although I will probably also need help). :) > Interesting choice with the mixing. I was of the understanding that the > idea was one should try to avoid mixing documentation styles according > to Divio. Admittedly, I find it hard to fully stick to exactly one type > of style, so I would be happy if I had just overlooked the "advice on > mixing". So, I have to admit that I have not read Divio in detail although I have been pointed at it many times and have had the high-level concepts explained to me. I've read bits and pieces, but I'm not sure what it says about mixing. But in terms of what makes an effective Policy document, I think a general structure of an explanation section introducing a part of packaging followed by how-to sections for the underlying tasks would work. > As for the content: The "How-to" style would make sense for the target > audience. I am less clear if all of these headlines makes up a "Policy" > as they sounds like something you could find in a "Debian Packaging 101" > guide. I think that about a quarter of Policy currently is already how-to text. For example, look at Policy 3.4: https://www.debian.org/doc/debian-policy/ch-binary.html#s-descriptions This is a disguised how-to document on how to write a good package description. There's a ton of stuff in Policy like this. What distinguishes it from a Debian Packaging 101 guide is that the how-to goes into *way* more depth than a 101 guide: edge cases, exceptions, advanced bits of packaging, etc. The main problem from the perspective of helping the typical packager, is that this is mixed in with oodles of advice that is irrelevant to anyone except debhelper maintainers. To take another short example, look at the section on symbolic links: https://www.debian.org/doc/debian-policy/ch-files.html#symbolic-links Half of that section is a specification for the packaging helper, which will fix symbolic links to follow those rules. The rest is sort of a how-to (mixed in with some basic shell command advice). > Side question: Does Policy add anything on the specification for > `symbols` and `shlibs` files as a reference document that is not covered > by dpkg's documentation for these formats? I assume the "symbols guide" > (on /when/ to use symbols and when not too) would go in the previous > section. Well, one can read the two side-by-side and see, and I'm biased as the person who wrote it, but I think it does. Policy duplicates dpkg documentation quite a lot, so this is a question worth asking, but I do think Policy has a good answer. The value that Policy adds over the dpkg documentation generally falls into three categories: 1. Policy is much more opinionated about what features supported by dpkg should be used in packages and how they should be used. There are sometimes things dpkg *can* do that we don't do. A bunch of this is how-to, but I think some of this is reference. 2. Policy is sometimes a lot more verbose and offers worked examples, and sometimes benefits from the additional formatting tools available in Sphinx. This could be imported into the dpkg documentation to some extent, of course, but as it stands I think there's value there. 3. dpkg documentation has to cover the complete operation of dpkg, whereas Policy, even in reference sections and packaging helper sections, should only need to cover the surface area that's visible to packaging at the lowest level. I agree that this is a source of some duplication of effort, although in my experience it's not the part that takes the most time. (But I haven't written triggers or multiarch documentation for Policy yet, so maybe it's part of the problem.) > What is it you would see go into this section [packaging helper > specification] that is not the previous section? Literally everything in Policy that you shouldn't think about because the packaging helpers will cover it. For example, the symlink canonicalization stuff mentioned above. How to run update-rc.d in maintainer scripts. How to compress man pages. All that stuff that Policy is riddled with right now that's basically a specification for debhelper. I don't want any of that stuff even in reference ideally, because the person packaging doesn't need to know any of it 99% of the time so it just eats up cognitive space unless you're digging into what debhelper is doing. But I don't want to *delete* it, because there is that 1% case where you have some really weird packaging problem and debhelper is doing the wrong thing. I think this is distinct from the pure reference stuff like, say, the specification for how maintainer scripts work or the list of all the fields in .dsc and .changes files. You *do* have to know that stuff if you're doing something advanced or if you're writing other tools that interact with Debian packages that aren't packaging helpers, so the audience is a fair bit larger. > I think it would take the Policy editors to have consensus on this as a > direction and then go step by step from there. Maybe turn the current > Policy into "Section II" as starting point and extract stuff into > "Section I" piece by piece. Yeah, I was thinking of something like that. > Lintian maintainer will love you for breaking all the section numbers > though! :D (I don't have a good solution for that problem). What I want to do is give sections persistent short codes that are easy to find and search for somehow and ideally should also serve as HTML anchors. Maybe we can do something with a Sphinx extension. > In that narrative, I think it would make sense for Policy to reference our > primary packaging toolchain a lot more - at least in Section I. As a > toolchain writer, my primary concern here is inertia. > I would prefer that the references enable the tool to evolve over > time. As an example, "This section assumes debhelper-compat (= 13)" > could work because that phrase implies that things can change in a > future compat level. Yup, that makes sense. I also want to leave space for entirely new packaging helpers to crop up. We've been in a fallow period for that for a while, with everything converging on debhelper, but my (informed :P) guess is that this is somewhat cyclical. Definitely a detail that we'd need to work out. -- Russ Allbery (r...@debian.org) <https://www.eyrie.org/~eagle/>
