Help:Laptop page guidelines

This article unifies the style and layout of all laptop pages and introduces guidelines and standards to ensure laptop pages are and remain high quality. This ensures that pages do not devolve to just dumps of the lspci/lsusb output or a user's personal notes about their device.

General

Add an appropriate category to the page, for example Category:Dell. If there is no category for your vendor, create one.

The page name should be "Vendor model number", for example "Lenovo ThinkPad X1 Carbon".

Do not create a redirect which just omits the vendor name, for example "X1 Carbon" or "ThinkPad X1 Carbon".

Tip: If you do not know what your page should look like, Dell Latitude 3500 is an example page which follows these guidelines.

Do not duplicate content from the general Laptop guidelines. A section just containing e.g "The webcam of this device works fine" will not help anyone, so do not add a section if there are no special instructions for it. Also avoid mentioning desktop environment or window manager specific content. This also applies to other things that are documented in the ArchWiki, e.g do not include instructions on how to flash the archiso to a USB-stick, just link to the page containing the instructions. This will result in less maintenance required.

Adding hardware information
Warning:
  • Keep all of the lines as short as possible because a wide table is hard to read and makes the page look disorganized.
  • Make sure the table is above the preface or introduction or the position of the table will change.

Add a table with style="float: right;" at the very beginning of the page with the following columns:

  1. Hardware
    1. It should contain the short name of the part, like "Bluetooth" or "Fingerprint reader".
    2. Only append the name of the vendor to the part if there are more than one. A common example for this would be more than one GPU (see table below).
    3. Consider running hw-probe to make the full set of hardware known to the Linux Hardware Database.
  2. PCI/USB ID
    1. It should contain the PCI or USB ID of the part, if available. This is important because some laptops may have varying hardware.
    2. lsusb shows the USB ID by default, but lspci must be run with -nn in order to obtain the PCI ID of devices.
      1. If there is a PCI/USB ID without a name, consider contributing the part to the PCI ID repository or USB ID repository respectively.
    3. If there is no applicable PCI/USB ID for this device, leave the column empty. Do not put Template:-, dashes or anything else into the column.
  3. Working?
    1. It should contain Template:Yes or Template:No. If these are not applicable, use Template:Y and a fitting, short description of its status, like "Untested" or "Partial".
      1. Use "Partial" when the part still does not work correctly with applied modifications.
    2. Use Template:Yes even if you need to install an external driver or if configuring this with device-specific parameters enhances its functionality.
Tip: If any part requires special instructions, 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", "Troubleshooting" and "Tips and Tricks".

Kernel module information

Do not put kernel module information into the table or a separate section for the part. This is usually pointless because there is only one module for this part. This does not apply if there are different drivers to choose from, but this has to be specified in the section for the part, not the table.

Example table

The following code will be displayed like the example on the right: 

{| class="wikitable" style="float: right;"
|-
! Hardware !! PCI/USB ID !! Working?
|-
| Bluetooth || {{ic|1234:abcd}} || {{Yes}}
|-
| Webcam || {{ic|abcd:1234}} || {{No}}
|-
| GPU (Intel) || {{ic|8086:0000}} || {{Yes}}
|-
| GPU (NVIDIA) || {{ic|10de:1111}} || {{No}}
|-
| Other part || {{ic|0000:aaaa}} || {{Y|Untested}}
|}
HardwarePCI/USB IDWorking?
Bluetooth1234:abcdYes
Webcamabcd:1234
GPU (Intel)Yes
GPU (NVIDIA)10de:1111
Other partUntested

List of common parts
  • Bluetooth
  • Webcam
  • Ethernet
  • Wifi
  • GPU
  • Touchpad
  • Keyboard
  • TPM
  • Fingerprint reader
  • SD-card reader
  • Speakers
  • Microphone
  • Ambient light sensor

Since all laptop pages should contain a hardware table floating right, the use of Template:Related as described in Help:Style#Related articles box is substituted with using only the "See also" section or direct links inside relevant sections to avoid right-floating elements clashing with each others.

"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 for installation, for example an AUR package for network connectivity, make the requirement prominent.

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

"Accessibility" section

