[erlang-questions] Documentation -- what I ran into when I installed kerl
Ivan Uemlianin
ivan@REDACTED
Wed Nov 21 12:59:12 CET 2018
Dear Lloyd
Kerl is fantastic and I use it a lot, but I have struggled with the
documentation like you have (in my case getting it to work on a Mac).
Kerl's documentation is very far from the worst for an open-source
project. The only real way to test installation and "getting started"
docs is to have someone not involved in the project to install and run
the software --- preferably under observation and at a time and place
not of their choosing.
I now have kerl running happily on a Mac and on Ubuntu. (Feel free to
ping me offline if I can help.)
The Unix environment is an ocean in whicha gnat may drink and an
elephant may bathe, which does complicate things. In case you haven't
come across it already, I find alias very handy, e.g., I have these
lines in my .alias file (or you might have .bash_aliases on Ubuntu):
alias erl18='. ~/bin/erl_kerl_builds/r183/activate'
alias erl20='. ~/bin/erl_kerl_builds/r203/activate'
alias erl21='. ~/bin/erl_kerl_builds/r210/activate'
(That '.' is a synonym for the command 'source'.)
So instead of having to type out '. ~/bin/erl_kerl_builds/r210/activate'
I can just use erl21.
Happy hacking!
Ivan
On 20/11/2018 22:37, lloyd@REDACTED wrote:
>
> Hello,
>
> We all know that writing software documentation is hard. I tip my hat
> to all who strive to do it well.
>
> My sense is that software docs are living documents ideally drafted
> through an iterative process that involves several cycles of unwitting
> users attempting to follow the how-to-install/how-to-use recipes
> proposed in the documentation followed closely on by doc revision
> based on user experience.
>
> This does lead to a challenge: how much can the doc writer reasonably
> assume about user knowledge and experience?
>
> Assume too much and you frustrate naive but motivated users. Assume to
> little and you risk frustrating knowledgeable users. I really don't
> know the best compromise. But it is a concern I believe worthy of
> discussion and debate.
>
> For what it's worth, here's what I ran into when I installed kerl:
>
> 1. First roadblock -- my lack of a lowl-level Linux skill, e.g. adding
> kerl to PATH. Dan Sommers provided the simple solution:
>
> $ cp $HOME/kerl $HOME/bin/
>
> Dan's solution worked a charm. Perhap it can be added as an example
> under the current instruction in kerl docs:
>
> "and drop it in your $PATH"
>
> 2. When I executed $ kerl build 21.1 I again ran into failure-- needed
> ncurses library. Took 15 minutes to find the right package name, but
> the solution was:
>
> ~$ sudo apt-get install libncurses-dev
>
> 3. Retried $ kerl build 21.1 and it worked but with numerous moans and
> growns:
>
> Building Erlang/OTP 21.1 (21.1), please wait...
> WARNING: It appears that a required development package 'automake' is
> not installed.
> WARNING: It appears that a required development package 'autoconf' is
> not installed.
> APPLICATIONS DISABLED (See:
> /home/lloyd/.kerl/builds/21.1/otp_build_21.1.log)
> * jinterface : No Java compiler found
> * odbc : ODBC library - link check failed
>
> APPLICATIONS INFORMATION (See:
> /home/lloyd/.kerl/builds/21.1/otp_build_21.1.log)
> * wx : wxWidgets not found, wx will NOT be usable
>
> DOCUMENTATION INFORMATION (See:
> /home/lloyd/.kerl/builds/21.1/otp_build_21.1.log)
> * documentation :
> * xsltproc is missing.
> * fop is missing.
> * xmllint is missing.
> * The documentation can not be built.
>
> Again, it took a bit of time looking up package names to meet the
> requirements. Given that, the following console commands filled in the
> blanks:
>
> ~$ sudo apt-get install xsltproc
> ~$ sudo apt-get install libncurses-dev
> ~$ sudo apt-get install automake
> ~$ sudo apt-get install autoconf
> ~$ sudo apt-get install xsltproc
> ~$ sudo apt-get install fop
>
> Some of these package names may be Ubuntu specific, which certainly
> makes doc drafting more difficult. But it would have saved
> considerable time and a bit easier on the blood pressure if kerl docs
> provided forewarning and, even better, a working example.
>
> All that said, thanks to the kerl authors for a very useful tool. My
> next step now is to build the Erlang docs.
>
> Best wishes,
>
> Lloyd
>
>
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions
--
============================================================
Ivan A. Uemlianin PhD
Llaisdy
Ymchwil a Datblygu Technoleg Lleferydd
Speech Technology Research and Development
ivan@REDACTED
@llaisdy
llaisdy.wordpress.com
github.com/llaisdy
www.linkedin.com/in/ivanuemlianin
festina lente
============================================================
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20181121/cdd8eb9c/attachment.htm>
More information about the erlang-questions
mailing list