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

[Keith Marshall]

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

In [comment #1 comment #1,] Branden said:
> Can you tell me where in the GNU Coding Standards document that a 'man'
target that generates man pages is mandated?
Section 7.2.6 "Standard Targets for Users"; at least that's where I had a
recollection of having seen it.
> Not saying it's a bad idea, I just can't locate the authority you're
citing.
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!  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 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
  
In follow-up [comment #3 comment #3,] Ingo said:
> Well-designed manual pages simply don't need to be built, just installed. 
So i don't see a problem with including them in the "install" target - and if
afflicted with the autoconf disease, also in the "all" target; but in most
cases, that disease only causes mild pain and suffering for manual pages, so
"man -l foo.man.in" usually works well enough anyway if you want to read these
files without installing them.
Maybe so, but our manpage sources *do* include templated substitutions, which
need some make target to process them.  It may well be sufficient for that
target to be "install"; I also don't object if "all" performs said
substitutions, in spite of the implied GCS non-compliance.  I *do*, however,
find it incongruous that, when we have a "man" target in place, it doesn't do
the job that it should!

> Providing extra user-visible targets for every trivial detail runs conter to
the important goal of keeping build systems simple and easy to maintain.
However, it is often convenient, (and I often find it helpful, from a
maintenance perspective), to implement user-visible targets in terms of
internal targets; although not necessarily intended to be user-visible, if any
of these make sense in a user-visible context, (as a "man" target may do),
then I see no grounds for objection.

BTW, I cannot agree with the categorization of autoconf as a "disease" ... I
find it to be a genuinely useful tool.  OTOH, automake ... well, I could view
that as a disease, and I'll say no more.

    _______________________________________________________

Reply to this item at:

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

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