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

_______________________________________________
Pd-dev mailing list
Pd-dev@lists.iem.at
https://lists.puredata.info/listinfo/pd-dev

Reply via email to