Hello Rafael,

Re: https://marc.info/?l=openbsd-tech&m=174492674026422

Rafael Sadowski wrote on Fri, Apr 18, 2025 at 05:26:20PM +0200:

> I think the idea is good, I would like to have native speakers and/or
> the docs wizards look over it.

Before commit, please apply on top:

-<h2 id="libva">Video Playback Acceleration with Libva</h3>
+<h2 id="libva">Video Playback Acceleration with Libva</h2>

because the closing H3 tag mismatches the opeing H2 tag.

I don't have the slightest idea whether this is accurate or helpful,
but i trust you when you say that it is.

From a documentation perspective, i deem the quality of the patch
tolerable, if it is true that this does not work out of the box
for some users, the patch slighly improves the situation.
So i think you should go ahead.  In general, with documentation,
you can be a bit more aggressive than with code.  When you are
confident that information is missing, you are confident where
to put it, and you are certain you know the truth, you can often
simply put it in, and if needed, it can then be polished in the tree.

This patch does not seem particularly good.  There are some questions
that seem obvious to me and that the patch provides no help with.
Please put it in anyway, it can be polished in subsequent steps.

 * You say Xenocara has libva support, meaning the library is part
   of the base system.  In general, we want the base system to be
   documented.  I do see the directory /usr/xenocara/lib/libva/,
   and that directory contains significant amounts of code, for
   example more than 20 C files and almost 100 header files.
   Ideally, your new FAQ entry should link to the manual pages
   for libva on man.openbsd.org,
 * How do i find out whether i have an AMD or an Intel card?
   I suspect this might have something to do with inteldrm0(4)
   or radeondrm(4) showing up in dmesg(1) - but even i am not
   really sure - maybe intel(4) or amdgpu(4) is more closely
   related?  Would it make sense to link to the most closely
   related manual page?
 * How do i find out the generation of my Intel GPU?
   For example, using the web, i guess that "Intel HD Graphics 5500"
   in the dmesg(1) indicates that i have a generation 8 card -
   but ideally, understanding the FAQ should not requires
   searching the web.
 * So i tried "pkg_add intel-media-driver"
   and now i see:
    $ pkg_info intel-media-driver
      Comment:
      VAAPI driver for Intel HD 5000 (Gen8) or newer
   Is that "Gen8 or newer" at odds with the "generation 5 or newer"
   in the new FAQ entry?
   Does anything need to be restarted?
 * "the binary package tools" sounds a bit wordy and vague.
   Maybe just link to pkg_add(1)?
   Linking to FAQ 15 is certainly not wrong, but unless you want
   to point to a rather unusual task specifically discussed in
   FAQ 15, for a completely normal and simple purpose, the manual
   page seems at least as relevant as the FAQ.
 * Even if this entry is added to the FAQ, i do not think i would
   ever have found it.  Unless i totally misunderstand, this is purely
   about hardware support, and having to manually install packages(7)
   to get hardware support feels unusual to me, and somewhat in
   violation of the principle of sane defaults.
   Why is some hardware only supported after manually installing
   a package?  Is there a downside to using the package?
   For example, does it pose security risks?  That would
   explain not having it by default.  But then i would expect
   a warning in DESCR or MESSAGE.

Yours,
  Ingo