FreeBSD Handbook Gets a New Layout

[Cath O'Deray]

If I recall correctly

Moments in time:

<{link removed}> – FreeBSD Porter's Handbook, long HTML, 2021-08-16

<{link removed}> – FreeBSD Handbook, long HTML, 2021-09-15

<{link removed}> – FreeBSD Handbook: Glossary, short HTML, 2021-12-12

<{link removed}>– FreeBSD Handbook: Glossary, short HTML, 2022-01-02

 

[Cath O'Deray]

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]

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]

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]

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

 

[Cath O'Deray]

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 \
%

 

[Cath O'Deray]

"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 {link removed}). Whilst not overtly side-stepping the many and varied requirements of the FreeBSD Documentation Project (FDP) {link removed}:

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

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

• ePub
• long HTML
• long PDF
• edit this page
• install documentation

…

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.

 

[Cath O'Deray]

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

<{link removed}> – FreeBSD Handbook: Glossary, short HTML, 2021-12-12

<{link removed}>– 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 {link removed}

 

[eternal_noob]

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.

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?

 

[Cath O'Deray]

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

concerning the handbook

As far as I can tell, neither is relevant.

 

[eternal_noob]

Yet. Nip it in the bud.

 

[Crivens]

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

 

[Cath O'Deray]

to this?

To frames and iframes that are not used?

 

[freezr]

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

 

[Cath O'Deray]

… the new handbook is missing definitely a searching function,

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

<{link removed}>

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

{URL removed}

• 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 {link removed}

 

[drhowarddrfine]

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

 

[Cath O'Deray]

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.

<{link removed}>
<{link removed}>
<{link removed}>

 

[bsduck]

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]

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.

 

[Cath O'Deray]

Also (back to page 1) PDF

 

[freezr]

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.

 

[Cath O'Deray]

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

 

[zirias@]

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.

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]

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@]

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.

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.