Submit Hint Search The Forums LinksStatsPollsHeadlinesRSS
14,000 hints and counting!

Use groff to easily create PDF pages UNIX
I need to automate PDF document generation and have looked at a number of options for doing this from a PHP enabled web site. The basic problem is that for machine-generated documents, it's easiest to work with text files, but for documents that end up in PDF format with headers, footers, and graphics, a word processor is easiest. Right now I use AppleScript to control Appleworks, but this means I have an Appleworks template, an AppleScript, I then edit a bit, and print to PDF. I have other processes that could benefit from automatic PDF generation, but generating the commands to drive the PDF creation is a bit complex. I want to be able to just generate a text file and have it become a nice PDF.

I ended up looking at TeX and LaTeX, but downloads were huge, a build I needed to do didn't work, and I couldn't get the complex software to work.

Then I stumbled on the standard groff. I had thought it was just for generating decent looking monospaced ASCII for a terminal. How wrong I was. This is a fully featured typesetting program on par with TeX. It takes plain ASCII text and generates beautiful, typeset output. There are resources called macro packages that allow complex editing tasks to be done.

Here are some examples of how it may be used -- these are for use in the Terminal:

Want to print up a hard copy of a man page? groff -l -mandoc `man -w apachectl` will give you the apachectl man page.

Want a postscript file of the groff man page that is then opened in Preview?
$ groff -mandoc > `man -w groff`
$ open
How about a system that will typset a manuscript? There is a document processing system called mom. It is a set of commands to groff that resides in what is called a macro file. Create a text file called x.txt and fill it with the following:
.TITLE    "MacOSXHints"
.SUBTITLE "A Fine Source of Hints"
.AUTHOR   "Your Name"
.blm PP

Here is a fine first paragraph.  

Here is the second.

Here is the third.
Then typeset it and open in Preview:
$ groff -mom > x.txt
$ open
Well, not earth shaking, but any text you want to look at is now typeset as a Postscript document. Just put the paragraphs as separate chunks of text separated by blank lines.

The benefit of this is that if you want to generate PDF's programmatically, all you have to do is write a text file, easy from most any program, to a file x.txt and then invoke:
groff -mom x.txt | pstopdf -i -o x.pdf
This uses the pstopdf utility to create file x.pdf from x.txt. You want PDF's of man pages? An exercise for the reader. And groff has great documentation, already on your computer. Look in /usr/share/doc/groff/ and open the folder there (1.19.1 or 1.19.1 or something like that). Go into each folder and find the intro.html file. As an example:


Contains an introduction to mom.

Also, the groff man page is good, as are the roff and troff manpages. Yeah, it is a bit of reading, but it is much easier to use than TeX and LaTeX, and it is already on your system, ready to go.

What I will be doing is using groff to generate automatic reports from PHP. Just have to emit some text to a file and execute the shell command for PDF creation...

[robg adds: I haven't tested this one, and we've mentioned groff on a few occasions before.]
  • Currently 2.57 / 5
  • 1
  • 2
  • 3
  • 4
  • 5
  (7 votes cast)

Use groff to easily create PDF pages | 13 comments | Create New Account
Click here to return to the 'Use groff to easily create PDF pages' hint
The following comments are owned by whoever posted them. This site is not responsible for what they say.
Use groff to easily create PDF pages
Authored by: zeb on Oct 24, '05 06:51:01AM

Wow! This is an awesome utility!

Thanks for the great tip!

..:: Zeb ::..

