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

[G. Branden Robinson]

Follow-up Comment #7, bug #61167 (project groff):

[comment #6 comment #6:]
> Right now, let me refrain from lobbying for the deletion of a target that
already exists, even if i doubt its importance; i think more important cleanup
work exists, and the bar for deleting an existing feature is likely a bit
higher than the bar for adding a new one would be.
> 
> That said, i think Keith is right that having a feature which does not work
is a bug, and thanks to Branden for the analysis of what goes wrong.
> 
> If we want "man" to be the name of a target (which apparently was already
decided in the past), then having a directory of the same name looks like
asking for trouble to me.  So if renaming the directory does indeed fix the
bug, then that sounds reasonable to me.  I did not inspect the patch, but
trust Branden to not break the build system if he decides to do it.

I think there are some bad assumptions here.

If you go to commit e1d74edf2cd5d99503d71d52ee49fdcd0df2ae8b (1 September
2014), as far as I can tell no "man" target exists, though a "man" directory
does.

The "man" target springs to life in the next commit, 9828e05cb, and its
purpose, then and to the present day, is to create a directory called "man" in
a build tree.

It is not to cause all the man pages to be built.

Keith's expectations regarding the semantics of a "man" target must have come
from outside the groff project.

The problem is not that a buggy feature is in place: a feature is absent, and
its most obvious implementation would slightly complicate our build system. 
(Of itself, that's not enough to deter me.)

Further, this is not a matter of simple renaming but of a merging relocation:
we already have a "doc/" directory and it already contains stuff, notably our
Texinfo manual.  It might be worth noting that doc/doc.am gets around an
analogous problem to the one under discussion ("doc" is both a phony target
and the name of a directory that already exists in the source tree and needs
to exist in the build tree) by "manually" checking for and creating the
directory in the rules of several targets.

I remain ambivalent about this issue.  It has historically been fairly popular
for free software projects to be organized such that man pages live in a
"man/" directory alongside, say, "src/".  But historically projects have also
often not supported out-of-tree builds, "freeing up" the target name "man" for
generation of man pages.

There's an impedance mismatch between traditions here.  groff, by design or
accident, after avoiding the issue until 2014, landed on the opposite side
from Keith's preference.

I don't have a strong objection to moving our "most general" man pages to
doc/, and since our Texinfo and other manuals (pic.ms, ms.ms) are there as
well, maybe it will even help future contributors pay appropriate attention to
the man pages there.

But as far as a larger project of doing this to manifest some broader standard
Keith might like to promulgate regarding a "man" target for projects, I am not
sure I personally have the energy for pushing on that rock (I feel
sufficiently taxed trying to persuade people to write good documentation at
all).  As far as I'm concerned, addressing the issue of this ticket would be a
groff idiosyncrasy.  Maybe a salutary one, but not one I generally expect from
projects.

    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?61167>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/