[bug #61167] "make man" does not generate manpages, as it should

[G. Branden Robinson]

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/