Switch document building to PDF

[timj]

Currently the document creation system generates Postscript documents by using latex and dvips. It would be much more convenient if we generated PDF documents directly with pdflatex.

I think this needs:

• Removal of .ps target and addition of .pdf target for LaTeX files.
• Conversion of embedded images from EPS to PDF
• Conversion of documents that use embedded graphics to use the includegraphics command provided by graphicx in LaTeX2e.
• The web server commands that download a hardcopy probably need to know they are looking for .pdf files in /star/docs.

This seems like a fairly well-constrained task and shouldn't take very long. Many of the documents don't need any changes at all to work.

[timj]

A quick investigation indicates this may be easier than expected as pdflatex can automatically convert EPS files to PDF for embedded images so there is a migration path. I had assumed that changing starconf.m4.in so that it includes _T.pdf in the STAR_LATEX_DOCUMENTATION definition instead of _T.ps would trigger PDF generation but after a clean build I ended up with many postscript files installed and only sc16, sun237, sc19, mud165, sun259, sc8, sun17, sc10, sc11, ssn72, sun216 PDF files ended up being built. For reference they seem to come from datacube, smurf, specx, and surf, which all have documentation in subdirectories and more to the point have a trailing slash in the STAR_LATEX_DOCUMENTATION line:

smurf/configure.ac:STAR_LATEX_DOCUMENTATION(sun258/ sun259/ sc19/)

versus

polpack/configure.ac:STAR_LATEX_DOCUMENTATION(sun223)

Maybe there are two different paths and I've only patched the first one in starconf.m4.in. Maybe @nxg can shed some light on this.

[nxg]

The difference that the trailing slash makes is that it assigns the list of targets (including _T.pdf) to the Makefile variable STAR_LATEX_DOCUMENTATION_SUN258 (etc), rather than to STAR_LATEX_DOCUMENTATION (see for example smurf/docs/sun259/Makefile.am

In the version of starconf.m4.in at a1993b0, I can see that STAR_XML_DOCUMENTATION mentions _T.pdf, but STAR_LATEX_DOCUMENTATION doesn't. Is that the bit you changed, @timj? With those two changes (at 1069 and 1072), I can't see any obvious reason why the change wouldn't work as planned, unless there's some extra cleverness in the corresponding Makefile.am files (as there isn't in the smurf one quoted above).

I remember someone mentioning in passing that the current build doesn't build the SGML docs. That's probably wise, since they depend on DSSSL/Jade, which has very unfortunately sunk without trace, to be replaced by its stunted evil twin, XSL. Given that, it might be wise to discard STAR_XML_DOCUMENTATION, which may now be too clever for its own good. It's a little alarming when one sees, as part of a parenthetical version test, something like

# The following converts space-separated integers to a single
# one.  It's perhaps a leeettle funkier than necessary...
VERSINT=[`echo "[Ss[z0<a]x]sa $JADEVERS 0 0 0 lax Ls100* Ls+100* Ls+p" | dc`]

I've just noticed that the significance of the trailing slash is explained in the STAR_XML_DOCUMENTATION definition, but not at the top of STAR_LATEX_DOCUMENTATION (and of course in SSN/78) -- that might be worth a little cut-and-paste.

[timj]

I had a local patch and a completely clean checkout other than that:

--- a/buildsupport/starconf/starconf.m4.in
+++ b/buildsupport/starconf/starconf.m4.in
@@ -1069,7 +1069,7 @@ AC_DEFUN([STAR_LATEX_DOCUMENTATION],
                       [STAR@&t@_LATEX_DOCUMENTATION="$STAR@&t@_LATEX_DOCUMENTATION DocCode.tex DocCode.ps DocCode.htx_tar"
 ],
                       [m4_define([_T], m4_bpatsubst(DocCode,[/]))dnl
-                       STAR_LATEX_DOCUMENTATION_[]_STAR_UPCASE(_T)="_T.tex _T.ps _T.htx_tar"
+                       STAR_LATEX_DOCUMENTATION_[]_STAR_UPCASE(_T)="_T.tex _T.pdf _T.htx_tar"
                        AC_SUBST(STAR_LATEX_DOCUMENTATION_[]_STAR_UPCASE(_T))])])
         fi
         STAR_DECLARE_DEPENDENCIES([sourceset], [star2html])

and of course some PDF files were built but only the ones that were in subdirectories. No additional cleverness in the Makefile.am files for those. I see that the line above only refers to the @STAR_LATEX_DOCUMENTATION_<sun>@ form so where do I change the definition of STAR_LATEX_DOCUMENTATION to stop it picking up the .ps file?

[timj]

