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

[Richard A. O'Keefe]

On 27/09/16 9:39 PM, Loïc Hoguin wrote:
> On 09/27/2016 09:44 AM, Kenneth Lundin wrote:
>> Man pages or not?
>> -------------------------
>>
>> I understand that some of you are using the man pages. But the question
>> is why are you using them?
>> Is it because it is easy to type "man lists" or "erl -man lists"? What
>> if "erl -man lists" pops up in a web-browser window of you choice
>> instead?,

I want to agree with everything Loïc Hoguin wrote in response.

I've been through this.  I have R installed on a desktop Mac and a
laptop Mac.  On both of them, you can do either
   % R
to run R in an existing terminal window, or
   % open -a R
to open a native GUI.  If you type
   > ?pmax
then the terminal version lets you page through plain text,
very like man(1), but the GUI version pops up a window which I presume
to be run by WebKit inside the GUI, links work &c.  Add to this the
fact that the GUI version opens native graphics windows while the
terminal version has to fire up X11 (not normally running) in order
to give you an X11 window for graphics.  So it's a clear win for the
GUI app, right?

Well, no.

For example, it quite often happens that I ssh from the laptop (which
might be at home) to the desktop in order to try something out on
data held on the desktop.  If the terminal version popped up a window
to display help, it would pop up on the desktop screen, which I would
be too many kilometres away from to see.

Did I mention that the R gui pays no attention to the font size I have
selected for my interaction window, and always pops up its help
window in the same markedly smaller font?  Seriously proctalgic.

So when seated at my desktop machine, I quite often run the
command-line version of R in order to *AVOID* the browser-style help.

Now there are times when I *want* to go a-wandering, hey clickety
clickety nonny no, and then % open `htman foobar` is fine.  It's
nice to have AS WELL.  It is nearly unforgivable to have INSTEAD.

A really nice thing about having the Erlang manual pages is that
I can read them without having to involve Erlang or a web browser
at all.  The R documentation is superb, but I really hate the
fact that there's no documented way to get to it except through R.

The only thing better than being able to do
   % man lists
would be being able to do
   % man lists:sort