Aw: Re: Generating 'cat' pages on make install

[Jason Curl]

Von:     Benoit SIGOURE <address@hidden>
> On Nov 4, 2007, at 7:59 PM, Jason Curl wrote:
> 
> > I've implemented the following:
> >
> > -----8<---- Makefile.am ----
> > man_MANS =                                                      \
> >    libmofo.3                                                   \
> >    convertstring.3                                             \
> >    mofobuilddate.3 mofobuildhost.3 mofoversion.3 mofoendian.3  \
> >    smsread.3
> >
> > html_DATA = $(man_MANS:.3=.html)
> >
> > CLEANFILES = $(html_DATA)
> >
> > EXTRA_DIST = $(man_MANS)
> >
> > all-local: $(html_DATA)
> >
> > # When we 'make' we create the .html files
> > SUFFIXES = .html
> 
> Automake can infer the suffixes automagically, you don't need to  
> fiddle with SUFFIXES.

Gone. 

> 
> > .3.html:
> >    @MAN2HTML@ $^ > $@
> > -----8<---- configure.ac ----
> > ...
> > AC_PATH_PROG(MAN2HTML,man2html,man2html)
> > ...
> > --------------------
> >
> > I haven't figured out how to define the variable $(MAN2HTML)  
> > instead using automake substitution with @address@hidden Did I miss  
> > something?
> 
> It works for me, that's weird.  Do you see the definition of MAN2HTML  
> in `Makefile'?

My foul, it is working. I was too premature in testing. Probably an incorrect 
"configure.ac" at the time of the test.

> 
> By the way, I'd do this instead:
> 
> AC_PATH_PROG([MAN2HTML], [man2html])
> test x"$MAN2HTML" = x && $as_unset MAN2HTML
> AM_MISSING_PROG([MAN2HTML], [man2html])
> 
> So that if the user hasn't got man2html installed, they will get:
> 
> /bin/sh /tmp/ac/missing --run man2html myman.3 myman.html
> /tmp/ac/missing: line 54: man2html: command not found
> WARNING: `man2html' is needed, and is missing on your system.
>           You might have modified some files without having the
>           proper tools for further handling them.  Check the `README'  file,
>           it often tells you about the needed prerequisites for installing
>           this package.  You may also peek at any GNU archive site, in case
>           some other package would contain this missing `man2html' program.
> make: *** [myman.html] Error 1
> 
> The $as_unset thing is to remove the variable MAN2HTML, in which case  
> AM_MISSING_PROG will enter into action.
> 
> > How can I prevent the rule from running if the user doesn't have  
> > 'man2html' in their path? I don't think I can just use a "dummy"  
> > command like echo, as the /usr/bin/install command would return an  
> > error:
> >
> > /usr/bin/install -c -m 644 '../../../../code/libmofo/man/ 
> > convertstring.html' '/home/jcurl/mofo/build/windows/release/share/ 
> > doc/libm
> > ofo/convertstring.html'
> > /usr/bin/install: cannot stat `../../../../code/libmofo/man/ 
> > convertstring.html': No such file or directory
> > make[3]: *** [install-htmlDATA] Error 1
> > make[3]: Leaving directory `/home/jcurl/mofo/build/windows/libmofo/ 
> > man'
> > make[2]: *** [install-am] Error 2
> > make[2]: Leaving directory `/home/jcurl/mofo/build/windows/libmofo/ 
> > man'
> > make[1]: *** [install-recursive] Error 1
> > make[1]: Leaving directory `/home/jcurl/mofo/build/windows/libmofo'
> > make: *** [install-recursive] Error 1
> >
> > Definitely not what I want...
> 
> Ah, then I see two ways out:
> 1. Consider that the HTML pages are BUILT_SOURCES.  This will entail  
> that they will be distributed (and you shouldn't list them in  
> CLEANFILES) so that people who don't have man2html and who simply  
> want to build your package without changing it can have the pre- 
> generated HTML pages right away.

My observations: It looks like that the sources are built in "build" directory 
and not in the "source" directory. It even works when using VPATH builds and 
make dist. However I like to check in built source files so all you need is a 
compiler and not the myriad of tools, matter of taste I guess. The HTML files 
are not packaged automatically, so I've included them in the EXTRA_DIST 
directive too.

> 2. Use an Automake conditional to fill the html_DATA variable only if  
> configure detected that man2html was available.
> 
> I prefer 1. better, since people *want* the documentation, without  
> the hassle of installing all the dependencies to build it.  If you go  
> for 2., consider providing a separate package that contains the pre- 
> built documentation.

My OpenSUSE distribution doesn't have "man2html" and when looking on the web it 
looks like there are multiple (incompatible) implementations. It looks like 
I'll be using rman that exists on Linux and also on Cygwin. Makes my build more 
portable.

> 
> Cheers,
> 
Merci.

In the end, everything works like a dream. Here's my solution for those who are 
interested, or who'd like to do something similar for their projects.

----- configure.ac -----
...
AC_PATH_PROG([RMAN], [rman])
test x"$RMAN" = x && $ac_unset RMAN
AM_MISSING_PROG([RMAN], [rman])
...
----- Makefile.am -----
man_MANS = file1.3 file2.3
html_DATA = ($man_MANS:.3=.html)
BUILT_SOURCES = $(html_DATA)
EXTRA_DIST = $(man_MANS) $(html_DATA)
all-local: $(html_DATA)
.3.html:
    cd `dirname $^`; \
    $(RMAN) --filter HTML -S `basename $^` > $@
----- end -----

The 'cd' is required in case a man page is a reference to another with the 
".so" command, so "rman" find the page in case of VPATH builds. It has the side 
effect of putting the results in the SOURCE directory. Some people may not like 
this, but I believe it should also work in the case of RO filesystems as the 
.html files are only built when they're not available. As the directives above 
cause the html files to be packaged, there should be no excuse, except for 
filesystems with screwed up timestamps.





Viel oder wenig? Schnell oder langsam? Unbegrenzt surfen + telefonieren
ohne Zeit- und Volumenbegrenzung? DAS TOP ANGEBOT FÜR ALLE NEUEINSTEIGER
Jetzt bei Arcor: günstig und schnell mit DSL - das All-Inclusive-Paket
für clevere Doppel-Sparer, nur  29,95 €  inkl. DSL- und ISDN-Grundgebühr!
http://www.arcor.de/rd/emf-dsl-2