Add section for Wayland in the x11 chapter

[trhodes]

Summary

This change:

• Adds a section about installing Wayland to FreeBSD;
• Adds subsequent sections covering three compositors (Wayfire, Sway, and Hikari);
• Works like a quick start guide covering major configurations and getting a screen lock working;
• Adds a small section on Wayland utilities that might be useful.

Would like feedback on:

• Anything else to add;
• Check the flow of the information;
• Validate I'm using the new tools properly;
• Added Glen in case I can push this in before release. :P

Test Plan

This patch fully builds, has been proofread, and tested.

[pauamma_gundo.com]

documentation/content/en/books/handbook/x11/_index.adoc

1966

Should this be under X Window, or a chapter of its own? Having the former when the section begins with "not the same at all" feels awkward.

1972

1 sentence per line, and s/utilize/use/ (the latter being arguably taste).

Clarification request: I have no idea what "Wayland can manage composite communications between clients and a compositor" means. What are composite communications? Didn't you imply above ("intermediary between clients using a different mechanism") that the compositor was a client too? (In that case, perhaps ise "between applications and a compositor" or, if only one compositor can run on a given computer, "the compositor".)

1974

It's what, 13 or 14 years old now? I would rewrite that in terms of "not all software has native support" or some such, without mentioning its age.

1975–1977

Is the description of architectural differences the right place to discuss a start-up option?

1985

s/And a/A/

1989

Does the comma after May need to be here? I thought it was only used when a day was present, like "May 8, 2021".

1990

Again, this seems to be about using it - or perhaps describe support by existing DEs - so perhaps divide the whole Wayland section into general description and support by other software, installing, using, and troubleshooting? (Assuming that content is present below - getting ahead of myself.)

1995

What's that functionality, and why would I want to use it or not use it?

2007

I have no idea what that means, not even enough to try guessing possible intended meanings.

2017

Since there was a discussion of (I think) several compositors earlier, this may be already part of the installing section if you go along with my suggested division.

2018

Bourne. And sh(1) isn't the Bourne shell anyway, so I'd change this to man:sh[1].

2033

s/the tmpfs file system/man:tmpfs[4]/
s/command and/command;/

I'd also add an example to keep the user from guessing or fumbling, perhaps

tmpfs /var/run tmpfs size=(whatever) 0 0

