Follow-up Comment #5, bug #61167 (project groff): Hi, Keith & Ingo (& Dave)!
(Ingo said:) [comment #3 comment #3:] > Well-designed manual pages simply don't need to be built, just installed. I don't share this implicit characterization of groff's man pages as ill-designed (a few have some internal structural defects, admittedly). To amplify one of Keith's points, _all_ of them undergo sed replacement of special strings that are not determined until configuration time. These include the version number of groff (embedded in page footers), numerous directory names, and a few other things like the default paper format. In my opinion all of the foregoing parameters have sufficient justification. Since groff 1.22.3, our man pages have actually gotten _better_ about documenting the project as configured, not to toot my own horn. Past page authors seemed to write in ignorance of the configuration variables, inserting hard-coded directory names which were often incorrect, or punting my omitting the directory portion altogether, both of which make the reader's job harder. I don't think it's controversial to assert that documentation should be accurate. I infer that there's a lot less room for configuration and build-time preference in OpenBSD; if groff were an OpenBSD project we might rip most or all of the Autoconf configuration knobs off, facilitating hard-coded-everything in the man page sources, but that is a counterfactual. (groff_man(7) and groff_man_style(7) are furthermore generated via m4 from a single source document, groff_man.7.man.in. The wisdom of this arrangement might be more debatable, but as it was my own innovation I will not trouble myself to defend it here and instead point to groff's commit history, since I try to share my rationales for changes, and await contention thereof. But even in the absence of this procedure, the use of sed would remain.) > So i don't see a problem with including them in the "install" target I think this is slightly beside Keith's point; by the time the `install` target sees the man pages, they're in their post-sed (and -m4) form. Keith's grievance is that a `man` target doesn't produce all these man pages for him. It's tantalizingly close--we already define a suffix rule for them[1]. > Providing extra user-visible targets for every trivial detail runs conter to the important goal of keeping build systems simple and easy to maintain. This is true, too. I'm ambivalent about the issue. (Keith wrote:) [comment #4 comment #4:] > My apologies; I thought "man" was among the alternative documentation formats, but apparently, my recollection is mistaken; "man" does not appear to be a mandatory target. > > Notwithstanding, we *do* provide a "man" target, and it is completely incongruous that invoking it elicits the response, "'man' is up to date", when it clearly isn't! The reason for it appears to be to support out-of-tree builds; we have a source directory called `man/`, which contains man pages that will need to undergo transformation by the suffix rule described above. The practice of groff's build system (except for executable programs) is to generate targets in the same directory as their source file, or in a build tree that reproduces the source structure. And that's where the trouble comes in. We have a source directory called `man/`, so we have to have a build directory called `man/` and there's no reason to expect any out-of-tree build directories to already exist, so we have to have targets for making them, and one of the fundamental idioms of make is that the name used for creating a target is the name _of_ the target. > To get the required effect, one must invoke the "all" target, yet the GCS explicitly *does* say that "all" should *not* build documentation, (other than, maybe, info: the actual statement suggests that "all" need not build any documentation, since pre-built info files should be included in the distribution, and all other formats should be requested explicitly). I feel that we should deviate from the GNU Coding Standards (GCS) in this respect (and let that not alarm us--we don't use the GCS's brace style, either). groff has historically produced its own man pages as part of its default target and I think it should continue to do so. The GCS has long been myopic with respect to man pages and 30+ years of having a Free Software troff implementation with a Free `an` macro package has failed to correct its vision. C'est la vie. > > I also don't see "man" in the list of standard targets documented in GNU Automake. > > https://www.gnu.org/software/automake/manual/html_node/Standard-Targets.html#Standard-Targets > That's hardly authoritative; the authoritative source is GCS section 7.2.6: > https://www.gnu.org/prep/standards/html_node/Standard-Targets.html#Standard-Targets Right. When I couldn't find support for your assertion in the GCS itself, I went hunting. The Automake manual seemed like the next best place to look for an enumeration of "standard" targets enshrined by the build system. I have a straw-man diff implementing a relocation of the groff man pages under man/ to doc/. I'll attach it. Regards, Branden [1] https://git.savannah.gnu.org/cgit/groff.git/tree/Makefile.am#n854 (file #51960) _______________________________________________________ Additional Item Attachment: File name: move-man-pages.diff Size:4 KB <https://file.savannah.gnu.org/file/move-man-pages.diff?file_id=51960> _______________________________________________________ Reply to this item at: <https://savannah.gnu.org/bugs/?61167> _______________________________________________ Message sent via Savannah https://savannah.gnu.org/
