<div dir="ltr">Hi Joe,<div><br></div><div>Have you looked at the Elixir doc for example <a href="http://elixir-lang.org/docs/stable/elixir/Kernel.html">http://elixir-lang.org/docs/stable/elixir/Kernel.html</a>?</div><div>I think the layout and function is quite good and the handling of css and javascript is from what I can understand</div><div>handled nicely.</div><div><br></div><div>For an application and modules they present pretty much the same as we do today.</div><div>For sure the Elixir community have more cometence around html, css, javascript than at least we on the OTP team have.</div><div><br></div><div>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.</div><div><br></div><div>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. <br><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Sep 27, 2016 at 11:46 AM, Joe Armstrong <span dir="ltr"><<a href="mailto:erlang@gmail.com" target="_blank">erlang@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Re: HTML<br>
<br>
I'd very much like to mock up a "nice" HTML display of the functions<br>
in a module.<br></blockquote><div><br></div><div>Have you looked at the Elixir doc for example <a href="http://elixir-lang.org/docs/stable/elixir/Kernel.html">http://elixir-lang.org/docs/stable/elixir/Kernel.html</a>?</div><div>I think the layout and function is quite good and the handling of css and javascript is from what I can understand</div><div>handled nicely.</div><div><br></div><div>For an application and modules they present pretty much the same as we do today.</div><div>For sure the Elixir community have more cometence around html, css, javascript than at least we on the OTP team have.</div><div><br></div><div>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.</div><div><br></div><div>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. <br><div class="gmail_extra"><br></div></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
What I'd like is for most of the information to be initially hidden<br>
and to be made available through clickable folds or hover popups.<br>
<br>
Doing this involves a few different problems:<br>
<br>
1) - extracting the necessary information to be displayed<br>
from the XML or erlang sources<br>
2) - turning 1) into HTML markup<br>
3) - adding some CSS/JS magic to create hover popups/folds<br>
and so on.<br>
<br>
I have a good idea how to do 1) - step 2) is easy if I know what markup<br>
to produce. I'm rubbish at step 3)<br>
<br>
I guess there must be someone reading this list who is skilled in the<br>
art of CSS/JS and could suggest a suitable markup.<br>
<br>
Being a tad fussy about these things I wonder if it's possible<br>
to get a pretty display *without* including 200KB of JS libraries and CSS<br>
stuff.<br>
<br>
If some kind people could mockup a a few pages with dummy markup<br>
it might help move things along<br>
<br>
Cheers<br>
<span class="gmail-HOEnZb"><font color="#888888"><br>
/Joe<br></font></span></blockquote><div><br></div><div>/Kenneth </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><span class="gmail-HOEnZb"><font color="#888888">
</font></span><div class="gmail-HOEnZb"><div class="gmail-h5"><br>
<br>
<br>
<br>
<br>
<br>
<br>
On Tue, Sep 27, 2016 at 9:44 AM, Kenneth Lundin <<a href="mailto:kenneth@erlang.org">kenneth@erlang.org</a>> wrote:<br>
> Hi,<br>
><br>
> I have followed this thread with interest since there are many good<br>
> suggestions and ideas. As Lukas mentioned it would be good if we could agree<br>
> on some action(s) in which the community could contribute.<br>
><br>
> First some info about what we (The OTP team at Ericsson and the Industrial<br>
> Erlang User Group) plan to do.<br>
><br>
> - Nicer , better HTML layout of the docs. The Elixir look layout looks quite<br>
> nice and since it is overlapping communities it could be good to have the<br>
> same or similar layout. The HTML, CSS, Javascript setup seems quite well<br>
> thought.<br>
> Take a look at<br>
> <a href="http://elixir-lang.org/docs/stable/elixir/Kernel.html#full-list" rel="noreferrer" target="_blank">http://elixir-lang.org/docs/<wbr>stable/elixir/Kernel.html#<wbr>full-list</a>.<br>
> If you have suggestions regarding the html layout they are welcome. In that<br>
> case it would be nice with a small example showing for example the beginning<br>
> of the lists module and a few functions. Note this step does not require<br>
> changes of the doc source which is XML it is just a matter of tooling.<br>
> Translating the current XML to html (when you know what html you want).<br>
><br>
> - Making it easier to contribute with documentation improvements. One simple<br>
> step can be to add a link to the doc source at github from the generated<br>
> html page. Another to write a short guide on how to contribute to the<br>
> documentation.<br>
><br>
> - Having technical writers going through the documentation in order to<br>
> correct language and consistency. This is ongoing.<br>
><br>
> - Making the search in documentation on <a href="http://www.erlang.org" rel="noreferrer" target="_blank">www.erlang.org</a> more visible. You can<br>
> search on application, modules, functions.<br>
><br>
> - Validate the current doc sources with XMLLINT to assure that we are<br>
> following our own DTDs. This is almost done and with this in place it is<br>
> easy to translate the doc sources to some other format like a simpler XML<br>
> dtd (or XSD), asciidoc or even markdown. Note that there is only one common<br>
> source for the documentation and it is in XML with a few exceptions. Each<br>
> application has a doc/src directory where its documentation source files<br>
> are. There is module references for the modules with public APIs and a User<br>
> Guide (mostly).<br>
><br>
> From this thread I think the following are the most interesting suggestions:<br>
><br>
> Examples in the doc<br>
> ------------------------------<br>
><br>
> I agree that we need more examples in the documentation. It would for<br>
> example be good to have a short example for<br>
> almost every function in a module.<br>
><br>
> This can be done in various ways. Either embed the example in the text or<br>
> have a separate example file in parallell with the text. In both cases I<br>
> would like to have the possibility to automatically check the syntax and<br>
> execution of the example during the build documentation build process. If<br>
> not checked we will soon have a number of non working examples.<br>
><br>
> The presentation view of examples is just a tooling question independent on<br>
> the actual source for the examples. The first thing is to create the source<br>
> for examples and what format we should use for this (same for all modules of<br>
> course).<br>
><br>
> Man pages or not?<br>
> -------------------------<br>
><br>
> I understand that some of you are using the man pages. But the question is<br>
> why are you using them?<br>
> Is it because it is easy to type "man lists" or "erl -man lists"? What if<br>
> "erl -man lists" pops up in a web-browser window of you choice instead?,<br>
> Note that it is exactly the same information shown in the lists.html and in<br>
> the man page for lists.<br>
><br>
> PDF or not?<br>
> ------------------<br>
><br>
> I think it is rather unusual that the PDF pages we generate to day are used<br>
> compared to the HTML variant. Correct me if I am wrong.<br>
> Perhaps Epub or something else would be more useful. I suppose the html<br>
> variant could also support printing and or saving as pdf without to much<br>
> effort from our side.<br>
><br>
> More User Guide oriented text or cook books.<br>
> ------------------------------<wbr>------------------------------<wbr>---<br>
><br>
> This is very valuable but does not have to be part of the Erlang/OTP<br>
> release. Could be hosted on a web-site like Erlang Central (and there is<br>
> already material like this there I think).<br>
><br>
> I have probably forgotten lots of things that I should have mentioned and<br>
> commented , but this is it for now.<br>
><br>
> /Kenneth, Erlang/OTP , Ericsson<br>
><br>
</div></div><div class="gmail-HOEnZb"><div class="gmail-h5">> ______________________________<wbr>_________________<br>
> erlang-questions mailing list<br>
> <a href="mailto:erlang-questions@erlang.org">erlang-questions@erlang.org</a><br>
> <a href="http://erlang.org/mailman/listinfo/erlang-questions" rel="noreferrer" target="_blank">http://erlang.org/mailman/<wbr>listinfo/erlang-questions</a><br>
><br>
______________________________<wbr>_________________<br>
erlang-questions mailing list<br>
<a href="mailto:erlang-questions@erlang.org">erlang-questions@erlang.org</a><br>
<a href="http://erlang.org/mailman/listinfo/erlang-questions" rel="noreferrer" target="_blank">http://erlang.org/mailman/<wbr>listinfo/erlang-questions</a><br>
</div></div></blockquote></div><br></div></div></div>