@nxg it's the DocCode.ps entry on line 1069 that I have to change to DocCode.pdf isn't it? So I need to change two lines. I'll give that a try.

[MalcolmCurrie]

@nxg wrote:

I remember someone mentioning in passing that the current build
doesn't build the SGML docs. That's probably wise, since they depend
on DSSSL/Jade, which has very unfortunately sunk without trace, to be
replaced by its stunted evil twin, XSL. Given that, it might be wise
to discard STAR_XML_DOCUMENTATION, which may now be too clever for
its own good. It's a little alarming when one sees, as part of a
parenthetical version test, something like

No great loss as the XML documents haven't been maintained. OTOH there's
is still important material in SSN/78 for those wishing to continue the
Starlink legacy, such as the Starconf macros.

Malcolm

Scanned by iCritical.

[timj]

I have moved XML documents discussion to #7. It's off-topic for this one.

[timj]

Documents all seem to build now with pdflatex. We still have EPS files in the repository for the moment because pdflatex automatically converts EPS to PDF using epstopdf. Once I've switched to native PDF building in the make world (easy) and that settles down I can do a final conversion of all the EPS to PDF and remove the EPS entries completely.

All the latex documents now use graphicx and they all no longer specify a file extension for the embedded image.

@dsberry AST seems to be deliberately forcing postscript output in the makefile. I assume there is a reason it is not picking up the default rules but can it be switched to PDF? (once installed the AST web pages will need to link to the right place but that's a good thing because PDF is better in a web browser than postscript anyhow).

[timj]

Star2HTML also seems to hard-wire in Postscript file building. @nxg is that some sort of hack to ensure that the MUD document is installed? Can't the MUD be installed using an explicit stardocsdir_DATA target or something? Or maybe STAR_LATEX_DOCUMENTATION could set some variable that could be used as the suffix?

[timj]

@nxg Probably should be a separate ticket but SUN/152 has a funky specialist Makefile that hard-wires in the use of latex instead of pdflatex and also does not install the postscript file. Furthermore, uniquely to SUN/152 the tex files are installed as a tar file with a latex_tar suffix rather than simply installing the .tex and the EPS files.

[nxg]

Re star2html: yes, star2html hard-wires in a lot of things. star2html is quite clever. Notice the prominent lack of me going anywhere near the thing in the star2html header's history list.

[nxg]

Re SUN/152: the sun152.ind target isn't particularly funky (how did I know that when you said 'funky specialist Makefile' you were referring to something I'd written?). All that target does is to update the index which is inline within sun152.tex, by creating sun152.ind and editing it in to sun152.tex (the motivation is to avoid having to use makeindex when building the docs; this is unusual only because it's unusual for a SUN to include an index -- evidence of Dave's, John's or Martin's diligence with this SUN). That is, sun152.ind is effectively a Makefile fake target.

I don't think there's any deep reason why this Makefile builds sun152.latex_tar but doesn't install. I vaguely recall that this was the standard pattern at one point. It might be that this custom Makefile was matching the at-the-time normal behaviour, which meant it didn't keep up-to-date when that normal changed.

[timj]

@nxg It does install the latex_tar file but that tar file is definitely anomalous compared to the rest of the system. The contents of the file is also a bit odd and I think there is a bug in the makefile because it also picks up the TeX files in the HTX sub-directory. The HTX tar file is already installed so it shouldn't be including that directory in the other tar file. I'll file an issue on that separately.

[timj]

Created tickets #8 and #9 for ECHOMOP build.

[timj]

I've enabled PDF building in starconf so we'll see whether Jenkins breaks. @grahambell there might be issues if pdflatex can't always convert EPS files in the background.

[timj]

I'm making good progress with the migration to PDF but the biggest problem now is latex2html since it ignores .png and .pdf images. Needs to be hacked to copy .png files and convert PDF to PNG. The latter can be done natively in ghostscript using the pngalpha device so it's not much of a problem. Might even be able to hack pstoimg to handle it.

[timj]

Latex2html uses latex and dvips to generate postscript images from supplied EPS images in order to handle the options for includegraphics properly. It seems I have two choices

1. Call pdf2ps from star2html to convert each PDF image back to postscript so that the normal latex2html infrastructure can convert as normal.
2. Attempt to switch to pdflatex without using dvips and then modify pstoimg to handle PDF files (ghostscript can already deal with it I think).

Option 1 might be the sanest although it feels wrong. The problem with option 2 is that you can't just do it for the externally provided images and it seems like a lot of work. latex2html is a maze of twisty passages all alike. The least I touch it the better I feel.

I think I'll probably go with option 1 as it means only changing star2html. I will just copy any PDF using the syntax docname_*.pdf