Re: [Groff] automake for man-pages

[Bertrand Garrigues]

Hi Bernd,

I've read your previous mails on this topic, sorry for answering a bit
late, summer makes me lazy...

On Thu, Aug 13 2015 at 09:31:30 AM, "Bernd Warken" <address@hidden> wrote:
> If you make a helping answer to this email, you will not be forced to do
> a fix yourself.
>
> The automake file Makefile.am has some functions regrading the man-pages.
> Unfortunately some of these functions are only commented in the generated
> Makefile.in/Makefile.
>
> I also do not know, how the man-pages get the final section number.

I used the Automake variables man1_MANS, man5_MANS, man7_MANS to define
the list of man files to be installed in sections 1, 5, and 7.

This is described here:

  https://www.gnu.org/software/automake/manual/automake.html#Man-Pages

So for example the files listed in man1_MANS will be automatically
installed with the correct suffix .1 in section1.  The variables
man1_MANS, man5_MANS, man7_MANS are initialized in Makefile.am and then
every .am file add its man files to one of these variables.

Moreover in groff all man files must be generated at build time because
some variables are subsituted.

So for example, in contrib/gpinyin/gpinyin.am:

  - contrib/gpinyin/gpinyin.n is generated from
    contrib/gpinyin/gpinyin.man.  The "suffix rule" to generate .n file
    from .man file is defined in Makefile.am:

      # Rule to build .man files. The brackets around the @ are used to prevent 
the 
      # substitution of the variable by automake. 
      .man.n:
           ...

  - We will install the resulting man file gpinyin.n in section 1:

    man1_MANS += contrib/gpinyin/gpinyin.n

  - Note also that contrib/gpinyin/gpinyin.man is added to EXTRA_DIST as
    it must be included in the tarball that will be distributed.

In Makefile.am, the code after

  if USEPROGRAMPREFIX

is used only in the case the build system detects an existing troff
installed on the sytem, in which case we have to add a 'g' prefix to
some of the man files.  The files that will have a 'g' prefix are listed
in the variables PREFIXMAN1, PREFIXMAN5 and PREFIXMAN7. In the generated
Makefile you see the corresponding code commented out because
USEPROGRAMPREFIX is not set on your system.  The only thing is that
after the 'else' the 3 lines

  man1_MANS += $(PREFIXMAN1)
  man1_MANS += $(PREFIXMAN5)
  man1_MANS += $(PREFIXMAN7)
  
are incorrect, it should be of course

  man1_MANS += $(PREFIXMAN1)
  man5_MANS += $(PREFIXMAN5)
  man7_MANS += $(PREFIXMAN7)

This was unnoticed because only PREFIXMAN1 is used in all the .am
files, PREFIXMAN5 and PREFIXMAN7 are currently empty.


I've left man files as .man in the source tree because it was the case
before the Automake migration.  I you prefer to have files in the source
tree that have a suffix corresponding to the section they belong to
(gpinyin.1.man instead of gpinyin.man for example) it should be possible
but more complicated because we would have to defined more suffix rules
to build the final man files from .1.man, .5.man and .7.man (we would
have to define a new suffix I think, see
https://www.gnu.org/software/automake/manual/automake.html#Suffixes).


Regards,

--
Bertrand Garrigues