Help talk:Laptop page guidelines

From ArchWiki
Latest comment: 24 June 2022 by Erus Iluvatar in topic Accessibility

Report special keys with function keys?

Should special keys like “power button” or “wireless switch” be included in the function keys table, if they reports events which can be captured by xev? If so, how should I name them? Dell Latitude 3500 example does not show them. -- Audeoudh (talk) 14:41, 5 May 2021 (UTC)Reply[reply]

I would say no. The function keys table is meant for function key combinations, so I wouldn't include keys or combinations that didn't otherwise involve Fn or F1F12. -- Flyingpig (talk) 16:52, 5 May 2021 (UTC)Reply[reply]
I would also say no. Function keys mean that they are (usually) invoked with Fn. Some laptops do have a wireless switch which is a function key (usually XF86RFKill) though. Feel free to add an extra section if the power button is problematic.
--- NetSysFire (talk) 16:59, 5 May 2021 (UTC)Reply[reply]

Couldn't the function keys table standard be a lot better?

Both as a reader and writer I find the current function key table standard to be quite terrible.

It uses poor wording (Visible and Marked both imply the exact same thing)

The 'Effect' column is meant to reference the key's assignment by the system, but this does not make sense when the system's default assignment for the key is wrong.

There is no column indicating whether or not the key works, I imagine the 'Effect' column was meant to be for that, but as I mentioned before, it makes no sense.

I would like to propose a new standard table that makes, at least to me, a lot more sense:

Key Detected Labeled Working Effect
Fn+NumPad0 Yes Yes Yes XF86AudioMute
Fn+Down Yes Yes Yes XF86MonBrightnessDown
Fn+F8 Yes No Yes XF86WLAN
Fn+F9 Yes No Yes XF86Bluetooth.
Fn+F5 Yes Yes Partially Eco Mode/XF86Battery
Fn+F7 No Yes No Fitting Description

Key: Same as before

Detected: Same as what visible used to be

Labeled: Same as what marked used to be (Marked works too, but I feel like labeled makes more sense linguistically since we usually talk about keyboard labels and not markings)

Working: Does the key work or not?

Effect: What is the intended effect of the button? (As opposed to the default system assigned effect, since these keys are sometimes wrongly assigned)

There are also no longer question marks in the table, because they're superfluous in the first place.

