Hi! On Sat, 2025-01-25 at 12:29:56 +0000, Sean Whitton wrote: > On Sat 25 Jan 2025 at 12:11pm +01, Guillem Jover wrote: > > This multitude of formatting languages has bothered me for a while, > > every time I take a peek at the sources. :) So this time around I > > pondered how hard could it be to do that unification, and started > > looking into this, which didn't look like that much work TBH. Before > > proceeding though, I'd appreciate confirmation that this is desired, > > and if so then the process surfaced multiple questions of preferences, > > that I'd have for the editors. > > Thank you for your interest in this. > > Converting Policy and dev-ref was most important because these are the > large documents where we want to make it as easy as possible for people > to make contributions to keep them up-to-date. > > The other documents change much less often. So I must admit, I'm not > sure there is much benefit. I guess it would mean that we could > simplify our build system, though? That would probably be good.
For me the main benefit would be avoiding the mental overload of having to deal with multiple different formatting languages (while you are right that the other documents do not see as many updates, but having to deal with Docbook-XML feels painful), the other as you mention is simplifying the build system and reducing build dependencies, and then… > A unified i18n for the whole source package would be beneficial. …yes, this would give us automatic localization infrastructure for the remaining documents (which they do not currently have). > > For the questions to the editors: > > > > - The policy/Makefile seems to be unused and a leftover from the > > original conversion? The policy build seems to be driven entirely > > by the source root Makefile, so I guess I could remove it? > > I think it's there so that you can do Sphinx builds of just policy/ > without doing the full package build. It's not very important, so, we > could delete it if you think it's confusing. I guess we could always add easy make targets for each individual document. Otherwise for consistency this might require adding similar Makefiles to each new document subdirectory, which I think I'd rather avoid. > > - There was an issue with duplicated translation directories some > > time ago, where Sean seems to have ended up unifying them in the > > next branch into the source root directory (I was expecting the > > reverse to happen :). I think this could be problematic, because > > then all documents will get dumped there, where they might end up > > sharing the same .po file if they match filename. Which from a > > gettext PoV should be just fine, but that means translators cannot > > easily decide to only translate specific documents based on their > > priorities or target audience for example. Should I move this back > > under policy/(locale|locales)/? > > Hmm. Do we actually have any duplicate filenames? Not currently, but we'll do. For the documents that are currently split in chapters on output, we'd have ch1, ch2, and index duplicates: $ dpkg -L debian-policy | grep -E '\.html/(index|ch[0-9])' > I'd prefer to leave them in the root until and unless we actually have > any duplicates. We don't gain new filenames often. See above. > > - While going over the build system I found several seemingly unused > > or obsolete things which I've removed, such as dblatex support, > > and support for the html.tar generation. While neither seem to be > > used, I'm not sure whether you want to preserve the support for > > the latter in case the intention was to enable this again in the > > future? > > I think we'd need to go case-by-case. Right, perhaps I should just start sending patches for stuff like this already, it might make discussing things more concretely easier. > For example, dblatex can obviously go once there is no docbook-xml left. dblatex does not appear used currently (there was a commit removing its use), even with the Docbook-XML toolchain. > I'm not sure what the html.tar is; can you say more? ISTR the debian-policy binary package might have shipped the SGML and then the XML sources as an html.tar.gz, but this got disabled at some point, so these are not shipped any longer in the .deb. But the build system still generates them. (The changes already have commit refs for when these got disabled.) > > - With sphinx it looks like the preferred/expected structure is to > > keep each document under their own subdirectory. I've moved those > > all under one each, except for README.rst because that looks to be > > more helpful if it's in the source root (which I think will require > > special handling in the build system as it does not follow the same > > pattern), but I can move it under a subdir too if you prefer the > > uniformity. I was a bit undecided how to call the subdir for that > > file, and initially had devel/, but then settled on simply README/, > > which might also make unifying the make rules easier. I guess another > > option could be to simply ship the README.rst with no HTML, which > > then removes the entire problem. But let me know what's your > > preference here. > > Let's keep it in the source root, as is standard for READMEs, and so > salsa will pick it up and format it. (This does not cover several other parts of the question, but I guess we can iterate when there's something more concrete on the table. :) > > - I've found the debconf_specification name a bit cumbersome in the > > past, both for its length and its underscore use, and now having > > debconf_specification/debconf_specification.rst and similar > > pathnames all over the place makes it a bit worse. There's also a > > mix of terms used all over the place in git for this for directories, > > make variables and doc-base support, including: > > > > debconf_specification > > debconf-spec > > debconf_spec > > debconf > > > > I was thinking about, at least for the sources to unify and rename > > all of these into debconf-spec to make the build system more uniform, > > then rename it when installing it into the .deb. (I could see also > > a proposal to rename it on the .deb, while preserving backward > > compat symlinks, but that might be more disruptive, and might require > > changes on the website for example, which I'd be prepared to handle > > as well, but there might be other potential unintended breakage). > > Let me know as well your preference here. > > Unifying it in the source is fine, people can 'git grep' for what they > want to edit. But yeah, keeping them installed in the same places in > the .deb sounds sensible. Ok, thanks, then I'll do for now the unification in the source and leave the current installed pathnames as before. > > - While moving things around, I also wondered whether it might be > > cleaner to move all fhs stuff under a new fhs/ subdir. > > As the file names already have 'fhs' in them, I'd prefer to leave them > in the source root. Ok, will do that. This was mostly to unify a bit the structure with the other files which can end up repeating their name in the dir and the file such as say «autopkgtest/autopkgtest.rst» (although I guess they could also be named something like «autopkgtest/index.rst»), and to unclutter the source root. To have something like: Makefile README/ README.rst autopkgtest/ copyright-format-1.0/ debconf-spec/ debian fhs/ historical/ menu-policy/ perl-policy/ policy/ tools/ virtual-package-names-list.yaml (But this was an aside while going over the build system and source tree, and is not really related or affecting the conversion work. :) > > - Should I work off master or next? > > Definitely 'next' for the moving around, though if you have minor fixes > that could go onto master immediately, send them in. Ack, thanks! Regards, Guillem
