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

[Joe Armstrong]

On Mon, Sep 26, 2016 at 2:57 AM, Richard A. O'Keefe <ok@REDACTED> wrote:
> It is not clear to me why Erlang document generation would involve
> any XSLT.  Back when XSLT was still newish and I wanted to be a
> general XMLpert I set out to learn XSLT.  One of the exercises I
> did was to translate the XSLT script that the W3C were then using
> to turn their documentation format into HTML into Scheme.
>
> By the time I had finished translating the sixth page of XSLT into
> Scheme and still hadn't filled up even one page of Scheme, I decided
> that XSLT was not for me.  No, I would use languages like Scheme,
> Prolog, Erlang, Haskell, Smalltalk, even on occasion C (yes *C*
> with a suitable library being shorter and clearer than XSLT),
> languages that had decent data structures and less inhumane syntax,
>
> Now XSL has two parts: the transformation language and the flow objects
> schema, and I'm not saying anything against XSL-FO.  It's just using
> XSLT to express transformations when we have Erlang that puzzles me.

I agree - the "goodness" comes from XSL-FO not XSLT.

Transforming the XML documentation to XSL-FO with an Erlang program is
relatively easy - I have done this a few time for my own experimental
purposes.

The main problem(s) seem to be:

    - maintaining the transformation program in the future
    - producing beautiful output for *all* inputs

This problem remains irrespective of the programming language used to
do the transformations.

    If the target (XST-FO for Apache fop) is fixed we also need to be
aware that Apache-FOP changes with time and is occasionally buggy.
So the transformation code needs to work around the bugs and
be sometimes written in a non-obvious manner to achieve certain nice
formattings.

   In the 10MB of inputs there will be numerous edge-cases that are not
nicely formatted - and things like widows and orphans are never addressed.

  Conversion to LaTeX is equally difficult - and to HTML leads to CSS hell.

  Personally I don't care what is used for the transformations - All I
require is that the input is validated XML, and the output beautiful
PDF - *how* this
is done I'd leave up to the programmer.

  If I was writing the program I'd use Erlang :-)

/Joe

> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions