Papyrus–a PDF Generator for RDoc (based on LaTeX)

This library is a plugin for Ruby’s documentation generator RDoc. It provides both a generator for outputting PDF (Portable document format) (the RDoc::Generator::Papyrus class) files and a formatter for turning the parsed RDoc markup into LaTeX code (RDoc::Markup::ToLaTeX; RDoc::Markup::ToLaTeX_Crossref adds cross-reference facilities).

Requirements

  • This is written in Ruby, so you’ll obviously need Ruby. Version 1.9.2 or greater required.

  • RDoc, the Ruby documentation tool, version 3.9 or greater.

  • The generator uses LaTeX to generate the PDF files (pdfLaTeX, to be exact), so you’ll need this as well. LaTeX2e required.

Installation

Papyrus is available via RubyGems. Install it via:

# gem install papyrus

If you prefer to be on the bleeding edge, clone the sourcecode repository and build the gem yourself:

$ git clone http://git.pegasus-alpha.eu/papyrus.git
$ rake gem
# gem install --local --pre pkg/papyrus-x.y.z

Usage

To use it from the commandline, pass RDoc the -f commandline switch specifying “papyrus”:

$ rdoc -f papyrus

You may also set this permantently in your RDOCOPT environment variable (although I don’t recommand this–all the gems you install will get PDF documentation then).

The other way is to use the library from within a Ruby program. Require it via:

gem "rdoc" #Won’t work with any RDoc < 3.9
require "rdoc/generator/papyrus"

and then do

opts = RDoc::Options.new
# Specify your options...
opts.generator = RDoc::Generator::Papyrus
RDoc::RDoc.new.document(opts)

In both cases you’ll find a file Documentation.pdf in your documentation output directory (usually doc/).

Extra commandline options

The PDF generator adds some commandline options to RDoc, namely:

--show-pages

Allows you to suppress the page numbers automatically added to each cross reference. If you know you won’t print your documentation and your PDF viewer supports cross-references, you may turn them off via --no-show-pages. Defaults to true.

--latex-command

If your pdfLaTeX’s executable for whatever reason isn’t named pdflatex (the default), you can set the name here.

--babel-lang

If you write your documentation in a language other than English, this option may be interesting for you. It specified the option(s) passed to the babel package loaded in the main generated LaTeX file and as such allows things like changing hyphenation patterns. Note however, that hard-coded strings like “Public class methods” aren’t changed by this yet (may come with a later release).

Web pages

Known Problems

  • No cross-referencing inside headings and the labels of labeled lists. This is a technical restriction as the complex references this template creates confuse LaTeX when used in that places.

Author

This software was written by Marvin Gülker for the German company of Pegasus Alpha, which disclaims all interest on Papyrus. You can contact me at m-guelker ÄT pegasus-alpha DÖT eu.

Thanks

Many thanks for the valuable help of Eric Hodel of RDoc fame. He gave me all the pieces of advice I needed when I was stuck at some obscure point of generation or formatting and even changed RDoc’s API to allow implementing non-HTML cross-references. Without him, this plugin wouldn’t have made it into a releasable state.

License

Papyrus is a RDoc plugin for generating PDF files.

Copyright © 2011 Pegasus Alpha

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

A note on the license

As soon as Ruby 1.9.3 final is out, this will be licensed under GPLv3. Just in case you wonder why it isn’t that yet, Ruby’s license is at the moment not compatible with the GPLv3, but with the upcomming 1.9.3 release, Ruby switches to a BSD-style license which allows this.