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

[Joe Armstrong]

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
>