FreeBSD Handbook Gets a New Layout

[...] It is difficult finding topics if you don't know or don't remember where those belong to...
I agree.

The handbook is most likely to be used by newcomers, even the ones that aren't tech savvy, these solutions are counter-intuitives for the majorities: [...]
As to the handbook users: you might be surprised there. The handbook is not only a user guide but also a reference. Perhaps you are thinking of not-new users that predominantly consult man pages: a lot of users—also experienced ones—will find this "ultimate reference" not always as easy an introduction or reference to an unknown or lesser known subject of FreeBSD. FreeBSD is big, so is it documentation. For very few it is something that is used or studied from "cover to cover" so to speak. Although IMO it pays off if you read it, at least loosely, once in its entirety to get the lay of the land. In time new subjects of interest arise: the handbook provides an easy starting point for that or for other sources of information.
The handbook is most likely to be used by newcomers, even the ones that aren't tech savvy, these solutions are counter-intuitives for the majorities:

A search field above the left TOC will greatly improve the UI/UX, making the content easily skimming.
In my experience a search field or search box is mainly being used to search the (entire) website to which the page belongs and will do nothing more than a simple text search (=verbatim search). Therefore, I'm curious:
  • What kind of functionality do you have in mind for such a "search field above the left TOC"?
  • Do you have any examples of such an implementation at other websites?
 

A simple search field on top of the left TOC to skim it, would be a great enhancement; while an "advanced search" in the same field might be just a link to whole website search function.

However the single html page looks broken because when you click any links rather than scrolling up and down the whole documentation it opens the link the split version.

This an example of documentation with a search function:

 
… IMO it pays off if you read it, at least loosely, once in its entirety to get the lay of the land. …

Keyword: loosely and for me, that means ignoring huge parts because they're non-intelligible to me, historic or entirely irrelevant. Reading and misunderstanding a mass is more harmful than reading and understanding bite-sized pieces of information that are well-organised.

To be a regular user of the major Unix OSes (FreeBSD and Linux, at least), you really don't need any programming skills, just a little bit of common sense for reading the manuals.

True, where the common sense is to not read the parts that make no sense to the reader ;-)

an example of documentation with a search function:

Nice.

Another comparison

Representation of manual pages in OpenZFS documentation.

<https://openzfs.github.io/openzfs-docs/man/7/zfsconcepts.7.html>, for example:

That was focused on a manual page. Less specifically:

OpenZFS documentation

I'm always pleased by pages that have the Sphinx credit.
 
Keyword: loosely and for me, that means ignoring huge parts because they're non-intelligible to me, historic or entirely irrelevant.
There is lots of documentation in this world that I don't understand. It doesn't mean that it probably shouldn't exist. I don't think my mother would understand much of the FreeBSD handbook either.

Historic information can be useful since FreeBSD does build on decades of work. Perhaps like the OpenGL RedBook, it can be marked as historic. I haven't really come across something that is 100% irrelevant.
 
Looking for some info on how tuning SSD disk I just realized the documentation page doesn't have any search function at all...
If at least would have the same nav-bar as the home page... I get it that is under construction but like this looks completely detached by whole website... 🤔
 
all font awesome intended glyphs don't render properly (use inter font)

Fixed:

1642292759949.png

– the book menu icon, and the eight types of icon at pages such as this:

<https://docs.freebsd.org/en/books/handbook/bsdinstall/>
  • edit
  • important
  • next
  • note
  • previous
  • tip
  • top
  • warning
 
Is there an option to generate the documentation using the old style? Then one could build the documentation locally, if one wants to.

Styles aside, for a moment: if you need it, <https://docs.freebsd.org/en/books/fdp-primer/doc-build/#doc-build-rendering-html> is for rendering to HTML, which I did during a recent pull request. That is, more broadly, part of Chapter 5. The FreeBSD Documentation Build Process (but I don't recall needing the entire chapter).

giorgiob also if you like I can share with you some rough notes to self (thanks to someone in GitHub) that helped me to get started quickly.

<https://github.com/freebsd/freebsd-doc/commit/2b027dd0175e739f8b5fedd2ae6bd96cf0c14125> (2021-12-11) was a milestone New Documentation Portal however I can't tell where styles are, if anywhere, on the timeline.

You might like to ask in IRC, although the room seemed quite quiet when I was last there; maybe better to address the e-mail list.

PS more simply, I use the installed long HTML and PDF versions, although I haven't looked closely to see whether they're recently updated.

HTH
 
Not quite what you are looking for but there is a plain text version of the handbook here:

