FreeBSD Handbook Gets a New Layout

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.
 
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.
 
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.
 
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...
 
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!
 
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.
 
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.
 
<{link removed}> is more intuitive for archive and legacy documentation ☑ than <{link removed}>.

forums.freebsd.org

Solved - Version-specific editions of the FreeBSD Handbook

en English: 12.3-RELEASE 13.0-RELEASE 13.1-RELEASE CURRENT From : … documentation on our web site is mostly for -current, the state of the art of the code base. …
forums.freebsd.org forums.freebsd.org

bakul said:
… asciidoc is far easier to use. …
Click to expand...

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

1639792285723.png


ipsum said:
line-height should be carefully adjusted. To much vertical white-space, for me.
Click to expand...

Agreed. If you'd like to share an improved style, I might use it (with e.g. Stylus).
 
Last edited:
<{link removed}> describes some other issues relating to the new layout. In reply, there's an acknowledgement from Sergio Carlavilla.

Are any other new bugs noticeable, in the documentation area, as a result of the new layout?

Thanks
 
Last edited:
Thanks jbodenmann, I might never have found that. (I use an advanced preference {link removed} to prevent unwanted theming of content with Firefox 95.)

For diagnosis:
  • FreeBSD documentation does not darken, for me, with layout.css.prefers-color-scheme.content-override 0
  • is that something other than Firefox in your screenshot, or Dark Reader, maybe?

jbodenmann said:
… already mentioned/reported …
Click to expand...

For anyone who's interested: a list of Documentation bugs {link removed}.
 
Last edited:
You must log in or register to reply here.
Back
Top