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

Tue Sep 27 13:13:37 CEST 2016

Hi Joe,

Have you looked at the Elixir doc for example
http://elixir-lang.org/docs/stable/elixir/Kernel.html?
I think the layout and function is quite good and the handling of css and
javascript is from what I can understand
handled nicely.

For an application and modules they present pretty much the same as we do
today.
For sure the Elixir community have more cometence around html, css,
javascript than at least we on the OTP team have.

The Elixir doc is genereated with a tool called Ex_doc written in Elixir of
course. It takes Markdown as input but that is not important right now when
we are discussing layout.

The left column (the navigation) is generated as Json data that is handled
by a fixed Javascript. There is also a search which takes Json data as
input. This way everything including search can be handled locally in the
browser without need for a web-server as far as I can see.

On Tue, Sep 27, 2016 at 11:46 AM, Joe Armstrong <erlang@REDACTED> wrote:

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

Have you looked at the Elixir doc for example
http://elixir-lang.org/docs/stable/elixir/Kernel.html?
I think the layout and function is quite good and the handling of css and
javascript is from what I can understand
handled nicely.

For an application and modules they present pretty much the same as we do
today.
For sure the Elixir community have more cometence around html, css,
javascript than at least we on the OTP team have.

The Elixir doc is genereated with a tool called Ex_doc written in Elixir of
course. It takes Markdown as input but that is not important right now when
we are discussing layout.

The left column (the navigation) is generated as Json data that is handled
by a fixed Javascript. There is also a search which takes Json data as
input. This way everything including search can be handled locally in the
browser without need for a web-server as far as I can see.

>
> 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
>

/Kenneth

>
>
>
>
>
>
>
> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160927/d72c6269/attachment.htm>