Dear Lazy Web,
I've started using sphinx to produce some documentation at work. The HTML output looks good, and I have the templating system figured out so I can change it to look the way we want. We also want to produce a PDF, and that's where I'm stuck. It looks like I need to go through LaTeX, then convert that to PDF. I'm a complete neophyte when it comes to TeX, though, so I'm not even sure where to start.
When I search for things like "converting TeX to PDF", I find some old posts (c. 2005) about how some tools use bitmapped fonts and "look terrible" or vague instructions like "Convert your TeX file to dvi in the usual way." I don't have a usual way, yet, though so that doesn't help me.
Can someone suggest a useful reference manual or starting point for me for using LaTeX under Linux?
I don't actually care about LaTeX, so if there's some other way to get nice looking PDF output from a Sphinx document tree, that information would be helpful, too.
Thanks in advance!
17 comments:
If sphinx outputs raw tex, pdftex is probably what you want.
That looked promising, but pdftex tells me it doesn't understand the file generated by sphinx:
$ pdftex input.tex
This is pdfTeX, Version 3.14159-1.10b (Web2C 7.4.5)
(./input.tex{/usr/share/texmf/pdftex/config/pdftex.cfg}
! Undefined control sequence.
l.2 \documentclass
[letterpaper,10pt]{manual}
It then goes into some sort of interactive mode.
The tetex site (the package that contains pdftex) says it is no longer supported and to look at TeXLive. Is that package the "state of the art" for LaTeX work?
In this case, the sphinx-dev list would be more helpful than the lazyweb :)
When building with the latex builder, Sphinx generates a Makefile for you in the output directory. Simply typing "make" there should generate a PDF for you.
About pdftex and tetex: in the same spirit as with Linux distributions, you have to distinguish between TeX distributions like the now-defunct tetex and the new standard, TeXLive, and the actual programs like tex, latex, pdftex, pdflatex and dozens more.
Hi, Georg,
I didn't notice the Makefile mixed in with all the other stuff in the output directory (mostly the HTML files). Thanks!
When I run make, it spews lots of stuff and then tells me it can't find utf8.def.
I'm on CentOS 4, so I wonder if I just have old tools?
It may be that your TeX distribution is a bit old, yes. If your file contains no non-ASCII characters you should be able to just comment out the "\usepackage[utf8]{inputenc}" line with a "%".
The tip about TeX distros is exactly what I'm looking for. I'm new to these tools, so I don't even know if I have the right thing installed much less how to use it.
What's the best set of tools for someone starting from scratch?
TeXLive is the recommended distribution of Unices nowadays: http://www.tug.org/texlive/
Great, I'll look into installing TeXLive.
Thanks!
You may want to look at http://princexml.com/ which makes PDF from HTML+CSS. I used it a work and it is very easy but great. Stuff like page numbering etc is just done via CSS. It is not free for commercial use though but too costly either. (BTW, I have no relation to PrinceXML...)
just need to add, I used Prince to creat PDF from basic reStructuredText's generated HTML....
You probably need to run pdflatex, not pdftex. \documentclass is a LaTeX command.
You'll find people generally use "LaTeX" and "TeX" interchangeably, when in fact LaTeX is a layer of macros on top of TeX which make it easier to use. Very few people write documents in low-level TeX. (OK, Knuth might..)
Yes, you need to run pdflatex. But sphinx should create a Makefile in your build/latex directory anyway, so you can just chdir to that and run `make pdf`.
For what it's worth, I recently ran into a PDF, which was generated from tex, that I wanted to change (it was evolution's quick reference). At the top of the tex source it said:
$ head -4 help/quickref/C/quickref.tex
% To rebuild the .pdf from this source, use something like the following
% latex quickref.tex
% dvips -t letter -f -Pcmz < quickref.dvi >| quickref.ps
% ps2pdf -sPAPERSIZE=letter quickref.ps
(la)tex is something I know nothing about, nor do I know much about dvips and ps2pdf, so I was rather happy with those instructions. Maybe the manpages will help you to adjust it to your specific needs.
Paul's commands are the "tradional" way to obtain PDF from (La)TeX. Current options are:
Option 1 (traditional). Run latex to produce .dvi. Run dvips on .dvi. Run ps2pdf on .ps.
Option 2. Run latex to produce .dvi. Run dvipdfm on .dvi. (Or dvipdfmx.)
Option 3 (preferred). Run pdflatex to produce .pdf.
Summing up Georg's directions, you typically have to use the following, from within the directory with your sphinx makefile:
make latex
cd .build/latex
make all-pdf
As for the distribution, I'm also with TeX Live, which is what you get on Ubuntu.
After downloading the ISO for TeX Live 2007 and adding the bin directory to the front of my PATH, the Makefile generated by sphinx worked great for creating a PDF.
Thanks to everyone who offered help!
Post a Comment