To help disabled users install Arch Linux on the device, add some accessibility info. This includes, but is not limited to:

  • The appearance of the firmware. Consider settings required to change in order to boot an official Arch Linux install medium.
    • Newer firmware interfaces may be more difficult to parse with OCR software on phones, which blind users frequently use as daily tools. If there is an option to revert the default design to the "classic" design, add instructions for it.
    • Some firmware even require the usage of a mouse and/or is overly complex. If it is not possible to change settings without eyesight, add a note describing this. For example:
    • Some firmware interfaces may use radio buttons and tightly packed menus extensively, which might prevent users with Parkinson's disease from changing certain settings.
  • Refer to a relevant section of the official manual (see #"See also" section) for your device that contains a list of all the shortcuts needed to navigate the firmware and to trigger certain actions, like changing the boot device.
    • If such a manual does not exist, you can add a list to the section instead.
  • Some devices may have a diagnostic LED, which visualizes beep codes. This is useful for deaf users.
    • Add a note if there is only a diagnostic LED, but no beep codes.

"Firmware" section

The page should contain a short note describing the fwupd support for this device.

A page should include a firmware section, when there is special behavior the user should be aware of. This includes, but is not limited to the following:

  • Certain optional firmware settings that can enhance the compatibility of this device
  • Firmware quirks that can impact the installation
  • Secure Boot information
    • Do custom keys work well on this device?
    • Are there any special firmware settings one needs to change for this?
    • Are there any other specialties the user should be aware of?
  • Does the firmware store recovery images or logs in a special path? This is important to know when choosing the size of an EFI system partition.
  • Sometimes it is crucial to update the firmware because it fixes critical bugs. If there are any important firmware updates, mention it in this section.

"Function keys" section

Add a table with the following columns:

  1. Key
    1. The key one needs to press. They usually start with
  2. Visible?
    1. Use Template:Yes or Template:No, depending on whether tools like can see this key.
  3. Marked?
    1. Use Template:Yes or Template:No, depending on whether the physical key has a symbol on it, which describes its function.
  4. Effect
    1. Usually, function keys emit a key or the firmware does something when the key is pressed.
    2. Specify the key when a key is emitted, like XF86MonBrightnessDown.
    3. A key may have a special effect which should be mentioned, like hard blocking network devices.
    4. Do not add desktop environment/window manager specific instructions.
    5. There are some keys that will be bound by systemd-logind by default, which should be marked (see table below).

Capturing function keys

It is possible to capture function keys using () or wev (). There is also but since many Wayland compositors use , the Xorg-specific names are preferred.

Desktop environments and even some window managers may come with a default configuration which swallows all the function keys, since it is handling them by itself. Temporarily use a minimal window manager like Openbox to capture the keys if this is the case.

Some function keys (such as ) may be bound to , which means they can not be captured with any tool by default. Use to temporarily suspend the handling of certain keys:

# systemd-inhibit --what=handle-suspend-key sleep 1h

As long as this command is running, will ignore these button presses and properly capturing the button press is possible.

Example table
Key Visible?1 Marked?2 Effect
Fn+EscNoYesToggles Fn lock
YesYesXF86AudioMute
YesYes
Yes3Yes
NoNoFitting description
  1. The key is visible to and similar tools.
  2. The physical key has a symbol on it, which describes its function.
  3. systemd-logind handles this by default.

"See also" section

This section should contain helpful links which include, but is not limited to the following:

  • Related other external wiki pages, like the ThinkWiki.
  • Official manual pages provided by the manufacturer, which can be helpful when debugging firmware issues.
  • certification.ubuntu.com pages, which can be a useful source for PCI/USB IDs and hardware variations.
  • A link to the Linux Hardware Database probe, which provides information about compatibility and PCI/USB IDs.
gollark: r/idonotknowreferences
gollark: *suddenly notices that a random AP egg he picked up is `orW1N`*
gollark: ||s||||p||||o||||i||||l||||e||||r||||s|||| ||||a||||r||||e|||| ||||f||||u||||n||||!||
gollark: Why the ||spoilers||?
gollark: All hail balloons, the best dragons.
This article is issued from Archlinux. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.