# FreeBSD Handbook Gets a New Layout



## Scribner (Dec 12, 2021)

I just visited <https://docs.freebsd.org/en/books/handbook/> and discovered it has a new, modern layout!


----------



## chrbr (Dec 12, 2021)

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!


----------



## Alain De Vos (Dec 12, 2021)

It's readable using text browsers like lynx.


----------



## ralphbsz (Dec 12, 2021)

Noticed that last night. I had to update my /etc/pf.conf (which was last done ~5 years ago), and that required actually reading the documentation, and the new look of the handbook surprised me. It was a pleasant surprise, it is quite readable.


----------



## Beastie7 (Dec 12, 2021)

Table of contents yessss


----------



## cmoerz (Dec 12, 2021)

I'll be damned. That section on `pf` is brand new to me. When I started working with `pf`, OpenBSD was the documentation source I fell back on.


----------



## eternal_noob (Dec 12, 2021)

It even has a dark mode now!


----------



## AngryChris (Dec 12, 2021)

I'd like them to put *<< Prev/Next >>* links at the top _and_ bottom of the page and not just at the bottom.


----------



## msplsh (Dec 12, 2021)

That's real nice.


----------



## freezr (Dec 13, 2021)

Nice!


----------



## SirDice (Dec 13, 2021)

The main website is likely to get a revamp too.









						FreeBSD Quarterly Status Report 3rd Quarter 2021
					

FreeBSD is an operating system used to power modern servers, desktops, and embedded platforms.




					www.freebsd.org


----------



## ipsum (Dec 13, 2021)

line-height should be carefully adjusted. To much vertical white-space, for me.


----------



## dave01 (Dec 14, 2021)

I'd prefer it if the banner scrolled off the top and didn't waste the limited vertical space on my laptop.  We can't all have nice large hi-res laptop screens.  We pretty much all have wider screens these days but web designers still design for taller, narrower screens such as 4:3 CRTs  If deigners want stuff to stay on the screen while we scroll, put it down the side, not across the top.

On a similar note, there doesn't seem to be a way to uncollapse the whole table of contents, making it harder when just having a browse for new sections/subsections or a specific topic.  Ditto on  a phone screen.  The collapsed table of contents takes a lot more navigation time whereas a full expanded list is easy to scroll through quickly.

Other than that, yes, it feels more readable.


----------



## bsduck (Dec 14, 2021)

I agree: why such a fat header bar? It's the same size as the one on this forum but here we have two lines in that space, and more elements in them... those only four links could go into a sidebar, or at least a much thinner bar.

As a whole, I liked the previous style better, but that's personal taste...


----------



## jbo (Dec 14, 2021)

Looks are of course very subjective. Personally I mainly enjoy the table of content. That is really nice!
I also think that the "code snippets" look nicer now.

Thanks a lot to everybody involved in making this!


----------



## drhowarddrfine (Dec 14, 2021)

ipsum said:


> line-height should be carefully adjusted. To much vertical white-space, for me.


Yep. Far too large.


----------



## drhowarddrfine (Dec 14, 2021)

Not too many years ago, I talked to Warren about redoing the site cause, after all, that was the business I was running. But after all the warnings about how the pages were generated, I decided to not get involved.

Then, a few years ago, someone mentioned to me about getting involved. I even talked to the Foundation about getting funding but that was more than I cared to get into.

Finally, two years or so ago, someone pointed me to all the documentation and tools for working on it. I wish I was shown that originally. I installed everything, did some poking around, got excited but I can't say why I drifted away. It may have been something as simple as no one encouraging me. (I'm not blaming anyone.) Then my wife said, "You're not getting paid to do that!" which may have actually put the nail in the coffin.

So this popping up without notice makes me glad I didn't work on this on my own cause it might not have been finished. It also makes me sad and jealous cause I would have done much better. That said, I'd bet it's done by someone on the side--when they had spare time. So I cannot disparage it at all.


----------



## bakul (Dec 14, 2021)

Now they are using asciidoc for documentation "source" files. Previously they used sgml. asciidoc is far easier to use. I wish someone extends it to allow the use of `[[some-file]]` links -- what many apps using markdown format such as Obsidian, LogSeq etc. allow. They also create _backlinks_ so that you can see what else refers to the current file. So for instance, the `ls` man page can say `See Also: [[chflags]](1), ...` and you could also see what other pages refer to the `ls` page.


----------



## grahamperrin@ (Dec 18, 2021)

<https://docs-legacy.freebsd.org/doc/> is more intuitive for archive and legacy documentation ☑ than <https://docs.freebsd.org/doc/>.









						Solved - Version-specific editions of the FreeBSD Handbook
					

en English:  12.3-RELEASE   13.0-RELEASE   13.1-RELEASE   CURRENT     From :   … documentation on our web site is mostly for -current, the state of the art of the code base. …




					forums.freebsd.org
				






bakul said:


> … asciidoc is far easier to use. …



I don't doubt it, but still, it turns me off:








ipsum said:


> line-height should be carefully adjusted. To much vertical white-space, for me.



