cxw42 / pfft

PDF From Formatted Text: very lightweight markdown-to-PDF converter

PDF From Formatted Text: markdown to PDF with fewer dependencies

I think TeX, LaTeX, and Pandoc are fantastic tools! However, I sometimes need a markdown-to-PDF converter with fewer dependencies. Pfft is that tool.

Pfft:

• Doesn't need a Web browser --- it doesn't use HTML
• Doesn't need a build system --- it comes with an autoconf-generated build script
• Doesn't need a separate rendering library --- it uses pangocairo, which is standard on GNOME systems.

Installing from a source tarball

(Package names may differ --- these are for Ubuntu)

$ sudo apt install -y libpango1.0-dev libgee-0.8-dev libgstreamer1.0-dev
$ tar xvf pfft-VERSION.tar.gz
$ cd pfft-VERSION
$ ./configure && make -j4 && sudo make install

For the HTML documentation, run make html, then open doc/valadoc/pfft/index.htm.

Contributing to Pfft's development

See CONTRIBUTING.md.

The version history is in CHANGELOG.md.

Thanks

• https://github.com/stefantalpalaru/vala-skeleton-autotools
• https://github.com/D3Engineering/d3-jetson-bsp

Legal

Most of pfft is BSD-3-clause (see file LICENSE). The files in src/logging are LGPL 2.1+ (see file LGPL-2.1).

pfft's Issues

Add auto table of contents and numbering

This will require multi-pass processing, which is also required for #14.

md4c-reader: markdown in special blocks

Add an rst (ReStructured Text) reader

https://github.com/hhatto/peg-rst looks like it might be usable as a parser.

Debian packaging

• Support it
• Have Travis run debs for Bionic, Eoan Travis can make the .deb, but I don't have a deployment provider set up to receive it!

Move code-block processing commands into core

Currently, the pango-markup writer recognizes ```pfft:foo ...-style code blocks as processing commands.

• Move that function into core (edit recognizing those blocks is still a reader function)
• Add objects to represent processing instructions in a source-agnostic way
• Update md4c-reader to recognize special blocks and use the new objects
• Update pango-markup to use the new objects edit Specific types of special block, and how they are rendered, should be in separate issues.

Switch to TAP driver

https://developer.gnome.org/glib/stable/glib-Testing.html

template: permit specifying font, size, justification

• Font face
• Size
• Justification (none/block)
• Alignment (left/center/right)

Add a pod6 reader

images: scale horizontally to keep on page

Note that the window is clipped at the right edge of the page --- it should not be.

Scale images so the width fits within the available area.

`make distcheck` failure on Travis

https://travis-ci.org/github/cxw42/pfft/builds/742124142

Code blocks: initial space, and needs background

• There seems to be a leading space in each code block --- remove it
• Add a light gray background behind code blocks for easier reading

Skip vertical space between paragraphs

Like \parskip in TeX.

• No space before the first paragraph
• No space after the last paragraph
• Space between paragraphs

pango-markup: no whitespace between consecutive headers

E.g.,

# Foo

Bar

leaves whitespace between the two paragraphs, but

# Foo

## Bar

does not.

Add missing dependency to README

depends on ubuntu libgee-0.8-dev

md4c-reader: Support (drop silently) HTML comments

Even if no other HTML is enabled, at least enabling comments permits annotating documents.

pango-markup: syntax highlighting of code blocks

Possible options:

• http://www.andre-simon.de/doku/highlight/en/highlight.php might be an option (GPL 3+).
• https://gitlab.gnome.org/GNOME/gtksourceview/-/blob/master/gtksourceview/gtksourceprintcompositor.h (LGPL 2.1+)

Add a template/page-description language

Blocked by #7.

Add a language for expressing templates, much as Pandoc has. Human-readable and -writeable. Should permit specifying:

• Headers/footers: L, C, R text with placeholders; rules; margins
• Page size, margins
• Default paragraph alignment (L, C, R, J)
• Default font and size
• Parskip

[ ] Find out if there is an existing one we can use. I looked at the list on https://en.wikipedia.org/wiki/Page_description_language and didn't see one that looked like it would fit. Edit Maybe Lua? Edit 2 For now, nothing anywhere near Turing-completeness :) .

• If necessary, design one. Serialize in YAML or TOML? Edit For now, using INI-like GLib keyfiles (vala, C)
• Implement the reader in core
• In the pango-markup writer, respond to the template commands.

pango-markup: Add option to include the number of pages in headers/footers ("page X of Y")

See src/writer/pango-markup.vala.

Currently, headers and footers can include %p, which will be replaced with the number of the current page. Add logic to replace %n with the number of pages.

I think the only way to do this is to render twice: once without actually laying down ink, to get the page count, and then a second time to make the PDF with the page count filled in.

Support units in template dimensions

I tried https://github.com/LLNL/units (see branch units). It looked good and compiled fine, but the resulting executable was 7.2MB. Since pfft is meant to be lightweight, I am going to leave units behind for now.

I already looked online, and LLNL's units was the best contender I found for a unit-parsing library with a permissive license. I think I am going to roll my own with regexes. https://www.cs.utexas.edu/users/novak/units95.html looks like it might have some good ideas.

Decide how to write unit tests for writer/pango-markup

It currently has many private functions. I would like to test them since many are not trivial. I can think of several options; any suggestions? Other alternatives I haven't thought of?

• MethodObject: refactor the complex functions into smaller classes
• Write the test code in src/writer alongside the code being tested
• Give more symbols package visibility and move the t/ files into the package where necessary
• Make all those functions public (not preferred)

Expand manpage

Edit src/pfft.pod, which is in perlpod format. Add any of the following (can be in separate PRs):

• --template
  • An overview of the template format and keys
• An overview or reference to Pango markup

Edit For bonus points, make it possible to autogen one of the manpage or the GLib argparser from the other. I would strongly prefer not to use vanilla help2man(1) since doing so prevents cross-compiling. (However, HOSTCC + some creative preprocessor defines in src/app might permit using help2man.)

Add libsnapd-glib-dev as a dev dependency

Support title pages

Various options:

• Wren
• Perhaps using template-glib, which already has Vala bindings.
• Does rst, adoc, pod6, or another format provide enough flexibility to represent title pages? If so, maybe write the corresponding reader first and use that reader to generate the title-page elements.
• YAML frontmatter in Markdown? https://github.com/rainwoodman/libyaml-glib/ , https://github.com/jimmuhk/glib-yaml/
• Data in special block
• Additional properties to hold title, subtitle, author

I would like to avoid having multiple sets of properties: (size, alignment, justification) x (title, subtitle, header, footer, heading, copy) is way too much for a flat list of properties.

Figures: Centered images with captions

Permit specifying types of values

Use gststructure instead of gstvalue.

Edit blocked on https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/303

Hyperlinks

Blocked on https://gitlab.gnome.org/GNOME/pango/-/issues/303

• md4c-reader
• any necessary core changes
• pango-markup writer