<div dir="ltr">Hi!<div class="gmail_extra"><br><div class="gmail_quote">On Thu, Sep 29, 2016 at 9:43 AM, Lutz Behnke <span dir="ltr"><<a href="mailto:lutz.behnke@informatik.haw-hamburg.de" target="_blank">lutz.behnke@informatik.haw-ha<wbr>mburg.de</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"><br>
the discussion leaves me with the impression that everybody has his or her own method of accessing the documentation. And even that may change according to circumstances. I think a solution should be modular to cater to a wide range of personal preferences and situational restrictions.<br>
<br>
Joe's suggestion of a REST engine, that can provide the documentation in the format of your choice, does not automatically mean it only works online. Lets write a small doc-engine that can do all that. It should run as a self contained program on your local machine. And <a href="http://erlang.org" rel="noreferrer" target="_blank">erlang.org</a> may need the full phoenix+nginx-proxy+hardware-l<wbr>oadbalancer (or whatever) to support the traffic (is that what CDNs are for?). But erlide or emacs or the erl-shell could all access this locally.<br>
The user can choose to configure the localhost, the work group server or <a href="http://erlang.org" rel="noreferrer" target="_blank">erlang.org</a> as the source machine.<br></blockquote><div><br></div><div>Several (and in increasing numbers) editors and IDEs have started using the concept of "language servers" that are standalone servers providing information about source code (code completion, context documentation, etc). There is a protocol specified at <a href="https://github.com/Microsoft/language-server-protocol" target="_blank">https://github.com/Microsof<wbr>t/language-server-protocol</a>. Serving documentation like we discussed is not yet part of the protocol, but I created an issue to see what they think about it. </div><div><br></div><div>I have started working on implementing such a server for (and in) Erlang. It's very prototype-y at the moment. Even if the standard protocol won't support this case, it would be easy to extend it.</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">I do not understand why there is a discussion on the html layout in the days of reactive design. Format the html for a lynx or similar for use when no javascript is available. Do proper _logical_ markup (function-definition, example, etc.) for CSS consumption. </blockquote><div><br></div><div>I believe it's because we're not web developers :-) The logical markup is what I set up to do. </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">Using the REST server concept it would be easy to add an option to use personalized CSS URLs. This would make catering to special accessibility needs (color blind, hate of syntax highlighting, etc.) a lot easier.<br></blockquote><div><br></div><div>That is an interesting idea. For the record, this can be done without any REST server, just make sure that whichever method is used to retrieve the docs accepts parameters and can do the processing.</div><div><br></div><div>best regards,</div><div>Vlad</div><div><br></div><div> <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
Even generating static man pages would be straight forward provided there is a erlDocREST2man script which will walk the documentation and write out the files and packages for installation with an (almost) minimal erlang system<br>
<br>
mfg lutz<br>
<br>
Am 29.09.2016 um 01:56 schrieb Richard A. O'Keefe:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
<br>
On 29/09/16 7:28 AM, Vlad Dumitrescu wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
Hi,<br>
<br>
Following the documentation discussion, and the details about how Elixir<br>
supports that as API, I wonder if we could (should?) support something<br>
similar for Erlang.<br>
</blockquote>
<br>
Quintus Prolog did this back in the 1980s.<br>
The manuals were originally written in Scribe,<br>
then switched over to LaTeX, using very simple<br>
markup.<br>
They were automatically converted to plain text<br>
files, one per section, and<br>
- REPL "take me to this section"<br>
- REPL "take me to this topic"<br>
- Emacs "take me to the documentation for this"<br>
- Emacs "navigate within documentation"<br>
worked from that.<br>
<br>
I believe SWI Prolog does something similar.<br>
<br>
R has its own markup "Rd" and<br>
R CMD Rdconv<br>
converts Rd to plain text, LaTeX, HTML,<br>
or extracts examples so R can run them.<br>
R CMD Rd2pdf<br>
converts Rd (listed files, or in a directory)<br>
to PDF.<br>
R CMD Rd2txt<br>
converts Rd to plain text<br>
This means that it's possible to write a 'man' equivalent<br>
for R if you know where the Rd files are. It also supports<br>
<br>
help(topic, package = NULL, lib.loc = NULL,<br>
verbose = getOption("verbose"),<br>
try.all.packages = getOption("help.try.all.packag<wbr>es"),<br>
help_type = getOption("help_type"))<br>
help.search(pattern, fields = c("alias", "concept", "title"),<br>
apropos, keyword, whatis, ignore.case = TRUE,<br>
package = NULL, lib.loc = NULL,<br>
help.db = getOption("help.db"),<br>
verbose = getOption("verbose"),<br>
rebuild = FALSE, agrep = NULL, use_UTF8 = FALSE,<br>
types = getOption("help.search.types")<wbr>)<br>
??pattern<br>
field??pattern<br>
?word<br>
<br>
in the REPL, and of course help() and help.search()<br>
may be called from code.<br>
<br>
Note that a good way to store XML is to use a compressor like XMill.<br>
<br>
______________________________<wbr>_________________<br>
erlang-questions mailing list<br>
<a href="mailto:erlang-questions@erlang.org" target="_blank">erlang-questions@erlang.org</a><br>
<a href="http://erlang.org/mailman/listinfo/erlang-questions" rel="noreferrer" target="_blank">http://erlang.org/mailman/list<wbr>info/erlang-questions</a><span><font color="#888888"><br>
</font></span></blockquote><span><font color="#888888">
<br>
<br>
-- <br>
Lutz Behnke<br>
Hochschule für Angewandte Wissenschaften Hamburg,<br>
Labor für Allgemeine Informatik,<br>
<br>
phone: +49 40 42875-8156 mailto:<a href="mailto:lutz.behnke@informatik.haw-hamburg.de" target="_blank">lutz.behnke@informatik.<wbr>haw-hamburg.de</a><br>
fax : +49 40 2803770 <a href="http://users.informatik.haw-hamburg.de/~sage" rel="noreferrer" target="_blank">http://users.informatik.haw-h<wbr>amburg.de/~sage</a><br>
Berliner Tor 7, 20099 Hamburg, Germany<br>
<br>
</font></span><br>______________________________<wbr>_________________<br>
erlang-questions mailing list<br>
<a href="mailto:erlang-questions@erlang.org" target="_blank">erlang-questions@erlang.org</a><br>
<a href="http://erlang.org/mailman/listinfo/erlang-questions" rel="noreferrer" target="_blank">http://erlang.org/mailman/list<wbr>info/erlang-questions</a><br>
<br></blockquote></div><br></div></div>