FreeBSD Handbook Gets a New Layout

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

tgl said:
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: [...]
Click to expand...
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.
tgl said:
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.
Click to expand...
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?
 
Erichans said:
I agree.
Click to expand...

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:

Search - Blender 4.3 Manual

docs.blender.org docs.blender.org
 
Erichans said:
… IMO it pays off if you read it, at least loosely, once in its entirety to get the lay of the land. …
Click to expand...

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.

chungy said:
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.
Click to expand...

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

tgl said:
an example of documentation with a search function:
Click to expand...

Nice.

grahamperrin said:
Another comparison

Representation of manual pages in OpenZFS documentation.

<{link removed}>, for example:
Click to expand...

That was focused on a manual page. Less specifically:

OpenZFS documentation {link removed}

I'm always pleased by pages that have the Sphinx credit {link removed}.
 
Last edited:
grahamperrin said:
Keyword: loosely and for me, that means ignoring huge parts because they're non-intelligible to me, historic or entirely irrelevant.
Click to expand...
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... ?
 
covacat said:
all font awesome intended glyphs don't render properly (use inter font)
Click to expand...

Fixed {link removed}:

1642292759949.png

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

<{link removed}>
  • edit
  • important
  • next
  • note
  • previous
  • tip
  • top
  • warning
 
Last edited:
giorgiob said:
Is there an option to generate the documentation using the old style? Then one could build the documentation locally, if one wants to.
Click to expand...

Styles aside, for a moment: if you need it, <{link removed}> is for rendering to HTML, which I did during a recent pull request. That is, more broadly, part of {link removed} (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.

<{link removed}> (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
 
Last edited:
kpedersen said:
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)
Click to expand...
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".
 
Terry_Kennedy said:
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".
Click to expand...
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.
 
kpedersen said:
Besides, has there really been big changes since Jan 2021? I don't see anything in there being out of date.
Click to expand...
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
 
chrbr said:
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!
Click to expand...

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.
 
A few FreeBSD bugs:
  • {link removed} maybe fixed confirmed fixed
  • {link removed}
  • {link removed}
  • {link removed}
  • {link removed}
  • {link removed} with reference to <https://forums.freebsd.org/posts/549007> on page 2 of this topic
  • {link removed}
  • {link removed}
The closest I could find to 262228 in the context of the FreeBSD Handbook was long HTML <{link removed}>, where the table is wide, but generally OK in both HTML and PDF.

Nearby <{link removed}> sometimes goes bonkers with a fall to the foot of the book in response to me manually resizing the window in Firefox:

1646142366104.png

– however this is not consistently reproducible; maybe an issue with my heavily-extended default profile for Firefox.
 
Last edited:
freezr said:
… basic HMTL … tested … with Netsurf …
Click to expand...

Thanks to freezr, browsing with NetSurf helped to reveal an accessibility issue.

FreeBSD bug {link removed}


With NetSurf, the bug is clear. The table of contents of the FreeBSD Handbook falls below the book's footnotes:

1647684800632.png

Without NetSurf, here's the bug in Firefox (looping animated GIF, note the responses to the Tab key):

2022-03-19 09-36.gif
 
Last edited:
freezr The Handbook covers FreeBSD and how it works. FAT32 is a third-party filesystem not native to BSD.

freezr said:
using four commands to format a USB Pendrive looks a little bit cumbersome
Click to expand...

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.
 
freezr said:
Also using four commands to format a USB Pendrive looks a little bit cumbersome... ?
Click to expand...
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.
 
You must log in or register to reply here.
Back
Top