FreeBSD Handbook Gets a New Layout

Jose said:
I don't care for it, but don't feel as strongly about it as you do. It is too crowded and busy. I like the option to collapse them as stated in bullet point 1 of #109.
Click to expand...

I have been reserving judgement. It has that same "early 2020's" feel to it that the foundation page has. Whilst this probably appeals to many, it ends up losing the "academic quality" look. Fitting in with the classic UNIX research papers kept a real consistency that Linux could never achieve. However, since visual trends tend to cycle every decade, I am sure we will be back to that.

Since a pdf can be generated, I have no real problems with it, though I would say the biggest issue is that now it makes the main freebsd.org website look out of place and inconsistent; almost appearing like the foundation page is the main portal which it should never be.

That said, I am impressed by carlavilla@'s efforts. It seems like a lot of work and design aside, it is looking very complete. Anything is better than a half-finished documentation portal (i.e Alpine, Debian Linux, etc).
 
gotnull said:
Yeah but you see the paradox, to have a clean layout one have to shrink the window.
Click to expand...
To alleviate the paradox, you could use a browser add-on to not display a toc. This isn't as luxurious as I suggested in my earlier message #42 with a certain on/off switch option on the page itself but I hope it has value.

FreeBSD Handbook - no tocs (Installing the Stylus add-on with basic settings)​

With the Firefox Stylus add-on:
Stylus
Redesign the web with Stylus, a user-style manager. Stylus allows you to easily install themes and skins for many popular sites.
Click to expand...
  1. add the Stylus add-on to your Firefox browser
  2. create a new Stylus tab by clicking on the Stylus icon at the right top area of your browser window and then in the small pop-up click manage
  3. click Write new style to create a new style; name it, then click save
  4. from the drop-down menu at the bottom select URL and enter next to it:
    https://docs.freebsd.org/en/books/handbook/
  5. in the Code 1: window pane add CSS code to disable the left and/or right toc
  6. verify with Live preview checked if it has the desired effect in another firefox tab with the URL mentioned at step #4
  7. save the style
ad # 5: I used:
CSS: 
/* toc at left side of the page */
main.main-wrapper-book aside.book-menu {
    display: none
}

/* toc & resources at right side of the page */
main.main-wrapper-book aside.toc {
    display: none  
}
With these settings you have no tocs on this web page relating to the current HTML URL. Pressing the next button at the bottom of the page brings you to a new page with a new URL where the added style settings are not active. In the Stylus tab of the browser, select at the drop-down menu at the bottom: URLs starting with Every HTML page of the Handbook should now be without both tocs.

Combine single HTML page (no tocs) & split HTML pages (with tocs)​

Perhaps you mostly use the Handbook online as a single HTML webpage without tocs, but you still want the split HTML page with both tocs. Use the previous setup, then:
  1. change the dropdown to URL with content next to it:
    https://docs.freebsd.org/en/books/handbook/book/
    (this is the URL of the single HTML web page)
  2. click on Add at the bottom to add another style section
  3. set in this newly created style section the dropdown to URLs starting with with content:
    https://docs.freebsd.org/en/books/handbook/
    because the window pane Code 2: has no code, the Handbook in split HTML displays in standard fashion with tocs
  4. verify with Live preview checked if it has the desired effect in another firefox tab with the URLs mentioned for these settings
  5. save the style
 
Thank you ;)
I am myself using this extension and played with it as an amateur (well this version doesn't work with the new layout obviously).
As for the handbook I'll stick to the PDF for now, as said before for me it's more comfortable, but I am sure that your solution will be useful to anyone who prefer to work with the online version, tricks are always welcome, thanks.
 
Here are my suggestions:

Light fonts

documentation/themes/beastie/assets/styles/main.scss
Code: 
@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");
}

Black font color instead of grey:

