[erlang-questions] Erlang documentation -- a modest proposal
Richard A. O'Keefe
Mon Sep 26 03:09:39 CEST 2016
> 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
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
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
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.
More information about the erlang-questions