[erlang-questions] Accessing the documentation at runtime
Thu Sep 29 09:43:00 CEST 2016
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
(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
Am 29.09.2016 um 01:56 schrieb Richard A. O'Keefe:
> On 29/09/16 7:28 AM, Vlad Dumitrescu wrote:
>> 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
> 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"))
> 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
Hochschule für Angewandte Wissenschaften Hamburg,
Labor für Allgemeine Informatik,
phone: +49 40 42875-8156 mailto:
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...
Size: 5006 bytes
Desc: S/MIME Cryptographic Signature
More information about the erlang-questions