documentation/themes/beastie/assets/styles/variables.scss
Code: 
.theme-light {
  --white: #FFF;
  --black: #000;
-  --global-font-color: #444;
+  --global-font-color: #000;
  --header-background: #AB2B28;
  --header-font-color: #FFF;

1697792429920.png
 
As an old fella with diminished eyesight, of those I'd go for Cleartype, font #000, but 400.

I hate grey fonts and too small fonts. It's not like we're saving anu trees, and who prints docs anymore?
 
Separate issue, but I'm still on 12.4 here so have all the books and articles with .pdf AND .html versions. Really handy.

Freshports currently still says:

FreshPorts -- misc/freebsd-doc-en: Documentation from the FreeBSD Documentation Project

The whole documentation set from the FreeBSD Documentation Project: Handbook, FAQ, articles and more.
www.freshports.org www.freshports.org

These upgrade notes are taken from /usr/ports/UPDATING 2022-03-26
Affects: users of misc/freebsd-doc-*
Author: blackend@FreeBSD.org
Reason: A change to the doc toolchain prevents the build of individual localized HTML versions of the documentation without building the en_US version. HTML option is currently disabled until a good solution is found. PDF version, the default option, is now the only available option. Please re-run "make config" to pick up this new default.

So, does that apply even to the US version, or only to the localised versions?

Scenario: installed FreeBSD OFFLINE, likely from DVD. No Xorg yet, no graphics, no PDF.

Need to read handbook / faq / articles with (included on DVD) links browser.

Or at other times offline, broken mobile link, think third world - need text browser and local docs. Is this really no longer possible?
 
Charlie_ said:
Code: 
 author   Danilo G. Baio <dbaio@FreeBSD.org>  2023-04-18 00:09:40 +0000
committer Danilo G. Baio <dbaio@FreeBSD.org>  2023-04-25 00:08:52 +0000

misc/freebsd-doc-*: Enable HTML in all languages and Simplify ports

Make the HTML option default for all languages.
Click to expand...

Excellent, thankyou Charlie_

So, it's now just the Freshports page that's out of date?
 
Hi

smithi said:
the Freshports page
Click to expand...

<{link removed}> Configuration Options, <{link removed}> Notes from UPDATING, or some other part of the page?

Related: {link removed}

For readers who may be unaware: as the UPDATING file gains additions (in special situations) but not subtractions, so it's normal for representations of entries to persist in FreshPorts.
 
Last edited:
VladiBG said:
Here are my suggestions:

Light fonts

documentation/themes/beastie/assets/styles/main.scss
Code: 
@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");
}

Black font color instead of grey:

documentation/themes/beastie/assets/styles/variables.scss
Code: 
.theme-light {
  --white: #FFF;
  --black: #000;
-  --global-font-color: #444;
+  --global-font-color: #000;
  --header-background: #AB2B28;
  --header-font-color: #FFF;

View attachment 17130
Click to expand...
Right now I'm busy with the new design for the website.
After that I'll improve the Documentation Portal.

Sorry for the delay.
 
Jose said:
… crowded and busy. I like the option to collapse …
Click to expand...

An option sounds good.

Flashback to early 2008: <{link removed}>.

Later that year: <{link removed}>

Now, the PDF is clean and clear but still, there's a colossal box that spans more than one page: <{link removed}> (shot taken 2023-10-15). HTML, live: <{link removed}>. Things such as these are, I guess, unintended long-term consequences of the enhancements that were made fifteen years ago.
 
Last edited:
grahamperrin said:
Hi
Click to expand...

Welcome back.

grahamperrin said:
<https://www.freshports.org/misc/freebsd-doc-en/#config> Configuration Options, <https://www.freshports.org/misc/freebsd-doc-en/#updating> Notes from UPDATING, or some other part of the page?
Click to expand...

Yes, Notes from UPDATING, though that aligned with something someone sometime mentioned regarding recent mentions of working with text-only browsers.

grahamperrin said:
Related: UPDATING: Add entry for misc/freebsd-doc-* changes · freebsd/freebsd-ports@c925b9a

For readers who may be unaware: as the UPDATING file gains additions (in special situations) but not subtractions, so it's normal for representations of entries to persist in FreshPorts.
Click to expand...

Lessons for me are 'dig deeper' (eg changes, commit msgs) and not to trust absence of a later UPDATING entry to mean that status is still current.

Anyway, glad it's fixed.
 
You are inconsistent with your usage of the closing slash `/>` on some tags. Note that the meta tag does not use and does not need a closing slash and never has in any HTML specification.
This is also true for all HTML tags.
 
Yes, I need to check the code with the w3c validator.
This was made because the editor I’m using.

My idea is to request feedback about the design.
 
I like the "black" text color compared to the grey from handbook. But i personally prefer font-weight:300 instead of 400 because the normal text appear as bolt instead of normal thin. Regarding the design you can check the different display sizes inside the lighthouse so if someone with 4K resolution will have the same experience as other which is viewing the page on HD or UHD. For example the page on 16:10 look better than 16:9.

1699278560231.png
 

News​

Abandoned when I resigned:

{link removed}

Essentially:
  • for each RELEASE: prune its pre-release points in time
  • <{link removed}> was my opposition to pagination.
<{link removed}> currently has:
  • a broken timeline, severed at 2010, that will require pagination (at <{link removed}>, Li-Wen Hsu notes some of most interesting points in the history of the Project)
  • too many historic items that will be of zero interest to a majority of users (this is why the page becomes too long).
 
Last edited:
What I'm interested in is the content, the rest is just "blue jeans". Plain text would be perfect for me, just be it up to date. My 2 euro cents.
 
You must log in or register to reply here.
Back
Top