Agreed. If you'd like to share an improved style, I might use it (with e.g. Stylus).


----------



## grahamperrin@ (Dec 20, 2021)

FreeBSD bugs:

260576 – Difficulties with navigation, content and/or orientation in parts of some books
260577 – Table of contents partially invisible in some browsers
260705 – Accessibility: with the redesign, it's no longer easy to reach the first (front, home) pages of books such as the FreeBSD Handbook
260721 – The FreeBSD logo at top left should refer to the FreeBSD home page


----------



## grahamperrin@ (Dec 20, 2021)

bsduck said:


> … why such a fat header bar? …



I don't enjoy the depth per se, but it might become necessary to use part of the bar to display the title of the document.

Like, _what's_ this book?


----------



## grahamperrin@ (Dec 27, 2021)

<https://lists.freebsd.org/archives/freebsd-questions/2021-December/000355.html> describes some other issues relating to the new layout. In reply, there's an acknowledgement from Sergio Carlavilla. 

Are any other new bugs noticeable, in the documentation area, as a result of the new layout? 

Thanks


----------



## jbo (Dec 28, 2021)

Not sure if this was already mentioned/reported but one thing I noticed is that specific type of "code section with steps" uses an unfortunate font color in dark mode.

Example: https://docs.freebsd.org/en/books/handbook/cutting-edge/#makeworld

Screenshot:


----------



## grahamperrin@ (Dec 28, 2021)

Thanks jbodenmann, I might never have found that. (I use an advanced preference to prevent _unwanted theming of content with Firefox 95._)

For diagnosis:

FreeBSD documentation does _not_ darken, for me, with `layout.css.prefers-color-scheme.content-override` `0`
is that something other than Firefox in your screenshot, or Dark Reader, maybe?



jbodenmann said:


> … already mentioned/reported …



For anyone who's interested: a list of Documentation bugs.


----------



## jbo (Dec 28, 2021)

grahamperrin said:


> is that something other than Firefox in your screenshot, or Dark Reader, maybe?


This screenshot was taken from/with stock FireFox 95 with selection of the _"Dark"_ theme at the bottom of the handbook page.


----------



## grahamperrin@ (Dec 28, 2021)

jbodenmann said:


> … _"Dark"_ theme at the bottom …



OK, I added two more bugs to the list, the first of which gives credit to you. Thanks again.


----------



## grahamperrin@ (Dec 29, 2021)

bakul said:


> … asciidoc for documentation "source" …



Sorry, I'm overwhelmed by the AsciiDoc User Guide, and given examples are confusing more than helping me.

How should I fix this:

`the extref:{handbook}[list in the Handbook, eresources-mail] and`

– to refer to the URL below?

<https://docs.freebsd.org/en/books/handbook/eresources/#eresources-mail>


----------



## Erichans (Dec 29, 2021)

Try:
https://docs.freebsd.org/en/books/handbook/eresources/#eresources-mail[Mailing Lists]

If you remove the text
Mailing Lists
the complete URL will be displayed. The square brackets(*) (even with zero characters between them) ensure that the URL is always parsed as a URL, e.g. when surrounding the whole caboodle with double quotes it will still be recognized as a URL (and displayed as such):
"https://docs.freebsd.org/en/books/handbook/eresources/#eresources-mail[Mailing Lists]"

Inside the square brackets any closing-square-bracket must be escaped by a preceding backslash character.

At AsciiDoc Home Page, using the TOC entry Cheatsheet, you'll find the examples at AsciiDoc cheatsheet - Macros: links, images & include perhaps also helpfull.

___
(*) you might be thrown off track by thinking these square brackets denote the "optional-thing"; here they do not: they are to be treated as literals, i.e. just the characters opening-square-bracket ( *[* ) and closing-square-bracket ( *]* ).


----------



## grahamperrin@ (Dec 29, 2021)

Thanks Erichans, the cheat sheet is an ideal starting point.

PR drafted, through which I should gain clarity on stuff that's in neither the primary cheat sheet, nor the nearby _AsciiDoc cheatsheet for GitHub_.


----------



## bakul (Dec 29, 2021)

You can also try using various asciidoc features in a small test file. That is sort of what I do to lean something new!


----------



## carlavilla (Dec 30, 2021)

AngryChris said:


> I'd like them to put *<< Prev/Next >>* links at the top _and_ bottom of the page and not just at the bottom.


Yes, you're not the first who request this thing to me. I'm gonna make this change too



jbodenmann said:


> Not sure if this was already mentioned/reported but one thing I noticed is that specific type of "code section with steps" uses an unfortunate font color in dark mode.
> 
> Example: https://docs.freebsd.org/en/books/handbook/cutting-edge/#makeworld
> 
> ...


Fixed, sorry for the inconvenience. I also improved more things in dark and high contrast themes.



grahamperrin said:


> Sorry, I'm overwhelmed by the AsciiDoc User Guide, and given examples are confusing more than helping me.
> 
> How should I fix this:
> 
> ...



I need to improve the extref macro, right now it's not easy to use and to understand, sorry 

