[erlang-questions] Erlang documentation -- a modest proposal
Tue Sep 27 11:59:51 CEST 2016
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.
Author of The Erlanger Playbook,
A book about software development using Erlang
More information about the erlang-questions