[erlang-questions] Accessing the documentation at runtime

[Lutz Behnke]

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

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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 5006 bytes
Desc: S/MIME Cryptographic Signature
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160929/7ccf0556/attachment.bin>