<html>
<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<p>Complexity is entropy. It occurs naturally in all human endeavor.
It takes work to keep things small, orderly, and rational. But
there is also a point where although a tool may be perfect in its
conception and execution, from its own perspective, it is not as
useful as a slightly more disorderly version that does what people
want it to do. "Well they shouldn't want that !" is a common
response. Then people write scripts to do for themselves what the
tool doesn't do. Which might be right, but it might lead to a
whole bunch of similar scripts to do the same thing, just a little
differently And that's when we discover that it would have been
better to have it in the one tool in the first place.<br>
</p>
So it's a back and forth, trial and error process. Eventually new
balances get struck, and people of like minds and tastes find a new
center, like Plan 9, or other things.<br>
<br>
Myself, I do tend to like tools that are smaller and more
single-minded in their function (and that makes it possible to have
documentation that is clearer and more concise), but as an example,
sometimes I want the "-u" switch on diff, to make a patch, sometimes
I don't, the default display is better for a quick review (but I
think or expect that the essential diff engine is being shared).
It's all a matter of judgment, but you can't apply good judgment
until you have the experience gained from trying several
alternatives. So things will get bloated up, and then they will need
to be pruned and re-engineered, but hopefully we don't throw out the
most helpful exceptions to the rule just because they don't fit with
some sort of consistency aesthetic.<br>
<br>
<div class="moz-cite-prefix">On 05/18/2024 11:52 AM, Clem Cole
wrote:<br>
</div>
<blockquote
cite="mid:CAC20D2NbHEdxKU6HA_ZQWYmc-HGhLE+F4e8XFoWePToRBP4-9Q@mail.gmail.com"
type="cite">
<div dir="ltr">
<div dir="ltr">
<div class="gmail_default"
style="font-family:arial,helvetica,sans-serif"><br>
</div>
</div>
<br>
<div class="gmail_quote">
<div dir="ltr" class="gmail_attr">On Sat, May 18, 2024 at
2:18 PM Larry McVoy <<a moz-do-not-send="true"
href="mailto:lm@mcvoy.com">lm@mcvoy.com</a>> wrote:<br>
</div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px
0.8ex;border-left:1px solid
rgb(204,204,204);padding-left:1ex">But I'm ok with a terse
man page with a SEE ALSO that<span class="gmail_default"
style="font-family:arial,helvetica,sans-serif"> </span>points
to a user guide.<br>
</blockquote>
<div><font color="#0000ff">Only if the SEE ALSO has more
complete and relevant information - otherwise, it degrades
to VMS's famous "see figure 1" SPR.</font> </div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px
0.8ex;border-left:1px solid
rgb(204,204,204);padding-left:1ex">
<br>
Docs should be helpful.<br>
</blockquote>
<div><font color="#0000ff"><span class="gmail_default"
style="font-family:arial,helvetica,sans-serif">And easy
to extract information.</span> </font></div>
<div><font color="#0000ff"><br>
</font></div>
<div><span class="gmail_default"
style="font-family:arial,helvetica,sans-serif"><font
color="#0000ff">The issue to be comes back to the type
of information each document is designed to give. I
believe there at least three types of docs:</font></span></div>
<div>
<ol>
<li><span
style="color:rgb(0,0,255);font-family:arial,helvetica,sans-serif">Full
manuals explain how something is built and it </span>it used<span
style="color:rgb(0,0,255);font-family:arial,helvetica,sans-serif">. It
helps to have theory/principles of operations behind
it and enough detail when done, you can understand why
and how<span class="gmail_default"
style="font-family:arial,helvetica,sans-serif"> to
use it.</span><span class="gmail_default"
style="font-family:arial,helvetica,sans-serif"></span></span><br>
</li>
<li><span
style="color:rgb(0,0,255);font-family:arial,helvetica,sans-serif">Tutorials
are excellent for someone trying to learn a new tool.
Less theory - and more -- examples, showing off the
features and how to do something.</span></li>
<li><font color="#0000ff">References pages - need to be
quick look-ups to remind someone how to use something
- particularly for tools you don't use every
day/generally don't memorize<span
class="gmail_default"
style="font-family:arial,helvetica,sans-serif">.</span></font></li>
</ol>
</div>
<div><span class="gmail_default"
style="font-family:arial,helvetica,sans-serif"><font
color="#0000ff"><br>
</font></span></div>
<div>
<div class="gmail_default"
style="font-family:arial,helvetica,sans-serif"><font
color="#0000ff">There are at least two more: an
academic paper which might be looked at as a start of #1
and full books which take #1 to even more details. Some
academic papers indeed are fine manuals, and I can also
argue the "manual" for some tools like awk/sed or, for
that matter, yacc(1) are full books. But the idea is the
>>complete<< review here.</font></div>
<div class="gmail_default"
style="font-family:arial,helvetica,sans-serif"><font
color="#0000ff"><br>
</font></div>
<div class="gmail_default"
style="font-family:arial,helvetica,sans-serif"><font
color="#0000ff">Tutorials and reference pages are
supposed to easy helpful things -- but often miss the
mark for the audience. </font><font
style="color:rgb(0,0,255)" face="arial, helvetica,
sans-serif">To me, the problem is the wrong type of
information is put in each one and, more importantly,
people's expectations from the document. I love
properly </font><font
style="font-family:Arial,Helvetica,sans-serif"
color="#0000ff">built<font face="arial, helvetica,
sans-serif"> </font></font><font
style="color:rgb(0,0,255)" face="arial, helvetica,
sans-serif">manual pages - I detest things like the
VMS/TOPS help command or gnu info pages. What I really
hate is when there is no manual, but they tell you
see the HELP command -- but which command or "subtopic"
-- Yikes. The traditional man system is simple quick
reminders, basic</font><font
style="font-family:Arial,Helvetica,sans-serif"
color="#0000ff"><font face="arial, helvetica,
sans-serif"> </font>reference</font><font
style="color:rgb(0,0,255)" face="arial, helvetica,
sans-serif"> and I can move on. For instance, I needed
to remember which C library has the definition these
days for some set of functions and what are its error
return codes -- man 3 functions, I'm done.</font><font
style="color:rgb(0,0,255)" face="arial, helvetica,
sans-serif"> </font></div>
<div class="gmail_default" style=""><font
style="color:rgb(0,0,255)" face="arial, helvetica,
sans-serif"><br>
</font></div>
<div class="gmail_default" style=""><font
style="color:rgb(0,0,255)" face="arial, helvetica,
sans-serif">Tutorials are funny. For some people, what
they want to learn the ideas behind a tool. Typically,
I don't need that as much as how this toll does some
function. For instance, Apple is forcing me the learn
lldb because the traditional debuggers derived from
UCB's DBX are not there. It's similar to different.
The man page is useful only for the command lines
switches. It turns out the commands are all really
long, but they have abbreviations and can be aliases. I
found references to this in an lldb tutorial - but the
tutorial is written to teach people more how to use a
debugger to debug there code, and less how this debugger
maps into the traditional functions. Hey I would like
to find an cheat sheet or a set of aliases that map
DBX/GDB into it -- but so far I've found nothing.</font><br>
</div>
<div class="gmail_default" style=""><font
style="color:rgb(0,0,255)" face="arial, helvetica,
sans-serif"><br>
</font></div>
<div class="gmail_default" style=""><font color="#0000ff"><font
style="" face="arial, helvetica, sans-serif">So Larry
-- I agree with you ... "</font><i>Docs should be
helpful</i>," but I fear saying like that is a bit
like the Faber College Motto/Founder's Quote: "<i>Knowledge
is good</i>."</font></div>
<div class="gmail_default" style=""><font
style="color:rgb(0,0,255)" face="arial, helvetica,
sans-serif"><br>
</font></div>
<div class="gmail_default" style=""><font
style="color:rgb(0,0,255)" face="arial, helvetica,
sans-serif"><br>
</font></div>
<br>
</div>
</div>
</div>
<div hspace="streak-pt-mark" style="max-height:1px"><img
moz-do-not-send="true" alt=""
style="width:0px;max-height:0px;overflow:hidden"
src="https://mailfoogae.appspot.com/t?sender=aY2xlbWNAY2NjLmNvbQ%3D%3D&type=zerocontent&guid=15f365c0-9308-4b29-b13c-6b3d6d0d42df"><font
color="#ffffff" size="1">ᐧ</font></div>
</blockquote>
<br>
</body>
</html>