documentation philosophy

[Benjamin Sailer]

Hello all,

i'm working on my first larger software project configured with
GNU autotools (automake and autoconf), and close to finishing
it, i was thinking about doing the documentation with texinfo.
The developement is done on RedHat Linux 7.3, but as the autotools
provided there are quite old, i upgraded to some rawhide packages:
autoconf-2.53-7
automake-1.6.3-5

First i produced

$(top_srcdir)/doc/runctrl.texi

, thinking it would be straight forward to place a

<snip>
info_INFOS = doc/runctrl.texi
<snip>

line in my Makefile.am.  But what is the idea behind this rule?
Should i deliver only the .texi file with my sources, or should i
also produce the .info file(s) when preparing the package (as done
in the GNU example package "hello").  Then what about other output
formats (.dvi/.ps, .html, .txt)?  My problem is that the users of
my software are not to familiar with info, so they will most likely
use either the postscript documentation or the html pages.

In my current configuration (where i try to produce the .html / .txt
files before packaging and the .ps file as part of the build) i
have two actual problems:

1. creating and installing of .ps file fails
--------------------------------------------
It seems to me that it is hard to produce .ps output during build
(although there are some rules availabe), when i want to meet the
following two requirements:

- i don't want to use recursive make (reading the article "Recursive
        Make Considered Harmful" from Peter Miller)
- i want to use the feature of GNU autotools to separate source and
        built tree (as i have several platforms to test the software -
        here it is a very helpful feature)

assume /home/bsailer/build/runctrl as the $(top_srcdir) and
/home/bsailer/build/i686-pc-linux-gnu/runctrltest as the build root:

<snip>
address@hidden $ make runctrl.ps 
make: *** No rule to make target `runctrl.ps'.  Stop.
address@hidden $ make runctrl.dvi
make: *** No rule to make target `runctrl.dvi'.  Stop.
address@hidden $ make doc/runctrl.dvi
TEXINPUTS="../../runctrl/config:$TEXINPUTS" \
MAKEINFO='/bin/sh /home/bsailer/build/runctrl/config/missing --run makeinfo   
-I ../../runctrl' \
texi2dvi ../../runctrl/doc/runctrl.texi
</snip>
...
<snip>
Output written on runctrl.dvi (81 pages, 249480 bytes).
Transcript written on runctrl.log.
address@hidden $ make doc/runctrl.ps 
TEXINPUTS="../../runctrl/config:$TEXINPUTS" \
MAKEINFO='/bin/sh /home/bsailer/build/runctrl/config/missing --run makeinfo   
-I ../../runctrl' \
texi2dvi ../../runctrl/doc/runctrl.texi
</snip>
...
<snip>
ps doc/runctrl.dvi -o doc/runctrl.ps
This is dvips(k) 5.86 Copyright 1999 Radical Eye Software (www.radicaleye.com)
dvips: ! DVI file can't be opened.
make: *** [doc/runctrl.ps] Error 1
address@hidden $ 
</snip>

this looks like i can neither place

<snip>
data_DATA = doc/runctrl.ps
</snip>

to my Makefile.am, nor

<snip>
data_DATA = runctrl.ps
</snip>

What to do?

2. info files are not installed
-------------------------------
being in the buid root, after configuring and making it looks like

<snip>
address@hidden $ make
make  all-am
make[1]: Entering directory `/home/bsailer/build/i686-pc-linux-gnu/runctrltest'
make[1]: Leaving directory `/home/bsailer/build/i686-pc-linux-gnu/runctrltest'
address@hidden $ make install
make[1]: Entering directory `/home/bsailer/build/i686-pc-linux-gnu/runctrltest'
/bin/sh ../../runctrl/config/mkinstalldirs /home/bsailer/bin
  /usr/bin/install -c agent /home/bsailer/bin/run_agent
  /usr/bin/install -c sequencer /home/bsailer/bin/run_sequencer
  /usr/bin/install -c manager /home/bsailer/bin/run_manager
/bin/sh ../../runctrl/config/mkinstalldirs /home/bsailer/bin
 /usr/bin/install -c scripts/ctrl /home/bsailer/bin/run_ctrl
/bin/sh ../../runctrl/config/mkinstalldirs /home/bsailer/share
 /usr/bin/install -c -m 644 ../../runctrl/doc/runctrl.html 
/home/bsailer/share/runctrl.html
 /usr/bin/install -c -m 644 ../../runctrl/doc/runctrl.txt 
/home/bsailer/share/runctrl.txt
 /usr/bin/install -c -m 644 ../../runctrl/doc/runctrl.xml 
/home/bsailer/share/runctrl.xml
 /usr/bin/install -c -m 644 ../../runctrl/tcl/runctrl.tcl 
/home/bsailer/share/runctrl.tcl
/bin/sh ../../runctrl/config/mkinstalldirs /home/bsailer/info
make[1]: Leaving directory `/home/bsailer/build/i686-pc-linux-gnu/runctrltest'
address@hidden $
</snip>

but the info files are not installed in /home/bsailer/info ???

Do i miss statements in Makefile.am / configure.in?  Do I have to
change the structure of my package?  Or do i just have to upgrade the
autotools?  Can anybody help?

Could You please send me a copy of the answer?  Too many mailing lists
for me ...

Thanks in advance

Benjamin

-- 
*****************************************************************
Benjamin Sailer
eMail: address@hidden
*****************************************************************
Disclaimer:  This signature has been generated automatically and
does not reflect my opinion at all.
                -- Benjamin Sailer

I'd like to meet the guy who invented beer and see what he's working on now.