But in first place, we're not using the old python implementation of AsciiDoc, this implementation was discontinued a couple of years ago. We're using AsciiDoctor, and the Asciidoctor documentation it's  here.

And to fix the problem you reported it would be:

`the extref:{handbook}ereources[list in the Handbook, eresources-mail]`

Try it first, maybe I forgot something, but it's something like this. Again, sorry for this macro, I need to improve it and pass the chapter as a param


----------



## jbo (Dec 30, 2021)

carlavilla said:


> Fixed, sorry for the inconvenience. I also improved more things in dark and high contrast themes.


Yep, I noticed a few minutes ago that this is now fixed 
Thank you for your work - It's very much appreciated! And certainly absolutely no need to apologize!

That being said: Welcome to the FreeBSD forums!


----------



## Erichans (Dec 30, 2021)

AngryChris said:


> I'd like them to put *<< Prev/Next >>* links at the top _and_ bottom of the page and not just at the bottom.



I'd like the *HOME* button in between *<< Prev/Next >>*
I'm unable to go to the index position (not reachable via TOC); now only possible by manipulating the URL.
The old markup had it, e.g.: Getting Started.


----------



## covacat (Dec 30, 2021)

all font awesome intended glyphs don't render properly (use inter font)


----------



## grahamperrin@ (Dec 30, 2021)

AngryChris said:


> *<< Prev/Next >>* links at the top _and_ bottom



Related: FreeBSD bug 260821 – Aim to make icons (book, edit, important, next, note, previous, tip, top, warning …) more broadly compatible across multiple operating systems and browsers



> … A potentially challenging bug, …
> 
> – sorry!
> 
> Let's not rush this. …



carlavilla that's a sincere apology. I suggest taking a well-deserved break   and shelving 260821 until the new year.

For what it's worth, I foresee only three more p2-like bugs arising, from the new design, over the next few days, then it'll be p3 and below. 

Big thanks for your recent work. Stupendous.



covacat said:


> all font awesome intended glyphs don't render properly (use inter font)



Is that, 260821?


----------



## grahamperrin@ (Dec 30, 2021)

Erichans said:


> … unable to go to …



Near the foot of the list of bugs, that might be these two (some overlap):

260576 – Difficulties with navigation, content and/or orientation in parts of some books
260705 – Accessibility: with the redesign, it's no longer easy to reach the first (front, home) pages of books such as the FreeBSD Handbook
The screenshot at <https://forums.freebsd.org/posts/547539> was an intentionally extreme example.


----------



## Erichans (Dec 30, 2021)

Ah! Didn't see those.

___
P.S. Referring to 260705 – Accessibility: with the redesign, it's no longer easy to reach the first (front, home) pages of books such as the FreeBSD Handbook; my 1-step workaround:


> To return to the beginning, edit the URL. Delete everything after:
> ... handbook/


 (tested on EN-DE-FR-NL-RU)


----------



## grahamperrin@ (Dec 31, 2021)

and/or Navigate Up:


----------



## grahamperrin@ (Dec 31, 2021)

Columns, and single-page alternatives

The wish for a *column-free and/or single-page* alternative is (for me) far more frequent than *readiness to edit*: 



carlavilla maybe the *Resources* subsection can, eventually, expand to something like this:

