The doc mentioned that sha256 for images is available at

http://alpha.de.repo.voidlinux.org/live/current/sha256sums.txt

But the files are named respectively sha256.txt and sha256.sig now. I don't know if the doc must be updated or the file renamed on the server.

Good topics to cover:

• diagnosing broken shlibs issues
• verifying that the repositories are configured correctly

This came up yesterday in the IRC channel, there are a number of default groups that void ships with that are currently not really documented.

I think a section in the docs that describes what each group does would be good to have.

You can create a virtualpkg to install a different version of the kernel without breaking dependencies. There should be a cannonical method documented for this.

virtualpkg=linux:linux5.6 in `/etc/xbps/newerkernel.conf?

We have a section on updating Void, but no discussion on how to troubleshoot common error messages when the update fails.

For example, removing orphans with xbps-remove -o sometimes resolves the "unresolvable shlibs" error that occurs when attempting xbps-install -Su.

The old wiki has some discussion about a related but different problem as well.

https://docs.voidlinux.org/xbps/repositories/mirrors/list.html

http://alpha.de.repo.voidlinux.org EU: Germany
Replace with Finland

http://beta.de.repo.voidlinux.org EU: Germany
Delete since it doesn't exist anymore.

The 'PulseAudio' section of the Handbook states:

There are several methods of allowing PulseAudio to access to audio devices. The simplest one is to make use of the audio group.

The wiki suggests that this means adding the relevant user to the 'audio' group. Is that correct? If so, i'll open a PR to add that information.

https://docs.voidlinux.org/installation/live-images/downloading.html#verify-image-authenticity links to the Void GPG key, which errors out with 404 right now (https://alpha.de.repo.voidlinux.org/live/current/void_images.asc). We should probably reword this part.

@the-maldridge I'm not sure how to explain this one. Should I just remove the mention about it being possible to download the asc file from that link?

Will there be an applications section? For example docs for getmail, mpv and other applications?

Something like -> https://wiki.voidlinux.org/Applications

From https://docs.voidlinux.org/installation/live-images/guide.html:

"Boot your machine from the install media you created. If you have enough RAM, there is an option on the boot screen to load the entire image into ram, which will take some time but speed up the rest of the install process."

Could it be said how much RAM is needed? I have an old computer with only 2 gigabyte of RAM. Is it worth to load the entire image into RAM? Right now we as users don't know. A recommendation here would be nice.

In this section the table looks borked. I don't know what causes it, maybe because the table has only one column?

The docs have reached a pretty good level of maintenance, and I'm glad to see the high quality bar that has been maintained over here. Lets start putting together a plan to once and for all EOL the wiki server. I want to reclaim those resources and reassign them to putting a mirror back in Germany, something we desperately need since the German intranet is very sad as of late.

Lets target end of August for me to shut down wiki.voidlinux.org and reclaim the resource into the pool. By that time lets grab any information that's worth saving.

@Duncaen to assist in this process can you make the wiki R/O on August 1?

Cf. @Johnnynator's comment on /r/voidlinux here.

This repo needs an automatic style check and ideally an auto-formatter. Now taking suggestions.

I noticed that there are some incensistencies in the title casings for headers. Some are capitalized on only the first word, some on all of them, and some others etc.

We should decide on a style and add it to the style guide; we should then comb through the existing documentation and bring it all up to speed.

I've described an issue I encountered at bobertlo/vmd/issues/7. In the meantime, this issue resulted in a successful travis check even though it should not return 0.

The NetworkManager page is empty. It should be written or removed.

Please add a guide explaining how to do Full Disk Encryption. There is This guide and This guide.

It would be nice to be able to explain some Void specific issues with doing this, and to have a recommended way to do Full Disk Encryption.

This is a bit ambitious and requires some discussion on the best way to proceed, but having a void-docs package available could be interesting for having access to offline documentation (without having to clone a git repo) and, more importantly, for including in the live images.

What we'd have to decide:

• How to package? Package all markdown files or convert them into some other format? Would this conversion keep them readable? How would the navigation work?
• How to version the package? When would we have new docs releases? Definitely when someone builds new live images, but only updating the package then seems bad practice.

Inspiration from this taken liberally from starting a DragonFlyBSD installation and having a README right there on the root dir.

Please extend guide about NetworkManager in docs with the info from "Wireless (NetworkManager, no window manager present)" from wiki.

• Add info that you need to create file /etc/polkit-1/rules.d/50-org.freedesktop.NetworkManager.rules.
• Add info that permission must be at least 644: chmod 644 /etc/polkit-1/rules.d/50-org.freedesktop.NetworkManager.rules (missing in the wiki).
• Add info that user should be in network group.

I was installing fresh void installation on my laptop and spent a lot of time debugging this issue. I kept getting errors that user is not authorized to manage network connections.

Source: config/xorg/index.md

This needs to be written by someone with knowledge of the subject, and it's not clear what needs to be covered in the first place. Attempts so far have filled out bits of the documentation (such as #38) but topics like using dbus-launch, ConsoleKit2, elogind, and other programs / services probably merits enough depth so that it's clear to users what the right thing to do is.

It'd also help to collect examples of previous questions (from reddit, the mailing list, IRC, etc.) and their solutions (when available) to figure out what troubleshooting problems come up.

• Skip to content #61
• unbind mdbooks arrow key bindings? I think this could interference with users who use the keyboard/arrow keys to navigate web pages.
• sitemap? not supported by mdbook.

Can/should we provide a single-page version of the Handbook? A user on IRC asked if there was one, and it seems to me that it would make it easier for users to search for particular terms within the Handbook.

Related: the above user noted that it was annoying to go to a page in the Handbook and find that it contained only a brief overview of the section. In a single-page version, i imagine this would be fine; but if we started adding ToCs for subsections (cf. #234), that might end up being unwieldy in a single-page version.

@ericonr, @bobertlo, thoughts?

I am trying to port everything needed from the wiki to the docs over time. Can I get some input on what should be ported first? I am trying to finish up steam, and docker, then will be moving on to whatever else is deemed most important. Is there anything not to port from the wiki?

Currently most links to man pages follow [page(section)](https://man.voidlinux.org/page.section), there is one exception I know of, the init(8) link on in about.md, it uses a link and "code" inside of the link text.

I personally prefer to keep it simpler and just use links.

It would be nice, if the Xorg sections would be expanded to contain the basic setup of a Xsession and how it is hooked up to either xinit/startx or a display manager. I really had issues with this when I was setting up my first minimalist Linux installation.

I know, that this is highly distro agnostic, but I think of it as an entry point for new users. (A starting point for more detailed research, so to say)

Following the wiki, installing gnome and enabling the gdm service does not work. I have been able to figure it out, but not document the process. You definitely need to also install xorg and xinit. Also I think elogind is required?

The main issue is that if you don't have everything right and start gdm it locks up. I have been adding gnome-session to my xinitrc and making sure it works, then gdm seems to be able to work? I also would touch /etc/sv/gdm/down and sv once gdm to test before getting things to work for sure.

I need to do more VM testing before trying to write up anything, but I think this would be useful information. We don't want people "breaking" their systems.

Is there any reason not to remove the "WEP configuration" subsection? As far as i'm aware, WEP is way past deprecated.

So, usually package installation is presented as the whole xbps-install command, but something that the Arch wiki actually does right IMHO is just list the packages that people have to install and hyperlink the word "install" to the guide about installing packages. That feels more concise, at least to me.

This also goes for enabling services. There are instructions for enabling dbus, for example, all around the docs. Wouldn't it be better to just mention "make sure that the dbus service is enabled" and link to the services page as well? That's what the NetworkManager page does, while the IWD and Bluetooth page both have the ln -s /etc/sv/dbus /var/service command.

This is not a really big issue, but it would be interesting if we could define some sort of guidelines around writing docs and keep a consistent style. Whatever decision is made, I can port the current pages to that (or not, if it's deemed unnecessary).

There is no definition of the scope of these documents, as was discussed on IRC. What should be included and what should not?

There seemed to be an agreement that these documents should be a manual for the setup and administration of void systems, and generally excluding how to use upstream software aside from documenting idiosyncrasies presented by void.

I think it would be useful to formalize this. Specifically with a definition of scope near the style guide and probably a less formal note near the how to read section explaining that we are not rewriting upstream application documentation, nor are we compiling a collection of links to said documentation which is easily found by the user.

This will be especially important if we make an open call for contributors. Those of us who have contributed seem to have similar use cases for void and similar opinions on the docs, but new users who can document software we aren't knowledgeable with may have very different ideas of what this manual is.

My goal with this issue is not to define policy, but to open a discussion.

@Duncaen mentioned this in irc and I think it is a good idea. Right now we have a short quick usage guide in the header of the Configuration > Services and Daemons section. I think a possible layout could be:

- Configuration
   - Runit
      - Starting/Stopping Services
      - Configuring Services
   - Services and Daemons
      - Cron
      - ...

With an explaination of what runit is and why it is used in the heading, but I am very open to discussion on that point. There's probably a third and better solution?

Especially in the context of people viewing Void Linux as an "anti-systemd" distro, I think we could mention how we are more "pro-runit" and dropped systemd promarily over compatibility issues.

I plan to start working on this, but am looking for input on how to handle this. There are SO many installation guides on the wiki, with SO much duplication. My proposal is to create a fleshed out "advanced installation" guide, along with other specific guides, which will only offer differences from the main guide.

Advanced Installation Guide

This guide will detail "manual" installation from start to finish, more in the style of the "live image installer" guide. This guide would be formal and fleshed out, mentioning alternatives to the given procedures. Topics would include:

• preparing and mounting partitions
• manually installing a system with xbps-install
• basic configuration of the system afterwards, up to the point of being able to use the rest of the manual.
• bootloader: only cover "regular" bootloader in this guide for BIOS/UEFI systems

Alternative Installation Guides

These guides will in every instance possible just reference the "main" advanced installation guide, and not duplicate those steps. They will only present changes to that procedure, and enough context for the user to be able to follow what is happening. Initial topics could include:

• encrypted disks
• raspberry pi
• other embedded systems
• dual booting
• alternative bootloaders
• etc

Proposed Process

1. Write a minimal installation guide. It should cover anything needed to go from nothing to a working system, but not try to cram everything from the wiki into it. A minimum viable product to manually install a system.
2. Write Alternative Guides for specific use cases and hardware, referencing them as needed from the main guide.
3. ???
4. Profit

For various reasons, I am no longer able to maintain a mirror in South Korea

with a quick look at wireshark upon connecting to the internet
connman updates connection stats over HTTP to ipv4.connman.net using GET requests

I'm not sure if this is a local server or what (traffic was only sent when ethernet was connected)
but anything that uses web technology is insecure and prone to WAN hacking

after a bit of research, it appears connman is Intel technology, so yeah, wouldn't be surprised if it's found Intel is actually spying.
(wouldn't be the first time they've done so)

also, while I do highly recommend removal from the docs, I also recommend removal from the repos.
normally I wouldn't go this far and recommend as such, since I support FOSS and ~OSI,
but there's at least 2 things against connman that make me consider otherwise:

• if the TCP/HTTP connections are indeed spying, then connman is a virus.
• web technologies don't adhere to the security attitude of BSD and are purely preferential.

I was goaded into the lightweightedness of connman from the docs which is why I installed.
(it's only a 32bit machine with 2GB of RAM)

if I had to recommend a replacement, network-admin seems much more viable:

if there's anything wrong with this though, I'll happily retract this recommendation ;)

Articles like GNOME and Plasma, among others, are not available at https://docs.voidlinux.org/

If I can help in any way I will be happy to do so. I ask for help from the community to make the documentation better and more complete in all aspects.

I had a perplexing issue where I had an application which would play sound, but not show up in pavucontrol, and would not play sound if pavucontrol was open. The solution to this - i linked a bunch of other services so I don't know if it was just this and really I should experiment before submitting this PR - was to install the alsa-plugins-pulseaudio package and restart pulse, may be worth adding to the docs

Might it be useful to port the Musl page on the wiki (or at least some of it) across to the Handbook, and mention things like the gcompat package?

As suggested in #225 (comment).

After somewhat lengthy discussion on IRC, I'd like to record it here. The proposal is to try and make a single section (possibly even a single page) as reference for all applications that aren't installed via xbps.

This page would:

• Be "probably in the installing section, near the existing documentation for nonfree" and "with a paragraph explaining the distinction between nonfree, non-distributable, and proprietary closed-source". @the-maldridge
• Refer to the resticted packages that can be built locally with xbps-src. It's a section that already exists in the docs. @flexibeast
• Tell people to try and use flatpaks for most of their external needs, especially when proprietary (we might need to document flatpak too, if people have issues with it). Probably list a few applications that flatpak allow people to use. @bobertlo
• Explain that some language package managers, such as pip and gem (#185) can require the respective devel packages for those languages (so python-devel and ruby-devel) in order to build some libraries. This can be even more relevant when using a musl build.
• If void-linux/void-packages#20735 is accepted, include information about it and how people can use xtools to extract that single file from the package, without installing it. Perhaps even make another xtool for that? To go along with xmandoc.

What we need, AFAIK:

• write the actual page
• decide if it's going into an existing section or if it's going to be its own section
• consider moving some docs to their respective packages

I wrote this right before going to sleep, so if there are any egregious mistakes I can correct them in a bit.

I am looking to port this page over from the wiki https://wiki.voidlinux.org/Applications
but I am not sure where to put it. Should there be an applications section?

I setup PCI passthrough on voidlinux by using various r/voidlinux reddit posts. I would like to formally document the process.

• Installing required packages
• Document isolating video card for pci passthrough (dracut and grub)
• Loading amd/intel iommu
• Document configuring virt-manager

Extra:

• Configuring scream for painless audio

@HadetTheUndying can maybe review the guide.

void-linux/void-packages#17225 must be merged before I can begin this guide.

The guide would only feature void specific issues when configuring PCI passthrough and link to archwiki for anything that's more general.

Is this guide appropriate for the handbook?

In the section on shells, oksh is listed, however on my system I get a message stating oksh is being removed from the repos. It seems to have been superseeded by loksh, which is not listed in the docs. This suggests to me that the docs are slightly outdated in this regard.

I have tried to create a PR to fix this, but something is broken along the line and it doesn't seem to be working.

Looking at the PR #41 it seems that the CUPS pages (config/install) are overlapping. I don't think that all of this information belongs on one page, but restructuring this section would be very helpful. There seems to be installation and configuration information mixed between both pages and, in some cases, duplicated.

Accessing the docs normally works great, but for some reason the "Maintenance" page still exists and is accessible. It even has its own outdated index.

https://docs.voidlinux.org/maintenance/index.html

https://docs.voidlinux.org/maintenance/repositories/mirrors/list.html -> this page has the added issue of showing outdated mirrors. Could be related to #200

A number of Handbook pages are simply introduction pages for subsections. Such pages should, after the introductory text, contain a 'table of contents' listing those subsections. For the purposes of having a consistent style, and to possibly facilitate data transformation (e.g. to address #243), the format of such ToCs should be:

## Section Contents

- [section name](path)
- [section name](path)

Base system requirements doc is either misleading or lacking information. It says EM64T CPU is required for 64-bit, but that's Intel only and implies that AMD CPUs are not supported. This needs clarification.

I took these values straight off of the wiki. I can only assume they were somewhat stale. It would be nice if these were tested, and especially with some context of what can be done with these minimal stats.

Sorry guys, I'm trying not to make too many doc issues,
but I keep finding stuff I've been advising against for years now :/

in here, you mention setting the default index in alsa.conf

... if you have 1 and only 1 sound card, then the issue doesn't concern you
but if you have 3 or more sound cards, then you may find yourself with shuffled devices

editing /etc/modprobe.d/alsa.conf only sets the preferred card index,
it doesn't prevent your sound cards from changing order on boot.
something that does help that though is editing /etc/modprobe.d/alsa-base.conf and specifying the order you want your drivers to load in, as mentioned in this old cringe-worthy askubuntu answer here
(ignore the comment in that answer, it actually does work)

there's something though that this won't fix
if you have multiple devices using the same driver in your system, and your preferred device is one of them, specifying the driver order will not stop your devices under that driver from shuffling about every reboot...
the only thing I can think of that would stop that is to disable the devices that aren't preferred
or take the cheap solution and use a device that uses a different driver as the preferred device.

not all apps allow you to specify an alsa device, and even some that do don't always work appropriately (utox)
so you're better off relying on a preferred device under alsa. ;)

TIP: if you're like me and rely purely on alsa for audio
these utilities are very helpful:
qastools volumeicon
QasMixer provides full control over your sound devices (better than Pulse)
volumeicon adds an interactive icon that allows you to quickly control your volume (useful for xfce)

the 1 disadvantage this has from Pulse is you can't control individual app streams
but for that you gain 2 advantages:

• if your card has separate mic-in and line-in ports, you can make use of both ports as they were intended to be used without configuration (pulse can only make use of 1 input and needs explicit loopback enable/disable)
• you don't run the risk of dropping all audio output when your CPU gets busy (pulse requires a system reboot)