FreeBSD Handbook Gets a New Layout

[freezr]

Can you create a FreeBSD install Pendrive with UFS?

Anyway on Debian to format a pendrive to Fat32 I use one command:

mkfs.vfat /dev/sdX -I

 

[chungy]

Anyway on Debian to format a pendrive to Fat32 I use one command:

You can do the same on FreeBSD: newfs_msdos /dev/da0

Both in this example and the one you posted, you are creating a FAT32 file system on the direct device, without a partition (the -I flag you use even bypasses a safety check that prevents doing just that). It can cause a lot of problems and even on Linux you really need to use fdisk or sysutils/gdisk first; the FreeBSD base equivalent of such is gpart(8).

Regardless of operating system, the process is basically always going to be:
1. Create partition
2. Format partition

Step 1 sometimes involves creating a new partition label first (the page you linked destroyed the existing one and created a new one). Sometimes you already have a partition; Windows is extremely sensitive to the partition type defined in the label whereas FreeBSD and Linux don't really care much about type, but it's still often a good idea to describe what should be in it.

Step 2 is where you get newfs_msdos(8) (FreeBSD), mkfs.fat (Linux), format (Windows).

 

[grahamperrin]

… the Handbook doesn't have a section that explains to the new comers how to do something trivial as formatting a USB pendrive into a FAT32 file systems.

<https://docs.freebsd.org/en/books/faq/#removable-drives> could be better:

• it begins with an msdosfs example, but does not show how to deal with a drive that does not already use msdosfs
• it exemplifies mounting at /mnt, a subdirectory of /media would be saner – see hier(7)
• it directs people to destroy data on da0

The table of contents lacks detail. There should be visible links to sections within each chapter.

Some of what's in the book of frequently asked questions would be better in the FreeBSD Handbook (maybe in appendices).

… four commands to format a USB Pendrive looks a little bit cumbersome...

Yeah. <https://forums.freebsd.org/posts/550989>

Postscript​

Discussion of content (not layout) continues under <https://forums.freebsd.org/posts/565692>.

 

[grahamperrin]

… Does gray on white text rather than black on white text reduce or induce eye strain? …

WebAIM: Contrast Checker finds no problem with two colours picked from the Handbook:

• <https://webaim.org/resources/contrastchecker/?fcolor=444444&bcolor=FCFCFD>

A related check revealed an obscure bug – not a design issue:

• FreeBSD bug 263457 – Documentation: reverse solidus \ and the subsequent character lack contrast (mis-coloured) in representation(s) of code

Resources​

From Low Vision & Color Accessibility – Learn Accessibility:

… A common false belief is that full black on full white is the best contrast. …

Why You Should Never Use Pure Black for Text or Backgrounds (2018-05-08)

What is the source for the W3C's Contrast Ratio formula?

The Word Wide Web Consortium (W3C) has a formula for the contrast ratio of any two arbitrary colors, which they use to set minimum standards for text legibility: http://www.w3.org/TR/WCAG20-TECHS/G18.

psychology.stackexchange.com

Why is white on black considered higher contrast than black on white?

While researching to answer Why are "Inverted Colors" considered an accessibility feature? I noticed the puzzling claim that "White text on a black background is a higher contrast to the opposite, ...

psychology.stackexchange.com

Formula for color contrast between text and background

In my Android app a user can choose the color of an item. This color is then shown in background with a text on it. I want to display the text either in black or white - depending on the background...

ux.stackexchange.com

– accepted answer ▶ Visualizing color contrast: a guide to using black and white text on colored backgrounds | by Roger Attrill | Medium

… and so on.

 

[drhowarddrfine]

grahamperrin All that is is random postings with no cohesive design plan and means nothing. Such a collection is pointless.

 

[grahamperrin]

Another quote from discussion of the FreeBSD Handbook:

… contrast …

skunk just rarely, maybe once or twice a year, I use the Font Contrast extension to Firefox. I don't recall ever needing it for FreeBSD documentation.

