Hi Peter, Peter Schaffter wrote on Sun, Sep 21, 2014 at 09:39:17PM -0400:
> Sorry not to get back on this right away. I've been away for a > couple of days--work and computer free! No problem. Unless a software project will be abondoned soon, a few days delay really don't matter. > On Fri, Sep 19, 2014, Ingo Schwarze wrote: >> Given that the build systems disables building HTML documentation >> when some support software is missing on the target system and >> that the main mom documentation is (very unfortunately, but that's >> the current state of affairs) HTML, > A lot of mom users would disagree that having the documentation in > html is unfortunate. :) Well, what i mean is this. In my tutorial on documentation here in Sofia i'm going to list seven quality criteria for software documentation: 1. correctness 2. completeness 3. conciseness 4. ease of access (both regarding searching and regarding the required tools for viewing it); ideally, all documentation should be in one place so you cannot miss it 5. semantic markup 6. ease of reading; ideally, uniform display markup and style 7. ease of writing; ideally, one simple, standard input language HTML flat-out fails on criteria 4-7. Regarding 4, it's not just that people cannot see it in man(1) where documentation is expected to be, but need to install a browser; on top of that, apropos(1) will be completely blind to it. >> we end up in a situation where some groff installations >> do not include full mom documentation. > However, I'm going to have a look at the > situation of disabling building html when support software is > missing. The mom docs require no special build tools, hence there's > no reason not to include the docs in every installation. In that case, disabling the build of grohtml(1) when gs(1) or pnmcut(1) are missing would indeed be wrong. It the build system maybe mixing up build and run dependencies here? *Building* something should be disabled if it requires linking against an external library that is not installed - since the build would fail otherwise. If something merely needs an additional external tool *at run time*, that should not disable the build, because it's completely legitimate to build first and maybe install the dependency later when you actually need the functionality. This holds even more when the dependency is only needed for a subset of the functionality. All this becomes even more important when talking about packaging, where the distinction of build and run dependencies is absolutely crucial - but a packaging system is out of luck of having something as a pure run dependency if the configure script already spoils the show and turns it into a needless build dependency. I have no idea what the situation with grohtml(1) is, that is, what that beast needs for building, and what it needs for which run-time functionality - i never used it. But it sounds good that you want to look into that. >> To mitigate that situation, i think it would help a bit to include >> a link to http://www.schaffter.ca/mom/mom-04.html (that file name >> seems a bit awkward; is it stable?) in contrib/mom/groff_mom.man >> below SEE ALSO. > Yes, that would help. I'll get onto it. Great, thanks for doing that. Your commit looks fine to me, it definitely makes finding the HTML docs easier. > Something else that would help, too, would be converting the docs > to pdf. Hell, *NO*. That's even worse than HTML. 4. ease of access: complete failure, now you suddenly need xpdf(1) to even read the docs?! 5. semantic markup: even worse than HTML; in HTML, you can do semantic markup if you want to (mandoc -Thml does), even though it's not much use because it's completely non-standard; in PDF, you can't at all. criteria 6 and 7: not much of a change So, there are two downsides to PDF but no benefit. Yours, Ingo