FreeBSD Handbook Gets a New Layout

Erichans

Active Member

Reaction score: 128
Messages: 143

[...] 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?
 

tgl

Active Member

Reaction score: 40
Messages: 105


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:

 

grahamperrin

Son of Beastie

Reaction score: 1,050
Messages: 3,528

… 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.
 

Beastie7

Aspiring Daemon

Reaction score: 652
Messages: 739

It'd be nice if we could somehow hide both the table of contents and the left side bar for more text real estate. That's one of the things I miss about the classic handbook.
 

kpedersen

Son of Beastie

Reaction score: 2,248
Messages: 3,076

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.
 

tgl

Active Member

Reaction score: 40
Messages: 105

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... 🤔
 

grahamperrin

Son of Beastie

Reaction score: 1,050
Messages: 3,528

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
 

kpedersen

Son of Beastie

Reaction score: 2,248
Messages: 3,076

grahamperrin

Son of Beastie

Reaction score: 1,050
Messages: 3,528

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
 

Terry_Kennedy

Aspiring Daemon

Reaction score: 351
Messages: 984

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".
 

kpedersen

Son of Beastie

Reaction score: 2,248
Messages: 3,076

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.
 

Terry_Kennedy

Aspiring Daemon

Reaction score: 351
Messages: 984

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
 
Top