[PD-dev] PR to revamp HTML manual

Paul Rankin hello at paulwrankin.com
Fri Aug 11 12:50:57 CEST 2017

Given that much of Pd development happens off of GitHub, I'd like to
draw some attention to a perhaps scandalous and contentious PR I've
submitted.... https://github.com/pure-data/pure-data/pull/171

This PR replaces the existing HTML manual with a single HTML file,
generated with [Pandoc](http://pandoc.org) from a new `pdmanual.md` file
(which was generated from the existing HTML manual).

A render the HTML manual can be found here:

A PDF output is also linked.

The proposed future workflow for updating the HTML manual would
therefore be to make changes to `pdmanual.md` and regenerated
with Pandoc.

The command to convert `pdmanual.md -> index.htm` is:

    $ pandoc pdmanual.md -s -N -S --toc -c pdmanual.css -o index.htm

### Advantages

- a single file
- sections can be linked by name, e.g. `(see [Audio and MIDI])` links to
  3.1 Audio and MIDI
- sections are automatically numbered
- table of contents is automatically generated
- smart typography
- easier to keep up to date
- easier to convert to other formats
- can be rendered nicely on GitHub

### Changes

- a single file
- I fixed all sections headings to use title case
- given that sections can now be anchored by name and are automatically
  numbered, I replaced some links e.g. (see section 1.2) -> (see Other
  Resources); this has the advantage of never again needing to
  know/update the section number when updating the manual
- fixed a bunch of obvious errors/typos
- fixed Windows paths, which I'm pretty sure are `C:\Program Files` not
  `C:Program Files`


More information about the Pd-dev mailing list