The previous comment mentions (obscure) bug 263457. That aside, there should be no need to adjust the contrast for the Handbook – at least for the default (light) theme.

– there's also the high contrast theme.

Last year:

… I also improved more things in dark and high contrast themes. …

carlavilla thanks again for the many and varied improvements.

 

[carlavilla]

Hi to all,

What changes do you want to see in the new (no so new now) in the documentation portal?

We're also gonna upgrade the website design too, the idea is to make the release with FreeBSD 14.

Bye!

 

[VladiBG]

What happened with grahamperrin ?

 

[carlavilla]

I have this things in my TODO list:

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. An index per book
4. Change gray font color to white
5. 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.

 

[Erichans]

Thanks for your continuing effort!

Especially in the pdf version of the Handbook, I'd welcome a precise version number/date of generation; e.g. on the "Abstract page". More importantly, I'd appreciate a header or footer in the pdf output that contains the relevant version information as mentioned on the "Abstract" page. That may be something like "This manual covers FreeBSD 13.2-RELEASE and 12.4-RELEASE", but anything shorter that at least mentions 13.2 and 12.4 I'd be happy with.

 

[balanga]

I would like to point out the Handbook doesn't have a section that explains to the new comers how to do something trivial as formatting a USB pendrive into a FAT32 file systems.
I ended up following this website: https://www.adminbyaccident.com/freebsd/how-to-freebsd/how-to-format-an-usb-drive-on-freebsd/

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

What does newfs_msdos /dev/da0 do?

 

[Alexander88207]

What happened with grahamperrin ?

What do you mean, is something happened?

 

[VladiBG]

He hasn't posted anything more than an year and his avatar is removed.

 

[carlavilla]

Thanks for your continuing effort!

Especially in the pdf version of the Handbook, I'd welcome a precise version number/date of generation; e.g. on the "Abstract page". More importantly, I'd appreciate a header or footer in the pdf output that contains the relevant version information as mentioned on the "Abstract" page. That may be something like "This manual covers FreeBSD 13.2-RELEASE and 12.4-RELEASE", but anything shorter that at least mentions 13.2 and 12.4 I'd be happy with.

Hmm, yes, we can add some kind of generation info

 

[gotnull]

What changes do you want to see in the new (no so new now) in the documentation portal?

Hi ,

I think readability could be improve by:
1) reducing the width of the index on the left and removing the TOC on the right (not sure it is useful to have both, once you reach a chapter, items are already there on the left)
2) removing the top navbar AND the footer because they both take a lot of space and IMO those don't belong in documentation pages, you don't see that often.

I won't lie since the new layout is there I don't read handbook online anymore just because of what I've said before, instead I prefer to read the PDF via zathura in full screen, it's a better experience for me BUT I like what have been done with the index on the left with the search bar it's convenient , the dark and light theme are also nice to have.

I already said that in another comment (I am sorry for repeating myself) but why not using/forking an existing tool meant for that task instead of starting from scratch, it's less work for a better result.

Thank you for asking and for your work.

 

[carlavilla]

Hi ,

I think readability could be improve by:
1) reducing the width of the index on the left and removing the TOC on the right (not sure it is useful to have both, once you reach a chapter, items are already there on the left)
2) removing the top navbar AND the footer because they both take a lot of space and IMO those don't belong in documentation pages, you don't see that often.

I won't lie since the new layout is there I don't read handbook online anymore just because of what I've said before, instead I prefer to read the PDF via zathura in full screen, it's a better experience for me BUT I like what have been done with the index on the left with the search bar it's convenient , the dark and light theme are also nice to have.

I already said that in another comment (I am sorry for repeating myself) but why not using/forking an existing tool meant for that task instead of starting from scratch, it's less work for a better result.

Thank you for asking and for your work.

Hi,

I'll reduce the height of the header and I can make it to don't be sticky, so if you make scroll you will don't see it

Regarding the TOC on the right and the list of chapters of a book on the left, I am not going to remove that.

Regarding this type of structuring, may I know what you think of [1] and [2] then?

