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