[erlang-questions] Erlang documentation -- a modest proposal

[Richard A. O'Keefe]

> On 09/23/2016 05:35 PM, Kenneth Lundin wrote:
>> I am actually thinking that we don't need PDF at all. HTML should be
>> enough.

PDF and HTML serve different purposes.
For that matter, HTML for a large display and HTML for a small tablet
serve different purposes.

>> Man pages can also be questioned since they are limiting when it comes
>> to format.

When I am looking things up in a man page, I couldn't care less
about format.  I have this little script in $HOME/local/bin/pman

#!/bin/sh
man -t "$@" | open -f -a /Applications/Preview.app

This formats a man page with fancy fonts and opens the result in the
usual PDF viewer.

Trying to give an honest estimate here, I use 'man' between 10 and 40
times a day.  Guess how often I use 'pman'?  That's right, almost never.
I use 'man' when I need a quick reminder of some detail and I DON'T
want to go clickety-scroll-clickety-clickety-scroll-fume-clickety
to find stuff and I don't give a pinch of frass for format.

Man pages are for *INFORMATION*.  Not for brightly coloured
advertising leaflets.

When I discovered that I could do 'erl -man $MODULE', I was very happy.

When do I use 'pman'?  Answer: for *long* documents with lots of text
I have to slog through to get to the meat.  That is, for badly written
man pages.  Almost the only thing I like about Perl is the way they
had the wit to break the Perl documentation into many man-pages.