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

Joe Armstrong erlang@REDACTED
Mon Sep 26 12:29:18 CEST 2016


On Mon, Sep 26, 2016 at 11:55 AM, Loïc Hoguin <essen@REDACTED> wrote:
> 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.

I disagree - Binary formats are for machine. ASCII formats are for people
XML is no better or worse than JSON or LISP for precisely entering a parse tree.

Editing a well-designed XML data structure in the nxml mode in
emacs is really easy.

As an *input* to a text processing system XML is great - the alternatives
are LaTeX/TeX which has no defined parse tree - and markdown type things
which have no defined syntax or semantics and involve a lot of guesswork.

You could of course use rich text and a WYSIWY(might)G editor - but then
automating things is terrible.

My Erlang books start off as XML and editing them is not a problem -
formulating the text *is* the problem.

/Joe

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



More information about the erlang-questions mailing list