<font face="arial" size="2"><p style="margin:0;padding:0;font-family: arial; font-size: 10pt; overflow-wrap: break-word;">Thanks for the thoughts and tips, Ivan!</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;">Love your quote:</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;">"The Unix environment is an ocean in which<span class="st"> a gnat may drink and an elephant may bathe"</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 class="st">And I would add, "and where a noobie can all too easily flounder around lost at sea."</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 class="st">I work alone on many fronts so, beyond the wonderful people on this list, depend upon books and the web as I try to become sufficiently competent in the many tasks required to bring the ambitious web app I've been working on to fruition. Documentation is often a make or break for me when I evaluate an app or tool. If I don't understand it, which happens all too often, it's Sayonara for that app.</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 class="st">This is complicated by the fact that as I age I don't retain information as well as I once did. So I've been struggling to develop a format and system for keeping track of all the things I need to know. </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 class="st">I hope soon to propose documentation for creating publish source GitHub repositories. If time and energy allow, I'll try to follow it up with a stab at a "Building Erlang on Ubuntu" draft inspired by Fred Hebert's suggestion.</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 class="st">I need to understand how to put such documents on the web, so I'll do so as time permits.</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 class="st">Thanks again,</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 class="st">Lloyd</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;">-----Original Message-----<br />From: "Ivan Uemlianin" <ivan@llaisdy.com><br />Sent: Wednesday, November 21, 2018 6:59am<br />To: erlang-questions@erlang.org<br />Subject: Re: [erlang-questions] Documentation -- what I ran into when I installed kerl<br /><br /></p>
<div id="SafeStyles1542829682">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:</div>
<blockquote>
<p style="margin:0;padding:0;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;">Hello,</p>
<p style="margin:0;padding:0;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;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;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;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;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;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;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;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;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;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;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;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;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;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;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;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;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;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;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;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;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;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;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;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;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;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;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;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;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;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;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;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;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;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;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;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;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;">Best wishes,</p>
<p style="margin:0;padding:0;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;">Lloyd</p>
<p style="margin:0;padding:0;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<p style="margin:0;padding:0;margin: 0; padding: 0; font-family: arial; font-size: 10pt; overflow-wrap: break-word;"> </p>
<br /><fieldset class="mimeAttachmentHeader"></fieldset><br />
<p style="margin:0;padding:0;">_______________________________________________
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 />
<p class="moz-signature" style="margin:0;padding:0;">--
============================================================
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>
</div></font>