Additionally, perhaps there should be standards for corner cases (for instance when a key is detected, but only when a specific kernel parameter is set a certain way, or if the key works, but only after it is manually given the correct assignment, or if the key is detected and can be assigned but doesn't work as intended by manufacturer (manufacturer specific keys that require specific applications, usually on windows, to work, yet are still detected on Linux and assigned keysyms properly), when a key is working as intended thanks to hardware detection but not actually detected by the kernel, etc)

Rabcor (talk) 03:31, 19 September 2021 (UTC)Reply[reply]

It seems you misunderstood what Visible is. As described in Help:Laptop page guidelines#Example table 2, Visible means if the key is visible to the kernel. Marked means if there is a physical marking on the key, e.g a waxing moon on the sleep key.
Changing marked to labelled would be fine.
I would not like an additional "Working" column in the table because it is redundant. If it is visible, it should™ work in most cases. If a key is not visible without an appropriate kernel parameter, note this in the section but put the result in the table you would see if it is appropriately configured.
The information in the laptop pages should not be relevant to only specific DEs or even WMs. If it is visible to the kernel (Visible) column, it suffices. Since there are no defaults in Arch Linux and every user is encouraged to customize their system, defining the intended purpose of a key is hard. However, this would not apply if the keymap is all mixed up for some reason and needs additional configuration to work, e.g when there is a "Brightness increase" label on say F1 but it emits Play/Pause, which it would not do on Windows.
-- NetSysFire (talk) 02:53, 20 September 2021 (UTC)Reply[reply]
I'm already confused by having two columns for function keys, three columns would definitely be too much. -- Alad (talk) 08:26, 20 September 2021 (UTC)Reply[reply]
I still think 'detected' makes more sense, e.g. it is 'detected' by the kernel. The kernel does not have eyes, nothing is technically speaking visible to the kernel.
For future reference, this is the relevant section for the model I am using MSI_GE75_Raider_8SX#Function_keys
Also, when you say "it should™ work in most cases.", that's the real kicker isn't it? What about the cases where this is not the case? My keyboard backlighting buttons are function keys, the kernel does not detect them, but they fully serve their intended purpose. What about airplane mode? I don't know if it is detected by the kernel or not, but it is not detected by X, yet it fully works (disables wifi and bluetooth as it should).
For that matter, how confident actually are you that this is what it's like for "most cases"? This might be the case for older laptop models, but manufacturers keep doing weird stuff to their laptops these days. The current standard may be fine for older models, but for new models we're almost definitely gonna be seeing more and more corner cases until the reality will be that for "most cases" the situation will not be as simple as you are describing.
We often see these kinds of shenanigans with 'gaming' branded laptops these days, and such laptops while they might not be the majority they are definitely not rare.
Whether we use the standard I suggested or not, I don't think there's much question about it that we need the standard to cover cases where the button works but is not detected by the kernel. And cases where the key is detected and assigned some keysym but cannot serve it's original purpose (like with my laptop's Turbo and Eco mode buttons)
I'll perhaps give you that it's true that for most keys the current standard covers all that's required. Because most keys are standard keys that have standardized functions which can be detected and correctly by the kernel.
But there are cases where the key is detected by the kernel but wrongly assigned, and there are several examples of that even on my laptop. And there are cases where the keys are fully functional without being detected by the kernel, however the hell that can happen anyways. The normal keys may be more common, but these kinds of cases are certainly not going to be rare among a certain category of laptops and this needs to be accounted for somehow in the standards.
Or else what am I supposed to do as the writer of that section I linked to? The standard doesn't allow me to cover everything that needs to be covered. That is a problem, is it not?
-- Rabcor (talk) 10:20, 20 September 2021 (UTC)Reply[reply]
As seen in Help:Laptop page guidelines#Capturing function keys, some keys are bound to e.g systemd-logind. You have to tell it to ignore the key or else it will not be visible to you in e.g xev.
I am not sure what keyboard backlight is controlling either, might be a firmware thing in my specific case or the kernel module is interpreting it since I can control the keyboard backlight via /sys.
I'd like to solve the specific problems instead of adding yet another column. In this case it may actually be a difference in kernel modules or configuration, see systemd-backlight@.service (systemd-backlight(8))
-- NetSysFire (talk) 11:59, 20 September 2021 (UTC)Reply[reply]
Well, let me just say first that I have not checked if the systemd-backlight service is doing anything for this laptop or not (i'm rather confident it is not though). But what I have noticed is that these backlight keys work even when I have not booted into an OS (e.g. in BIOS) and that the setting is remembered between boots (e.g. if I set the kbd backlight to full and then reboot, then on the post screen the keyboard backlight will be full). Similarly the keyboard can remember the color profile used between different operating systems (if I configure the lighting scheme on windows, it will remain the same after I boot into Linux too, and on the post screen for that matter.)
As for the systemd-logind thing. We're not talking about a problem that needs fixing here. Or rather, we are, but I already fixed it. I have no motive at present to try to find a different way to fix it, nor do I have a reason to believe or care systemd-logind is related to the initial issue. If you want me to check these things, I will play along... But only if you give me every specific set of commands I need to run to do these checks, because I cannot be assed to dig them up myself since as I said before I have no motive to do so. If you want to do that though, I believe we should move that discussion to the relevant section for the laptop I'm testing it on.
If your only issue is that I didnd't name airplane mode something else, just rename the damn thing into whatever it should be named, the key works so it stands to reason that it is getting correctly assigned, it is safe to do so.
As far as I'm concerened, all these little details are just that, details. The important information is there, it's not in the exact format suggested by the standard which is unfortunate, but as I mentioned, it did not fit within the standard. Whether some key's effect is not labeled exactly correct doesn't matter because the reader will understand what the effect of the key is the way it is currently written anyways, and if someone has a problem with the way it is currently written they are free to rewrite it.
Rabcor (talk) 00:11, 21 September 2021 (UTC)Reply[reply]


Can someone better clarify what parts of this are necessary? I can't find even a single laptop page other than the provided Dell_Latitude_3500 'example' that has this section, yet it seems to be deemed mandatory. Is it enough to denote what the various LEDs do? Inclusion or lack thereof a PC speaker? What do we need here?

Ensayia (talk) 02:28, 25 April 2022 (UTC)Reply[reply]

Hi! Have a look at Toshiba Satellite L300 for an older page that got updated with an accessibility section.
From what I remember, many laptop pages were written before the laptop style rules were set in place, doubled with the fact that the accessibility section was not explicitly marked as required for a while, which explains why many laptop pages are not compliant . On that note, pease flag the pages you find with Template:Laptop style if you can, so that people watching the page or having the hardware can contribute it.
From what I understand, this section tries to answer the question "could a non-sighted person install Arch Linux on it's own" particularly in regards to UEFI settings (sonce it's a place hwere the OS is not yet setup with assistive software), but does not limits itself to only this information (e.g. if the user is deaf, has to troubleshoot and can use LED codes to that end).
--Erus Iluvatar (talk) 06:00, 25 April 2022 (UTC)Reply[reply]
Looking at your example, and the Dell one, both only really indicate that the BIOS may be usable with a screen reader. I've never heard of any accessibility software that works pre-os and searching around online others concur. There are few to no hardware accessibility options on computers, especially modern ones which often lack status LEDs and system speakers. This problem seems to be approached somewhat backward. Is it really necessary to revise every article and slap the same redundant information on it or perhaps limit the accessibility notation to the few machines that might have those features?
-- Ensayia (talk) 12:28, 25 April 2022 (UTC)Reply[reply]
Author of the laptop page guidelines here. I made the accessibility section mandatory recently because many new laptop pages just did not include that one at all, which is unfair to people with disabilities.
With screen reader I specifically mean OCR software here, many blind people use their phone to see. That could be clarified, I agree. To tone down the redundancy it is possible to use templates but since there are not many pages having accessibility information at all, I do not deem this necessary yet. If a laptop does not have any status LEDs, they do not need to be mentioned.
-- NetSysFire (talk) 21:28, 25 April 2022 (UTC)Reply[reply]
I've added the OCR phone example from above[1] and some other small changes. As said above, I think it is useful to distinguish and group related obstacles to boot the Arch install image in the first place, and performing the installation. Also, the suggestion to use an accessibility notation is great. It would be ideal, if the section gives a clear and short overview to distinguish particularly non-/accessible devices. With more examples over time, it is perhaps possible to boil it down to a notation, but it will always be difficult to make perpetual comparable ratings and text is per se pretty accessible.
--Indigo (talk) 22:13, 13 May 2022 (UTC)Reply[reply]
On this topic, I think we could add a few examples of pages where the accessibility section is well written, like System76 Oryx Pro#Accessibility ? --Erus Iluvatar (talk) 19:05, 24 June 2022 (UTC)Reply[reply]