Hi Andras, Andras Farkas wrote on Tue, May 19, 2020 at 05:26:24PM -0400: > On Mon, May 18, 2020 at 2:59 PM Ingo Schwarze <schwa...@usta.de> wrote:
>> Can somebody work through the tutorial and confirm that everything >> still works as described with our -current vi(1)? It is too >> wordy for my personal taste, so i would hate having to read it all. > I can do this. I'll begin sometime this week, and send a report on > it, and a diff too if necessary. I'd love to see it included. > :D Good, i'll just wait for your results. > In general: man pages are reference material Yes. > (meant for people who are already familiar with unix or with the man > page's topic, I disagree with your definition of "reference manual". A reference manual is simply documentation of a tool that is complete, precise, concise, and organized according to the inner logic of the tool. Whether the reader is already familiar with the topic has nothing to do with it. Which preliminary knowledge is already needed to even start contemplating a topic has nothing to do with it either. You can't use the vi(1) tutorial either unless you already know what these terms refer to: a directory, a file, a text file, a shell, ... When i want to learn about a completely new tool, i usually strongly prefer a good reference manual over a good user manual (i.e. an incomplete manual trying to use simplified terms and to provide simplified but longer explanations, organized according to didactial considerations) over a good tutotial (and often i even prefer a mediocre reference manual over good documentation of any other kind). In user manuals and tutorials, i rarely read more than the section titles. Reading those titles is occasionally useful to understand what the software authors consider most relevant for beginners. Reading substantial amounts of text in a user manual or tutorial usually feels like a waste of time to me. If i need the tool just once, there is just too much text in non-reference documentation, and the relevant bits are harder to find. If i potentially want to use the tool often, sooner or later, i have to read the reference manual anyway, so again no point to additionally read user manuals or tutorials, which are often longer. (I realise this in part involves personal learning style, people who like tutorials and user manuals do exist, but i guess they are less common among OpenBSD users than elsewhere.) > often not meant to be read cover to cover, Most of our reference manuals = manual pages are well suited to being read from cover to cover, and using them that way is definitely encouraged. There are some rare exceptions, though, for example perlfunc(1) and openssl(1). (To avoid misunderstanding, of course they are also well-suited to looking up particular details you aren't sure you remember correctly.) > definitely doesn't hold your hand) When needed, they most definitely do hand-holding. For example, look at https://man.openbsd.org/httpd.conf#EXAMPLES Often, hand-holding just wouldn't be useful: https://man.openbsd.org/true > a considerable amount of the documentation (though certainly not all!) > in /usr/src is tutorial material (meant for learning something for the > first time, easily read cover to cover, holds your hand) usable by newbs. If they are correct and work with the current code, tutorials are appropriate for installation in /usr/share/doc/ - like the mg(1) tutorial which is already installed there. Completeness is irrelevant for tutorials. If there are few tutorials there, that's likely because OpenBSD developers were less eager to spend time on them than they were about spending time elsewhere, and nobody else jumped in either. We don't want user manuals in OpenBSD because we can't afford the extra maintenance effort. Even for a bloody beginner, an outdated or inaccurate user manual is much worse than a good reference manual. Yours, Ingo
