Would you take a crack at implementing the documentation generation
in the autotools build? Basically we need to do with autotools what
is done by bld/Makefile make docs, i.e., generate (and then install)
nco.ps, nco.dvi, nco.info from doc/nco.texi.
Thanks,
Charlie
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Charlie,
I put back the making of the doc/ directory. However, when making in doc/, 'makeinfo' crashes because the nodes are screwed up in the new ncap section. I know the .info file will be automatically generated and installed. I'm not positive about the .dvi and .ps files; I might have to add a line somewhere. However, until 'makeinfo' sucessfully generates a .info file, I can't check it out. You might be able to fix nco.texi easier than I since I think you added the most recent stuff.
rorik
<snip>
Making all in doc
make[2]: Entering directory `/home/rorik/nco/doc'
cd . \
&& /bin/sh /home/rorik/nco/autobld/missing --run makeinfo \
`echo nco.texi | sed 's,.*/,,'`
./nco.texi:2693: Next field of node `Left hand casting' not pointed to.
./nco.texi:2875: This node (Intrinsic mathematical functions) has the bad Prev.
./nco.texi:2649: Node `ncap netCDF Arithmetic Processor' lacks menu item for `Left hand casting' despite being its Up target.
./nco.texi:2746: Next field of node `Syntax of @command{ncap} statements' not pointed to.
./nco.texi:2875: This node (Intrinsic mathematical functions) has the bad Prev.
./nco.texi:2649: Node `ncap netCDF Arithmetic Processor' lacks menu item for `Syntax of @command{ncap} statements' despite being its Up target.
./nco.texi:2794: Next field of node `Intrinsic functions' not pointed to.
./nco.texi:2875: This node (Intrinsic mathematical functions) has the bad Prev.
./nco.texi:2649: Node `ncap netCDF Arithmetic Processor' lacks menu item for `Intrinsic functions' despite being its Up target.
./nco.texi:2693: warning: unreferenced node `Left hand casting'.
./nco.texi:2746: warning: unreferenced node `Syntax of @command{ncap} statements'.
./nco.texi:2794: warning: unreferenced node `Intrinsic functions'.
makeinfo: Removing output file `/home/rorik/nco/doc/nco.info' due to errors; use --force to preserve.
make[2]: *** [nco.info] Error 1
make[2]: Leaving directory `/home/rorik/nco/doc'
make[1]: *** [all-recursive] Error 1
make[1]: Leaving directory `/home/rorik/nco'
make: *** [all] Error 2
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
OK, I fixed one syntax error in nco.texi but I could not
fix any of the node referencing errors that are causing
makeinfo to fail. I tried removing the offending nodes
one-by-one and could not figure out where the problem
is. Please use makeinfo --force for now and maybe
someone else will be able to isolate the problem in
nco.texi.
Thanks,
Charlie
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Charlie,
'makeinfo' works now with nco.texi. However, now I'm getting TeX errors when processing nco.texi. Do you have similar problems?
rorik
rorik@chabuku:~/nco/doc$ tex nco.texi
This is TeX, Version 3.14159 (Web2C 7.3.7)
(./nco.texi (/usr/share/texmf/tex/texinfo/texinfo.tex
Loading texinfo [version 2002-03-26.08]: Basics, pdf, fonts, page headings,
tables, conditionals, indexing, sectioning, toc, environments, defuns, macros,
cross references, (/usr/share/texmf/tex/plain/dvips/epsf.tex) localization,
and turning on texinfo input format.) [1] [2] (Foreword) (Summary) [1] [2]
Chapter 1 [3] [4]
Overfull \hbox (87.99039pt too wide) in paragraph at lines 265--277
@textrm from @texttt http://sourceforge.net/projects/nco\[] @textrm and @texttt
ftp://dust.ps.uci.edu/pub/zender/nco/nco.tar.gz[]@textrm .
Underfull \hbox (badness 5893) in paragraph at lines 308--319
@textrm out down-load-ing the en-tire source dis-tri-bu-tion), visit the @texts
c nco @textrm home-page at
[5] Cross reference values unknown; you must run TeX again. [6] [7] [8]
Chapter 2 [9] [10] [11] [12] [13] [14] [15] Chapter 3 [16] [17] [18] [19]
[20] [21] [22] [23] [24] [25] [26] [27] [28] [29]
WARNING: for users of Unix TeX 3.0!
This manual trips a bug in TeX version 3.0 (tex hangs).
If you are running another version of TeX, relax.
If you are running Unix TeX 3.0, kill this TeX process.
Then upgrade your TeX installation if you can.
(See ftp://ftp.gnu.org/pub/gnu/TeX.README.)
If you are stuck with version 3.0, run the
script ``tex3patch'' from the Texinfo distribution
to use a workaround.
Overfull \hbox (33.4pt too wide) in paragraph at lines 2335--2361
[] [][][][][][][]
Overfull \hbox (33.4pt too wide) in paragraph at lines 2363--2399
[] [][][][][][]
Overfull \hbox (33.4pt too wide) in paragraph at lines 2401--2451
[] [][][][][][][][]
! This `@end table' doesn't have a matching `@table'.
@unmatchedenderror ...esn't have a matching `@#1'}
Overfull \hbox (33.4pt too wide) in paragraph at lines 2476--2804
[] [][][][][][]
! You can't use `@end' in internal vertical mode.
<recently read> @ptexend
On my Redhat systems, only 1 & 2 work, and 3,4,5 fail.
At nco.sourceforge.net, 1,2,3,4 all appear to work and there is no dvips (5).
So, the texinfo support seems to be sensitive to the OS and the
versions of all the commands that are installed (bummer!).
I'm not sure when/if "tex nco.texi" needs to be run, but if
autotools tries and fails it's probably because the texinfo
installation is screwed up or out of date, like Redhat's.
I just made one changed to nco.texi that might help things.
So try it again and cross your fingers. Also, I cannot figure
out why the web page is serving up old versions of the documentation
but that's a fight for another day.
Charlie
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Charlie,
It appears that TeX (mine verison at least) does not like the footnote at about line 2236. It is something with the way it is processing the set/clear flags. I made a change removing the flags, so now TeX, and thus texi2dvi, work. It might need further work however.
rorik
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
The way I understand it, texi2dvi is just a wrapper around TeX. texi2html is an independent, huge perl script. The problem is most likely not TeX (I think Knuth is paying $1024 or more right now for finding errors), but I'm not sure how setting and clearing flags works in TeX, it is too cryptic and I simply use LaTeX. The way flags were set and cleared seems OK according to the Texinfo documentation; but maybe that's not entirely correct or complete.
rorik
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Charlie,
Do you think the .dvi .ps .pdf and .html documentation should be generated _automatically_ when 'make' is issued form the top level dir? The other option is to only generate each type of documentation when going to doc/ and executing 'make nco.ps' or 'make nco.pdf' or 'make nco.html', etc. The second option saves having to wait through all the documentation generation everytime you do a 'make clean;make'
rorik
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I understand that the doc build can be slow the first
time because of all the font generation etc.
But my feeling is that docs should build automatically
with the top level make. If the dependencies are set
up correctly then nco.ps : nco.texi. So after the first
build you have nco.ps and it should not be rebuilt
unless nco.texi has changed. make clean should
get rid of intermediate targets, but not nco.ps, nco.pdf,
nco.dvi, nco.info*, or nco.html. This is in the ideal
world. It may be true that some architectures have
all the compilers required to build the executables,
but have none of the tools required to build the docs.
Would it be possible to have autotools check for
existence of, e.g., dvips before attempting to run it?
That way builds will not break on those architectures.
So my feeling is that if we can get the dependencies
sorted out correctly, then make clean;make should
only be slow the first time. make distclean; make
should always be slow and remake all targets.
Does this sound feasible? BAsically most users
want the docs but are too inept to figure out they
have to type, e.g., make nco.ps in order to get them,
so we want to work with that in mind.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Oh yeah, note that this only pertains to the CVS snapshot. The distribution generated with 'make dist' (i.e. nco-2.6.2.tar.gz) will still contain nco.html nco.pdf nco.ps nco.dvi and nco.info.
rorik
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I guess if we could figure out how to link to the
update manual from the NCO homepage then
it's fine if the top-level make does not build the
docs. However, I cannot figure out why the website
links to old version of the manuals. It's like I'm getting
cached copies. Do you get the latest docs when
you visit the website?
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Yeah, I got version 2.6.2 in the dvi form, but the ps is old (april 2001) and the pdf is corrupted. The html looks newer, as it has ncap stuff, but I didn't see a version.
rorik
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
OK, I just had to clear the cache on my stupid browser.
I'm afraid the ps is old and the pdf is corrupted because
the sourceforge machines are the only ones I can build
the documentation on and they lack dvips. It's hard for me to work on the docs because I can't actually work
interactively on them on my own machine...
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I can easily make the creation of various types of documentation depenant on having the correct tools (ie texi2dvi, dvips, etc). However, the removal of .dvi and .ps files from the doc/ directory is hardcoded into Automake-1.6 I'm not sure why, because .info files are only removed on 'make maintainer-clean'. I think I'll post the query to their list.
In the meantime, I'm going to hold off commiting the changes to automatically make documentation if you have the tools. You can still do it manually in the doc/ directory, and I put that in the README in doc/
rorik
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Hi Rorik,
Would you take a crack at implementing the documentation generation
in the autotools build? Basically we need to do with autotools what
is done by bld/Makefile make docs, i.e., generate (and then install)
nco.ps, nco.dvi, nco.info from doc/nco.texi.
Thanks,
Charlie
Charlie,
I put back the making of the doc/ directory. However, when making in doc/, 'makeinfo' crashes because the nodes are screwed up in the new ncap section. I know the .info file will be automatically generated and installed. I'm not positive about the .dvi and .ps files; I might have to add a line somewhere. However, until 'makeinfo' sucessfully generates a .info file, I can't check it out. You might be able to fix nco.texi easier than I since I think you added the most recent stuff.
rorik
<snip>
Making all in doc
make[2]: Entering directory `/home/rorik/nco/doc'
cd . \ && /bin/sh /home/rorik/nco/autobld/missing --run makeinfo \ `echo nco.texi | sed 's,.*/,,'`
./nco.texi:2693: Next field of node `Left hand casting' not pointed to.
./nco.texi:2875: This node (Intrinsic mathematical functions) has the bad Prev.
./nco.texi:2649: Node `ncap netCDF Arithmetic Processor' lacks menu item for `Left hand casting' despite being its Up target.
./nco.texi:2746: Next field of node `Syntax of @command{ncap} statements' not pointed to.
./nco.texi:2875: This node (Intrinsic mathematical functions) has the bad Prev.
./nco.texi:2649: Node `ncap netCDF Arithmetic Processor' lacks menu item for `Syntax of @command{ncap} statements' despite being its Up target.
./nco.texi:2794: Next field of node `Intrinsic functions' not pointed to.
./nco.texi:2875: This node (Intrinsic mathematical functions) has the bad Prev.
./nco.texi:2649: Node `ncap netCDF Arithmetic Processor' lacks menu item for `Intrinsic functions' despite being its Up target.
./nco.texi:2693: warning: unreferenced node `Left hand casting'.
./nco.texi:2746: warning: unreferenced node `Syntax of @command{ncap} statements'.
./nco.texi:2794: warning: unreferenced node `Intrinsic functions'.
makeinfo: Removing output file `/home/rorik/nco/doc/nco.info' due to errors; use --force to preserve.
make[2]: *** [nco.info] Error 1
make[2]: Leaving directory `/home/rorik/nco/doc'
make[1]: *** [all-recursive] Error 1
make[1]: Leaving directory `/home/rorik/nco'
make: *** [all] Error 2
OK, I fixed one syntax error in nco.texi but I could not
fix any of the node referencing errors that are causing
makeinfo to fail. I tried removing the offending nodes
one-by-one and could not figure out where the problem
is. Please use makeinfo --force for now and maybe
someone else will be able to isolate the problem in
nco.texi.
Thanks,
Charlie
Charlie,
'makeinfo' works now with nco.texi. However, now I'm getting TeX errors when processing nco.texi. Do you have similar problems?
rorik
rorik@chabuku:~/nco/doc$ tex nco.texi
This is TeX, Version 3.14159 (Web2C 7.3.7)
(./nco.texi (/usr/share/texmf/tex/texinfo/texinfo.tex
Loading texinfo [version 2002-03-26.08]: Basics, pdf, fonts, page headings,
tables, conditionals, indexing, sectioning, toc, environments, defuns, macros,
cross references, (/usr/share/texmf/tex/plain/dvips/epsf.tex) localization,
and turning on texinfo input format.) [1] [2] (Foreword) (Summary) [1] [2]
Chapter 1 [3] [4]
Overfull \hbox (87.99039pt too wide) in paragraph at lines 265--277
@textrm from @texttt http://sourceforge.net/projects/nco\[] @textrm and @texttt
ftp://dust.ps.uci.edu/pub/zender/nco/nco.tar.gz[]@textrm .
Underfull \hbox (badness 5893) in paragraph at lines 308--319
@textrm out down-load-ing the en-tire source dis-tri-bu-tion), visit the @texts
c nco @textrm home-page at
[5] Cross reference values unknown; you must run TeX again. [6] [7] [8]
Chapter 2 [9] [10] [11] [12] [13] [14] [15] Chapter 3 [16] [17] [18] [19]
[20] [21] [22] [23] [24] [25] [26] [27] [28] [29]
WARNING: for users of Unix TeX 3.0!
This manual trips a bug in TeX version 3.0 (tex hangs).
If you are running another version of TeX, relax.
If you are running Unix TeX 3.0, kill this TeX process.
Then upgrade your TeX installation if you can.
(See ftp://ftp.gnu.org/pub/gnu/TeX.README.)
If you are stuck with version 3.0, run the
script ``tex3patch'' from the Texinfo distribution
to use a workaround.
Overfull \hbox (33.4pt too wide) in paragraph at lines 2335--2361
[] [][][][][][][]
Overfull \hbox (33.4pt too wide) in paragraph at lines 2363--2399
[] [][][][][][]
Overfull \hbox (33.4pt too wide) in paragraph at lines 2401--2451
[] [][][][][][][][]
! This `@end table' doesn't have a matching `@table'.
@unmatchedenderror ...esn't have a matching `@#1'}
@next ...ing '}@else @unmatchedenderror @endthing
@fi @else @csname E@endthi...
l.2803 @end table
?
Overfull \hbox (33.4pt too wide) in paragraph at lines 2476--2804
[] [][][][][][]
! You can't use `@end' in internal vertical mode.
<recently read> @ptexend
l.4877 @bye
?
)
*! Interruption.
<*>
? q
OK, entering @batchmode
rorik@chabuku:~/nco/doc$
Hi Rorik,
Here are the commands we want autotools to run:
1. makeinfo nco.texi
2. texi2html -monolithic -verbose nco.texi
3. texi2dvi nco.texi
4. texi2dvi --pdf nco.texi
5. dvips -o nco.ps nco.dvi
On my Redhat systems, only 1 & 2 work, and 3,4,5 fail.
At nco.sourceforge.net, 1,2,3,4 all appear to work and there is no dvips (5).
So, the texinfo support seems to be sensitive to the OS and the
versions of all the commands that are installed (bummer!).
I'm not sure when/if "tex nco.texi" needs to be run, but if
autotools tries and fails it's probably because the texinfo
installation is screwed up or out of date, like Redhat's.
I just made one changed to nco.texi that might help things.
So try it again and cross your fingers. Also, I cannot figure
out why the web page is serving up old versions of the documentation
but that's a fight for another day.
Charlie
Charlie,
It appears that TeX (mine verison at least) does not like the footnote at about line 2236. It is something with the way it is processing the set/clear flags. I made a change removing the flags, so now TeX, and thus texi2dvi, work. It might need further work however.
rorik
Bueno, let's just try to make sure that whatever needs to be
done looks OK (or does not lose information content) in the
manual.
The way I understand it, texi2dvi is just a wrapper around TeX. texi2html is an independent, huge perl script. The problem is most likely not TeX (I think Knuth is paying $1024 or more right now for finding errors), but I'm not sure how setting and clearing flags works in TeX, it is too cryptic and I simply use LaTeX. The way flags were set and cleared seems OK according to the Texinfo documentation; but maybe that's not entirely correct or complete.
rorik
Charlie,
Do you think the .dvi .ps .pdf and .html documentation should be generated _automatically_ when 'make' is issued form the top level dir? The other option is to only generate each type of documentation when going to doc/ and executing 'make nco.ps' or 'make nco.pdf' or 'make nco.html', etc. The second option saves having to wait through all the documentation generation everytime you do a 'make clean;make'
rorik
I understand that the doc build can be slow the first
time because of all the font generation etc.
But my feeling is that docs should build automatically
with the top level make. If the dependencies are set
up correctly then nco.ps : nco.texi. So after the first
build you have nco.ps and it should not be rebuilt
unless nco.texi has changed. make clean should
get rid of intermediate targets, but not nco.ps, nco.pdf,
nco.dvi, nco.info*, or nco.html. This is in the ideal
world. It may be true that some architectures have
all the compilers required to build the executables,
but have none of the tools required to build the docs.
Would it be possible to have autotools check for
existence of, e.g., dvips before attempting to run it?
That way builds will not break on those architectures.
So my feeling is that if we can get the dependencies
sorted out correctly, then make clean;make should
only be slow the first time. make distclean; make
should always be slow and remake all targets.
Does this sound feasible? BAsically most users
want the docs but are too inept to figure out they
have to type, e.g., make nco.ps in order to get them,
so we want to work with that in mind.
Oh yeah, note that this only pertains to the CVS snapshot. The distribution generated with 'make dist' (i.e. nco-2.6.2.tar.gz) will still contain nco.html nco.pdf nco.ps nco.dvi and nco.info.
rorik
I guess if we could figure out how to link to the
update manual from the NCO homepage then
it's fine if the top-level make does not build the
docs. However, I cannot figure out why the website
links to old version of the manuals. It's like I'm getting
cached copies. Do you get the latest docs when
you visit the website?
Yeah, I got version 2.6.2 in the dvi form, but the ps is old (april 2001) and the pdf is corrupted. The html looks newer, as it has ncap stuff, but I didn't see a version.
rorik
OK, I just had to clear the cache on my stupid browser.
I'm afraid the ps is old and the pdf is corrupted because
the sourceforge machines are the only ones I can build
the documentation on and they lack dvips. It's hard for me to work on the docs because I can't actually work
interactively on them on my own machine...
I can easily make the creation of various types of documentation depenant on having the correct tools (ie texi2dvi, dvips, etc). However, the removal of .dvi and .ps files from the doc/ directory is hardcoded into Automake-1.6 I'm not sure why, because .info files are only removed on 'make maintainer-clean'. I think I'll post the query to their list.
In the meantime, I'm going to hold off commiting the changes to automatically make documentation if you have the tools. You can still do it manually in the doc/ directory, and I put that in the README in doc/
rorik
OK, sounds good. We don't want the executable
build to fail just because the docs won't build.