Hello, 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. A unified i18n for the whole source package would be beneficial. > I've got a sketch now with everything converted by hand, but the build > system is not fully migrated, so this all needs polishing, and I just > found Hideki Yamane's conversion scripts in the rst-conversion branch, > which I might try to reuse to split the menu-policy and perl-policy > documents into chapters. My plan, like with the original DebianDoc-SGML > conversion would be to create a report in the BTS to track the progress, > and then to send a set of preparatory patches (several of which I have > and seem independent of this conversion anyway) to make the conversion > easier. Then create/adapt a script to ideally handle the switch > automatically, and apply any necessary fixups, so that if this takes time > or the documents evolve in the mean time, then no manual work needs to be > done. That sounds good. > 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. > - 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? I'd prefer to leave them in the root until and unless we actually have any duplicates. We don't gain new filenames often. > - 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. For example, dblatex can obviously go once there is no docbook-xml left. I'm not sure what the html.tar is; can you say more? > - 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. > - 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. > - 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. > - 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. Thank you again. -- Sean Whitton
Attachment:
signature.asc
Description: PGP signature