First of all, I'd like to thank everyone who replied to me! Thank you for explaining things.
On Mon, May 18, 2020 at 2:59 PM Ingo Schwarze <schwa...@usta.de> wrote: > Andras Farkas wrote on Mon, May 18, 2020 at 01:07:36PM -0400: > > For example, I first learnt vi a few years ago, back > > when I was first learning Unix, with these files: > > https://cvsweb.openbsd.org/src/usr.bin/vi/docs/tutorial/ > > Hum, looks like a reference to those files is indeed missing > from the manual page. > > Also, i don't see what would be wrong with installing them to > /usr/share/doc/vi/tutorial/ > Yes, the tutorial is painfully slow and extremely wordy, and some > parts are hilariously antiquated, like this: > "Learning a new computer system implies learning a new text editor." > That wasn't even accurate at the time it was presumably written, > probably around 4.4BSD (i.e. almost 30 years ago). It may have > been more or less true 40 years ago, though. I'd say that sentence still contains some truth: when someone's trying out OpenBSD as a desktop OS when they've only used Windows as a desktop OS before... > 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 On Mon, May 18, 2020 at 3:01 PM Marc Espie <es...@nerim.net> wrote: > On Mon, May 18, 2020 at 01:07:36PM -0400, Andras Farkas wrote: > > I saw in fsck_ffs.8 > > https://man.openbsd.org/fsck_ffs.8 > > that the answers could be found in > > Fsck_ffs - The UNIX File System Check Program > > This is perfectly fine. Not every piece of information belongs in a > > man page. Man pages are the right format for some sorts of info, and > > absolutely the wrong format for some other sorts. > > BUT: I looked and couldn't find it, and ended up using > > https://docs.freebsd.org/44doc/smm/03.fsck/paper.pdf > > which is where I found my answer. > > Only after I already solved the problem did I find that the mentioned > > file exists here: > > https://cvsweb.openbsd.org/cgi-bin/cvsweb/src/sbin/fsck_ffs/SMM.doc/ > Most of these files haven't been updated in ages. That is true, and important. > Seriously, *none* of those files are necessary *for beginners*. Once you > reach the stage where you might benefit from them (say, because you actually > want to become a developer, and could learn from worse sources), you should > be able to figure out how to get them. I disagree. In general: man pages are reference material (meant for people who are already familiar with unix or with the man page's topic, often not meant to be read cover to cover, definitely doesn't hold your hand) and in contrast, 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. Examples supporting this comparison: man 1 ed versus the Brian W. Kernighan "A Tutorial Introduction to the UNIX Text Editor" man 1 yacc versus the Stephen C. Johnson Yacc "Yacc: Yet Another Compiler-Compiler" man 1 vi versus vi.beginner (though indeed, vi.1 has the Fast Startup section, vi.1 is an exception rather than the norm) Just looking at a list of BSD USD (UNIX User's Supplementary Documents) documents or Unix v7 supplementary documents (The UNIX Programmer's Manual volume 2) can provide more examples. Some of them don't particularly have a man page they match up to, by being broader and more newb-oriented in theme. The only point against this, though a BIG and important one, is that the datedness of the tutorial materials does make them less usable for newbs. I agree much of the stuff is outdated and less usable than it used to be. I also think having it with a disclaimer is better than not having it at all. Ideally... I myself should put in effort into checking some of them and fixing and updating them. Also: I do like OpenBSD's man pages and FAQ! Don't let anything I've said above convince you otherwise. I use them a lot and appreciate them. Thanks so much, everybody.
