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

[Loïc Hoguin]

On 09/26/2016 11:25 AM, Joe Armstrong wrote:
> On Mon, Sep 26, 2016 at 9:38 AM, Loïc Hoguin <essen@REDACTED> wrote:
>> On 09/26/2016 02:57 AM, Richard A. O'Keefe wrote:
>>>
>>> It is not clear to me why Erlang document generation would involve
>>> any XSLT.
>>
>>
>> Typically one can just use the DocBook XSL files (or other tooling, like
>> db2latex) and not have to write their own, or only write a few specific
>> things. But the XSL files in OTP are pretty big, and there's also some
>> pretty big Erlang code around it. I'm not sure why. It's possible that the
>> DocBook tooling wasn't that great when this was first written.
>
> I've used DocBook - I consider it to be total overkill for the Erlang
> documentation - it's using a battleship to crack a walnut.
>
> Straightford XML -> XSL-FO with an Erlang program is really easy
> the problem is making it look beautiful.

Nobody should use DocBook directly. It's a great intermediary format, 
not something you should write in.

XML is for machines, not for people.

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