Page MenuHomeFreeBSD

handbook/x11: refactor
Needs ReviewPublic

Authored by ziaee on Aug 9 2024, 12:50 AM.
Referenced Files
Unknown Object (File)
Mon, Apr 7, 1:08 PM
Unknown Object (File)
Wed, Mar 26, 10:33 PM
Unknown Object (File)
Fri, Mar 14, 10:21 PM
Unknown Object (File)
Fri, Mar 14, 10:15 AM
Unknown Object (File)
Mar 10 2025, 10:50 AM
Unknown Object (File)
Feb 24 2025, 11:58 AM
Unknown Object (File)
Feb 19 2025, 4:20 PM
Unknown Object (File)
Feb 9 2025, 11:53 PM

Details

Reviewers
carlavilla
Group Reviewers
Doc Committers
doceng
docs
x11
Summary

This chapter is has been getting neglected. Shame, because this is very stable and now that linux has moved to Wayland, upstream has become very agreeable to supporting us. Further, X11 is much lighter and more responsive than equivalent Wayland setups that I've seen. Here is a draft attempting to fix this chapter.

Rendered: https://people.freebsd.org/~ziaee/tmp/handbook_en.pdf#x11-synopsis

Rough changelog:

Graphics

+ drivers logically come first, and explain why we have to install them
+ intel graphics is not always integrated and not always cards
+ clarify whats the vaapi driver package

Xorg
+ disambiguate Xorg server/X Window System
+ xorg-ins should directly precede xorg-cfg
+ try to tersely explain why at more points
+ autoconfiguration should not be a warning in a previous chapter,
  it needs to be part of the introduction to configuration
+ explain why we have xf86-input drivers, there are good use cases for them

Fonts
+ sort and sync fonts intro
+ truetype fonts are what most users are looking for, for screens.
+ postscript fonts are specialized for typography, for printing.
+ therefore, move truetype first, and explain the difference.

Pointy hat for whoever removed XDM:
- XDM Just Works (every single time)
- it is the lightest solution
- it is cfg'd in a very traditional manner consistent with xterm
- there is a massive trove of info and example cfg
- it has literally been stable for generations
- no X11 DM has been left here in it's space!
- forgetting to take it out of the synopsis makes everything look crusty

Outstanding:
+ yes, abstract at the top is not correct style. I am not trying to merge it like that, this is very much a draft.
+ the fonts section really needs more love. I don't like removing information, but this has become very simple for the user. Just drop the font in .fonts, done.
+ I think the xorg configuration section could possibly say something guiding people to the desktops section.
+ ...the whole thing could still be a little clearer.

Test Plan

Proofread PDF located at doc/documentation/public/en/books/handbook/handbook_en.pdf generated with make pdf-books DOC_LANG="en" HUGO_ARGS="--verbose --debug".

Test these instructions!

Diff Detail

Repository
R9 FreeBSD doc repository
Lint
Lint Skipped
Unit
Tests Skipped
Build Status
Buildable 62879
Build 59763: arc lint + arc unit

Event Timeline

ziaee requested review of this revision.Aug 9 2024, 12:50 AM
ziaee created this revision.

Removed duplicated warning after testing and proofreading.

Found a few straggler typos, sorry for the noise.

ziaee edited the summary of this revision. (Show Details)
ziaee edited the test plan for this revision. (Show Details)

Additional attempting to clarify more of the instructions. It's still WIP, but appreciate any general feedback.
Thanks @bcr for showing me the testing instructions! Proofreading the rendered output is massively easier!

Next revision will include increased detail about fonts and configuring touchpads with libinput, however I am really hoping to fix this problem at what I perceive to be the root with upstream manpage.

Some language and typo fixes.

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

s/so this is/which is why/

219

s/accellerator/accelerator/

291

s/to video group/to the video group/

617

s/breif/brief/

Alexander88207_protonmail.com added inline comments.
documentation/content/en/books/handbook/x11/_index.adoc
178

There are two Intel acceleration drivers where the users have to chose one depending on the hardware that they are using.

libva-intel-driver
libva-intel-media-driver

It might be also worth to mention that libva-intel-driver is deprecated / an discontinued project.

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

