netatalk
netatalk copied to clipboard
Netatalk
Remove generated man pages from revision control
Since it's trivial to generate man pages from xml with docbook-xsl, we should consider removing them from revision control.
Pros: Removes the maintenance overhead of commits and PRs of regenerated man pages Always have up to date man pages, no risk of divergence when someone forgets to go through the manual process Slightly lighter tarballs
Cons: make will fail when man pages are absent Introduces dependencies on xsltproc and docbook-xsl
In netatalk3 this may be hard to automate with the current setup due to the rigidity of autotools. We can't bootstrap when a single *.in file is missing, so we can't reach the ./configure --with-docbook... stage to generate the files.
In netatalk2 the docbook generation is a separate workflow (a static Makefile in doc/manual/ ) so it's fairly easy, although it does introduce a manual bootstrap step which is cumbersome. Maybe it can be automated as a pre-autoconf step in the bootstrap script?
For me the whole manpage generation thing from .in files adds an extra layer of complexity that doesn't need to be there. Manpages can be generated directly during make from their xml files, be installed with make install and used for manual generation when make html is run. Any updating is done within the xml source so manpages and manual html will be updated automatically. Yes, it does introduce dependencies on xsltproc and docbook-xsl but these can be easily installed with package management. This approach is used in many projects such as Samba and iputils and leads to simplicity and transparency which is good.
@dgsga There has been an interesting development in this space lately. The now-infamous xz backdoor attack that affected Debian and Red Hat in particular involved seeding a malicious autotools m4 macro into the release tarball ... which was not under revision control but injected when rolling the tarball.
I'm following the debian-devel mailing list where there's now an ongoing debate about adding a sanitation step to Debian packaging that validates tarball sources against the upstream revision controlled sources. So, the practice of shipping "bootstrapped" release tarballs is now effectively viewed with suspicion, and may very well become banned in the future.
@dgsga I would be up for postponing this until after we remove the autotools build system. What do you think?
@dgsga Tentatively removing from the 3.2.0 scope. Please add it back if you disagree. :)