[erlang-questions] Accessing the documentation at runtime

[Joe Armstrong]

On Thu, Sep 29, 2016 at 9:43 AM, Lutz Behnke
<lutz.behnke@REDACTED> wrote:
> Hi all,
>
> 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.

Not really - whatever you do on-line can easily be achieved with
a local webserver which can be packaged with the rest of the system

> Lets write a small doc-engine that can do all that. It should run as a self
> contained program on your local machine.

Yes - but it could use the same REST interface as above

/Joe

> 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.
>
> The documentation should not be part of the beam file. My production servers
> don't need documentation. On the other hand, a location convention for
> documentation placement for an app and module would be very helpful. This
> would allow the doc-server to be pointed to a OTP source drop and get
> additional locations to my personal app library, so that I can access all
> documentation through the same mechanism.
>
> 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. 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.
>
> 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
>