[ Reply to This | # ]
I love this hint
Authored by: gshenaut on Oct 24, '05 09:03:27AM
As someone who has been using *roff since about 1976 (first roff, under V6 UNIX, then nroff/troff, then ditroff, then MKS/SoftQuad sqroff, then groff under BSDI and FreeBSD and now under MacOS/X), it warms my heart to see that the program continues to live on and have value.

One of the most useful features in the *roff family is the set of filters that exist for it. These are aimed at tables (tbl), equations (eqn), figures (pic), graphs (grap), and references (refer). There are also macro packages that may have value to some other than -mom and -man, such as -ms, which is probably the oldest, widely-used package, and -me, which was designed for typesetting dissertations. Finally, for those who are inclined towards programming, it can be very useful to use make(1) to manage all the pieces, filtering, and transformations in a longer groff document.

There are weaknesses with *roff in today's environment, chiefly the fact that it doesn't directly support output formats that are currently portable, such as .rtf and .pdf (you can get to .pdf from .ps as in the hint and also in various other ways, but the current .rtf translators are unacceptable). The problem is that some journals require either .doc or .rtf for manuscripts. However, there are other output formats that are supported, see groff(1).

Greg Shenaut

[ Reply to This | # ]

Use groff to easily create PDF pages
Authored by: Doc Drang on Oct 24, '05 10:26:24AM

While I generally prefer LaTeX for reports and such, troff's ability to put text exactly where you want on the page makes it superior for printing labels. I've written a couple of simple perl programs for making address labels and file folder labels.

I prefer ps2pdf over pstopdf for translating my PS files, but that may be a matter of taste. One thing I'm sure of: don' open a PostScript file in Preview unless you plan to go out for lunch while its translating.

Doc Drang

[ Reply to This | # ]

PS man pages
Authored by: sjk on Oct 24, '05 12:35:27PM

"man -t name ..." is an easy way to create PostScript format man pages.

[ Reply to This | # ]
Use groff to easily create PDF pages
Authored by: gunnmjk on Oct 24, '05 12:40:14PM
I forgot where I got this from, but a better way too open man pages in is this script


if [ $# -eq 0 ] 
# "$#" is number of parameters- here we test whether it is not equal to 0 
echo "Usage: $0 <UNIX command> ..." # not one parameters 
# so print message 
exit 2 # and fail ($0 is # name of command). 

man -t $1 | pstopdf -i -o /tmp/$1.pdf 
open -a /Applications/ /tmp/$1.pdf 
( sleep 60; rm -f /tmp/$1.pdf) &

Call it pman, make it executable, put it in the $PATH, and just type "pman name_of_unix_app" in the terminal and it will open it up in Preview.

[ Reply to This | # ]
viewing piped postscript
Authored by: WhisperLite on Nov 15, '05 09:11:10PM

Even easier is to just pipe your output open with '| open -a /Applications/ -f'. This'll open your PostScript (or what-have-you) up in Preview without writing it to an intermediate file.

[ Reply to This | # ]
Use gv(1) to look at postscript
Authored by: gshenaut on Oct 24, '05 03:26:33PM
I've been using a script I call "pipegv" to look at postscript output from groff without translating it to pdf:


if [ "$1" = "" ] ; then
        trap "rm -f $T" EXIT INT
        cat > $T
        gv $T
        gv $*
This reads postscript from standard input into a temp file, calls gv on the temp file, and then removes it when gv exits. Gv runs under X-windows, so you have to have that running to use it. There is a program called xditview which is supposed to preview groff output, but I've never been able to get it to work right.

Greg Shenaut

[ Reply to This | # ]

Use groff to easily create PDF pages
Authored by: gork on Oct 24, '05 07:10:48PM

groff is a fun and easy typesetting utility. If you don't like to use postscript you can also bring in documents in many other formats.

However, if you are generating PDF's from scratch using PHP, a better and more portable alternative to using external commands may be to use the excellent FPDF library at It's writtin in pure php and is very capable when generating PDF's. The license terms are also very accomidating (vs libpdf especially).. Even if PHP is not your thing, there are bindings for some other languages too (though they still require that PHP be installed)

[ Reply to This | # ]
Both are of use
Authored by: kd4ttc on Apr 06, '06 07:13:09PM

I appreciate your comment. I had looked at FPDF. It is a very good choice for a document where items are placed in various places on the page. It was a little cumbersome, however, for just flowing out long paragraphs of wrapped text. For simple text to a PDF the simple workflow that could be had with groff was a real plus. Also, the source file generated by PHP in this workflow was saveable as a draft version, so later editing of the text file was an option in the groff based workflow, but wouldn't be with the FPDF workflow.

I agree about FPDF being the best tool for PDF generation out of PHP in general, though.

Steve Holland

[ Reply to This | # ]
man -t ???
Authored by: jms1 on Oct 24, '05 07:54:32PM
I've always used "man -t" to generate postscript versions of man pages. When I've needed them as PDF files, I do something like tihs...
man -t ___ | pstopdf -i -o ___.pdf
It's always worked well for me.

[ Reply to This | # ]
Use TexShop to easily create PDF pages
Authored by: sapporo on Oct 25, '05 12:37:36AM
If you find the LaTeX setup too complicated, you really should check out TexShop, which comes with instructions for installing Gerben Wierda's LaTeX distribution. This is the premier LaTeX environment for the mac, and it doesn't get any easier than that.

[ Reply to This | # ]
Use enscript and Ghostscript
Authored by: pxa270 on Oct 26, '05 05:02:08AM

If you don't need fancy typesetting, you can also use enscript with the -p option (see: man enscript), it's a bit faster than groff and also installed by default on Panther. Also, ghostscript's ps2pdf is faster and produces smaller pdf's than Apples pstopdf.

[ Reply to This | # ]
not respectful of word breaks, but makes .rtf files!
Authored by: kd4ttc on Apr 24, '06 07:54:42PM

Ooooh. Tried that. Cute. Perfect for quick output of source code. The line wrapping does not respect word breaks, though, so words are broken at end of lines. What it does offer, though, is a fast conversion from ascii to rtf.

Steve Holland

[ Reply to This | # ]