No more Erlang manuals

As incredible as it may sound, Erlang/OTP doesn’t ship with their man(1) pages any longer.

As of R27 (or, OTP 27), only the Unix manuals that pertain to main binaries — erl(1), dialyzer(1), etc. — ship with the install, but the module-manuals have been set ablaze over some fjord in Sweden somewhere.

Now, the Erlang community has always been critiqued for poor documentation in the past, so it’s certainly been on the radar for the core team to do something about it.

And ‘do something about it,’ they have.

The Erlang Docs corner has been tightened up, and anyone coming from JS or Haskell can find everything to have a familiar, searchable, browseable, modern spin on docs.

But this is at the detriment to Erlang fuddy-duddies who would typically just use erl -man lists to look things up in the usual Unix manpage way.

(At a glance, it seems that the toolchain to build the new docs from source-code didn’t gel with outputting to Unix manuals. So the powers that be just said ‘F’ it.)

JS envy

The mailing list for Erlang has long been retired in preference for ‘Erlang Forums’ that has a loading spinner, and a day-care color scheme. I am not sure, but I think the mailing list saw more action, to be honest.

And the facelifts continue: now the Erlang docs can only be found on the web. You will spend a good chunk of your time just making sure Google didn’t send you to a deprecated doc page.

Online docs…

Well, this won’t do. I am constantly coding where there is no Internet connection, and I do everything on the terminal… not going to change that just because JS is winning, and core teams can’t help themselves catering to what ‘Tsoding’ defines as the ‘slop-ification’ of programming languages.

Cope

Well, in lieu of my ‘working offline’ constraints, I had to rectify my situation.

But, I can only cope so hard, so some disclaimers:

1. I wasn’t going to write anything that turned source-code documentation into manpages. That would take more time than I have, and there’s a good chance manpages will return at some point when the Erlang team gets around to it;
2. Since offline HTML pages were not going to be searchable, I was not going to replicate how the online docs work/look/feel, only locally;
3. My annoyance with no more local manuals didn’t warrant anything more complicated than a single script, and a couple of notes spinkled in my script’s source-code. Erlang updates should only require a small amount of manual work to get my docs up-to-date.

This is what I came up with.

A familiar face

I wrote a script called erl-man that takes one arg (the OTP module name). I put that in my ‘$home/bin’ directory, made it executable… it’s as follows:

#!/home/foobar/bin/rc

# N.B. OTP_MAN_PATH can be set; requires curl(1), w3m(1), ed(1)

if ( ! ~ $#* 1 ) echo '*** usage: erl-man ' && exit 1

# N.B. set var to first arg w/o possible surrounding whitespace
a = `{ echo $1 | xargs }

if ( ~ $OTP_MAN_PATH () ) {
    OTP_MAN_PATH = $home^/share/otp
}

if ( ! test -d $OTP_MAN_PATH ) exit 1
if ( ! test -d $OTP_MAN_PATH^/doc ) exit 1
if ( ! test -d $OTP_MAN_PATH^/lib ) exit 1
if ( ! test -d $OTP_MAN_PATH^/erts-* ) exit 1

u = `{ ed -s >[2] /dev/null <<EOE
H
r ! curl -s file://$OTP_MAN_PATH/doc/man_index.html
1,/<div id=.top-content.>/-1d
1;/<table/ku
'u+1,$$d
1,'u-1d
,s/<tr/\
&/g
1,2d
,s#</code>.*##
,s/^.*<a href=.//
,s/^\(.*\).><code class=.inline.>\(.*\)$$/\2::\1/
! # N.B. swap file path in
,s#\.\.#file://$OTP_MAN_PATH#
! # N.B. delete everything that isn't $1
v/^$a::/d
! # N.B. print local file-url
$$s/^$a::\(.*\)/\1/p
EOE
}

if ( ~ $u ? ) {
    echo '*** erl-man: no otp-module found called `'^$a^''''
    exit 1
}

# N.B. open up apt doc
w3m $u

But it’s not that magical…

With every new OTP release, you have to point curl(1) to the apt ‘.gz’ file from https://www.erlang.org/download and put that in the place erl-man expects it to be: ‘$home/share/otp’…

This typically goes as follows:

$ cd $home/share
$ mkdir otp
$ cd !$
$ curl -OJL https://erlang.org/download/otp_doc_html_27.3.tar.gz

Note that the tar you want are the HTML ones; so…

otp_doc_html_*.tar.gz

And of course, you want the version that matches your current OTP installation.

This works to glean into that version:

# find /usr/local -name '*OTP_VERSION*' -print

Take a peak in there.

With that download in hand, a tar zxvf otp_doc_html_27.3.tar.gz will get you everything you need for erl-man to work. A quick ls -1 should yield the following:

doc
erts-15.2.3
lib
otp_doc_html_27.3.tar.gz

Usage

The erl-man program is a nod to this pattern: erl -man erl which will still work for those Erlang binaries, as stated already.

In this new case, however, erl-man lists will open up a w3m(1) text browser so you can locally navigate the full ‘lists’ documentation.

The rc(1) script above is just a place-holder, really, for anyone to ‘roll their own.’ In my case, my rc(1) script relies on w3m(1), ed(1), curl(1), and the global ‘OTP_MAN_PATH’ can be set outside the program too. (This last point is a common enough pattern that I feel I don’t need to explain too much what is going on.)