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 (XeLaTeX, to be exact), so you’ll need this as well. LaTeX2e required.

  • In addition to LaTeX itself, the following LaTeX packages need to be installed:

    • fontspec

    • xunicode

    • textcomp

    • eurosym

    • lastpage

    • geometry

    • fancyhdr

    • fancyvrb

    • longtable

    • xcolor

    • titlesec

    • titletoc

    • hyperref

    If any of these is missing, you’ll get that obscure

    Invoking xelatex failed with exitstatus 1!

    message. To see which was the cause for this error, you can pass the --debug option to RDoc as in:

    rdoc -f papyrus --debug WHATEVERYOUWANTTODOCUMENT

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
$ git checkout devel
$ 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 XeLaTeX’s executable for whatever reason isn’t named xelatex (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.

When it crashes

Before you report a bug against Papyrus (see above) you should check wheather it’s really Papyrus’ fault or your setup’s. Installing LaTeX can be a tricky task, so make sure everything is where it ought to be. You should also try to run rdoc with the --debug option which will turn on RDoc’s and Papyrus’ debug mode. Using this can cause masses of output, so be prepared. Usually you’ll find something like

! LaTeX error: ...

somewhere in the output–this will tell you what went wrong.

If you’re sure you’ve found some misbehaviour in Papyrus (which is totally legit as we’re all human beings that tend to make mistakes) use the bugtracker pointed to above and include the output of a debug run along with your Ruby and RDoc version. Please also attach a description on what you did and (if useful) what you expected Papyrus to do.

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.

Font license

The fonts included by Papyrus are copyrighted by Philipp H. Poll (linuxlibertine.sf.net) and licensed under the Open Font license. See the OFL.txt file in the data/fonts directory for more information.