docs: track texinfo export

1 files changed, 1535 insertions, 0 deletions

diff --git a/carbslinux.texi b/carbslinux.texi
new file mode 100644
index 0000000..d99c49d
--- /dev/null
+++ b/carbslinux.texi
@@ -0,0 +1,1535 @@
+\input texinfo    @c -*- texinfo -*-
+@c %**start of header
+@setfilename carbslinux.info
+@settitle Carbs Linux User Manual
+@documentencoding UTF-8
+@documentlanguage en
+@c %**end of header
+
+@copying
+Copyright @copyright{} 2020 Cem Keylan
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts and no Back-Cover Texts.
+A copy of the license is included in the section entitled "GNU Free
+Documentation License."
+
+@end quotation
+@end copying
+
+@dircategory System Administration
+@direntry
+* Carbs Linux: (carbslinux). Carbs Linux User Manual.
+@end direntry
+
+@finalout
+@titlepage
+@title Carbs Linux User Manual
+@author Cem Keylan
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top Carbs Linux User Manual
+
+This is the full documentation of @uref{https://carbslinux.org, Carbs Linux}, from the details of the
+distribution, installation, to the package manager. It is not yet complete.
+
+@ifplaintext
+You can build and install the @command{info} package in order to view this
+documentation with the info reader. It is divided into sections and easier to
+read.
+@end ifplaintext
+
+@ifhtml
+This documentation is also available in the distribution by the
+@command{carbs-docs} package, which can be read by either running
+@code{info carbslinux} or reading @file{/usr/share/doc/carbslinux.txt} with your
+favorite pager. You can install either the @command{info} or @command{texinfo}
+for doing the first.
+@end ifhtml
+@end ifnottex
+
+@menu
+* Installation::                 Installing Carbs Linux
+* Init System::                  Configure the init system
+* Contribution Guidelines::      Contribute to Carbs Linux
+* GNU Free Documentation License:: Your rights
+
+@detailmenu
+--- The Detailed Node Listing ---
+
+Installation
+
+* Preparing Environment::        Getting ready to chroot
+* Chroot::                       Going inside your new system
+* System Configuration::         Customizing your system for personal use
+* Kernel::                       Compiling your own kernel
+* Making your system bootable::  Installing bootloader and boot scripts
+* Post-installation::            Post-installation tasks
+
+Preparing Environment
+
+* Download::                     Download the root filesystem tarball
+* Signature verification::       Verify the signature of the rootfs tarball
+* Extracting the tarball::       Extracting the root filesystem to the desired location
+* Obtain the chroot helper::     Download the script to easily chroot into the new filesystem
+
+Chroot
+
+* Setting up repositories::      Basic setup for obtaining repositories
+* Updating packages::            Update your system
+* Installing packages::          Install new software on your system
+* Essential Software::           Software you might want to include on your system
+* Obtaining the documentation::  Install documentation for offline use (optional)
+
+System Configuration
+
+* Configuring hostname::         Setting up system hostname (recommended)
+* Hosts file::                   Setting up hosts file for networking (optional)
+
+Kernel
+
+* Obtaining the kernel sources:: Downloading the Linux source code
+* Kernel dependencies::          Requirements for building the kernel
+* Building the kernel::          Configure and compile the kernel
+
+Making your system bootable
+
+* Bootloader::                   Install a bootloader for your system
+* Init scripts::                 Install init scripts for your system
+* Fstab::                        Generating fstab
+
+Post-installation
+
+* KISS repositories::            Acquire kiss repositories
+
+Init System
+
+* Configuring Init::             Ways to configure the init system
+* Changing Init Program::        Replace the default busybox init with something new
+
+Configuring Init
+
+* Kernel Command Line::          Configure init through the boot parameters
+* @samp{/etc/init/rc.conf} file: @samp{/etc/init/rcconf} file.  Configure init through the configuration file
+* Init Hooks::                   Configure init through hooks
+
+Changing Init Program
+
+* Rebooting after changing init:: Ways to reboot after replacing the init system
+
+Contribution Guidelines
+
+* Conventions::                  Conventions of the distribution
+
+Conventions
+
+* Shell Conventions::            Conventions for shell scripts
+* Repository Conventions::       Conventions for repository build scripts
+
+@end detailmenu
+@end menu
+
+@node Installation
+@chapter Installation
+
+These are the step-by-step instructions for installing Carbs Linux. It can be
+acquired as plain-text to be viewed offline with a pager from
+@uref{https://carbslinux.org/docs/install.txt}.
+
+@menu
+* Preparing Environment::        Getting ready to chroot
+* Chroot::                       Going inside your new system
+* System Configuration::         Customizing your system for personal use
+* Kernel::                       Compiling your own kernel
+* Making your system bootable::  Installing bootloader and boot scripts
+* Post-installation::            Post-installation tasks
+@end menu
+
+@node Preparing Environment
+@section Preparing Environment
+
+To install Carbs Linux, you will need a Live Linux ISO@. For that purpose, you
+can obtain a Gentoo or Void Linux live image. You can follow their instructions
+to boot and setup your network.
+
+You will need the following programs in order to install Carbs Linux:
+
+@itemize
+@item
+tar
+@item
+wget
+@item
+xz
+@item
+some form of base utilities (coreutils, sbase, busybox, etc.)
+@end itemize
+
+Rest of these instructions will assume that you have set all of these up, and
+will continue on that point.
+
+@menu
+* Download::                     Download the root filesystem tarball
+* Signature verification::       Verify the signature of the rootfs tarball
+* Extracting the tarball::       Extracting the root filesystem to the desired location
+* Obtain the chroot helper::     Download the script to easily chroot into the new filesystem
+@end menu
+
+@node Download
+@subsection Download
+
+First, we need to download the rootfs tarball. You can do the following in order
+to obtain the rootfs. If you are using an i686 machine, replace the @samp{x86_64}
+with @samp{i686}. We are setting this in a URL variable so that we don't have to
+write it every time.
+
+@example
+wget $URL/carbs-rootfs.tar.xz.sha256
+sha256sum -c carbs-rootfs.tar.xz.sha256
+@end example
+
+@node Signature verification
+@subsection Signature verification
+
+It is highly recommended to verify the signature of the tarball. You will need
+GPG for this.
+
+@example
+wget $URL/carbs-rootfs.tar.xz.sig
+gpg --recv-keys FF484BDFEFCEF8FF
+gpg --verify carbs-rootfs.tar.xz.sig
+@end example
+
+@node Extracting the tarball
+@subsection Extracting the tarball
+
+You will need to extract the tarball to your desired location. For partitioning,
+you can follow @uref{https://wiki.archlinux.org/index.php/Partitioning, this guide}. This will assume that you will be mounting your root
+partition to @samp{/mnt}.
+
+@example
+mount /dev/sdx1 /mnt
+tar xf carbs-rootfs.tar.xz -C /mnt
+@end example
+
+@node Obtain the chroot helper
+@subsection Obtain the chroot helper
+
+You can obtain the @samp{cpt-chroot} script in order to do a simple chroot into your
+new root filesystem.
+
+@example
+wget https://dl.carbslinux.org/distfiles/cpt-chroot
+chmod a+x cpt-chroot
+@end example
+
+@node Chroot
+@section Chroot
+
+Chroot into Carbs Linux!
+
+@example
+./cpt-chroot /mnt
+@end example
+
+@menu
+* Setting up repositories::      Basic setup for obtaining repositories
+* Updating packages::            Update your system
+* Installing packages::          Install new software on your system
+* Essential Software::           Software you might want to include on your system
+* Obtaining the documentation::  Install documentation for offline use (optional)
+@end menu
+
+@node Setting up repositories
+@subsection Setting up repositories
+
+Newest tarballs do not come with repositories, so you will need to manually
+obtain them, and set your @samp{CPT_PATH} environment variable. Carbs Linux
+repositories can either be obtained by @samp{git} or @samp{rsync}. While rsync
+repositories are overall faster and smaller, git offers the whole history of the
+repository and a means to manipulate your repository as you like it. If you want
+to obtain the git repository, you will need to install @samp{git} itself.
+
+The following guide will assume that you put the repositories into @samp{~/repos/}
+directory, but you can put the repositories into any directory you want. So go
+ahead and create that directory:
+
+@example
+mkdir -p $HOME/repos
+@end example
+
+@enumerate
+@item
+Obtaining from git
+
+
+Carbs Linux git repositories can be found both from the main server and GitHub
+(mirror). Here are both their repository links. You can clone any of them.
+
+@itemize
+@item
+git://git.carbslinux.org/repository
+@item
+@uref{https://github.com/carbslinux/repository}
+@end itemize
+
+@example
+git clone git://git.carbslinux.org/repository $HOME/repos/carbs
+@end example
+
+@item
+Obtaining from rsync
+
+
+Carbs Linux rsync repositories live in rsync://carbslinux.org/repo. In
+order to obtain it, run the following:
+
+@example
+rsync -avc rsync://carbslinux.org/repo $HOME/repos/carbs
+@end example
+
+@item
+Making the package manager use the repositories
+
+
+In your shell's configuration file, or in your @samp{~/.profile} file, add the
+following lines:
+
+@example
+CPT_PATH=$HOME/repos/carbs/core
+CPT_PATH=$CPT_PATH:$HOME/repos/carbs/extra
+CPT_PATH=$CPT_PATH:$HOME/repos/carbs/xorg
+CPT_PATH=$CPT_PATH:$HOME/repos/carbs/community
+export CPT_PATH
+@end example
+@end enumerate
+
+@node Updating packages
+@subsection Updating packages
+
+It is good practice to make sure your system is up to date, especially before
+building new packages. If there is an update for the package manager you will
+need to update twice.
+
+@example
+cpt-update && cpt-update
+@end example
+
+@node Installing packages
+@subsection Installing packages
+
+Since you are operating on a really small base, you might need to build and
+install new programs to extend the functionality of your system. In order to
+build and install packages new packages in Carbs, you need to execute the
+following. "Package" is not actually a package and is given as an example.
+
+@example
+cpt-build   package
+cpt-install package
+@end example
+
+@node Essential Software
+@subsection Essential Software
+
+Here is a list of software that you might want to have on your system.
+
+@strong{BOOTLOADERS}
+
+@itemize
+@item
+efibootmgr
+@item
+grub
+@end itemize
+
+@strong{FILESYSTEMS}
+
+@itemize
+@item
+e2fsprogs
+@item
+dosfstools
+@item
+ntfs-3g
+@end itemize
+
+@strong{NETWORKING}
+
+@itemize
+@item
+dhcpcd
+@item
+wpa@math{_supplicant}
+@end itemize
+
+@strong{TEXT EDITORS}
+
+@itemize
+@item
+nano
+@item
+vim
+@item
+neatvi
+@item
+emacs
+@item
+emacs-nox (terminal-only version of emacs)
+@end itemize
+
+@strong{USER SHELLS}
+
+@itemize
+@item
+bash
+@item
+zsh
+@item
+oksh
+@item
+rc
+@end itemize
+
+@strong{POSIX BASE UTILITIES}
+
+@itemize
+@item
+busybox
+@item
+sbase
+@item
+coreutils
+@end itemize
+
+@strong{DOCUMENTATION}
+
+@itemize
+@item
+carbs-docs
+@item
+man-pages
+@item
+man-pages-posix
+@end itemize
+
+@node Obtaining the documentation
+@subsection Obtaining the documentation
+
+All the documentation for Carbs Linux can be found on a single info manual to be
+viewed offline. You can obtain texinfo or the info (standalone) package in order
+to view the documentation.
+
+@example
+# Install the documentation.
+cpt b carbs-docs && cpt i carbs-docs
+
+# Install either texinfo or the info package. We will be installing standalone info
+# as it doesn't need perl.
+cpt b info && cpt i info
+
+# You can then run info and navigate through the documentation.
+info carbslinux
+@end example
+
+@node System Configuration
+@section System Configuration
+
+After you have finished installing some extra packages, you can configure your
+system to your liking.
+
+@menu
+* Configuring hostname::         Setting up system hostname (recommended)
+* Hosts file::                   Setting up hosts file for networking (optional)
+@end menu
+
+@node Configuring hostname
+@subsection Configuring hostname
+
+You might want to add a hostname, especially in a networked environment. Your
+hostname will default to 'carbslinux' unless you set this.
+
+@example
+echo your-hostname > /etc/hostname
+@end example
+
+@node Hosts file
+@subsection Hosts file
+
+You can edit your /etc/hosts file, which is the static lookup table for host
+names. By default, there are two entries for localhost which are OKAY@. You can
+replace the 'localhost' part of these entries to your hostname.
+
+@example
+127.0.0.1  localhost.localdomain localhost
+::1        localhost.localdomain localhost ip6-localhost
+@end example
+
+@node Kernel
+@section Kernel
+
+Kernel isn't managed under the main repositories, even though you could package
+one for your personal use. Here is an @uref{https://github.com/cemkeylan/kiss-repository/tree/master/personal/linux, example kernel package}, which you will
+need to reconfigure for your specific setup if you want to make use of it.
+
+@menu
+* Obtaining the kernel sources:: Downloading the Linux source code
+* Kernel dependencies::          Requirements for building the kernel
+* Building the kernel::          Configure and compile the kernel
+@end menu
+
+@node Obtaining the kernel sources
+@subsection Obtaining the kernel sources
+
+You can visit the @uref{https://kernel.org} website to choose a kernel that you want
+to install. Though only the latest stable and longterm (LTS) versions are
+supported.
+
+@example
+# Download the kernel and extract it
+wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.9.1.tar.xz
+tar xf linux-5.9.1.tar.xz
+
+# Change directory into the kernel sources
+cd linux-5.9.1
+@end example
+
+@node Kernel dependencies
+@subsection Kernel dependencies
+
+In order to compile the kernel you will need to install some dependencies. You
+will need @samp{libelf} to compile the kernel. If you want to configure using the
+menu interface you will also need @samp{ncurses}.
+
+@example
+# The package manager asks to install if you are building more than one package,
+# so no need to run 'cpt i ...'
+cpt b libelf ncurses
+@end example
+
+In the vanilla kernel sources, you need perl to compile the kernel, but it can
+be easily patched out. You will need to apply the following patch. Patch was
+written by @uref{https://github.com/E5ten, E5ten}. You will need to obtain and apply the patch in the kernel
+source directory.
+
+@example
+wget https://dl.carbslinux.org/distfiles/kernel-no-perl.patch
+patch -p1 < kernel-no-perl.patch
+@end example
+
+@node Building the kernel
+@subsection Building the kernel
+
+Next step is configuring and building the kernel. You can check Gentoo's
+@uref{https://wiki.gentoo.org/wiki/Kernel/Configuration, kernel configuration guide} to learn more about the matter. Overall, Gentoo Wiki
+is a good place to learn about configuration according to your hardware. The
+following will assume a monolithic kernel.
+
+@example
+make menuconfig
+make
+install -Dm755 $(make -s image_name) /boot/vmlinuz-linux
+@end example
+
+@node Making your system bootable
+@section Making your system bootable
+
+In order to be able to boot your fresh system, wou will need an init-daemon,
+init-scripts and a bootloader. The init daemon is already provided by busybox,
+but you can optionally change it.
+
+@menu
+* Bootloader::                   Install a bootloader for your system
+* Init scripts::                 Install init scripts for your system
+* Fstab::                        Generating fstab
+@end menu
+
+@node Bootloader
+@subsection Bootloader
+
+In the main repository, there is efibootmgr and grub to serve as bootloaders.
+efibootmgr can be used as a standalone bootloader, or can be used to install
+grub in a UEFI environment. efibootmgr is needed unless you are using a device
+without UEFI support (or you really want to use BIOS for a reason).
+
+@enumerate
+@item
+GRUB BIOS installation
+
+
+@example
+cpt b grub && cpt i grub
+grub-install --target=i386-pc /dev/sdX
+grub-mkconfig -o /boot/grub/grub.cfg
+@end example
+
+@item
+GRUB UEFI installation
+
+
+@example
+cpt b efibootmgr && cpt i efibootmgr
+cpt b grub && cpt i grub
+
+grub-install --target=x86_64-efi \
+             --efi-directory=esp \
+             --bootloader-id=CarbsLinux
+
+grub-mkconfig -o /boot/grub/grub.cfg
+@end example
+@end enumerate
+
+@node Init scripts
+@subsection Init scripts
+
+Only thing left to do is installing the init-scripts, and now you are almost
+ready to boot your system!
+
+@example
+cpt b carbs-init && cpt i carbs-init
+@end example
+
+@node Fstab
+@subsection Fstab
+
+You can now manually edit your fstab entry, or you can use the genfstab tool.
+If you want to use the tool, exit the chroot and run the following:
+
+@example
+wget https://github.com/cemkeylan/genfstab/raw/master/genfstab
+chmod +x genfstab
+./genfstab -U /mnt >> /mnt/etc/fstab
+@end example
+
+@node Post-installation
+@section Post-installation
+
+The base installation is now complete, you can now fine tune your system
+according to your needs. Rest of these instructions are completely optional.
+You can check the rest of the documentation to learn more about the system.
+
+@menu
+* KISS repositories::            Acquire kiss repositories
+@end menu
+
+@node KISS repositories
+@subsection KISS repositories
+
+While not 100% compatible with cpt, you can use kiss repositories in your
+system the same way you are using the distribution repositories. Here is an
+example for the KISS Linux Community repository.
+
+@node Init System
+@chapter Init System
+
+Carbs Linux init scripts are run by the init daemon (@samp{busybox} by default) on
+boot and shutdown processes. It also provides its own halting program named
+shalt. This provides a portable method that doesn't rely on non-POSIX external
+programs.
+
+@menu
+* Configuring Init::             Ways to configure the init system
+* Changing Init Program::        Replace the default busybox init with something new
+@end menu
+
+@node Configuring Init
+@section Configuring Init
+
+There are three ways you can change the behaviour of the init system. Those are:
+
+@itemize
+@item
+Kernel Command Line
+@item
+@samp{/etc/init/rc.conf} file
+@item
+Init Hooks
+@end itemize
+
+@menu
+* Kernel Command Line::          Configure init through the boot parameters
+* @samp{/etc/init/rc.conf} file: @samp{/etc/init/rcconf} file.  Configure init through the configuration file
+* Init Hooks::                   Configure init through hooks
+@end menu
+
+@node Kernel Command Line
+@subsection Kernel Command Line
+
+On GRUB, you can edit the kernel command line parameters, which will be parsed
+as variables on the init system. Not all of the parameters will be acted upon,
+but all of them will be set as variables on the init script. For example an
+example command line, and how it is interpreted.
+
+@example
+BOOT_IMAGE=/boot/vmlinuz root=/dev/sda2 rw loglevel=3 quiet
+@end example
+
+This command line will be parsed to set the following variables:
+
+@example
+BOOT_IMAGE=/boot/vmlinuz
+root=/dev/sda2
+rw=1
+loglevel=3
+quiet=1
+@end example
+
+Some of these variables, such as @samp{rw=/=ro}, @samp{loglevel}, and @samp{quiet}, will be
+used by the init system to change the behaviour of the startup.
+
+@node @samp{/etc/init/rcconf} file
+@subsection @samp{/etc/init/rc.conf} file
+
+However, the kernel command line isn't the only place to set your boot
+parameters. You can specify variables here as well, although note that the
+kernel command line always gets the priority for these variables since they can
+be set just before boot.
+
+@node Init Hooks
+@subsection Init Hooks
+
+Init hooks are for custom personal commands that the user may want to add to
+alter their boot. These can be used to load kernel modules, modify interfaces,
+and lot more. Those hooks are added to the @samp{/etc/init} directory with the
+hook name as the suffix. For example, a boot script will be placed as
+@samp{/etc/init/my-hook.boot}. Currently, there are 4 hooks that the user can use.
+
+@table @asis
+@item early-boot
+Run after pseudo-filesystems are mounted.
+@item boot
+Run before the boot stage is completed.
+@item pre.shutdown
+Run first when shutting down.
+@item umount
+Run just before filesystems are unmounted.
+@item post.shutdown
+Run just before the system is halted.
+@end table
+
+@node Changing Init Program
+@section Changing Init Program
+
+By default, Carbs Linux comes preinstalled with @samp{busybox-init}, but this can
+easily be replaced without any issues. Currently, available init systems are:
+
+@itemize
+@item
+@samp{sinit}
+@item
+@samp{busybox}
+@item
+@samp{runit}
+@item
+@samp{shinit}
+@end itemize
+
+This example is for runit, but it will work with all init systems packaged in the
+distribution repositories. See the @samp{cpt-alternatives(1)} manual page for more
+details.
+
+@example
+cpt a runit /usr/bin/init
+cpt a runit /usr/bin/poweroff
+cpt a runit /usr/bin/reboot
+@end example
+
+@menu
+* Rebooting after changing init:: Ways to reboot after replacing the init system
+@end menu
+
+@node Rebooting after changing init
+@subsection Rebooting after changing init
+
+After switching init systems, your running init system may not accept the
+new poweroff commands. You will need to reboot/poweroff using the running init's
+utilities for the new utilities to work. These commands are for the init system
+currently running on your system and not the one you are switching to.
+
+@multitable {aaaaaaaaaaaa} {aaaaaaaaaaaaaaaa}
+@headitem Program
+@tab Command
+@item busybox
+@tab @samp{busybox reboot}
+@item runit
+@tab @samp{runit-init 6}
+@item shinit/sinit
+@tab @samp{kill -s INT 1}
+@end multitable
+
+@node Contribution Guidelines
+@chapter Contribution Guidelines
+
+Thanks for taking your time to contribute! To maintain stylistic behaviour
+throughout the repositories, one must adhere to these conventions. Exceptions
+and changes may occur with good reasoning.
+
+@menu
+* Conventions::                  Conventions of the distribution
+@end menu
+
+@node Conventions
+@section Conventions
+
+@macro contid{id}
+[@anchor{\id\}\id\]
+@end macro
+
+@macro sectid{id, sect}
+@strong{@contid{\id\} \sect\}
+@end macro
+
+@table @asis
+@item [@anchor{0010}0010]
+Try to keep the file readable.
+@table @asis
+@item [@anchor{0011}0011]
+Characters on a line shouldn't exceed 100 characters.
+@item [@anchor{0012}0012]
+Make sure you don't have code commented out during
+commit. Uncomment them or remove them completely.
+@item [@anchor{0013}0013]
+Do not add comments following the code, add them to the
+top of the code. It makes it harder to read, and lines longer. Here is an example:
+@end table
+
+@example
+# Good way of commenting.
+your code goes here
+
+your code goes here  # Avoid this way of commenting.
+@end example
+@end table
+
+@menu
+* Shell Conventions::            Conventions for shell scripts
+* Repository Conventions::       Conventions for repository build scripts
+@end menu
+
+@node Shell Conventions
+@subsection Shell Conventions
+
+Shell is central to Carbs Linux projects. Most of the tools and packages are
+written in POSIX sh.
+
+@table @asis
+@item [@anchor{1010}1010]
+Use 4 spaces for indentation, don't use tabs.
+@item [@anchor{1020}1020]
+Make sure you don't use bash-specific code.
+@item [@anchor{1030}1030]
+Make sure you lint your code with @samp{shellcheck} and if
+you are new to POSIX sh, use @samp{checkbashisms}.
+@item [@anchor{1040}1040]
+Don't spawn new processes if you don't absolutely need
+to, especially during string manipulation.
+@table @asis
+@item [@anchor{1041}1041]
+Never use a program for text manupilation that isn't
+defined in the POSIX standard. This includes @samp{gawk} and @samp{perl}.
+@item [@anchor{1042}1042]
+Instead of @code{$(basename $file)}, use @code{$@{file##*@}}.
+@item [@anchor{1043}1043]
+Instead of @code{$(dirname $file)}, use @code{$@{file%/*@}}.
+@end table
+
+@example
+# This is the same thing as basename /path/to/test.asc .asc
+
+$ file=/path/to/test.asc file=$@{file##*/@} file=$@{file%.asc@}
+$ echo $file
+test
+@end example
+@item [@anchor{1050}1050]
+Instead of backticks, use @code{$(..)}.
+@end table
+
+@node Repository Conventions
+@subsection Repository Conventions
+
+Repository conventions are important in order to ensure every package resemble
+themselves. Here are the things to keep in mind:
+
+@table @asis
+@item [@anchor{2010}2010]
+Prefer tarballs over git packages unless there is a
+sensible reason. Here are some:
+@itemize
+@item
+Every patch is a new release. (See @uref{https://github.com/vim/vim, vim})
+@item
+There are no releases. (See @uref{https://git.suckless.org/sbase, sbase})
+@item
+Following a development branch.
+@item
+There has been a long time since the latest release, but upstream is far
+ahead.
+@end itemize
+@item [@anchor{2020}2020]
+Prefer sources without a dependency to @samp{automake}. There
+are usually distribution tarballs that are @samp{autoconf}'ed. Don't submit tarballs
+with an automake dependency unless you are @samp{sure} there is no alternative.
+@item [@anchor{2030}2030]
+Avoid these packages:
+@table @asis
+@item dbus   
+Usually can be disabled by @code{--disable-dbus}.
+@item gettext
+Usually can be disabled by @code{--disable-nls}.
+@end table
+@item [@anchor{2040}2040]
+@itemize
+@item
+Always install a package to the @samp{/usr} prefix.
+@item
+All binaries should go to @samp{/usr/bin}, not @samp{/usr/sbin} or any other directory.
+@item
+All libraries should go to @samp{/usr/lib}.
+@end itemize
+@item [@anchor{2050}2050]
+All build files on the repository should be a POSIX
+shell script, and must start with @code{#!/bin/sh -e}.
+@end table
+
+The next section is about package templates that should be used in order to
+ensure stylistic consistency. Note that the option configurations shouldn't be
+taken literally, they are meant as examples.
+
+@enumerate
+@item
+Make [@anchor{2210}2210]
+
+
+@example
+#!/bin/sh -e
+
+make
+make DESTDIR="$1" PREFIX=/usr install
+@end example
+
+@item
+Configure/Make [@anchor{2211}2211]
+
+
+@example
+#!/bin/sh -e
+
+./configure \
+    --prefix=/usr \
+    --disable-option \
+    --enable-option
+
+make
+make DESTDIR="$1" install
+@end example
+
+@item
+Autoconf/Automake [@anchor{2212}2212]
+
+
+@xref{2020}
+
+@example
+#!/bin/sh -e
+
+autoreconf -fi
+
+./configure \
+    --prefix=/usr \
+    --disable-option \
+    --enable-option
+
+make
+make DESTDIR="$1" install
+@end example
+
+@item
+Meson [@anchor{2220}2220]
+
+
+@example
+#!/bin/sh -e
+
+export DESTDIR=$1
+
+meson \
+    --prefix=/usr \
+    -Doption=false \
+    -Doption2=true \
+    . output
+
+ninja -C output
+ninja -C output install
+@end example
+
+@item
+Cmake [@anchor{2230}2230]
+
+
+@example
+#!/bin/sh -e
+
+export DESTDIR=$1
+
+cmake -B build \
+    -DCMAKE_INSTALL_PREFIX=/usr \
+    -DCMAKE_BUILD_TYPE=Release \
+    -DOPTION=ON
+
+cmake --build   build
+cmake --install build
+@end example
+
+@item
+Go [@anchor{2240}2240]
+
+
+@example
+#!/bin/sh -e
+
+export GOPATH=$PWD/gopath
+trap "go clean -modcache" EXIT INT
+go mod vendor
+
+go build
+install -Dm755 program "$1/usr/bin/program"
+@end example
+
+@item
+Python [@anchor{2241}2241]
+
+
+@example
+#!/bin/sh -e
+
+python setup.py build
+python setup.py install --prefix=/usr --root="$1"
+@end example
+@end enumerate
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+
+@center Version 1.3, 3 November 2008
+
+@display
+Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
+@uref{http://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{free}
+in the sense of freedom: to assure everyone the effective freedom
+to copy and redistribute it, with or without modifying it, either
+commercially or noncommercially. Secondarily, this License
+preserves for the author and publisher a way to get credit for
+their work, while not being considered responsible for
+modifications made by others.
+
+This License is a kind of "copyleft", which means that derivative
+works of the document must themselves be free in the same sense.
+It complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for
+free software, because free software needs free documentation:
+a free program should come with manuals providing the same freedoms
+that the software does.  But this License is not limited to
+software manuals; it can be used for any textual work, regardless
+of subject matter or whether it is published as a printed book.  We
+recommend this License principally for works whose purpose is
+instruction or reference.
+
+@item
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium,
+that contains a notice placed by the copyright holder saying it can
+be distributed under the terms of this License.  Such a notice
+grants a world-wide, royalty-free license, unlimited in duration,
+to use that work under the conditions stated herein.  The
+"Document", below, refers to any such manual or work.  Any member
+of the public is a licensee, and is addressed as "you".  You accept
+the license if you copy, modify or distribute the work in a way
+requiring permission under copyright law.
+
+A "Modified Version" of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A "Secondary Section" is a named appendix or a front-matter section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could
+fall directly within that overall subject.  (Thus, if the Document
+is in part a textbook of mathematics, a Secondary Section may not
+explain any mathematics.)  The relationship could be a matter of
+historical connection with the subject or with related matters, or
+of legal, commercial, philosophical, ethical or political position
+regarding them.
+
+The "Invariant Sections" are certain Secondary Sections whose
+titles are designated, as being those of Invariant Sections, in the
+notice that says that the Document is released under this License.
+If a section does not fit the above definition of Secondary then it
+is not allowed to be designated as Invariant.  The Document may
+contain zero Invariant Sections.  If the Document does not identify
+any Invariant Sections then there are none.
+
+The "Cover Texts" are certain short passages of text that are
+listed, as Front-Cover Texts or Back-Cover Texts, in the notice
+that says that the Document is released under this License.
+A Front-Cover Text may be at most 5 words, and a Back-Cover Text
+may be at most 25 words.
+
+A "Transparent" copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed
+of pixels) generic paint programs or (for drawings) some widely
+available drawing editor, and that is suitable for input to text
+formatters or for automatic translation to a variety of formats
+suitable for input to text formatters.  A copy made in an otherwise
+Transparent file format whose markup, or absence of markup, has
+been arranged to thwart or discourage subsequent modification by
+readers is not Transparent.  An image format is not Transparent if
+used for any substantial amount of text.  A copy that is not
+"Transparent" is called "Opaque".
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, @LaTeX{} input format,
+SGML or XML using a publicly available DTD, and standard-conforming
+simple HTML, PostScript or PDF designed for human modification.
+Examples of transparent image formats include PNG, XCF and JPG@.
+Opaque formats include proprietary formats that can be read and
+edited only by proprietary word processors, SGML or XML for which
+the DTD and/or processing tools are not generally available, and
+the machine-generated HTML, PostScript or PDF produced by some word
+processors for output purposes only.
+
+The "Title Page" means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the
+material this License requires to appear in the title page.  For
+works in formats which do not have any title page as such, "Title
+Page" means the text near the most prominent appearance of the
+work's title, preceding the beginning of the body of the text.
+
+The "publisher" means any person or entity that distributes copies
+of the Document to the public.
+
+A section "Entitled XYZ" means a named subunit of the Document
+whose title either is precisely XYZ or contains XYZ in parentheses
+following text that translates XYZ in another language.  (Here XYZ
+stands for a specific section name mentioned below, such as
+"Acknowledgements", "Dedications", "Endorsements", or "History".)
+To "Preserve the Title" of such a section when you modify the
+Document means that it remains a section "Entitled XYZ" according
+to this definition.
+
+The Document may include Warranty Disclaimers next to the notice
+which states that this License applies to the Document.  These
+Warranty Disclaimers are considered to be included by reference in
+this License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and
+has no effect on the meaning of this License.
+
+@item
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License
+applies to the Document are reproduced in all copies, and that you
+add no other conditions whatsoever to those of this License.  You
+may not use technical measures to obstruct or control the reading
+or further copying of the copies you make or distribute.  However,
+you may accept compensation in exchange for copies.  If you
+distribute a large enough number of copies you must also follow the
+conditions in section 3.
+
+You may also lend copies, under the same conditions stated above,
+and you may publicly display copies.
+
+@item
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly
+have printed covers) of the Document, numbering more than 100, and
+the Document's license notice requires Cover Texts, you must
+enclose the copies in covers that carry, clearly and legibly, all
+these Cover Texts: Front-Cover Texts on the front cover, and
+Back-Cover Texts on the back cover.  Both covers must also clearly
+and legibly identify you as the publisher of these copies.  The
+front cover must present the full title with all words of the title
+equally prominent and visible.  You may add other material on the
+covers in addition.  Copying with changes limited to the covers, as
+long as they preserve the title of the Document and satisfy these
+conditions, can be treated as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto
+adjacent pages.
+
+If you publish or distribute Opaque copies of the Document
+numbering more than 100, you must either include a machine-readable
+Transparent copy along with each Opaque copy, or state in or with
+each Opaque copy a computer-network location from which the general
+network-using public has access to download using public-standard
+network protocols a complete Transparent copy of the Document, free
+of added material.  If you use the latter option, you must take
+reasonably prudent steps, when you begin distribution of Opaque
+copies in quantity, to ensure that this Transparent copy will
+remain thus accessible at the stated location until at least one
+year after the last time you distribute an Opaque copy (directly or
+through your agents or retailers) of that edition to the public.
+
+It is requested, but not required, that you contact the authors of
+the Document well before redistributing any large number of copies,
+to give them a chance to provide you with an updated version of the
+Document.
+
+@item
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document
+under the conditions of sections 2 and 3 above, provided that you
+release the Modified Version under precisely this License, with the
+Modified Version filling the role of the Document, thus licensing
+distribution and modification of the Modified Version to whoever
+possesses a copy of it.  In addition, you must do these things in
+the Modified Version:
+
+@enumerate A
+@item
+Use in the Title Page (and on the covers, if any) a title
+distinct from that of the Document, and from those of previous
+versions (which should, if there were any, be listed in the
+History section of the Document). You may use the same title as
+a previous version if the original publisher of that version
+gives permission.
+
+@item
+List on the Title Page, as authors, one or more persons or
+entities responsible for authorship of the modifications in the
+Modified Version, together with at least five of the principal
+authors of the Document (all of its principal authors, if it has
+fewer than five), unless they release you from this requirement.
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+Include, immediately after the copyright notices, a license
+notice giving the public permission to use the Modified Version
+under the terms of this License, in the form shown in the
+Addendum below.
+
+@item
+Preserve in that license notice the full lists of Invariant
+Sections and required Cover Texts given in the Document's
+license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+Preserve the section Entitled "History", Preserve its Title, and
+add to it an item stating at least the title, year, new authors,
+and publisher of the Modified Version as given on the Title
+Page. If there is no section Entitled "History" in the Document,
+create one stating the title, year, authors, and publisher of
+the Document as given on its Title Page, then add an item
+describing the Modified Version as stated in the previous
+sentence.
+
+@item
+Preserve the network location, if any, given in the Document
+for public access to a Transparent copy of the Document, and
+likewise the network locations given in the Document for
+previous versions it was based on. These may be placed in the
+"History" section. You may omit a network location for a work
+that was published at least four years before the Document
+itself, or if the original publisher of the version it refers
+to gives permission.
+
+@item
+For any section Entitled "Acknowledgements" or "Dedications",
+Preserve the Title of the section, and preserve in the section
+all the substance and tone of each of the contributor
+acknowledgements and/or dedications given therein.
+
+@item
+Preserve all the Invariant Sections of the Document, unaltered
+in their text and in their titles. Section numbers or the
+equivalent are not considered part of the section titles.
+
+@item
+Delete any section Entitled "Endorsements". Such a section may
+not be included in the Modified Version.
+
+@item
+Do not retitle any existing section to be Entitled
+"Endorsements" or to conflict in title with any Invariant
+Section.
+
+@item
+Preserve any Warranty Disclaimers.
+@end enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant.  To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled "Endorsements", provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version.  Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity.  If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+@item
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under
+this License, under the terms defined in section 4 above for
+modified versions, provided that you include in the combination all
+of the Invariant Sections of all of the original documents,
+unmodified, and list them all as Invariant Sections of your
+combined work in its license notice, and that you preserve all
+their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy.  If there are multiple Invariant Sections with the same name
+but different contents, make the title of each such section unique
+by adding at the end of it, in parentheses, the name of the
+original author or publisher of that section if known, or else
+a unique number.  Make the same adjustment to the section titles in
+the list of Invariant Sections in the license notice of the
+combined work.
+
+In the combination, you must combine any sections Entitled
+"History" in the various original documents, forming one section
+Entitled "History"; likewise combine any sections Entitled
+"Acknowledgements", and any sections Entitled "Dedications".  You
+must delete all sections Entitled "Endorsements."
+
+@item
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other
+documents released under this License, and replace the individual
+copies of this License in the various documents with a single copy
+that is included in the collection, provided that you follow the
+rules of this License for verbatim copying of each of the documents
+in all other respects.
+
+You may extract a single document from such a collection, and
+distribute it individually under this License, provided you insert
+a copy of this License into the extracted document, and follow this
+License in all other respects regarding verbatim copying of that
+document.
+
+@item
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other
+separate and independent documents or works, in or on a volume of
+a storage or distribution medium, is called an "aggregate" if the
+copyright resulting from the compilation is not used to limit the
+legal rights of the compilation's users beyond what the individual
+works permit.  When the Document is included in an aggregate, this
+License does not apply to the other works in the aggregate which
+are not themselves derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half
+of the entire aggregate, the Document's Cover Texts may be placed
+on covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic
+form.  Otherwise they must appear on printed covers that bracket
+the whole aggregate.
+
+@item
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of
+section 4.  Replacing Invariant Sections with translations requires
+special permission from their copyright holders, but you may
+include translations of some or all Invariant Sections in addition
+to the original versions of these Invariant Sections.  You may
+include a translation of this License, and all the license notices
+in the Document, and any Warranty Disclaimers, provided that you
+also include the original English version of this License and the
+original versions of those notices and disclaimers.  In case of
+a disagreement between the translation and the original version of
+this License or a notice or disclaimer, the original version will
+prevail.
+
+If a section in the Document is Entitled "Acknowledgements",
+"Dedications", or "History", the requirement (section 4) to
+Preserve its Title (section 1) will typically require changing the
+actual title.
+
+@item
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense, or distribute it is void,
+and will automatically terminate your rights under this License.
+
+However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the
+copyright holder fails to notify you of the violation by some
+reasonable means prior to 60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from
+that copyright holder, and you cure the violation prior to 30 days
+after your receipt of the notice.
+
+Termination of your rights under this section does not terminate
+the licenses of parties who have received copies or rights from you
+under this License.  If your rights have been terminated and not
+permanently reinstated, receipt of a copy of some or all of the
+same material does not give you any rights to use it.
+
+@item
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions of
+the GNU Free Documentation License from time to time.  Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.  See
+@uref{http://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version
+number.  If the Document specifies that a particular numbered
+version of this License "or any later version" applies to it, you
+have the option of following the terms and conditions either of
+that specified version or of any later version that has been
+published (not as a draft) by the Free Software Foundation.  If
+the Document does not specify a version number of this License,
+you may choose any version ever published (not as a draft) by the
+Free Software Foundation.  If the Document specifies that a proxy
+can decide which future versions of this License can be used, that
+proxy's public statement of acceptance of a version permanently
+authorizes you to choose that version for the Document.
+
+@item
+RELICENSING
+
+"Massive Multiauthor Collaboration Site" (or "MMC Site") means any
+World Wide Web server that publishes copyrightable works and also
+provides prominent facilities for anybody to edit those works.
+A public wiki that anybody can edit is an example of such
+a server.  A "Massive Multiauthor Collaboration" (or "MMC")
+contained in the site means any set of copyrightable works thus
+published on the MMC site.
+
+"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
+license published by Creative Commons Corporation,
+a not-for-profit corporation with a principal place of business in
+San Francisco, California, as well as future copyleft versions of
+that license published by that same organization.
+
+"Incorporate" means to publish or republish a Document, in whole
+or in part, as part of another Document.
+
+An MMC is "eligible for relicensing" if it is licensed under this
+License, and if all works that were first published under this
+License somewhere other than this MMC, and subsequently
+incorporated in whole or in part into the MMC, (1) had no cover
+texts or invariant sections, and (2) were thus incorporated prior
+to November 1, 2008.
+
+The operator of an MMC Site may republish an MMC contained in the
+site under CC-BY-SA on the same site at any time before August 1,
+2009, provided the MMC is eligible for relicensing.
+@end enumerate
+
+@page
+
+@anchor{ADDENDUM How to use this License for your documents}
+@appendixsec ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@example
+Copyright (C)  YEAR  YOUR NAME.
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+Texts.  A copy of the license is included in the section entitled ``GNU
+Free Documentation License''.
+@end example
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the "with@dots{}Texts."@tie{}line with this:
+
+@example
+with the Invariant Sections being LIST THEIR TITLES, with
+the Front-Cover Texts being LIST, and with the Back-Cover Texts
+being LIST.
+@end example
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License, to
+permit their use in free software.
+
+@bye
\ No newline at end of file