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

[Joe Armstrong]

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.

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.

I Googled

   "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
acceptable manner.

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.

Cheers

/Joe


> --
> Loïc Hoguin
> http://ninenines.eu
> Author of The Erlanger Playbook,
> A book about software development using Erlang
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions