Man page installation and distribution #12921

I did this

Recently there's been a lot of changes around man pages concerning generation, installation, distribution, and build-by-default.

First, here's my understanding of some automake variables used in curl:

• man_MANS: Man pages listed here will get built by default and installed, but not distributed
• dist_man_MANS: Man pages listed here will get built by default, installed, and distributed.
• noinst_man_MANS: This doesn't actually do anything. I don't see any reference to it in automake or the generated Makefile.
• nodist_MANS: This doesn't do anything either. Looking at automake source, there is nodist_man_MANS, which is the same as man_MANS since man pages aren't distributed by default (see https://www.gnu.org/software/automake/manual/html_node/Man-Pages.html). The comment in the source says "We handle nodist_ for uniformity. man pages aren't distributed by default so it isn't actually very important".
• EXTRA_DIST: Files here are distributed, but not installed or built by the default target.

Here's a summary of the recent history of a few man pages:

• Before 8.6.0, mk-ca-bundle.1 was not generated, but it was distributed since it was in noinst_man_MANS, which was present in EXTRA_DIST.

  • 8.6.0 included eefcc1b, which added it to man_MANS, making it get installed and built by default. Since noinst_man_MANS was dropped from EXTRA_DIST, it no longer got distributed.
  • a911f4f removed it from man_MANS, so it was no longer installed or built by default. The only reference left to mk-ca-bundle.1 at this point was through noinst_man_MANS, a bogus variable not used by anything, and CLEANFILES.
  • 755b31d added it to dist_man_MANS, making it get installed once again, distributed, and built by default. This is the current state.

  It seems to me that the intent is for it to be built by default and distributed, but not installed. I think the way to do this is to remove mk-ca-bundle.1 from dist_man_MANS, add it to EXTRA_DIST to distribute it, and add a dependency all-local: $(MK_CA_DOCS) to build it by default.

• Before 8.6.0, curl.1 was distributed since it was present in noinst_man_MANS, which was added to EXTRA_DIST.

  • As above, eefcc1b dropped noinst_man_MANS from EXTRA_DIST, which caused curl.1 to no longer be distributed.
  • cf5f604 added it back through a dist-hook copying it to curl.1.dist. This is fine, but this could have also been done by adding curl.1 to EXTRA_DIST, which is what was done prior to 8.6.0 (indirectly). If you do end up sticking with the dist-hook and naming it curl.1.dist, there is some other logic that can be removed:
    

    curl/docs/Makefile.am

    Lines 115 to 127 in 922091c

    	# $(abs_builddir) is to disable VPATH when searching for this file, which
    	# would otherwise find the copy in $(srcdir) which breaks the $(HUGE)
    	# rule in src/Makefile.am in out-of-tree builds that references the file in the
    	# build directory.
    	#
    	# First, seed the used copy of curl.1 with the prebuilt copy (in an out-of-tree
    	# build), then run make recursively to rebuild it only if its dependencies
    	# have changed.
    	$(abs_builddir)/curl.1:
    	if test "$(top_builddir)x" != "$(top_srcdir)x" -a -e "$(srcdir)/curl.1"; then \
    	$(INSTALL_DATA) "$(srcdir)/curl.1" $@ \
    	&& touch -r "$(srcdir)/curl.1" $@; fi
    	cd cmdline-opts && $(MAKE)

    
    

    curl/docs/Makefile.am

    Lines 34 to 36 in 922091c

    	# EXTRA_DIST breaks with $(abs_builddir) so build it using this variable
    	# but distribute it (using the relative file name) in the next variable
    	man_MANS = $(abs_builddir)/curl.1

    
    I believe this was only needed to make the distinction between the distributed curl.1, and the built curl.1 for out-of-tree builds. If the distributed file is called curl.1.dist, I think this tricky logic can be removed. However, for uniformity, if one distributed manual using the .dist naming scheme, so should the others (curl-config.1 and mk-ca-bundle.1).

As described above, some automake variables set by curl aren't actually used by automake. I think noinst_man_MANS and nodist_MANS should be removed from docs/Makefile.am, docs/libcurl/Makefile.am, and docs/libcurl/opts/Makefile.am, since it just adds to the confusion.

I can work on a pull request to resolve these issues, but first, maybe you could confirm the desired behavior? I think it is

Additionally, should distributed man pages be named foo.[1-9] or foo.[1-9].dist?

I expected the following

No response

curl/libcurl version

Current master 5a4b2f9

operating system

N/A