FreeBSD Handbook Gets a New Layout

grahamperrin

Son of Beastie

Reaction score: 1,050
Messages: 3,528

grahamperrin

Son of Beastie

Reaction score: 1,050
Messages: 3,528

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
%
 

Trihexagonal

Son of Beastie

Reaction score: 2,430
Messages: 3,008

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>
 

drhowarddrfine

Son of Beastie

Reaction score: 2,507
Messages: 4,453

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

Son of Beastie

Reaction score: 2,248
Messages: 3,076

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

Son of Beastie

Reaction score: 1,050
Messages: 3,528

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

grahamperrin

Son of Beastie

Reaction score: 1,050
Messages: 3,528


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

grahamperrin

Son of Beastie

Reaction score: 1,050
Messages: 3,528

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
 

eternal_noob

Daemon

Reaction score: 921
Messages: 1,207

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?
 

Crivens

Moderator
Staff member
Moderator

Reaction score: 1,747
Messages: 2,589

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

tgl

Active Member

Reaction score: 40
Messages: 105

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

Son of Beastie

Reaction score: 1,050
Messages: 3,528

… 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
 

grahamperrin

Son of Beastie

Reaction score: 1,050
Messages: 3,528

tgl

Active Member

Reaction score: 40
Messages: 105

grahamperrin

Son of Beastie

Reaction score: 1,050
Messages: 3,528

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

Zirias

Son of Beastie

Reaction score: 1,786
Messages: 3,033

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

Daemon

Reaction score: 921
Messages: 1,207

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

Son of Beastie

Reaction score: 1,786
Messages: 3,033

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