Help talk:Laptop page guidelines

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)

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 F1–F12. -- Flyingpig (talk) 16:52, 5 May 2021 (UTC)

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)

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)

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)

I'm two year late to the party, but maybe we should create a template like Template:Laptops table header for this one?

I feel like "Labelled" would be easier to understand that "Marked" to ask if a key has a legend on it or not, but without a template it's going to be a lot of manual labor to update all the pages with a "Function keys" section :/ The bonus would be that like Template:Laptops table header, we could add legends to each headers with an explanation of what's expected where.

Thoughts? Erus Iluvatar (talk) 12:22, 4 April 2024 (UTC)

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)

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)

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)

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)

Add a requirement to list all the needed firmware packages

As Arch splitted the linux-firmware package into several ones, I think it is worth to list all the needed specific linux-firmware-… packages explicitly in the "Installation" section.

This topic was originally raised in the Add "Vendor" column to "wikitable archwiki-table-laptop" conversation with @Erus Iluvatar.

Example: Dell Inspiron 13 (5378)#Installation. Ok, not really good example because of two consecutive links, I mean the "linux-firmware-atheros Linux firmware" part.

— Andrei Korshikov (talk) 15:06, 15 August 2025 (UTC)

I don't think it's necessary to make it mandatory, but hinting at it is probably good. In the Installation guide we have not changed the wording and still point people to the meta-package, so it's probably not a requirement to list the specific firmware needed if it's a dependency of it.

-- Erus Iluvatar (talk) 08:17, 16 August 2025 (UTC)

Totally agree. I was thinking about "best practice" or just "recommendation", but have chosen the wrong word. Not a "requirement" or "mandatory option", of course. Tip—in a plain text or {{Tip|…}}—is enough IMO.

— Andrei Korshikov (talk) 10:41, 16 August 2025 (UTC)

I'm unsure if Help:Laptop page guidelines#"Installation" section is the best place for the hint at listing firmware packages needed by some hardware. I would have thought it belonged more logically in the respective device sections, maybe in the note from Help:Laptop page guidelines#List of common parts ?

-- Erus Iluvatar (talk) 09:47, 12 November 2025 (UTC)

Well… in principle I agree, but… It's kinda "the only list vs spreading different items (maybe sometimes duplicated?) in many subsections". Ok. Here is my preferred solution (at this moment):

• Put everything into "Installation"—it will ease installation process: everything needed for installation is present in one place.
• Add links to all appropriate "common parts" sections if they exist. E.g. if I mention linux-firmware-atheros linux-firmware-atheros and "Wi-Fi" and/or "Bluetooth" sections exist, then I should mention them (kinda "see "Wi-Fi" and "Bluetooth"").

Aha, finally, I see the root cause of this question. Not every laptop has all these "common parts" sections, but it may need to have special firmware even if it does not have appropriate "common parts" section.

Ok, these are my current (wild:) thoughts. I don't know how to express them as a wiki recommendation right now)

— Andrei Korshikov (talk) 19:19, 28 January 2026 (UTC)

This sounds good as it would help reduce the number of single-sentence hardware sections (e.g. for Audio the regular "Install Sound Open Firmware to get audio working." and nothing else).

We would need to adjust simultaneously the instructions in Help:Laptop page guidelines#"Installation" section and the note at the end of Help:Laptop page guidelines#List of common parts. I'll come up with a draft tomorrow.

-- Erus Iluvatar (talk) 17:54, 29 January 2026 (UTC)

As usual with wiki time, "tomorrow" turned into "a week later", but here's the drafts, I slightly changed my mind on which note needed the mention. --Erus Iluvatar (talk) 10:58, 8 February 2026 (UTC)

Draft

Note in "Adding hardware information"

Note

• If any part requires special instructions (outside of installing the necessary firmware: relevant packages should simply be listed in the "Installation" section), you are encouraged to add a section just for this part.
• Unfortunately it clutters the page when using certain standard sections, so avoid using Known issues, Tips and Tricks and Troubleshooting.

"Installation" section

This section should contain information that is necessary to install Arch Linux on this device. This includes, but is not limited to:

• Kernel parameters
• Important firmware settings (also see #"Firmware" section)
  • This does not include obvious settings like changing the boot device.
  • It is encouraged to link to relevant posts in the forums, like this example post focusing on an issue with Dell devices.
• If a device needs a special firmware to work, list its package here (e.g. an audio device that would need Sound Open Firmware).
  • If the firmware might impact the installation process, for example an AUR package for network connectivity, make that requirement prominent.

Omit this section if there are no quirks that need to be addressed.

Order of hardware components ("common parts")

As you definitely noticed, our hardware tables are a bit chaotical. I don't like it for two reasons.

At first, when the same visual element ("hardware table" in our case) looks different in different places the whole wiki part feels unprofessional?… amateur?… I'm not sure if I know the word, but I hope you see the point. It's kinda "created by crazy students".

At second (and this point is way more important IMO), random order means that we have to read the whole list every time. No way to skim/skip. I don't know polite words to describe my feeling when I have to read a random list over and over again :D

I've tried alphabetical order in Dell Inspiron 13 (5378) but I don't really like it: Audio is the first. wtf?! I do not care about the Audio!

My current suggestion: put the most important part(s) (GPU?) to the top, place other parts in alphabetical order.

What do you think?..

— Andrei Korshikov (talk) 20:36, 3 September 2025 (UTC)

I'm suggesting we copy the order of the linux-hardware probe, as arbitrary as it sounds the order "feels" right to me :P

-- Erus Iluvatar (talk) 08:03, 4 September 2025 (UTC)

Aha, I see the root of the "chaos":D (well, "chaos" in my perception:))

Anyway, my point is simple—the wiki is for readers, and, especially, newcomers—hardcore professionals read the source code:DD (or, at least, manual pages…)

So, our current "order" is convenient for hw-probe copy-pasting, but is not convenient for a person who is not aware about hw-probe or just bought their brand new laptop and wants to install Arch first time.

— Andrei Korshikov (talk) 19:23, 6 September 2025 (UTC)

I'm OK with defining a different order, but that means more churn to try to get older pages into shape, as many people create new pages by copying the existing one for the older model.

What did you have in mind as the "logical" priority of components? The one used by Template:Laptops table header (i.e. Video/Sound/Ethernet/Wi-Fi/Bluetooth)?

-- Erus Iluvatar (talk) 13:51, 1 October 2025 (UTC)

get older pages into shape

I can automate it. I have general knowledge about MediaWiki Action API (I use pure API requests for getting wikitext), so e.g. I could look at wiki-scripts and learn something new.

"logical" priority of components

My only thought was "GPU should be the first", I did not have another good suggestions. I'm OK with Template:Laptops table header, i.e. in our case it would be: GPU (Intel), GPU (NVIDIA), Audio, Ethernet, Wi-Fi, Bluetooth, other components in alphabetical order.

— Andrei Korshikov (talk) 13:16, 3 October 2025 (UTC)

Sold! I'm not clever enough to figure out the automation so I'm happy to see you can handle it :) Erus Iluvatar (talk) 10:28, 12 October 2025 (UTC)