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

lloyd@REDACTED lloyd@REDACTED
Tue Sep 27 19:05:23 CEST 2016


Hello,

In the spirit of eating our own dog food, Erlang Nitrogen provides many nice functions (elements and actions) for creating dynamic web pages, including such things as clickable folds and hover pop ups. 

It's easy to get started. Jesse Gumm and I have trying in the small spaces of busy lives to produce a how-to book. Still very rough but more to come "real soon now." You can download work-in-progress for free:

http://builditwith.com/nitrogen

Best,

LRP




-----Original Message-----
From: "Joe Armstrong" <erlang@REDACTED>
Sent: Tuesday, September 27, 2016 5:46am
To: "Kenneth Lundin" <kenneth@REDACTED>
Cc: "Lukas Larsson" <lukas@REDACTED>, "erlang-questions@REDACTED" <erlang-questions@REDACTED>
Subject: Re: [erlang-questions] Erlang documentation -- a modest proposal

Re: HTML

I'd very much like to mock up a "nice" HTML display of the functions
in a module.

What I'd like is for most of the information to be initially hidden
and to be made available through clickable folds or hover popups.

Doing this involves a few different problems:

    1) - extracting the necessary information to be displayed
          from the XML or erlang sources
    2) - turning 1) into HTML markup
    3) - adding some CSS/JS magic to create hover popups/folds
          and so on.

I have a good idea how to do 1) - step 2) is easy if I know what markup
to produce. I'm rubbish at step 3)

I guess there must be someone reading this list who is skilled in the
art of CSS/JS and could suggest a suitable markup.

Being a tad fussy about these things I wonder if it's possible
to get a pretty display *without* including 200KB of JS libraries and CSS
stuff.

If some kind people could mockup a a few pages with dummy markup
it might help move things along

Cheers

/Joe







On Tue, Sep 27, 2016 at 9:44 AM, Kenneth Lundin <kenneth@REDACTED> wrote:
> Hi,
>
> I have followed this thread with interest since there are many good
> suggestions and ideas. As Lukas mentioned it would be good if we could agree
> on some action(s) in which the community could contribute.
>
> First some info about what we (The OTP team at Ericsson and the Industrial
> Erlang User Group) plan to do.
>
> - Nicer , better HTML layout of the docs. The Elixir look layout looks quite
> nice and since it is overlapping communities it could be good to have the
> same or similar layout. The HTML, CSS, Javascript setup  seems quite well
> thought.
> Take a look at
> http://elixir-lang.org/docs/stable/elixir/Kernel.html#full-list.
> If you have suggestions regarding the html layout they are welcome. In that
> case it would be nice with a small example showing for example the beginning
> of the lists module and a few functions. Note this step does not require
> changes of the doc source which is XML it is just a matter of tooling.
> Translating the current XML to html (when you know what html you want).
>
> - Making it easier to contribute with documentation improvements. One simple
> step can be to add a link to the doc source at github from the generated
> html page. Another to write a short guide on how to contribute to the
> documentation.
>
> - Having technical writers going through the documentation in order to
> correct language and consistency. This is ongoing.
>
> - Making the search in documentation on www.erlang.org more visible. You can
> search on application, modules, functions.
>
> - Validate the current doc sources with XMLLINT to assure that we are
> following our own DTDs. This is almost done and with this in place it is
> easy to translate the doc sources to some other format like a simpler XML
> dtd (or XSD), asciidoc or even markdown. Note that there is only one common
> source for the documentation and it is in XML with a few exceptions. Each
> application has a doc/src directory where its documentation source files
> are. There is module references for the modules with public APIs and a User
> Guide (mostly).
>
> From this thread I think the following are the most interesting suggestions:
>
> Examples in the doc
> ------------------------------
>
> I agree that we need more examples in the documentation. It would for
> example be good to have a short example for
> almost every function in a module.
>
> This can be done in various ways. Either embed the example in the text or
> have a separate example file in parallell with the text. In both cases I
> would like to have the possibility to automatically check the syntax and
> execution of the example during the build documentation build process. If
> not checked we will soon have a number of non working examples.
>
> The presentation view of examples is just a tooling question independent on
> the actual source for the examples. The first thing is to create the source
> for examples and what format we should use for this (same for all modules of
> course).
>
> Man pages or not?
> -------------------------
>
> I understand that some of you are using the man pages. But the question is
> why are you using them?
> Is it because it is easy to type "man lists" or "erl -man lists"? What if
> "erl -man lists" pops up in a web-browser window of you choice instead?,
> Note that it is exactly the same information shown in the lists.html and in
> the man page for lists.
>
> PDF or not?
> ------------------
>
> I think it is rather unusual that the PDF pages we generate to day are used
> compared to the HTML variant. Correct me if I am wrong.
> Perhaps Epub or something else would be more useful. I suppose the html
> variant could also support printing and or saving as pdf without to much
> effort from our side.
>
> More User Guide oriented text or cook books.
> ---------------------------------------------------------------
>
> This is very valuable but does not have to be part of the Erlang/OTP
> release. Could be hosted on a web-site like Erlang Central (and there is
> already material like this there I think).
>
> I have probably forgotten lots of things that I should have mentioned and
> commented , but this is it for now.
>
> /Kenneth, Erlang/OTP , Ericsson
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions
>
_______________________________________________
erlang-questions mailing list
erlang-questions@REDACTED
http://erlang.org/mailman/listinfo/erlang-questions





More information about the erlang-questions mailing list