<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body text="#000000" bgcolor="#FFFFFF">
Dear Lloyd<br>
<br>
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). <br>
<br>
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.<br>
<br>
I now have kerl running happily on a Mac and on Ubuntu. (Feel free
to ping me offline if I can help.)<br>
<br>
The Unix environment is an ocean in which<span class="st"> a 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):</span><br>
<br>
<tt> alias erl18='. ~/bin/erl_kerl_builds/r183/activate'</tt><tt><br>
</tt><tt> alias erl20='. ~/bin/erl_kerl_builds/r203/activate'</tt><tt><br>
</tt><tt> alias erl21='. ~/bin/erl_kerl_builds/r210/activate'</tt><br>
<br>
(That '.' is a synonym for the command 'source'.)<br>
<br>
So instead of having to type out '.
~/bin/erl_kerl_builds/r210/activate' I can just use erl21.<br>
<br>
Happy hacking!<br>
<br>
Ivan<br>
<br>
<br>
<div class="moz-cite-prefix">On 20/11/2018 22:37,
<a class="moz-txt-link-abbreviated" href="mailto:lloyd@writersglen.com">lloyd@writersglen.com</a> wrote:<br>
</div>
<blockquote type="cite"
cite="mid:1542753421.4224266@apps.rackspace.com">
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<font face="arial" size="2">
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;">Hello,</p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;">We all know that writing
software documentation is hard. I tip my hat to all who strive
to do it well.</p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;">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.</p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;">This does lead to a
challenge: how much can the doc writer reasonably assume about
user knowledge and experience?</p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;">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.</p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;">For what it's worth, here's
what I ran into when I installed kerl:</p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;">1. First roadblock -- my
lack of a lowl-level Linux skill, e.g. adding kerl to PATH.
Dan Sommers provided the simple solution:</p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"><span style="font-family:
monospace;">$ cp $HOME/kerl $HOME/bin/</span></p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"><span style="font-family:
monospace;">Dan's solution worked a charm. Perhap it can be
added as an example under the current instruction in kerl
docs:</span></p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"><span style="font-family:
monospace;">"and drop it in your $PATH"</span></p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<!--WM_COMPOSE_SIGNATURE_START-->
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;">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:</p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;">~$ sudo apt-get install
libncurses-dev</p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;">3. Retried $ kerl build 21.1
and it worked but with numerous moans and growns:</p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;">Building Erlang/OTP 21.1
(21.1), please wait...<br>
WARNING: It appears that a required development package
'automake' is not installed.<br>
WARNING: It appears that a required development package
'autoconf' is not installed.<br>
APPLICATIONS DISABLED (See:
/home/lloyd/.kerl/builds/21.1/otp_build_21.1.log)<br>
* jinterface : No Java compiler found<br>
* odbc : ODBC library - link check failed</p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;">APPLICATIONS INFORMATION
(See: /home/lloyd/.kerl/builds/21.1/otp_build_21.1.log)<br>
* wx : wxWidgets not found, wx will NOT be usable</p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;">DOCUMENTATION INFORMATION
(See: /home/lloyd/.kerl/builds/21.1/otp_build_21.1.log)<br>
* documentation :<br>
* xsltproc is missing.<br>
* fop is missing.<br>
* xmllint is missing.<br>
* The documentation can not be built.</p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;">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:</p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;">~$ sudo apt-get install
xsltproc<br>
~$ sudo apt-get install libncurses-dev<br>
~$ sudo apt-get install automake<br>
~$ sudo apt-get install autoconf<br>
~$ sudo apt-get install xsltproc<br>
~$ sudo apt-get install fop</p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;">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.</p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;">All that said, thanks to the
kerl authors for a very useful tool. My next step now is to
build the Erlang docs.</p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;">Best wishes,</p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;">Lloyd</p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;font-family: arial; font-size:
10pt; overflow-wrap: break-word;"> </p>
<!--WM_COMPOSE_SIGNATURE_END--></font>
<br>
<fieldset class="mimeAttachmentHeader"></fieldset>
<br>
<pre wrap="">_______________________________________________
erlang-questions mailing list
<a class="moz-txt-link-abbreviated" href="mailto:erlang-questions@erlang.org">erlang-questions@erlang.org</a>
<a class="moz-txt-link-freetext" href="http://erlang.org/mailman/listinfo/erlang-questions">http://erlang.org/mailman/listinfo/erlang-questions</a>
</pre>
</blockquote>
<br>
<pre class="moz-signature" cols="72">--
============================================================
Ivan A. Uemlianin PhD
Llaisdy
Ymchwil a Datblygu Technoleg Lleferydd
Speech Technology Research and Development
<a class="moz-txt-link-abbreviated" href="mailto:ivan@llaisdy.com">ivan@llaisdy.com</a>
@llaisdy
llaisdy.wordpress.com
github.com/llaisdy
<a class="moz-txt-link-abbreviated" href="http://www.linkedin.com/in/ivanuemlianin">www.linkedin.com/in/ivanuemlianin</a>
festina lente
============================================================ </pre>
</body>
</html>