How good is OpenBSD Documentation, actually?
ฝัง
- เผยแพร่เมื่อ 28 ส.ค. 2024
- People on the Internet will often talk about how "good" the documentation is on OpenBSD. But is this true? And what does it actually mean? In this video look at a few manuals and try to answer this question.
![[UNCUT] The Loyal Pin ปิ่นภักดิ์ EP.4 (4/4)](http://i.ytimg.com/vi/d3l5rxl5CVo/mqdefault.jpg)
I find OpenBSD to be beautifully simple. I get the impression that it will always stay that way. I will always love Debian; I just got curious about the BSDs.
I only use Debian Sid to play games. Otherwise I’d run FreeBSD full time on my desktop, like my laptop.
online documentation is another area worth considering. if we compare the faq to the debian/ubuntu/whatever wikis, it seems like most useful linux documentation is found in third party blog posts or stackexchange-type discussion boards. openbsd's official stuff is a lot better there too (and never has outdated info like many linux findings from even a few years back tend to do).
The out-of-date thing is something I didn't think of mentioning, but probably should have. Man pages ship with your software, so the documentation you are reading is definitely the documentation for the software version you are using. When you search stuff online for Linux, it's easy to mess up and read information that is outdated, or sometimes too up to date. That's another big advantage to having solid man pages.
I think it's time we move manuals to something other than roff. It isn't easy to find information because man pages are just a wall of text. HTML documents can contain links and a table of contents. I'm not going to argue for HTML, I just feel like we could do better in the 21st century
@@adammontgomery7980I mean there's also GNU info, which has hyperlinks
I am sorry but I can not find the source of what I am about to write. It was either Richard Stallman's talk or a random post on the internet about "Why the GNU code is so verbose?" (verbose as in "bloat").
It is because we take everything for granted now. We can create a piece of code, license it as free and open source and there are no problems.
But back in the days, when everything was proprietary, GNU had to work extra hard to not get sued.
If GNU made a simple copy of a BSD program, BSD could say "Now, wait a minute. That's basically our code!".
GNU had to make everything very, very verbose. They put a lot of comments in the code, so that if someone compares... let's say "cd" in BSD and "cd" in GNU, there is no doubt that this is NOT THE SAME code.
They had to make programs function the same way, but they could not make them in the same way.
I would assume it applies both to source code and to the man pages.
Now, there are projects like ToyBox (Which I really like btw) that do everything in a minimalistic way.
A ToyBox function program can be few lines of code while the GNU equivalent is 100's lines of code.
But we must not forget that the times are extremely different.
If ToyBox was released back in the days when proprietary ruled the world, it would get (most probably) sued.
If anyone has a link do this talk or a link to a forum post, it would be nice to have it.
------------
As of the documentation, I really like the "Example" section in OpenBSD.
(Partly because of the reason mentioned above) Information/Content ratio in OpenBSD is better than GNU.
That being said, I do not know why the GNU man is so verbose. The man (in my opinion) should be kept small and on-point. More verbose version should be (and probably is) placed in "info".
The OpenBSD man is more "handy" because OpenBSD is created by people who use OpenBSD. They make it good so that they can use it.
While Linux is created by people who give a talk in a conference using a Mac.
I actually read someone saying something similar a while back regarding GNU utilities--I think it was GNU true in particular. Where they wrote it far more verbosely to get around potential code similarity issues.
My assumption regarding the documentation differences is that its a cultural thing. On the GNU side of things, people are far more likely to go right to the Internet and bypass the manual, so there isn't much incentive to improve the manual. I know that's what I did for the longest time--and I'm sure I'm not alone in that.
And you're definitely right regarding OpenBSD and it being obviously used by the people that work on it. I always find it amusing how it has the reputation of being harder to set up as a desktop vs. FreeBSD, when my experience has always been the exact opposite. FreeBSD is definitely better in terms of performance and compatibility, but I've always found OpenBSD to be more-or-less plug and play--at least on supported hardware.
That last paragraph. I died laughing.
> If GNU made a simple copy of a BSD program, BSD could say "Now, wait a minute. That's basically our code!".
It happens sometimes, and BSD can do nothing, cause you can relicense the file under GPL, or something like that, but then BSD guys cannot edit it, without using GPL. Funny trolling.
But beside that If I remember correctly GNU existed before any of BSDs. So it's wasn't really a problem for them. BSD got sued, because they used direct copy of bell labs code.
> The OpenBSD man is more "handy" because OpenBSD is created by people who use OpenBSD. They make it good so that they can use it.While Linux is created by people who give a talk in a conference using a Mac.
I guess it's opposite. OpenBSD isn't really good for desktop. It's usually the BSD guys who run macOS because it has some BSD code in it, while Linux guys can run linux on laptops and make presentations.
I think that if you open a issue about the tar(1) don't have a example on extracting a file, the OBSD guys would fix that pretty quickly.
I didn't open an issue, but I just got an email from somebody who did. There's an examples section in there now,
man.openbsd.org/tar
I'm very new to OpenBSD, but my impression that main difference between GNU/Linux and OpenBSD documenting approach is that OpenBSD tries to have man-pages for all parts of the system. For example, OpenBSD has man pages for drivers and GNU/Linux mostly for userland programs only.
Interesting comparison, thank you for sharing, I love Debian and OpenBSD both are great !!
I agree. I've been having a lot of fun with both of them.
Don't for get about the"--help" option after a command. If I can't figure it out the command from this, I check the man page. It does show an example for extracting from tar on my Rocky VM and one for Open/FreeBSD.
This conversion reminds me of a quote I read from Doug McIlroy, known for unix pipelines:
Everything was small... and my heart sinks for Linux when I see the size of it. [...] The manual page, which really used to be a manual page, is now a small volume, with a thousand options... We used to sit around in the Unix Room saying, 'What can we throw out? Why is there this option?' It's often because there is some deficiency in the basic design - you didn't really hit the right design point. Instead of adding an option, think about what was forcing you to add that option.
A lot of documentation is like that(looking at you MSFT). All that extra advanced info is nice but i just want to know how to use the bloody software.
shift+g should take you to the bottom of the man page, assuming it’s using the default pager (often that’s `less`)
I prefer the way the BSD docs provide all the optional flags in a single block. Much easier to parse than the GNU approach.
What might be more useful than this is comparing the BSDs to each other, as a lifelong Linux user looking at BSDs, I'm unsure of which to switch to for my use cases. Additionally I find myself 'stuck' with Linux for certain software packages and ease of use for development as that's just what I'm used to. I try to write stuff that's platform agnostic as much as possible however. Anyway, OpenBSD vs. FreeBSD vs. DragonFly BSD vs. NetBSD documentation shootout!
That's a really interesting idea actually. I'd need to spend some time thinking about standards for actually evaluating documentation first.
@@DouglasRumbaugh we have four bsd's mind you and it would be even better if you could compare illumos too...
Yeah I just don't think there is enough critical mass for BSD to sleep on it's docs. Linux has at least a dozen comments under a blog post for how to do x y or z and one of those comments is like "this guide used to work but dependency Charlie changed it's api, use this command instead" and you can't get that with BSD. Not always. Idk. I wish there was a big player that pushed BSD instead of suse and that hat company.
@@paulgupta2454As far as openbsd goes, I think that's kind of the point in some ways. Like a by hackers for hackers kind of thing. Thats the vibe I get with openbsd docs in general. which I kind of appreciate in comparison to the clusterfuck of present day linux/gnu. maybe im wrong.
Regarding man page line length, this is one thing I really hate. I'm just trying to get information quickly, solve a problem and move on. I'm not trying to get my PhD in the tar command. What is wrong with these people.
zero mention of "man afterboot"...
Just reading the top of both manuals as you were talking, the open BSD gets right to the point and the Debian manual is mind numbing. The Debian man looks like the kind of thing I would not read and would not be useful to me.
10:52 He says there are no examples at all, and that's true cuz they aren't in the man page, lol. At 10:10 in the video, there is a frame that actually shows this too, but he scrolled right past it too fast. This manpage is a short description of GNU tar. For a detailed discussion, including examples and usage recommendations, refer to the GNU Tar Manual available in texinfo format. If the info reader and the tar documentation are properly installed on your system, the command
info tar
should give you access to the complete manual.
He didn't "scroll right past it too fast," he talked about it and even tried running the command but `info` wasn't installed on his system. You're trying way too hard to gaslight in order to defend what is, for any practical purpose, a subpar man page.
Even if an argument could be made that for GNU utilities `info` should be used by default, that manual is still obscenely verbose and doesn't change the fact that it's a big part of the reason why Linux users often rather turn to online tutorials.
Thanks DeVelox--I was going to respond with something similar, but decided I couldn't be bothered.
I do understand the argument that there are different ways of documenting software, and info is just one of them. But from a usability standpoint, I've always found info to be far more of a hassle to use than man, so I tend to avoid it. Providing full documentation in info is fine, but I think the "brief" overview in the man page should include common examples; that is where most people turn first. If anything, having the full manual in info should allow for even better man pages, because they don't need to be comprehensive.
I have been unable to navigate the info manuals. I always end up exiting the program and starting over. It is very difficult to move through information with info.
@@manueljoseblancamolinos8582 i just tried info for the first time ever (not a fan of emacs-style stuff). It tells you on the bottom when open an info page that there is a guided tutorial which seems pretty good if you want to have a look at it.
@@manueljoseblancamolinos8582 this might be because the info system uses a completely different approach to man, and the man page for info doesn't tell you how to use info. When you run info it mentions a tutorial on the default page but that page can be overwhelming for new users.