ePub
long HTML
long PDF
edit this page
install documentation
(That's an _en_-specific link.) 

You could, equally/alternatively, have install documentation in the footer, however if it's (often) hidden down there, then readers will be *far* less likely to realise the benefits.

Generally

Each link should be *Control-click -friendly*, to simplify opening in a new tab. _Command_-click -friendly, on Macs. (Compare: UX problems with the _BSD Hardware Database_.) IIRC some collapsible items lacked this quality a few days ago, today  at a glance it's much better. Thanks!


I don't enjoy saying/writing this … the three-column approach doesn't appeal to me. Sorry. There's often duplication, sometimes also wastes of (white) space.

A much more enjoyable afterthought, as 2022 approaches: 









						FreeBSD workflow working group
					

FYI:   https://gitlab.com/bsdimp/freebsd-workflow  Pleasantly exciting:    …  – Do we move to something else hosted elsewhere?  GitHub has code review on its pull requests GitLab has code review for its modification requests  𠉧…   I don't know enough about GitLab, although I'm a user...




					forums.freebsd.org


----------



## grahamperrin@ (Dec 31, 2021)

Erichans said:


> *HOME* button in between *<< Prev/Next >>*



Fixed, thanks to carlavilla.


----------



## dave01 (Dec 31, 2021)

Can we try setting the text colour in the left column/Chapters to black instead of 68% mid-grey please?  The text is a bit small and increased contrast might make it more readable.  Many of us are greybeards these days.  I realise that many web designers seem to be enamoured with the current fad of mid-grey text on pale grey backgrounds, but just because everyone else is doing it doesn't mean it's the right thing to do    Thankfully, you didn't go all Microsoft and choose pale grey on light grey and "hidden" hyperlinks 

Oh yes, and I second the motion to get rid of the right side column.  It just seems to be an expansion of section content list already in the left column.  It looks redundant.


----------



## Erichans (Jan 1, 2022)

grahamperrin said:


> [...] I don't enjoy saying/writing this … the three-column approach doesn't appeal to me. Sorry. There's often duplication, sometimes also wastes of (white) space.


The two TOCs take up a lot of real estate and are not always needed. Even with a wide screen this more or less forces the user to set the browser to full width while for example a half width wide screen with only the handbook text is quite agreeable and readable.

Besides this scenario for a wide screen, there are also a lot of "narrow" screens around. Quite a lot of (FreeBSD) laptops do not have a wide screen and in a desktop two monitor setting a secondary monitor may not be wide screen.

Apart from the possibility of a HTML-handbook-text-only (no side TOCs) as in the old style handbook, there is another option that could be used for the current set up:




Clicking on a triangle in the grey side bar will expand that side TOC to its original form. Some form of triangle in the opposite direction will remain at the border of the side TOC and the main text: clicking on that one will minimize the side TOC again as shown in the picture. This somewhat resembles a similar action in Adobe Acrobat Reader where two side area's can be manipulated. There the width of side areas are controlled gradually by sliders. I don't think such a slider is necessary here. A switch-on switch-off is much easier to implement: basically the two elements (TOC & hidden TOC with vertical bar) could both be present in the loaded html page, both are alternatively switched on or off.


----------



## grahamperrin@ (Jan 1, 2022)

Thanks. 

One collapsible sidebar: OK

Two sidebars, with or without collapse: less usable. 

Two sidebars at a *distance* from each other: far less usable, and the negative effect of distance is worse whenever the user aims to perform dual actions involving _both_ sidebars. Actions such as scrolling, clicking, collapsing, whatever … IMHO it's simply not good UX. 

(This is the reason for me having a user style that aims to keep the two sidebars *adjacent* to each other.)


----------



## grahamperrin@ (Jan 1, 2022)

For 'power' users, in combination with the HeadingsMap extension: the user style at <https://forums.freebsd.org/posts/549017>. 

This combination seems to work with:

articles (the first screenshot below)
long HTML books (second and third shots)
but *not* dual-column split HTML books (fourth shot).


----------



## grahamperrin@ (Jan 9, 2022)

Erichans said:


> … a lot of "narrow" screens around. …



Cross-reference <https://old.reddit.com/r/freebsd/comments/ryzqzt/-/hrs4cbg/?context=2>



> … a table near the bottom of the page - if you're on mobile the formatting will be messed up. …


----------



## Deleted member 30996 (Jan 9, 2022)

I just noticed it tonight and it does look 100% better.  

I rarely ever looked at it for anything but there is an abundance of information contained now.


----------



## zirias@ (Jan 9, 2022)

I personally think the old styling looked much nicer  

BUT: Usability is clearly improved, and that's more important of course 

BTW:


chrbr said:


> table of content in a separate frame


Glad they didn't use a HTML `<frame>` for that! Progressive enhancement starting at the most basic console browsers is really important here


----------



## drhowarddrfine (Jan 9, 2022)

Zirias said:


> Glad they didn't use a HTML `<frame>` for that!



The <frame> element has been obsolete for many years.


----------



## zirias@ (Jan 9, 2022)

drhowarddrfine said:


> The <frame> element has been obsolete for many years.


Which means just nothing in practice. Browsers support it and it continues to be used (e.g. by any doxygen-generated docs with toc). Btw, `iframe` is _not_ deprecated and would still pose similar problems.


----------



## Erichans (Jan 9, 2022)

_A complete TOC_
- enabling a quick search for a specific term or topic
- enabling a detailed overview of the complete contents of the handbook
 _An index_
Apart from (the 100% option of) just the text(*), in the newly styled online handbook, I really miss _the complete TOC_ like "the old TOC". A complete TOC, in addition to a "small" one, is also somewhat similar of a (big and important) book that has two TOCs. One giving the reader just an overview: _the big picture_. The other giving a detailed picture guiding the reader in the detailed structure of the contents of the book. This aspect may be easily underestimated but, getting familiar with the structure of such a large and rich content of a book as the FreeBSD handbook is IMO an important aspect for new users and even for experienced users that may know their way around in _quite a few parts_ of the handbook but not _all parts_. 

When searching "the old TOC" you could search for a term _in the context_ of its surrounding sub-titles (for example poudriere). The TOC on the left side cannot be easily expanded completely, for example with just one click. Not surprisingly, a search hit for a search term in a sub-title in teh left or right TOC, will only occur when the text is actually visible. The search of the complete TOC could be considered a pour man's search however, that is a search where you will find main (sub)topics in the context of its surrounding titles. This brings me to the index.

I also miss an index in the online handbook (like "the old index"). An index is the detailed and _tailored_ mechanism to find the _relevant text parts_ for a particular term. I emphasized relevant because that sets it apart from an ordinary string search over the complete HTML text of the handbook. Compiling an index is a non-trivial task!

I woul find something like this already really helpfull:




Note: yellow only for highlighting and right hand side TOC not done.
___
(*) I noticed at the newly styled online handbook page, when clicking _Single HTML_: the TOC on the right stays but, the left TOC disappears! 
(If I recall correctly, that was not the case earlier in the newly styled online handbook.)

Edit: screenshot image added; clarification added as to  referring to the newly styled online handbook betweem "([...])"


----------



## grahamperrin@ (Jan 9, 2022)

Erichans said:


> If I recall correctly



Moments in time:

<https://web.archive.org/web/20210816060439/https://docs.freebsd.org/en/books/porters-handbook/book/> – _FreeBSD Porter's Handbook_, long HTML, 2021-08-16

<https://web.archive.org/web/20210915235234/https://docs.freebsd.org/en/books/handbook/book/> – _FreeBSD Handbook_, long HTML, 2021-09-15

<https://web.archive.org/web/20211212080725/https://docs.freebsd.org/en/books/handbook/glossary/> – _FreeBSD Handbook: Glossary_, short HTML, 2021-12-12

<https://web.archive.org/web/20220102211109/https://docs.freebsd.org/en/books/handbook/glossary/>– _FreeBSD Handbook: Glossary_, short HTML, 2022-01-02


----------



## grahamperrin@ (Jan 9, 2022)

Erichans said:


> _the complete TOC_



Here: 





```
% pkg provides /usr/local/share/doc/freebsd/en/books/handbook/book.pdf
Name    : en-freebsd-doc-20211029,1
Desc    : Documentation from the FreeBSD Documentation Project
Repo    : FreeBSD
Filename: usr/local/share/doc/freebsd/en/books/handbook/book.pdf
%
```


----------



## Deleted member 30996 (Jan 9, 2022)

Zirias said:


> Which means just nothing in practice. Browsers support it and it continues to be used (e.g. by any doxygen-generated docs with toc). Btw, `iframe` is _not_ deprecated and would still pose similar problems.


That's right.

YouTube gave me iframe code to embed part of a video the other day:


```
<iframe width="560" height="315" src="https://www.youtube.com/embed/XzlTXDWw-8U" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
```


----------



## drhowarddrfine (Jan 9, 2022)

Zirias said:


> Which means just nothing in practice. Browsers support it and it continues to be used



Only by Mickey Mouse developers who are clueless. You can also use <marquee>, which has never been part of any HTML spec, but no sane developer would.

There are better ways to do things without the worry that one day, without notice, any browser can cease to support any of the obsolete methods--and they have. There's a reason why, when they write the standard, they mark them obsolete and the specification says "don't use this".

Trihexagonal  <iframe> is not obsolete.


----------



## kpedersen (Jan 9, 2022)

drhowarddrfine said:


> There are better ways to do things without the worry that one day, without notice, any browser can cease to support any of the obsolete methods--and they have.


Annoyingly for every obsolete method, there are a good few hundred Javascript pollyfills that web developers can't wait to shove on their site rather than do a decent job


----------



## grahamperrin@ (Jan 9, 2022)

Please, can we have discussion of `<frame>` and `<iframe>` in a separate topic?

As far as I can tell, neither is relevant to the FreeBSD Handbook (or, more broadly, the FreeBSD site). Thank you.



Spoiler: no detectable relevance.





```
% su -
Password:
root@mowa219-gjp4-8570p-freebsd:~ # gh repo sync grahamperrin/freebsd-doc && cd /usr/doc && gh repo sync && git -C /usr/ports pull --ff-only && git -C /usr/src pull --ff-only && cd
✓ Synced the "grahamperrin:main" branch from "freebsd:main"
✓ Synced the "main" branch from grahamperrin/freebsd-doc to local repository
Already up to date.
Already up to date.
root@mowa219-gjp4-8570p-freebsd:~ # exit
logout
% cd /usr/doc/website/
% time grep -R -i "<iframe" .
7.101u 0.408s 0:18.66 40.1%     25+173k 5554+0io 0pf+0w
% time grep -R -i "<frame" .
./static/security/patches/SA-19:03/wpa-12.patch:+       /* stype=<val> ok=<0/1> buf=<frame hexdump> */
./static/security/patches/SA-19:03/wpa-12.patch:+       /* freq=<MHz> datarate=<val> ssi_signal=<val> frame=<frame hexdump> */
./static/security/patches/SA-19:03/wpa-12.patch:          "<frame id> <hexdump of elem(s)> = add vendor specific IEs to frame(s)\n"
./static/security/patches/SA-19:03/wpa-12.patch:          "<frame id> <hexdump of elem(s)> = remove vendor specific IE(s) in frame(s)\n"
./static/security/patches/SA-19:03/wpa-11.patch:+       /* stype=<val> ok=<0/1> buf=<frame hexdump> */
./static/security/patches/SA-19:03/wpa-11.patch:+       /* freq=<MHz> datarate=<val> ssi_signal=<val> frame=<frame hexdump> */
./static/security/patches/SA-19:03/wpa-11.patch:+       /* freq=<MHz> datarate=<val> ssi_signal=<val> frame=<frame hexdump> */
./static/security/patches/SA-19:03/wpa-11.patch:+         "<frame id> <hexdump of elem(s)> = add vendor specific IEs to frame(s)\n"
./static/security/patches/SA-19:03/wpa-11.patch:+         "<frame id> = get vendor specific IE(s) to frame(s)\n"
./static/security/patches/SA-19:03/wpa-11.patch:+         "<frame id> <hexdump of elem(s)> = remove vendor specific IE(s) in frame(s)\n"
6.851u 0.394s 0:07.28 99.4%     25+172k 0+0io 0pf+0w
% head ./static/security/patches/SA-19:03/wpa-12.patch
--- Makefile.inc1.orig
+++ Makefile.inc1
@@ -963,6 +963,14 @@
                rm -f ${OBJTOP}/usr.sbin/ntp/libntpevent/.depend.*; \
        fi
 
+# 20181209  r341759 track migration across wpa update
+       @if [ -e "${OBJTOP}/usr.sbin/wpa/wpa_supplicant/.depend.rrm.o" ] && \
+           egrep -q 'src/ap/rrm.c' \
+           ${OBJTOP}/usr.sbin/wpa/wpa_supplicant/.depend.rrm.o; then \
%
```


----------



## grahamperrin@ (Jan 10, 2022)

Erichans said:


> "the old index"



+1

However, I imagine that it was a maintenance burden. 

Indices can be relatively easy to build then maintain in _solo author_ scenarios. Less easy with collaborative authoring and edition.


Let's expand things for a couple of minutes. 

With the redesign, the invitation to Edit this page seems to be omnipresent across articles and books (two of the three categories within the documentation set). Whilst not _overtly_ side-stepping the many and varied requirements of the FreeBSD Documentation Project (FDP):

a GitHub-oriented workflow – Edit this page – _does_ effectively lower the bar
– and so, *fewer people are discouraged from assisting* with additions, corrections and general maintenance *☑*

From the overview: 

high quality, accurate documentation is paramount
– this is inarguable. It simply will not happen consistently _and in good time_ without enough hands on deck.


Back to Erichans and the shared wish for a traditionally indexed FreeBSD Handbook. 

The realistic short-/mid-term alternative to two indices per book (one for short HTML, the other for long) is: 

the indexing and other features that are native to PDF
– this is partly why I envisage *prominent encouragement to install documentation*, which includes PDF versions of things such as the Handbook.



grahamperrin said:


> … @carlavilla maybe the *Resources* subsection can, eventually, expand to something like this:
> 
> ePub
> long HTML
> ...



I know, PDF is not a panacea, but it can do some of what's currently not done with HTML online. 

Maybe the FDP can add HTML indices to large multi-author items in a year or two, but for the next few months, I guess, thoughts will focus on a main site refresh ahead of the thirtieth anniversary.


----------



## grahamperrin@ (Jan 11, 2022)

dave01 said:


> Can we try setting the text colour in the left column/Chapters to black instead of 68% mid-grey please? …𒀦





grahamperrin said:


> <https://web.archive.org/web/20211212080725/https://docs.freebsd.org/en/books/handbook/glossary/> – _FreeBSD Handbook: Glossary_, short HTML, 2021-12-12
> 
> <https://web.archive.org/web/20220102211109/https://docs.freebsd.org/en/books/handbook/glossary/>– _FreeBSD Handbook: Glossary_, short HTML, 2022-01-02



Is the greyness any different between those two dates? Or just the size/weight?

Cross-reference points (d) and (g) in FreeBSD bug 261104 – new handbook website format, multiple problems


----------



## eternal_noob (Jan 11, 2022)

Zirias said:


> Which means just nothing in practice.


Not true. Screen readers used by blind people still get confused by them. If you use frames, you lock out disabled people. That's why they are obsolete and the use is discouraged.



grahamperrin said:


> Please, can we have discussion of `<frame>` and `<iframe>` in a separate topic?


Should be allowed to discuss technical issues concerning the handbook here. Or is this thread only meant for eye-candy stuff?


----------



## grahamperrin@ (Jan 11, 2022)

grahamperrin said:


> As far as I can tell, neither is relevant to the FreeBSD Handbook (or, more broadly, the FreeBSD site).





eternal_noob said:


> concerning the handbook



As far as I can tell, neither is relevant.


----------



## eternal_noob (Jan 11, 2022)

Yet. Nip it in the bud.


----------



## Crivens (Jan 11, 2022)

Instead of, ahem, aguing over this - has anyone asked what a blind person might say to this?


----------



## grahamperrin@ (Jan 11, 2022)

Crivens said:


> to this?



To frames and iframes that are not used?


----------



## freezr (Jan 11, 2022)

As a dumb user I would say the new handbook is missing definitely a searching function,or at least I couldn't find where this is locate.

Is it a known issue?

It is difficult finding topics if you don't know or don't remember where those belong to...


----------



## grahamperrin@ (Jan 11, 2022)

tgl said:


> … the new handbook is missing definitely a searching function,



For a range of FreeBSD pages (not the Handbook alone):

<https://www.freebsd.org/search/#web>

For a verbatim search of the English edition of the FreeBSD Handbook, short HTML pages:

`https://www.google.com/search?q=STRING+site%3Adocs.freebsd.org%2Fen%2Fbooks%2Fhandbook%2F&tbs=li%3A1#unfucked`

replace the word `STRING` with the string of characters that you want to find.



> or at least I couldn't find where this is locate. …



Partly related: FreeBSD bug 261039 – The /search/ page is useful, but obscure


----------



## drhowarddrfine (Jan 11, 2022)

Google has or had a free service you could easily attach to any web page for searching your site.


----------



## grahamperrin@ (Jan 11, 2022)

drhowarddrfine said:


> Google has or had a free service you could easily attach to any web page for searching your site.



I guess that DuckDuckGo was chosen to avoid complaints about Google. 

<https://www.freebsd.org/status/report-2013-09-devsummit.html#Documentation>
<https://github.com/freebsd/freebsd-doc/commit/35a4e5ba7f2b4bb098c51d9f8dee21c6f6a7bd12>
<https://github.com/freebsd/freebsd-doc/commit/f595e3118ea1c5e1e39a14f812b30f12709f1b03>


----------



## bsduck (Jan 12, 2022)

tgl said:


> It is difficult finding topics if you don't know or don't remember where those belong to...


Use the Single HTML version rather than Split HTML and you don't need anything else than Ctrl-F 

No need for Google nor any of my fellow ducks.


----------



## drhowarddrfine (Jan 12, 2022)

grahamperrin said:


> I guess that DuckDuckGo was chosen to avoid complaints about Google.



His post suggested there was no search or it was a poor one. I mentioned Google but should have mentioned DDG also provided the same.


----------



## grahamperrin@ (Jan 12, 2022)

Also (back to page 1) PDF


----------



## freezr (Jan 12, 2022)

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:


https://www.google.com/search?q=STRING+site:docs.freebsd.org/en/books/handbook/&tbs=li:1#*unfucked*
Use the Single HTML version rather than Split HTML and you don't need anything else than Ctrl-F
A search field above the left TOC will greatly improve the UI/UX, making the content easily skimming.


----------



## grahamperrin@ (Jan 12, 2022)

Sorry, I know the word is generally offensive, but it _is_ technically the method that's required to get *verbatim* results.


----------



## zirias@ (Jan 12, 2022)

eternal_noob said:


> Not true. Screen readers used by blind people still get confused by them. If you use frames, you lock out disabled people. That's why they are obsolete and the use is discouraged.


Sure, you can just strip any context (yes, this was about the fact frames _are_ used nevertheless, even with examples), just to get the chance for your "not true". 

But hey, at least attach a questionable argument 

For once, "iframe" is not obsoleted and creates the exact same issues. And then, for a *screen* reader, it doesn't matter what HTML rendered that separately scrollable area. For a tool working _on the html_, supporting any kind of "frame" is no rocket science, the problem is just to understand the logical structure again.



eternal_noob said:


> Should be allowed to discuss technical issues concerning the handbook here. Or is this thread only meant for eye-candy stuff?


There is no technical issue. Someone was talking about the TOC in a separate "frame", I just noted it's nice no actual `<frame>` element was used for that. AND I think it improves usability, no matter how it is implemented.


----------



## eternal_noob (Jan 12, 2022)

Zirias said:


> Sure, *you can just strip any context* (yes, this was about the fact frames _are_ used nevertheless, even with examples), just to get the chance for your "not true".


I didn't strip away context, the "not true" was a reaction to your statement that using frames "means just nothing in practice."

If you like it or not,
Frames are no longer part of HTML. Because of limited support and difficulty in making them accessible and highly usable, frames should typically be avoided.


> Those using screen readers cannot quickly scan the contents of multiple pages. All of the content is experienced in a linear fashion, one frame at a time. Frames are not _inaccessible_ to modern screen readers, but *they can be disorienting*.


----------



## zirias@ (Jan 12, 2022)

eternal_noob said:


> I didn't strip away context, the "not true" was a reaction to your statement that using frames "means just nothing in practice."


You did, exactly from that statement. The context made clear it was about the _usage_ of frames.



eternal_noob said:


> If you like it or not,
> Frames are no longer part of HTML. Because of limited support and difficulty in making them accessible and highly usable, frames should typically be avoided.


I like it, a lot. As should also be obvious from the context given in my original post.

But it seems you fail to see that the same "disorientation" occurs with some scrollable "div". It's just as impossible for the screen-reader to tell how it relates to the logical document structure as if it was created by an actual "frame" (or: "iframe") element.


----------



## Erichans (Jan 12, 2022)

tgl said:


> [...] It is difficult finding topics if you don't know or don't remember where those belong to...


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


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:
> 
> 
> https://www.google.com/search?q=STRING+site:docs.freebsd.org/en/books/handbook/&tbs=li:1#*unfucked*
> ...


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?


----------



## freezr (Jan 12, 2022)

Erichans said:


> I agree.



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 Manual
					






					docs.blender.org


----------



## grahamperrin@ (Jan 13, 2022)

Erichans said:


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



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.



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:



Nice. 



grahamperrin said:


> 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 (Jan 13, 2022)

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 (Jan 13, 2022)

grahamperrin said:


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


----------



## drhowarddrfine (Jan 13, 2022)

kpedersen said:


> Historic information can be useful since FreeBSD does build on decades of work.



In fact, many of us keep old books around from decades ago because the information is more readable (doesn't sound like a marketing pitch for some new method) and sticks to the fundamentals.


----------



## freezr (Jan 14, 2022)

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@ (Jan 14, 2022)

tgl said:


> the documentation page doesn't have any search function





grahamperrin said:


> Partly related: FreeBSD bug 261039 – The /search/ page is useful, but obscure


----------



## grahamperrin@ (Jan 16, 2022)

covacat said:


> all font awesome intended glyphs don't render properly (use inter font)



Fixed: 




– 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


----------



## giorgiob (Jan 16, 2022)

Zirias said:


> I personally think the old styling looked much nicer


Is there an option to generate the documentation using the old style? Then one could build the documentation locally, if one wants to.


----------



## kpedersen (Jan 16, 2022)

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.


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)

More and more I like to shed my dependence on a web browser and this is a good step.


----------



## grahamperrin@ (Jan 16, 2022)

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.



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


----------



## giorgiob (Jan 16, 2022)

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)
> 
> More and more I like to shed my dependence on a web browser and this is a good step.


