# Render FreeBSD Handbook using old style?



## blackhaz (Jul 14, 2022)

Is there any way I can get FreeBSD Handbook PDF (or, better, HTML) rendered using the old style? The new style is just unusable and killed the whole thing for me. :-(


----------



## SirDice (Jul 14, 2022)

With all the changes happening I don't know if this still works. But you can pull the documentation and build it in various other formats:









						Chapter 5. The FreeBSD Documentation Build Process
					

Describes the FreeBSD Documentation Build Process




					docs.freebsd.org


----------



## jbo (Jul 14, 2022)

blackhaz said:


> The new style is just unusable and killed the whole thing for me. :-(


If you can provide actual feedback / specific items one could discuss, review and potentially improve those.
To me, this seems similar to the "it's not working"-type of posts.


----------



## blackhaz (Jul 14, 2022)

I have provided them to Sergio before. I'll try to distill. 

1. Table of contents is separated in two panes on both sides of the main content. I think this is a harmful decision. The main content is just a single narrow column of text. This narrow column forces to split text into shorter and shorter paragraphs to remain readable, until each sentence ends up on its own paragraph. This is a booklet/brochure format. I don't think this is the right format for a book, as we are not trying to grab attention here. Design should disappear and let user do his stuff.

2. Table of contents should appear at one place - left-hand or at the top. It's really strange that you click on a topic in the left pane, and then an update happens on the right pane all the way across the main text, but the context for both panes is the same - providing user with a ToC. Also, the right pane is called "Table of Contents" but it's ToC for the current chapter only, not for the entire book. Then you have "Book chapters" on the left - is this the full ToC? (Should "chapters" be capitalized?) I very much prefer the old system with just one ToC at the beginning of the book, as in all the books we read, or ToCs appearing at the beginning of the chapters. 

3. I don't like complex CSS getting involved at all. The less CSS/JS, the better. I appreciated Handbook being a simple HTML. I hate when web pages begin to hide elements, or things begin to slide, fold and unfold, text moving on the screen, and so on. I am here to read the book, learn things and do my stuff in the other window. I would do everything as static as possible. The less the UI interferes with the reading process, the better. This includes the two ToC panes that are scrollable. It's like reading a book with inserts. 

4. Do we really need the "top" button at the bottom of the page? Why would want to clutter our screen with that button if there's a Home button on the keyboard? Are you optimizing for tablets and phones? But most mobile devices can scroll back to the top, at least iOS can. We don't need another element here.

5. Interline spacing is not for a book - too much space between lines. Is that 1.15 or 1.2? I'd go back to the old format. 

6. The font is gray - we are loosing contrast and straining eyes for no good reason. 

7. The font system doesn't match FreeBSD's web site. Is there a FreeBSD style book?

8. The hyperlinks are not underlined and are now more difficult to find and identify visually.

9. There should be vertical indent between paragraphs.

10. Random irrelevant italics. Quick example: paragraph 2.2. Architectures are in bold italics. I can understand bold here, but why italics? Although I'd make bold a little less pronounced. It really screams a headline where it shouldn't.

11. The code snippet background color, e.g. paragraph 4.3.1. It was a pleasant almond in the old book. Now the background is black. We are inverting from grey text on white all the way to white text on black. This strains eyes. I guess this was a simulation of a terminal window, but not all terminals are black. This inversion breaks the coherence IMHO.

12. Chapter/section/subseciton titles were dark red in the old book, which helped to "unglue" different subjects vertically, especially in a single HTML. Now they're all grey. There's a barely visible (actually to the point of irritation!) horizontal underlining in chapter titles, but as it's an underline it actually contributes to the vertical clutter.

13. Filenames were green in the old book, and now they are grey, but not only that - they're extremely bold. This one is controversial, but I really dislike jumping to that much bold in the main content - I think it interferes with attention and makes the text look incoherent, as bolded out filenames stand out from the rest of the text. With that much bold, and especially with main text being a subtle grey, filenames really grab too much attention and even compete with chapter titles.

14. Warning and note section titles are in the serif font. Why suddenly serif here - what is the reason? Don't get me wrong, I really like serif. I would switch FreeBSD all the way back to serif, I think it was pleasant for the eyes and easy to read.


----------



## SirDice (Jul 14, 2022)

grahamperrin@ was recently added to the documentation project. He'll know where you can send your suggestions to.


----------



## hbsd (Jul 14, 2022)

SirDice said:


> grahamperrin@ was recently added to the documentation project. He'll know where you can send your suggestions to.


I think he's gone from forum. I even messaged him but didn't get a reply.


----------



## chrbr (Jul 14, 2022)

Even FreeBSD contributors may have holidays, have to do business trips and so on. I do not hope so, but they might get sick as well as we mortals . Just wait one or two weeks.


----------



## priyadarshan (Jul 15, 2022)

blackhaz said:


> Is there any way I can get FreeBSD Handbook PDF (or, better, HTML) rendered using the old style? The new style is just unusable and killed the whole thing for me. :-(


blackhaz 

Thank you for opening this thread and also offering a very detailed information down the thread (#4). I always wanted to ask about it, and I could not have been more clear and precise.

To people like myself, who suffer from severe case of CVS (Computer Vision Syndrome), the current style is quite unusable, if not physically painful. To me at least, the earlier style was simply perfect. I understand the need for progress and change, I only wish there could be a switch "keep-readable" mode in the current documentation, without resorting to custom builds.

Thanks again.


----------



## Phishfry (Jul 15, 2022)

At least these changes have not hit the pdf version yet.


			https://download.freebsd.org/doc/en/books/handbook/handbook_en.pdf


----------



## Phishfry (Jul 15, 2022)

We have been mentally conditioned to ignore the right one third of screen due to ??? Spam?? Big media??
Google News. All the 'factchecking' on the right third.
Not really news but one third the screen.

It occurs all over the internets. I am not sure who is controlling it exactly.
It has now come to our glorious handbook.


----------



## drhowarddrfine (Jul 15, 2022)

Phishfry said:


> We have been mentally conditioned to ignore the right one third of screen due to ??? Spam?? Big media??


We read from left to right--at least most of us. When a paragraph ends, it ends our reading, so the rightmost side is left out to dry. (Or is that right out to dry?)
So the most important information should be on the left.

Yes, we have been conditioned to ignore ads on web page, not ignore ads and other garbage just because they're on the right hand side. There is a study about this somewhere.


----------



## Beastie7 (Jul 15, 2022)

I actually the prefer the classic version myself too. I like the visual hierarchy and max use of white space. That word wrapping nightmare on the Left side of the new version is just unappealing IMO.


----------



## zirias@ (Jul 15, 2022)

Let's start with the one thing I totally agree with: I really don't get what an additional ToC column on the right is supposed to buy you. It just irritates until you realize it repeats the ToC of the one chapter currently displayed.

But, in general, I'd say _having_ a ToC column at all really improves usability, so at least here's a clear plus for the new style.

About the width of the content column: IMHO, there should be a max width. Reading paragraphs gets harder the longer the lines are (cause moving the eye back to the left and hitting the next line correctly is getting more and more error-prone). There's a reason books are typically printed on smaller paper formats ... and newspapers use multi-column layouts.

The new style seems to use a single CSS breakpoint to hide both ToC columns at once. That's maybe not the best decision. Also, the content column gets ridiculously narrow before hitting this breakpoint. Yep, better rework that.

All the rest of complaints is more or less about visual style. While I'd also say I found the old style visually more appealing (is it just because I was used to it? not really sure...), you can't claim this new style wasn't clean and readable, that's really exaggerating things.


----------



## blackhaz (Jul 16, 2022)

I think this discussion, partially, is the consequence of horrible 16:9 screens optimized for movies. Zirias, do you run your browser window at full width?

Should we constrain users with the maximum column width? I don't think so. See the screenshot attached. On the left is the new Handbook, and on the right is the old one. The new style constrains the user. Why would a FreeBSD stylesheet allow somebody to force me their way to read content? 

I think this should be the function of the web browser window. Users should be able to set their own widths. The content should be optimized for a book, not a brochure. If I don't like the text width, I can narrow my browser. 

I keep my Firefox at 4/5th of the screen width - my keyboard shortcut to "centralize" windows sets them this way. All my working apps - LibreOffice, Thunderbird, terminal windows, file managers, etc - generally run at 4/5 width. I guess Apple has also scratched their heads on how to deal with the 16:9 issue, as their Maximize button in MacOS stopped stretching windows to full widths at some point. Sometimes I do maximize windows if I need zero distractions, but operating at 100% width on a 16:9 screen isn't optimal, and the text is generally going to be too wide. Fixing that with an artificial column width in the CSS is completely wrong, though.


----------



## zirias@ (Jul 16, 2022)

blackhaz said:


> Zirias, do you run your browser window at full width?


Ho do you get *that* weird idea? I said a max-width would make sense, and just never had my browser window wide enough to realize there actually *is* one (which is good, as explained above).


blackhaz said:


> I think this should be the function of the web browser window. Users should be able to set their own widths.


If by that, you mean the widths of text columns (exceeding a certain maximum), typographers will *strongly* disagree. Of course, it *would* be possible to make use of extra vertical space e.g. by switching to a two-column layout. But that would create other problems, cause you don't have classic paging in a browser, and scrolling through text columns is nonsense... So, it's common practice to use this space for whatever non-essential meta-info you could display there.


----------



## blackhaz (Jul 16, 2022)

Well, you're advocating for an artificial text width limit, so I thought the old Handbook was too wide for you. You can easily control it with your browser's width to your liking. Typographers would want fixed column width on print when the output format is fixed, and I agree with that. But with an online HTML version, that's a different case. Everyone has different monitors, at various distances, people have different eyesight, prefer different font sizes, and so on. Why rob users of their freedoms?

Also, I don't really need a book to display me "whatever" just because it's an empty space, in somebody's opinion. Every design decision should have practical application.


----------



## zirias@ (Jul 17, 2022)

Yep, I see you apply the strategy of just _ignoring_ the argument.


Zirias said:


> Reading paragraphs gets harder the longer the lines are (cause moving the eye back to the left and hitting the next line correctly is getting more and more error-prone).


This is actual fact. And it's taken into account by typographers, and "web designers" learned to take it into account as well. You'll rarely find professionally designed websites nowadays that _don't_ have some hard limit for the width of the main (text) content column any more.

If you really hate that so much and think you're different than anyone else with your reading capabilities, disable CSS.

Unfortunately, most websites nowadays are also broken without CSS, but that's an entirely different issue.


----------



## drhowarddrfine (Jul 17, 2022)

We had a web designer at my company whose background was in typography. He spent a lot of time working out line widths and font sizes. You can't cover all instances of monitor sizes and eye sight of the user. So you work with the CSS to control the things you can control. You let those with bad vision have the ability to zoom without breaking the flow. You restrict the width of the text to allow for readability. If you have an ultra wide monitor, so be it, but our textual, information-only page is going to be centered with lots of white space on both sides but will be highly readable.


----------



## vermaden (Jul 17, 2022)

I also liked the old Handbook/FAQ style more.


----------



## blackhaz (Jul 17, 2022)

Zirias, don't compare Handbook with just any web sites out there. For example:





						Cisco 5400 Enterprise Network Compute System Hardware Installation Guide  - Overview of the Cisco 5400 Enterprise Network Compute System [Cisco 5000 Series Enterprise Network Compute System]
					

Overview of the Cisco 5400 Enterprise Network Compute System



					www.cisco.com
				




This allows user to control the width of the content by adjusting their browser window. You should fix the column width, say, on an index page, so your web site will appear right even if the user has 16:9 screen with browser width maxed out. But you shouldn't be doing that on a documentation style. Cisco did it right.


----------



## zirias@ (Jul 17, 2022)

Because: for documentation, the difficulty with reading very long lines magically doesn't apply?


----------



## blackhaz (Jul 17, 2022)

Whew... You don't appear to be hearing me. Narrow your browser window to avoid wide lines if you have a wide monitor. It's your problem. Not Handbook's. On the contrary, I can't widen the text if somebody has set a fixed column width there or decides to fill the space with something just to make sure the column width cannot be maxed out. Freedom vs no freedom situation.


----------



## zirias@ (Jul 17, 2022)

You don't seem to get it. A web layout is meant to be readable, no matter how the dimensions of your browser are. And btw, people (including me) tend to NOT want to continuously resize their browser window to get a readable version of every single webpage, especially not with tabbed browsing.

The majority of users just expects a readable version. If you, for some reason, disagree, well, that's kind of bad luck -> disable CSS.


----------



## drhowarddrfine (Jul 17, 2022)

Zirias said:


> A web layout is meant to be readable, no matter how the dimensions of your browser are.


I paid people a lot of money for decades whose sole job was to make sure that happened.

The general rule some would use is that no line would extend past 75 characters but that's a rule for people who don't know what to do. Our designer frequently found 90 to 100 characters on a line to be good. But that depends on a lot of design decisions. Readability is key.

Grab a book off your shelf right now and count the number of characters, including spaces, commas, apostrophes, etc. I'd bet you'll wind up with somewhere around 80 to 100 on a line.


----------



## smithi (Jul 17, 2022)

I'm currently limited to mobile phone browsing, in this case Samsung Internet, which is surprisingly good lately.  I've had to abandon my older Firefox 68.11 as unusable for writing into these forums, and it chops 2 or 3 characters off the left of all latest Handbook pages in Mobile mode. Later Firefox mobile versions are sadly rubbish, destroyed, gone.

So I set Samsung Internet to Desktop mode to look at the current handbook.  I concur with many of the misgivings above.  Grey on white(ish) is very poor on older eyes, worse with blue light filter on. The RHS menu sure isn't needed, waste of space.  Yea, more vertical spacing than necessary.

However in Mobile mode it's not too bad.  I Force dark mode and that looks ok.  The chapter TOC becomes a hamburger box at top 'Book Menu', which has an issue on dismissal but the 99% of the time that it's unwanted, it's out of the way.

Yes, the headings are all way oversized.  <H1>, H2 and H3, even H4 display larger than appropriate, here at least. There are no H5s on the page I checked, so I'll suggest demoting all <Hn> tags to <H(n-1)> as a easy start.

Strangely (perhaps?) Firefox 68 in Desktop mode looks about the same as Samsung Internet in Mobile mode, i.e. no LHS or RHS menus, better text layout, 'book menu' as above.  Weird.

I've yet to try Links or Lynx, but basic browsers should work fine for documentation without people having to chase latest, shiniest browsers, no?


----------



## zirias@ (Jul 17, 2022)

drhowarddrfine said:


> The general rule some would use is that no line would extend past 75 characters but that's a rule for people who don't know what to do.


In fact, that's a rule for monospaced fonts  (they need in average more horizontal space per character than proportional fonts). There's a reason 80col-terminals were very successful for a long time!


----------



## zirias@ (Jul 17, 2022)

smithi said:


> I've yet to try Links or Lynx, but basic browsers should work fine for documentation without people having to chase latest, shiniest browsers, no?


"Should" is the key, unfortunately. Well, didn't test FreeBSD handbook so far, I kind of expect it to stand out as a good example, yet to be verified.

But in general, making sure your markup is correct (including all necessary semantics) is "forgotten" very often nowadays.  That's why I said "you might run into other problems" when saying "if you dislike layout decisions, disable CSS"...


----------



## Beastie7 (Jul 17, 2022)

Slightly off topic. 

I think there should be a subsection in Chapter 5 for configuring a few popular window managers; a great opportunity to bring in some content from vermadens blog. There's a lot involved in a bare bones setup; including it would make the handbook better teaching material for minimal desktops IMO.


----------



## drhowarddrfine (Jul 17, 2022)

Beastie7 The Handbook isn't a teaching resource in that way


----------



## VladiBG (Jul 18, 2022)

With some minor CSS changes the handbook can look like this:







```
diff --git a/documentation/themes/beastie/assets/styles/documentation.scss b/documentation/themes/beastie/assets/styles/documentation.scss
index 7826480db8..eaf66ac7c1 100644
--- a/documentation/themes/beastie/assets/styles/documentation.scss
+++ b/documentation/themes/beastie/assets/styles/documentation.scss
@@ -51,7 +51,7 @@
   justify-content: center;
   margin-left: auto;
   margin-right: auto;
-  max-width: 1440px;
+  max-width: 1920px;
   width: 100%;

   .article {
@@ -74,7 +74,7 @@
   justify-content: center;
   margin-left: auto;
   margin-right: auto;
-  max-width: 1440px;
+  max-width: 1920px;
   width: 100%;

   .book-menu {
diff --git a/documentation/themes/beastie/assets/styles/global.scss b/documentation/themes/beastie/assets/styles/global.scss
index 765d81b672..9a78fb17f3 100644
--- a/documentation/themes/beastie/assets/styles/global.scss
+++ b/documentation/themes/beastie/assets/styles/global.scss
@@ -50,7 +50,7 @@ body {
   padding: 0;
   margin: 0;
   font-size: 100%;
-  font-weight: 400;
+  font-weight: 300;
   font-style: normal;
   cursor: auto;
   background-color: var(--global-background-color);
@@ -64,7 +64,7 @@ body {
   justify-content: center;
   margin-left: auto;
   margin-right: auto;
-  max-width: 1440px;
+  max-width: 1920px;
   transition: padding .15s;
   background-color: var(--global-background-color);

diff --git a/documentation/themes/beastie/assets/styles/main.scss b/documentation/themes/beastie/assets/styles/main.scss
index 8d3fdbb1c9..33433e271f 100644
--- a/documentation/themes/beastie/assets/styles/main.scss
+++ b/documentation/themes/beastie/assets/styles/main.scss
@@ -28,7 +28,7 @@
 @font-face {
   font-family: 'Inter';
   font-style:  normal;
-  font-weight: 400;
+  font-weight: 300;
   font-display: swap;
   src: url("../fonts/inter/Inter-Regular.woff2") format("woff2"),
         url("../fonts/inter/Inter-Regular.woff") format("woff");
diff --git a/documentation/themes/beastie/assets/styles/variables.scss b/documentation/themes/beastie/assets/styles/variables.scss
index 717f154347..ae07481b1d 100644
--- a/documentation/themes/beastie/assets/styles/variables.scss
+++ b/documentation/themes/beastie/assets/styles/variables.scss
@@ -46,7 +46,7 @@
 .theme-light {
   --white: #FFF;
   --black: #000;
-  --global-font-color: #444;
+  --global-font-color: #000;
   --header-background: #9F0E0F;
   --header-font-color: #FFF;
   --global-background-color: #FFF;
```


----------



## gotnull (Aug 19, 2022)

What's bother me is the table of content and the menu section (cf. the picture in blue), they take way too much space compared to the main reading section, and they can't hide.
That's easier to focus on text when what you want to read is the only thing displayed on screen (my resolution is 1920x1080).
The header (cf. the picture in green) is too big also, it's a book there not need for a banner that large, or even a banner at all.

TBH I think using 'mdbook' or 'gitbook' could have been more convenient (at least less work) for the authors/contributors, or even 'readthedocs'.
Documentation in markdown or restrucuredtext, from my point of view, give better results because that's what they do.

I am not saying that the handbook as it is right now is bad or unusable, it's not, it's looking good and it feels more modern than before.
It must have been a lot of work, but it's not what I expected.


----------

