<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 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 face="arial, helvetica, sans-serif" style="color:rgb(0,0,255)">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 color="#0000ff" style="font-family:Arial,Helvetica,sans-serif">built<font face="arial, helvetica, sans-serif"> </font></font><font face="arial, helvetica, sans-serif" style="color:rgb(0,0,255)">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 color="#0000ff" style="font-family:Arial,Helvetica,sans-serif"><font face="arial, helvetica, sans-serif"> </font>reference</font><font face="arial, helvetica, sans-serif" style="color:rgb(0,0,255)"> 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 face="arial, helvetica, sans-serif" style="color:rgb(0,0,255)">  </font></div><div class="gmail_default" style=""><font face="arial, helvetica, sans-serif" style="color:rgb(0,0,255)"><br></font></div><div class="gmail_default" style=""><font face="arial, helvetica, sans-serif" style="color:rgb(0,0,255)">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 face="arial, helvetica, sans-serif" style="color:rgb(0,0,255)"><br></font></div><div class="gmail_default" style=""><font color="#0000ff"><font face="arial, helvetica, sans-serif" style="">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 face="arial, helvetica, sans-serif" style="color:rgb(0,0,255)"><br></font></div><div class="gmail_default" style=""><font face="arial, helvetica, sans-serif" style="color:rgb(0,0,255)"><br></font></div><br></div></div></div><div hspace="streak-pt-mark" style="max-height:1px"><img 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>