[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:
https://htmlpreview.github.io/?
https://github.com/rnkn/pure-data/blob/doc-polish/doc/1.manual/index.htm
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`
--
www.paulwrankin.com
More information about the Pd-dev
mailing list