[erlang-questions] Erlang documentation -- a modest proposal
Mon Sep 26 11:25:05 CEST 2016
On Mon, Sep 26, 2016 at 9:38 AM, Loïc Hoguin <> 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.
It's like making web pages look beautiful - the HTML markup is trivial
the CSS is hell.
I wrote some crappy looking HTML with my pathetic attempts at
prettifying them with a handful of CSS.
I got the daft idea of using a CSS framework to "simplify" the process
of beautifying my pages.
"small css frameworks"
(why small? - because I like to take a quick peek at the code I intend to use
and vaguely understand it)
What did Google come up with:
- 12 Small CSS Frameworks To Use In Your Web Designs
- 17 Minimal CSS Frameworks
- 10 Lightweight Alternatives To Bootstrap & Foundation
- 100+ Best CSS Frameworks for Responsive Design
Lot's to choose from here :-)
A few mouse clicks later and I'm staring at the documentation
which *assumes* I know all about sass, grunt, bower, npm, blither,
dither bother and blast.
Now let's suppose (just suppose) that I chose one of these and
tagged up my HTML with the appropriate classes and organised the
HTML so it looked beautiful with my chosen framework.
Now suppose - horror upon horror that I wanted to *change* frameworks
all my carefully tagged up HTML would need re-tagging.
This we call progress ...
Writing beautiful documentation is very difficult and very time consuming.
The text *alone* is difficult - I often rephrase a paragraph many
times before I'm happy with it. Beautiful formatting is beyond me.
I guess this is why markdown is popular - the Input is simple
the output is related to the input in a unpredictable but usually
The output is not beautiful - but probably fit for purpose and good enough.
Sorry for the rant - but Every time I try to make my crap html look
pretty by waving a bit of CSS at it I get in a bad mood.
I am actually a fan of XSL-FO since it has a defined parse tree and
the CSS type attributed do actually make sense. The old-timers
on this list might remember DSSSL with a mixture of pleasure and horror.
CSS seems to be all the bad bits of DSSSL with the good bits omitted.
> Loïc Hoguin
> Author of The Erlanger Playbook,
> A book about software development using Erlang
> erlang-questions mailing list
More information about the erlang-questions