Thanks, that looks quite nice.


----------



## Terry_Kennedy (Jan 21, 2022)

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)


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


----------



## grahamperrin@ (Jan 21, 2022)

FreeBSD bug 261370 – Book menu: no longer working



Terry_Kennedy said:


> … downloadable documentation has been getting stale …



255972 – Non-HTML formats for articles and books are not being created
– blocking 258078 – Outdated documentation (including the FreeBSD Handbook) in PDF

For the packaged FreeBSD Handbook:





Also (bug reports pending):


----------



## kpedersen (Jan 21, 2022)

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


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 (Jan 21, 2022)

kpedersen said:


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

```
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
```


----------



## tux2bsd (Jan 21, 2022)

jbodenmann said:


> ... with selection of the _"Dark"_ theme at the bottom of the handbook page.


on the left, it's far less obvious than it should be.


----------



## rotor (Jan 26, 2022)

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!



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.


----------



## carlavilla (Feb 4, 2022)

So, after reading all the posts. The remaining things are:


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.
Add more resources to the resources section, like pdf, long html, etc
Search in the book menu to filter chapters
An index per book
Change gray font color to white
Increase the font size in the ToCs
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.


----------



## grahamperrin@ (Mar 1, 2022)

A few FreeBSD bugs:

258078 – Outdated documentation (including the FreeBSD Handbook) in PDF maybe fixed confirmed fixed
259494 – FreeBSD Handbook glossary and colophon detached from the Handbook
262228 – Horizontal scrollbars only visible at end of section when viewing wide sections of the FDP primer in split-HTML mode with 150% zoom
262269 – FreeBSD documentation sidebar content can not be revealed with the scroll bar for the sidebar
262270 – FreeBSD documentation scroll bars: visibility, accessibility
262271 – FreeBSD documentation: please consider having sidebars to the left, not the right, of content with reference to <https://forums.freebsd.org/posts/549007> on page 2 of this topic
262274 – FreeBSD Handbook: Abstract: remove FreeBSD Mall
262661 – FreeBSD documentation: long HTML: references to items within the same document should not switch away (to short/split HTML)
The closest I could find to 262228 in the context of the FreeBSD Handbook was long HTML <https://docs.freebsd.org/en/books/handbook/book/#reservedip6>, where the table is wide, but generally OK in both HTML and PDF.