Sorry i didn't update this. My draft has come very far but is maybe not ready for review. Carlavilla removed this block because it's discontinued on the latest current handbook.

vishwin added inline comments.
documentation/content/en/books/handbook/x11/_index.adoc
178

The deprecation statuses et al for Intel graphics-related auxiliary software is kind of weird. Each implementation only supports a range of graphics hardware generations, and they tend to overlap somewhat. Even when they discontinue active development or support of one of the software, for those who have hardware that the newer software don't support, they still point users to the "older" software.

Here's my current draft, I am not suggesting this is mergable currently,
maybe parts of it are, but here's just what I've got so far in case
anyone is interested in this issue.

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

It sounds like I need to figure out which one is for which generation and write something? They are necessary parts of the driver, right?

ziaee edited the test plan for this revision. (Show Details)
ziaee edited the summary of this revision. (Show Details)

A few minor edits. Good job on this section.

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

s/be//

410

Space at end of line.

415

configuration.

795

s/catagory/category/

797

Space at end of line.

806–807

Consider "displaying on".

829–835

s/There are p/P/

ziaee marked 11 inline comments as done and 2 inline comments as done.

Thanks Jim, these are all great!

carlavilla added a subscriber: carlavilla.

I think you can commit it, if there's an improvement, we can change it later.
Thanks for all the improvements.

This revision is now accepted and ready to land.Feb 24 2025, 10:01 PM

One problem that keeps me from wanting to merge this, is that the Xorg FreeType Module has not existed in at least 15 years, but I can't really find any information about that to rewrite the relevant areas.

I've been hacking on this a while, here's what I've got so far.

This revision now requires review to proceed.Mar 12 2025, 4:42 AM
documentation/content/en/books/handbook/x11/_index.adoc
135

Consider bolding the bulleted term to make it stand out and separate it from the surrounding text:

  • *Direct Rendering drivers*, allowing PRIME offloading.
  • *Kernel Modesetting (KMS)*, the technology provided...
  • *User Modesetting*, the oldest class of drivers is still supported. However...
136–137

Consider fully explaining PRIME here as this is the first time most readers will have come across the term. An example -

"PRIME refers to a mechanism for offloading rendering tasks between different GPUs in a system. It is primarily used in hybrid graphics setups such as laptops with both an integrated GPU and a separate, discrete GPU for heavier rendering tasks. The X11 PRIME framework is designed to let multiple graphics devices work together efficiently."

BIOS modifications may be needed in some systems."

185–186

Consider
"... to the following showing either UEFI or BIOS:"

345

Consider suggesting that the user reboot at this point. This does two things - 1. It validates the above procedures are correct for the user's system, and 2. It loads the necessary driver(s) and the user is ready for the the actual install coming up in the next section.

392

It is at this point that the user can know things are working or not working.
Consider instructing (instead of suggesting) the user to run startx(1), and show a sample image for confirmation:

"Test the existing setup by running startx(1). If everything is working correctly, the tmw(1) window manager should appear as shown in the following image."

[insert twm image here]

"If the command is successful, place the cursor in the large terminal window on the left and type Ctl-D. This will cause the twm window manager to exit.

If the command is not successful, read the next section for additional configuration options.

Also, consider how to start X11 every time - manually with startx(1) or use a display manager to start a graphical login on boot."

403

If the previous instructions to try startx(1) were successful, consider giving the user the option of skipping the X.org Configuration section and moving directly to desktop selection and configuration - maybe moving lines 380-381 here.

It's good reference material, but there's not much to be gained in mucking around in xorg.conf files unless you really need to.

414

Consider referencing other authoritative sources for configuring Xorg configuration files, or at least make the user aware that such resources exist.

468

On my lenovo T530, with 14.1 (fresh install) there is no "intel" driver installed with the drm-kmod package. There is an older Intel driver with the "xf86-video-intel" package, but it is not installed by default with the "drm-kmod" package.

792

Fonts are a visible attribute, so somewhere in this section consider explaining how to install a tool (or use existing desktop tools) to display fonts. Older applications like xfd(1) can be installed to display all glyphs in a font, but there are probably better applications.

829

Consider whether this is redundant with lines 811-812