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

[Loïc Hoguin]

On 09/27/2016 11:08 AM, Kenneth Lundin wrote:
>     * lack of search; command line manual search is very useful (man -k
>     and others)
>
> I don't think the search has to be worse in the html form, it depends on
> how we do it.

I'm not sure how you would get the equivalent of the erldoc online 
search in static html files. Unless you mean doing something like "erl 
-mansearch term" which is yet another custom thing to write.

>     * man pages are readable in 80x24 windows; browsers aren't
>
> Have you tried lynx? a text based web-browser I think our html pages
> looks quite good in that one.

I don't find it anywhere close to man pages usability. The lack of 
indentation between function name, types, description etc. makes it very 
difficult to make out what is what, especially considering the bold is 
also gone from the function name. Nearly unreadable.

Not to mention it's not very good for navigating inside the page (by 
default at least).

>     * opening in a separate window is awkward; currently I need to do
>     this to have what I need: Menu key (opens a terminal), "man lists";
>     with what you suggest I need at least a couple more steps
>     * if i want to have the manual side by side with the code, I need a
>     different browser or browser window; I already fight with Dialyzer
>     because it runs out of memory on some modules, I don't need the
>     waste browsers add on top of that
>
>     Also note that in the absence of man pages, I'd look first into
>     'info' or PDF formats before I consider local HTML. HTML is just not
>     practical for manuals.
>
>     I'm also wondering why the intent to remove man/PDF formats. They're
>     already working, it doesn't sound like they would need much
>     maintenance to be kept, they have users, so why consider removing
>     them? It doesn't make much sense to me.
>
>
> html, pdf and man are 3 different backends for generating documentation
> of course it will cost more to maintain and develop 3 backends instead
> of 1 or 2. This is especially true if new features are introduced in the
> document source format or if we even change the format completely.

That's the thing. You shouldn't have to maintain 3 different backends. 
You have all this because long ago you (OTP team) decided to roll your 
own instead of using existing formats and tooling.

Joe said DocBook is too big for your purposes, but the only big thing I 
see is the amount of custom code you have in erl_docgen. :-)

The way most people do documentation today is to have one input format 
(Asciidoc, ReST, DocBook, TexInfo...) and to use the associated tooling 
to generate various output formats.

In Asciidoc that means using a2x, which generates DocBook and from there 
pretty much any format is possible with next to zero effort:

* man, PDF, HTML, chunked HTML are built-in, one command needed
* mobi and epub need one extra command
* info needs an intermediate file to be kept; then it's one more command

If you need more than stylesheets and configuration, then something is 
not right. You shouldn't have to maintain 3 different backends.

If you change the format completely, then I don't see how different 
output formats is going to be a problem, unless you choose to roll your 
own again, or you choose (gasp!) Markdown. But even then Pandoc can help 
in the worst case scenario.

-- 
Loïc Hoguin
http://ninenines.eu
Author of The Erlanger Playbook,
A book about software development using Erlang