FreeBSD Handbook Gets a New Layout


Son of Beastie

Reaction score: 2,518
Messages: 3,382

Noticed that last night. I had to update my /etc/pf.conf (which was last done ~5 years ago), and that required actually reading the documentation, and the new look of the handbook surprised me. It was a pleasant surprise, it is quite readable.


Active Member

Reaction score: 77
Messages: 169

I'll be damned. That section on pf is brand new to me. When I started working with pf, OpenBSD was the documentation source I fell back on.



Reaction score: 16
Messages: 30

I'd prefer it if the banner scrolled off the top and didn't waste the limited vertical space on my laptop. We can't all have nice large hi-res laptop screens. We pretty much all have wider screens these days but web designers still design for taller, narrower screens such as 4:3 CRTs If deigners want stuff to stay on the screen while we scroll, put it down the side, not across the top.

On a similar note, there doesn't seem to be a way to uncollapse the whole table of contents, making it harder when just having a browse for new sections/subsections or a specific topic. Ditto on a phone screen. The collapsed table of contents takes a lot more navigation time whereas a full expanded list is easy to scroll through quickly.

Other than that, yes, it feels more readable.


Well-Known Member

Reaction score: 285
Messages: 306

I agree: why such a fat header bar? It's the same size as the one on this forum but here we have two lines in that space, and more elements in them... those only four links could go into a sidebar, or at least a much thinner bar.

As a whole, I liked the previous style better, but that's personal taste...


Aspiring Daemon

Reaction score: 320
Messages: 572

Looks are of course very subjective. Personally I mainly enjoy the table of content. That is really nice!
I also think that the "code snippets" look nicer now.

Thanks a lot to everybody involved in making this!


Son of Beastie

Reaction score: 2,507
Messages: 4,453

Not too many years ago, I talked to Warren about redoing the site cause, after all, that was the business I was running. But after all the warnings about how the pages were generated, I decided to not get involved.

Then, a few years ago, someone mentioned to me about getting involved. I even talked to the Foundation about getting funding but that was more than I cared to get into.

Finally, two years or so ago, someone pointed me to all the documentation and tools for working on it. I wish I was shown that originally. I installed everything, did some poking around, got excited but I can't say why I drifted away. It may have been something as simple as no one encouraging me. (I'm not blaming anyone.) Then my wife said, "You're not getting paid to do that!" which may have actually put the nail in the coffin.

So this popping up without notice makes me glad I didn't work on this on my own cause it might not have been finished. It also makes me sad and jealous cause I would have done much better. That said, I'd bet it's done by someone on the side--when they had spare time. So I cannot disparage it at all.


Active Member

Reaction score: 93
Messages: 164

Now they are using asciidoc for documentation "source" files. Previously they used sgml. asciidoc is far easier to use. I wish someone extends it to allow the use of [[some-file]] links -- what many apps using markdown format such as Obsidian, LogSeq etc. allow. They also create backlinks so that you can see what else refers to the current file. So for instance, the ls man page can say See Also: [[chflags]](1), ... and you could also see what other pages refer to the ls page.


Son of Beastie

Reaction score: 1,050
Messages: 3,528

<> is more intuitive for archive and legacy documentation ☑ than <>.

… asciidoc is far easier to use. …

I don't doubt it, but still, it turns me off:


line-height should be carefully adjusted. To much vertical white-space, for me.

Agreed. If you'd like to share an improved style, I might use it (with e.g. Stylus).


Son of Beastie

Reaction score: 1,050
Messages: 3,528