bugGNU troff - Bugs: bug #61167, "make man" does not...

 
 

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

Submitted by:  Keith Marshall <keithmarshall>
Submitted on:  Wed 15 Sep 2021 11:04:52 PM UTC
 
Category:  General Severity:  3 - Normal
Item Group:  Build/Installation Status:  Fixed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  1.23.0
* Mandatory Fields

Add a New Comment (Rich Markup)
   

Comment Type & Canned Response:
       No canned response available

 

( Jump to the original submission )

Mon 21 Feb 2022 11:19:59 AM UTC, comment #10: 

commit 9f8cae9ac0ec6ea6b55fe0e23959b6bb4ab7c1e4
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Mon Feb 21 01:11:08 2022 +1100

    doc/doc.am: Add targets "man-all" and "man-clean".

    * doc/doc.am: Add phony targets "man-all" and "man-clean" to
      (re-)generate and delete all man pages, respectively.

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

G. Branden Robinson <gbranden>
Project Administrator
Sun 20 Feb 2022 02:13:02 PM UTC, comment #9: 

Pending push:

commit 6681cb7756b36a1ce116af543c027bcf5ef17bb6 (HEAD -> master)
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Mon Feb 21 01:11:08 2022 +1100

    doc/doc.am: Add targets "man-all" and "man-clean".

    * doc/doc.am: Add phony targets "man-all" and "man-clean" to
      (re-)generate and delete all man pages, respectively.

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

Not quite what Keith asked for but it will have to serve pending feedback on comment #7.

G. Branden Robinson <gbranden>
Project Administrator
Tue 25 Jan 2022 04:27:16 PM UTC, comment #8: 

Would a "manpages" target be satisfactory?

After the machinery I added for generation of a 380-page compilation PDF of all of groff's man pages, it'd be a one-liner to implement.

G. Branden Robinson <gbranden>
Project Administrator
Sun 26 Sep 2021 07:02:32 AM UTC, comment #7: 

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.

G. Branden Robinson <gbranden>
Project Administrator
Sat 25 Sep 2021 01:46:22 PM UTC, 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.

Ingo Schwarze <schwarze>
Project Member
Sat 25 Sep 2021 05:39:30 AM UTC, comment #5: 

Hi, Keith & Ingo (& Dave)!

(Ingo said:)
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:

> 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)

G. Branden Robinson <gbranden>
Project Administrator
Fri 24 Sep 2021 11:44:51 PM UTC, comment #4: 

In 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, 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.

Keith Marshall <keithmarshall>
Project Member
Fri 24 Sep 2021 11:13:16 AM UTC, comment #3: 

Dave dixit:

> the red-headed stepchildren of documentation


Maybe, but i don't consider this an indication.  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.

Providing extra user-visible targets for every trivial detail runs conter to the important goal of keeping build systems simple and easy to maintain.

Ingo Schwarze <schwarze>
Project Member
Fri 24 Sep 2021 04:34:58 AM UTC, comment #2: 

comment #1:

> 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 page lists "the most useful targets that the GNU Coding Standards specify."  The comprehensive list of GNU make targets seems to be at

http://www.gnu.org/prep/standards/html_node/Standard-Targets.html

which says "All GNU programs should have the following targets in their Makefiles."

This page still does not list a "man" target.  Man pages are mentioned in passing under the "install" target.  It seems even in 2021, GNU considers man pages the red-headed stepchildren of documentation.

Dave <barx>
Project Member
Thu 23 Sep 2021 03:24:30 AM UTC, comment #1: 

Hi Keith,

Can you tell me where in the GNU Coding Standards document that a 'man' target that generates man pages is mandated?

Not saying it's a bad idea, I just can't locate the authority you're citing.

I looked here:

https://www.gnu.org/prep/standards/html_node/Man-Pages.html#index-man-pages

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

Regards,
Branden

G. Branden Robinson <gbranden>
Project Administrator
Wed 15 Sep 2021 11:04:52 PM UTC, original submission:  

To me, this looks like a GCS non-compliance: with a fresh git clone, after running "./bootstrap", and "./configure", I expect "make man" to generate manpages, but I see

$ make man
make: 'man' is up to date.

and no manpages are generated; to get them, I have to run (effectively) "make all".

This is not the behaviour stipulated by the GNU Coding Standards: "make all" is not supposed to generate manpages; that is the job of "make man"!  Requiring me to execute "make all", instead of "make man" is overkill: it forces me to build the whole kit and caboodle, when all I wanted was the manpages.

Keith Marshall <keithmarshall>
Project Member

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #51960:  move-man-pages.diff added by gbranden (5KiB - text/x-patch)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by schwarze (Posted a comment)
  • -email is unavailable- added by barx (Posted a comment)
  • -email is unavailable- added by gbranden (Posted a comment)
  • -email is unavailable- added by keithmarshall (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

     

     

     

    Follow 8 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-02-21 gbranden StatusIn Progress => Fixed
        Open/ClosedOpen => Closed
        Planned ReleaseNone => 1.23.0
    2022-02-20 gbranden StatusNeed Info => In Progress
        Assigned toNone => gbranden
    2022-01-25 gbranden CategoryNone => General
    2021-09-25 gbranden Attached File- => Added move-man-pages.diff, #51960
    2021-09-23 gbranden StatusNone => Need Info

    Back to the top


    Powered by Savane 3.9