Nearby <https://docs.freebsd.org/en/books/handbook/book/#_background_on_ipv6_addresses> _sometimes_ goes bonkers with a fall to the foot of the book in response to me manually resizing the window in Firefox:



– however this is *not* consistently reproducible; maybe an issue with my heavily-extended default profile for Firefox.


----------



## grahamperrin@ (Mar 19, 2022)

freezr said:


> … basic HMTL … tested … with Netsurf …



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

FreeBSD bug 262660 – FreeBSD documentation: a table of contents should be near the head, not the foot


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



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


----------



## freezr (Mar 29, 2022)

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


----------



## drhowarddrfine (Mar 29, 2022)

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



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.


----------



## kpedersen (Mar 29, 2022)

freezr said:


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


I think it is similar on Linux (fdisk) and Windows (diskpart), just using an interactive mode which I don't think gpart has:

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


----------



## freezr (Mar 29, 2022)

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 (Mar 29, 2022)

freezr said:


> 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@ (Mar 30, 2022)

freezr said:


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



freezr said:


> … 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@ (Apr 21, 2022)

roper said:


> … 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 (Apr 22, 2022)

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


----------



## grahamperrin@ (Apr 23, 2022)

Another quote from discussion of the FreeBSD Handbook: 



skunk said:


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



carlavilla said:


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



 carlavilla thanks again for the many and varied improvements.


----------

