<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Thu, Sep 29, 2016 at 1:28 AM, Richard A. O'Keefe <span dir="ltr"><<a href="mailto:ok@cs.otago.ac.nz" target="_blank">ok@cs.otago.ac.nz</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><br>
On 28/09/16 9:55 PM, Vlad Dumitrescu wrote:<br>
>>[I was very unhappy about the Elixir Kernel.html page.]<br>
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
I don't know what Kenneth wanted to highlight with the Elixir docs, but<br>
I don't think that he meant the exact presentation.<br>
</blockquote>
<br>
He certainly praised "layout".<br></blockquote><div> </div><div>Yes, but layout (according to my understanding of the term) doesn't have anything to do with use colors or fonts. </div><div>Just the placement in page. </div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">I didn't find the structure especially helpful either.<br>
The distinction between types and functions and macros<br>
is an *IMPLEMENTOR*'s distinction, not a *USER*'s distinction.<br></blockquote><div><br></div><div>I will comment here instead of below because the text is very long. </div><div><br></div><div>There are important and valuable things there to be noted and taken into consideration, but most of them </div><div>are about the _content_ of the documentation. </div><div><br></div><div>What I can do right now, with relatively little effort, is take the current sources and try to present</div><div> them in a slightly better way, for some definition of 'better'. At the moment, I only did a few small </div><div>changes, which I hope showed that improvement can be done even without touching the sources.</div><div><br></div><div>Restructuring the whole documentation, adding marking to allow sorting and indexing by different keys and </div><div>grouping by semantic relatedness, catering for both "beginner" and "expert" users; all without </div><div>using javascript or any more advanced features (so that even browsers that can't handle them </div><div>can be used) is a huge undertaking that is a task for the future. </div><div><br></div><div>Regarding how Joe is using the docs. How can one provide a static HTML that is able to guess</div><div>which mode the user is in right now ('beginner' or 'expert')? </div><div><br></div><div><bringing in a snippet from the end></div><div>> HTML is great for when you have no idea what the user's<br>> screen resolution is, very little idea what fonts they<br>> have, how big their browser window is, whether they can<br>> discriminate colours (and in our fairly small department,<br>> two of my colleagues are red-green colour-blind, making<br>> many syntax colouring themes worse than useless for them),<br>> whether they can tolerate small text, ....<br></div><div><br></div><div>On the web, this is exactly the situation. We don't know anything about the users' situation. At best, we can get statistics </div><div>about some of these things. What is different in our situation? What more information do we have about the users? Except</div><div>that they are Erlang users, but that doesn't help much.</div><div><br></div><div>For typographically wonderful documentation, there is the PDF version. For the web we can implement things that are impossible</div><div>with PDF, namely interactivity (sorting, grouping, filtering, theming), for users that can and want to use a modern browser and </div><div>javascript. Otherwise one can target just one group at a time.</div><div><br></div><div>best regards,</div><div>Vlad</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
Eiffel gets this right: what is the distinction, *for a user*,<br>
between a named constant, a variable that is exported from a<br>
class (such variables can only be modified by the class's own<br>
code), and a feature (method) with no parameters? There isn't<br>
any.<br>
<br>
What I need is<br>
- an application or module overview<br>
- a pointer to separate example modules or scripts (complete things)<br>
test cases and maybe the source code<br>
- a list of topics (table-of-contents)<br>
- within topics<br>
- an overview of the topic<br>
- a pointer to examples (code fragments) relating to that topic<br>
test cases and maybe the source code<br>
- a list of subtopics (table-of-contents)<br>
- within subtopics<br>
- name<br>
- syntax (type definition, function interface, &c)<br>
- semantics (what the alternatives for a type mean, what<br>
is the function supposed to compute)<br>
- pragmatics (when did it become available, has it been<br>
superseded and if so by what, are there any performance<br>
or security issues I should know about)<br>
- a pointer to examples and test cases and maybe the source code.<br>
<br>
The *last* thing I need to know is whether something is a<br>
type, a constant, a function, a macro &c.<br>
<br>
In all honestly, organising things by Types Functions Macros<br>
is like the bad old days of Pascal programs where you had to<br>
put all the labels, then all the constants, then all the<br>
types, then all the variables, then all the procedures and<br>
functions, meaning that you had to rip semantically related<br>
things apart on implementation grounds.<br>
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
I can only see one major difference: the function list for a module is<br>
inline (elixir) instead of in the sidebar (erlang). Which one is best?<br>
I've heard people arguing for both.<br>
</blockquote>
<br>
They are both wrong. They are alphabetic rather than topical.<br>
This has, for example, the *ABSURD* consequence that<br>
binary_to_term/1<br>
term_to_binary/1<br>
are far from each other in the erlang module's documentation.<br>
Similarly, the weeping members of the integer_to_list/1,<br>
list_to_integer/1, float_to_list/1, list_to_float/1 family<br>
are cruelly separated.<br>
<br>
More precisely, they are both half right. If I *know* which<br>
function I want, the alphabetic list helps me find it quickly.<br>
But if I only know what the function is *about*, the alphabetic<br>
list helps very little.<br>
<br>
The actual descriptions of semantically related functions should<br>
be physically close in the body of the text so that when I am<br>
looking at one, a related one is just a glance away.<br>
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
IMHO, presenting reference documentation so that everybody is pleased is<br>
extremely difficult, because people use the docs in many different ways.<br>
Different layout and information detail are most useful for beginners<br>
(that browse to see what's available and might learn something unrelated<br>
in the process)<br>
than for people that mostly know what they look for (that need fast<br>
access to some detail, often from the shell).<br>
</blockquote>
<br>
If there's anyone here who is NOT a beginner, it's surely Joe<br>
Armstrong. Yet he has made the point that in each module that<br>
he uses, there is a small number of functions that he uses a lot,<br>
and the rest which he uses very seldom. That means that<br>
*sometimes* when he looks at dict *sometimes* he will be approaching<br>
it as an expert refreshing his memory about something and<br>
*sometimes* he will be approaching it as a beginning looking for<br>
information about a function he uses so rarely he can't even recall<br>
its name.<br>
<br>
Every release there seems to be new stuff in the erlang: module,<br>
so every release I am a beginner again about *something* useful<br>
in that module.<br>
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
It's also difficult to create a presentation that works for a full-blown<br>
browser as well as for lynx.<br>
</blockquote>
<br>
It doesn't have to be the same HTML file does it?<br>
HTML-optimised-for-Lynx-or-w3m<wbr>-or-Emacs-w3 and<br>
HTML-optimised-for-Firefox-on-<wbr>a-huge-screen and<br>
HTML-optimised-for-a-Windows-p<wbr>hone<br>
really need to be three different versions.<br>
<br>
≥ I'm not referring to the visuals, but the<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
module and function index, which is<br>
huge and needs to be folded. I can't come up with a way to do that<br>
without javascript.<br>
</blockquote>
<br>
But I don't *want* "huge" function and module indices<br>
in my pages all the time. (Hint: "huge" lists are hard<br>
to find things in.) There's one thing I do heartily<br>
approve of in the Elixir pages, which is that there is a<br>
very simple way to get rid of the navbar. In fact I'm<br>
personally quite happy to have<br>
- a module list in one tab<br>
- a topic (NOT function!) list in another tab<br>
- the main text scrolled to the current topic in another tab<br>
because quite often when I click on a navbar link what I<br>
want is to see another topic *as well* (in a new tab),<br>
not *instead* of the one I'm looking at.<br>
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
BTW, it's trivial (see comment above regarding html friendliness,<br>
though) to make the erlang docs look more like elixir's while keeping<br>
the good parts. See picture :-)<br>
<a href="https://www.dropbox.com/s/jqpqpcimv3qxdce/e0.png?dl=0" rel="noreferrer" target="_blank">https://www.dropbox.com/s/jqpq<wbr>pcimv3qxdce/e0.png?dl=0</a><br>
</blockquote>
<br>
Problem 1: the structure is<br>
<highly obtrusive bar> <function header><br>
Types:<br>
<argument and result types><br>
<br>
<text><br>
<br>
[ Example:<br>
<Haskell doctest-style example> ]<br>
<br>
The word "Types:" is pointless. I can *see* that they are types.<br>
<br>
Problem 2: if anything should be highlighted here, it is the<br>
function name. If the function name is bold. there's no need<br>
for the <highly obtrusive bar>, and my eye is directed to the<br>
most salient piece of information.<br>
<br>
Problem 3: the font used for code in the <function header><br>
and <argument and result types> and the font used for code<br>
in the <text> are not the same font. Worse still, the<br>
font used for the expression in the <Haskell doctest-style<br>
example> and the font used for the result are not the same<br>
font. (Or more precisely, they may be different weights of<br>
the same font.)<br>
<br>
Problem 4: the font used for code in the <text> does not have<br>
the same x-height as the font used for ordinary text. The<br>
code font is markedly smaller.<br>
<br>
Problem 5: the font used for code in the <text> and for the<br>
result in <...example> are markedly fainter than the other<br>
fonts.<br>
<br>
I could go on.<br>
<br>
But this is the fundamental problem with trying to do fancy<br>
typography in HTML. It is very very hard to make it look good.<br>
If you want fancy typography that actually looks good,<br>
PDF is the only game in town.<br>
<br>
HTML is just the wrong tool for that job.<br>
<br>
HTML is great for when you have no idea what the user's<br>
screen resolution is, very little idea what fonts they<br>
have, how big their browser window is, whether they can<br>
discriminate colours (and in our fairly small department,<br>
two of my colleagues are red-green colour-blind, making<br>
many syntax colouring themes worse than useless for them),<br>
whether they can tolerate small text, ....<br>
<br>
</blockquote></div><br></div></div>