https://download.freebsd.org/doc/en/books/handbook/book.txt.bz2 (and should be on the disk)
Did you see the timestamp on that file? 2021-Jan-24 06:33, confirmed by checking the internal creation timestamp of the PDF version.

The downloadable documentation has been getting stale for nearly a year. Way-back-when I had a discussion with someone involved and the info I got was "toolchain issues - we're working on it".
 
Did you see the timestamp on that file? 2021-Jan-24 06:33, confirmed by checking the internal creation timestamp of the PDF version.

The downloadable documentation has been getting stale for nearly a year. Way-back-when I had a discussion with someone involved and the info I got was "toolchain issues - we're working on it".
Indeed. We should focus less with the web docs and focus more on the offline docs. Though I predict more people are interested in a volatile Arch Linux style wiki than classic stable offline .txt files.

Besides, has there really been big changes since Jan 2021? I don't see anything in there being out of date.
 
Besides, has there really been big changes since Jan 2021? I don't see anything in there being out of date.
Yes. As a major example, there are 25 instances of # mergemaster and 0 of # etcupdate.

I sent the following to freebsd-doc@ back in June 2021. Hopefully these suggestions are being / will be considered for future Handbook editions.
Code:
  In https://tinyurl.com/45wtwnby (and surrounding replies) I noted that
the official PDF version of the FreeBSD Handbook from:
https://download.freebsd.org/ftp/doc/en/books/handbook/book.pdf
is the version from January 23, 2001. Of relevance to that particular
forum discussion, the PDF version of the Handbook still refers to using
mergemaster, while the HTML version of the Handbook uses etcupdate.

  Looking at other various languages (I checked DE, ES and FR) they all
have dates from late January. It appears that whatever system is used to 
re-generate the downloadable Handbook variants has been broken since
late January.

  In addition, while researching this I have discovered 2 other issues
which the Documentation Project might want to address:

  1) The tree that is apparently the "definitive version" of the Handbook
     at https://docs.freebsd.org/en/books/handbook/ does not include any
     date or version information other than a copyright date. That makes
     it impossible to tell what version is being viewed. I suggest that
     the same text that appears in the hardcopy edition, namely:

        FreeBSD Handbook
        Revision: 0d4371e5cc
        2021-01-18 18:33:37 +0100 by Fernando Apesteguma.

     (auto-updated as appropriate) appear in the online edition as well.

  2) Any downloadable / printable versions of the handbook should contain
     something like the following text:

        The FreeBSD Handbook is a living document. By definition, down-
        loaded or printed editions will soon be out-of-date. Please refer
        to https://docs.freebsd.org/en/books/handbook/ (for the online
        edition) or https://download.freebsd.org/ftp/doc/ (for download-
        able editions) to obtain the latest version.

        Thanks for your time,
        Terry Kennedy     http://www.glaver.org      New York, NY USA
 
To have the table of content in a separate frame makes the navigation easier, at least in my opinion.

Thank you to the docs team for the improvement!

Wow, I just noticed this change.

The Handbook is so much easier to navigate and find answers to things that stump me!

Many thanks to the doc team for this significant upgrade.
 
So, after reading all the posts. The remaining things are:

  1. Allow to collapse the menu book and the "Table of Contents". Like Gitlab, for example. -> I'll try to do this without Javascript, using only HTML/CSS. I think I can get this using transitions.
  2. Add more resources to the resources section, like pdf, long html, etc
  3. Search in the book menu to filter chapters
  4. An index per book
  5. Change gray font color to white
  6. Increase the font size in the ToCs
  7. Improve the separation between the books menu and the rest of the page. Like https://doc.rust-lang.org/cargo/index.html <- This was requested by email.
 
freezr The Handbook covers FreeBSD and how it works. FAT32 is a third-party filesystem not native to BSD.

using four commands to format a USB Pendrive looks a little bit cumbersome

FreeBSD has the flexibility to do a lot of things Windows can't do. Just try and format a pendrive with UFS in one command on Windows or FAT32 on Linux while keeping the flexibility to do other filesystems.
 
Also using four commands to format a USB Pendrive looks a little bit cumbersome... 🤨
I think it is similar on Linux (fdisk) and Windows (diskpart), just using an interactive mode which I don't think gpart has:
Code:
> diskpart
  select disk 1
  clean
  create partition primary
  format /FS:FAT32 /Q

In either case, including on *BSD, I do it infrequently enough that I pretty much need to look it up each time! I do recommend writing a quick shell script to do it for you.
 
Back
Top