[1] https://vuejs.org/guide/introduction.html
[2] https://learn.microsoft.com/en-us/dynamics365/guidance/implementation-guide/security

 

[SirDice]

He hasn't posted anything more than an year and his avatar is removed.

He's changed his avatar himself. And I guess his new responsibilities are taken up a lot of his time.

 

[Maxnix]

He hasn't posted anything more than an year and his avatar is removed.

Maybe he is not very active on the forums. On reddit is.

 

[blackhaz]

If you allow, I would prefer a style with less distracting visual clutter, and the primary content not crammed into a tiny column in the middle, i.e. only one ToC column on the left. I wonder if people would find the following styles to be more appropriate for FreeBSD documentation:

IBM Documentation

IBM Documentation.

www.ibm.com

Issues When Installing Oracle Solaris 11.4 - Oracle® Solaris 11.4 Release Notes

The following issues might occur during or after the installation of Oracle Solaris 11.4.

docs.oracle.com

Thales Luna PCIe HSM 7 Product Documentation

thalesdocs.com

Out of the above, to me Thales's style appeals the most as the least visually intrusive, clean and conveying.

A few other suggestions attached.

 

[gotnull]

Regarding this type of structuring, may I know what you think of [1] and [2] then?

From my point of view they are the same 3 columns style like the handbook, sorry I don't like it, I prefer the one you linked before the doc.rust-lang , it's simple TOC/index doesn't get in your way there is no header no footer, it is just plain text without distraction.

I am aware that I am speaking for myself here while there are probably many people that actually like the new layout so ...

I'll reduce the height of the header and I can make it to don't be sticky, so if you make scroll you will don't see it

Thank you, that is a good starting point.

 

[Erichans]

I think readability could be improve by:
1) reducing the width of the index on the left and removing the TOC on the right (not sure it is useful to have both, once you reach a chapter, items are already there on the left)

The width of the index colums on the left and right are fixed, when they are present. When making the browser window narrower, there comes a moment when only the text column remains; for a wide screen monitor that means displaying the bowser in half a screen-width it'll display only the text (as do the other referenced external websites). Using Firefox, at ca. 2/3 screen width both "extra" colums disappear and the text column remains.

 

[carlavilla]

I’m gonna improve the doc portal with all your comments.
I’m gonna remove the right TOC too and leave only the left menu.

About the fixed size, it’s true, my idea was to make it with media queries, as I see, I’m failed

I’ll try to improve all of that ASAP

My apologies for the inconvenience.

 

[Jose]

I am aware that I am speaking for myself here while there are probably many people that actually like the new layout so ...

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.

 

[smithi]

He hasn't posted anything more than an year and his avatar is removed.

Graham mentioned signing out from the forums over a year ago.

Maybe he is not very active on the forums. On reddit is.

He still posts occasionally to freebsd_questions@ and [edit] various other mailing lists.

This post most recently, which also points to his reddit page.

 

[gotnull]

The width of the index colums on the left and right are fixed, when they are present. When making the browser window narrower, there comes a moment when only the text column remains; for a wide screen monitor that means displaying the bowser in half a screen-width it'll display only the text (as do the other referenced external websites). Using Firefox, at ca. 2/3 screen width both "extra" colums disappear and the text column remains.

Yeah but you see the paradox, to have a clean layout one have to shrink the window.

I’m gonna improve the doc portal with all your comments.
I’m gonna remove the right TOC too and leave only the left menu.

About the fixed size, it’s true, my idea was to make it with media queries, as I see, I’m failed

I’ll try to improve all of that ASAP

My apologies for the inconvenience.

No need to apology you didn't not fail, you brought modern design and that's good.
You probably did the work more with a mobile design in mind and in the end we have a visual aspect between desktop and mobile.
But I understand it's difficult and very challenging to make everyone happy.
I appreciate the fact that you can listen to criticisms without getting too sensitive, in this time it is a good and rare quality thank you for that

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.

Agree, TBH most of the listed ideas are interesting.
I like the bullet point 2 (export as a long HTML) like the old layout, then making a research with ctrl-f can be done quickly.