(check my syntax, and I have no idea how much to give it - du says it uses 59K on my laptop, but that doesn't include metadata, and my use case (X11+XFCE) has little in common with Wayland.)

2034

Since you mention ZFS, I assume this is an alternative to tmpfs. I'd make that explicit.

2035

Which scenario, tmpfs or ZFS+XDG_RUNTIME_DIR?

2039

For traditional X11 managers such as Plasma and GNOME , seatd is not needed, but ...
s/need enabled/need to be enabled/ (may confuse non-native readers)
Is a compositor environment the same as a compositor? Or is it the Wayland equivalent of a DE?

2040

s/now,/now/

2048

I thought from the description at the start of this section that a compositor was more lie a X server? Or did you mean "compositor environment" here?

2055

Beauty is in the eye of the beholder.

2074

Famous to who? I have no idea what that is.

2080

Please tell me there's a way to autoconf like with xorg.

2086

s/hertz/refresh rate/ (Or is that the dot clock? I don't know what unit it uses. kilohertz? millihertz?)

2116

Is it usable as a compose key?

2119

s/nless/Unless/

2129

s/was/is/g maybe?

2130

s/the default/default/

2143

s/valuable enough/used often enough/ (if that's what you mean, otherwise clarify)

2152

s/maybe/may be/

2165

Be sure to back up [.filename]#wayfire.ini# so all changes can be restored.

[pauamma_gundo.com]

Pausing now, will look at the Sway section later.

documentation/content/en/books/handbook/x11/_index.adoc

2175

One sentence per line.

I'm confused at the terminology here (having never heard of hikari before), so someone trying this for the first time will likely be as well. If "views" are windows, I'm not sure why use another word than the one consecrated by usage.

And I understand, sort of, that a sheet and a group are both a collection of windoows, but what is the difference between them and why does it matter?

2175–2176

Aren't the last 2 sentences saying the same thing?

2178

Link to a specific manual page.

s/utilizing/using/ (or better, with)

2179

The/This Hikari installation

s/comprise of/contain/ (or better, "use")

I'd make alacritty package:x11/alacritty[] for consistency.

2193

"To start configuring Hikari, create..."

2211

"the key bound to it" maybe? And which key is that?

2212

s/it should be noted/please note/

2213

It it L or L+Return? (Also, isn't "Enter" the preferred name?)

By "is actually", do you mean you just need to press the Windows logo key and Enter? Or the Windows key+L letter key chord?

"previously discussed" where? If you mean in "using the bound key press", I would call that a mention, not a discussion.

2214

I'd just call it "the Windows key" or maybe "the left Windows key", consistent with question 11.5 in https://docs.freebsd.org/en/books/faq/#X11.

2215

"requires"

"to be created for each"

2238

s/button/key/

2240

Link to specific manual page (I assume man:hikari[]).

s/documentation it should be read/documentation; read it/ (or at least s/documentation/documentation and/).

2244

s/kbd:[L] (Windows logo key)/kbd:[Windows]/

2245–2246

Without some explanation of how (and why) to mark a view public or not public, this is confusing and probably not useful here.

If they're hidden, how can they expose sensitive information?

2247

It's discussed in the next section, not this one. Also, an intradocument link would be good.

[pauamma_gundo.com]

One thing this is sorely lacking is accessibility options. The three areas that need a mention are:

• sticky keys: for some people (eg, those with motor disabilities affecting fine motor control, arthritis, or other joint problems including various forms of joint pain) holding the Windows, pressing and holding shift, and finally pressing return isn't an option.
• screenreader support.
• voice control for people unable to type at all.

Done with sway (for the first read-through anyway), XWayland is next, after a message from our sponsor.

documentation/content/en/books/handbook/x11/_index.adoc

2267

I'd suggest "For a basic configuration, make your own copy of the default sway configuration file and edit the copy:"

2295

"The example above loads... and sets..." (and at the risk of repeating myself, I'd just call that key "the Windows key").

2296

"Next, it selects alacritty as the terminal emulator and defines a screen lock command, as explained in more detail below." (with "as explained in more detail below" a link to where you explain more).

2297

output "My Workstation" mode 1366x786@60Hz position 1366 0
output * bg ~/wallpapers/mywallpaper.png stretch

From this, I assume you mean something like:

The first output line sets the video mode and position, and the second sets background wallpaper and stretches it to fill the screen.

This leads me to the following questions:

• What does "My Workstation" represent?
• Can I tell Sway to use the largest display size the hardware support and if so, how?
• If I can't do that, how do I find the exact parameters to supply? That is, how do I go from

VT: Replacing driver "efifb" with new "fb".
start FB_INFO:
type=11 height=1080 width=1920 depth=32
cmsize=16 size=8294400
pbase=0xb0000000 vbase=0xfffff800b0000000
name=drmn0 flags=0x0 stride=7680 bpp=32
cmap[0]=0 cmap[1]=7f0000 cmap[2]=7f00 cmap[3]=c4a000
end FB_INFO

(or whatever excerpt from /var/run/dmesg.boot holds the relevant info) to what I would need to use instead of "mode 1366x786@60Hz position 1366 0"?

2301

Link to the actual manual page you mean.

2302

s/customing/customizing/

2304

s/the Windows logo key (mod)/kbd:[Windows]/
s/the kbd:[d] key/kbd:[d]/

2305

Swap around to active, eg "Use the keyboard arrow keys to navigate the men.u"

2306

"See man:sway-bar[5] for information on setting the layout of the bar and adding a tray."

2318

s/using the combination of holding the Windows logo key/by holding the Windows key/

2319

"Installing Sway from a package or using the (magic words for link to section 4.5) the FreeBSD Ports Collection also installs a default man:pam.conf[5] file under [.filename]#/usr/local/etc/pam.d#."

2321

I'd remove that sentence unless you mean something else than the pam.conf manual page. (If you do, link.)

2323

s/logo //

BTW, you can use kbd: for key combinations: see https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#ex-kbd.

[pauamma_gundo.com]

Done with the first round. For the second one, if you don't use https://wiki.freebsd.org/Phabricator#Create_a_Revision_via_command_line_.28if_using_git.29 but prefer https://wiki.freebsd.org/Phabricator#Create_a_Revision_via_Web_Interface, can you make sure to use -U999999? That way, reviewers should be able to suggest changes directly instead of through a long seriess of s/foo/bar/.

documentation/content/en/books/handbook/x11/_index.adoc

2346

Maybe explain why -devel? What are the pros and cons, eg for someone who privileges stability over features?

2347

Either "way to (en|dis)able" or "method for (en|dis)abling"

Also, since the reader presumably wants to use it with their compositor, they likely care about enabling more than disabling, if at all about the latter. I wouldn't mention that - or not here anyway.

2359

s/recommened/recommended/

2367

s/build/built/

2368

A link to the ports section would be good.

2386

s/use // maybe?

2411

Why wayland-1 here and :0 above?

2415

Is that a trou

2421

Should be "grep X11" (or "grep -i x11") to output the lines below.

2424

s/ information//

2440

Can you confirm it should be run as non-root?

2445

Missing ]

2447–2452

Is that displayed in the terminal window where the failed instance was run? /var/log/Xorg.(mumble).log? Both?

2490

Does the wayvnc documentation explain how to generate them? Are there any extra utilities involved?

2492

s/overwritten/overridden/ unless you really mean running the server will change the file contents.

2502

Trick I learned from hanging around on Wikipedia: add "2022" or "February 2022" to help readers ask or check whether that's still true.

2504

I would remove at least this sentence, lest the reader think they should request that and flail because they have no idea how or who the port maintainer is. I would also consider removing the previous one, but I'm less positive there.

2509

Comfort levels vary, but having to change /etc/gettytab and /etc/ttys isn't what I could call "minimal".

2517

s/,/;/
s/import/important/

2533

Where will it appear? ttyv1? Will vt switch to that automatically the way it switches to ttyv8 when running xdm -nodaemon on it in /etc/ttys?

2535

s/At minimal/At a minimum/

2539

s/setting ttyv0 up/setting up ttyv0/ (or better, "using ttyv0").

kbd:[alt+F1] should work. Same as the Windows key combo above.

2542

s/swap/scroll/ maybe?

Do you mean "compositors"? I thought, based on the above, that Wayland didn't have window managers.

Also, "supported"? Did you mean "installed"?

2550

"supporting"? Does waybar use PulseAudio?

2575

[.programlisting]

2582

Will it always be eDP-1? I have no idea what that is, other than the first of several similar lines in /var/run/dmesg.boot on my laptop.

[bcr]

Any update on this? Would love to show the world that FreeBSD supports Wayland to the degree that is described here.
We can then add stuff later once we already have a basic handbook chapter.

[pauamma_gundo.com]

In D32436#791757, @bcr wrote:

Any update on this?

Are you and I waiting for each other to do something, or are you asking someone else?

[bcr]

In D32436#791966, @pauamma_gundo.com wrote:

In D32436#791757, @bcr wrote:

Any update on this?

Are you and I waiting for each other to do something, or are you asking someone else?

In general. There were some changes proposed which would still need to go into a new patch.
But I'm thinking if they are not too critical, then we should think about getting a Wayland chapter into the handbook in the first place and the do the fixes in a followup commit. That would not stall this initiative (having the info in a public place) and also enable others to contribute their own work.

[pauamma_gundo.com]

In D32436#792520, @bcr wrote:

In general. There were some changes proposed which would still need to go into a new patch.
But I'm thinking if they are not too critical, then we should think about getting a Wayland chapter into the handbook in the first place and the do the fixes in a followup commit. That would not stall this initiative (having the info in a public place) and also enable others to contribute their own work.

I think https://reviews.freebsd.org/D32436/#inline-212355 (I think it would break doc build), https://reviews.freebsd.org/D32436/#inline-212373 (same) and https://reviews.freebsd.org/D32436/#inline-212353 (command and output text inconsistent) need to be fixed before committing this. https://reviews.freebsd.org/D32436/#inline-212362 probably should as well, as it feels misleadingly incorrect to me. Others may be able to wait for a follow-up, but I don't see the benefit of doing that, since this needs some changes anyway IMO.

documentation/content/en/books/handbook/x11/_index.adoc

2415

I think I meant "a troubleshooting section", or maybe "a troubleshooting question/paragraph/whatever".

[trhodes]

Sorry - I am always so busy, then I tell myself to look at this and never do because something always comes up in life. Anyway, how about I submit a new review where the section is migrated to a new chapter? Then we can continue improving and adding to a chapter instead of a section. I should have free time this weekend. Thanks! And sorry I go missing all the time! :(

[trhodes]

Since a few people requested this be put it a single chapter, I created D35099. There are no content changes with this change, it just moves the current version to a single chapter. Then, I would like to work with everyone who has made comments here and make sure they are addressed. Thank you for your patience with me, my free time is not as abundant as we would like.

[2khramtsov_gmail.com]

I moved on to D35099.