[erlang-questions] Accessing the documentation at runtime

[Vlad Dumitrescu]

Hi!

On Thu, Sep 29, 2016 at 9:43 AM, Lutz Behnke <lutz.behnke@REDACTED
mburg.de> wrote:

>
> 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.
>
> 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 erlang.org may
> need the full phoenix+nginx-proxy+hardware-loadbalancer (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.
> The user can choose to configure the localhost, the work group server or
> erlang.org as the source machine.
>

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 https://github.com/Microsof
t/language-server-protocol. Serving documentation like we discussed is not
yet part of the protocol, but I created an issue to see what they think
about it.

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.

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.


I believe it's because we're not web developers :-) The logical markup is
what I set up to do.


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

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.

best regards,
Vlad



> 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
>
> mfg lutz
>
> Am 29.09.2016 um 01:56 schrieb Richard A. O'Keefe:
>
>>
>>
>> On 29/09/16 7:28 AM, Vlad Dumitrescu wrote:
>>
>>> Hi,
>>>
>>> Following the documentation discussion, and the details about how Elixir
>>> supports that as API, I wonder if we could (should?) support something
>>> similar for Erlang.
>>>
>>
>> Quintus Prolog did this back in the 1980s.
>> The manuals were originally written in Scribe,
>> then switched over to LaTeX, using very simple
>> markup.
>> They were automatically converted to plain text
>> files, one per section, and
>> - REPL "take me to this section"
>> - REPL "take me to this topic"
>> - Emacs "take me to the documentation for this"
>> - Emacs "navigate within documentation"
>> worked from that.
>>
>> I believe SWI Prolog does something similar.
>>
>> R has its own markup "Rd" and
>>   R CMD Rdconv
>>     converts Rd to plain text, LaTeX, HTML,
>>     or extracts examples so R can run them.
>>   R CMD Rd2pdf
>>     converts Rd (listed files, or in a directory)
>>     to PDF.
>>   R CMD Rd2txt
>>     converts Rd to plain text
>> This means that it's possible to write a 'man' equivalent
>> for R if you know where the Rd files are.  It also supports
>>
>>   help(topic, package = NULL, lib.loc = NULL,
>>           verbose = getOption("verbose"),
>>           try.all.packages = getOption("help.try.all.packages"),
>>           help_type = getOption("help_type"))
>>   help.search(pattern, fields = c("alias", "concept", "title"),
>>           apropos, keyword, whatis, ignore.case = TRUE,
>>           package = NULL, lib.loc = NULL,
>>           help.db = getOption("help.db"),
>>           verbose = getOption("verbose"),
>>           rebuild = FALSE, agrep = NULL, use_UTF8 = FALSE,
>>           types = getOption("help.search.types"))
>>   ??pattern
>>   field??pattern
>>   ?word
>>
>> in the REPL, and of course help() and help.search()
>> may be called from code.
>>
>> Note that a good way to store XML is to use a compressor like XMill.
>>
>> _______________________________________________
>> erlang-questions mailing list
>> erlang-questions@REDACTED
>> http://erlang.org/mailman/listinfo/erlang-questions
>>
>
>
> --
> Lutz Behnke
> Hochschule für Angewandte Wissenschaften Hamburg,
> Labor für Allgemeine Informatik,
>
> phone: +49 40 42875-8156    mailto:lutz.behnke@REDACTED
> fax  : +49 40 2803770       http://users.informatik.haw-hamburg.de/~sage
> Berliner Tor 7, 20099 Hamburg, Germany
>
>
> _______________________________________________
> 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/20160929/582cfdac/attachment.htm>