Hi Andras, Andras Farkas wrote on Mon, May 18, 2020 at 01:07:36PM -0400:
> Lots of documentation is unavailable outside of the /usr/src tree. It isn't "lots", it's only a tiny number of documents. > that the answers could be found in > Fsck_ffs - The UNIX File System Check Program > This is perfectly fine. Not really. If it's reference documentation, it would be better to have it in the manual page. Of course, in some cases, whether some piece of information should be part of the reference documentation or whether it is theoretical background that would exceed the scope of documentation and be more adequately explained in a research paper may be a matter of debate. Explaining the meaning of messages that are displayed to the user is, IMHO, usually in scope for documentation, unless the meaning of these messages is totally obvious in the first place. > https://cvsweb.openbsd.org/cgi-bin/cvsweb/src/sbin/fsck_ffs/SMM.doc/ The ancient non-manual-page roff(7) documents were sacrificed a decade ago because: (1) We want the base system self-contained, and keeping groff - which is piece of GNU "C with classes" software - in base just to format a handful of historical documents felt excessive. Similarly, writing an -ms input mode for mandoc - which would cause a few weeks of work, and add probably a few thousand lines of code to the tree - also felt excessive for such a small set of documents: nobody has been writing new documentation in -ms or -me or even -mm for decades. [kettenis@ did say that he'd appreciate a BSD-licensed roff in base, but that would cause even more work, so nobody tackled that, either. The licensing of the main modern roff implementations (and even those unmaintained historical ones that i'm aware of) is non-free: groff is GPL (viral), Heirloom and Solaris 10 troff are both CDDL (viral), Plan9 is Lucent Public License (polluted by verbiage about patents and explicitly asserting U.S. law), DWB is Eclipse Public License (viral).] (2) While no one denies that some parts of these ancient documents can occasionally still be useful, many parts are probably outdated since they haven't been maintained for deacdes. No one volunteered so far to check their content and properly add those parts that still apply to the respective manual pages. (3) Since they are unmaintained anyway, pointing to old copies on the web is not that much worse than having them installed, in this special case. Of course, having the content installed would be even better, but it's not trivial to achieve. > This is a situation I occasionally run into, where useful > documentation isn't included with OpenBSD, nor is available on > OpenBSD's website (FAQ, etc). It's occasional, but it's frustrating > every time. > > Not only are the USD, PSD, and SMM missing, but other bits of info > often are, too. In such cases, as an immediate measure to improve the situation, please submit a patch to the SEE ALSO section of the respective manual page. I'd consider it a documnetation bug if a useful supplemental document exists, no matter whether in the tree or elsewehere, but isn't mentioned. > 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. 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. Yours, Ingo
