FreeBSD Handbook Gets a New Layout

the complete TOC

Here:

1641747698589.png

Code:
% 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
%
 
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:

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

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

+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 pagedoes 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:

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.
 
Can we try setting the text colour in the left column/Chapters to black instead of 68% mid-grey please? …𒀦


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
 
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?
 
Instead of, ahem, aguing over this - has anyone asked what a blind person might say to this?
 
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...
 
… 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
 
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.
 
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.
 
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.

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