diff options
Diffstat (limited to 'carbslinux.txt')
| -rw-r--r-- | carbslinux.txt | 1327 |
1 files changed, 1327 insertions, 0 deletions
diff --git a/carbslinux.txt b/carbslinux.txt new file mode 100644 index 0000000..ddf94f6 --- /dev/null +++ b/carbslinux.txt @@ -0,0 +1,1327 @@ + _________________________ + + CARBS LINUX USER MANUAL + + Cem Keylan + _________________________ + + +Table of Contents +_________________ + +1. Copying +2. Installation +.. 1. Preparing Environment +..... 1. Download +..... 2. Signature verification +..... 3. Extracting the tarball +..... 4. Obtain the chroot helper +.. 2. Chroot +..... 1. Setting up repositories +..... 2. Updating packages +..... 3. Installing packages +..... 4. Essential Software +..... 5. Obtaining the documentation +.. 3. System Configuration +..... 1. Configuring hostname +..... 2. Hosts file +.. 4. Kernel +..... 1. Obtaining the kernel sources +..... 2. Kernel dependencies +..... 3. Building the kernel +.. 5. Making your system bootable +..... 1. Bootloader +..... 2. Init scripts +..... 3. Fstab +.. 6. Post-installation +..... 1. KISS repositories +3. Init System +.. 1. Configuring Init +..... 1. Kernel Command Line +..... 2. `/etc/init/rc.conf' file +..... 3. Init Hooks +.. 2. Changing Init Program +..... 1. Rebooting after changing init +4. Contribution Guidelines +.. 1. Conventions +..... 1. Shell Conventions +..... 2. Repository Conventions +5. GNU Free Documentation License + + +This is the full documentation of [Carbs Linux], from the details of the +distribution, installation, to the package manager. It is not yet +complete. + +You can build and install the 'info' package in order to view this documentation +with the info reader. It is divided into sections and easier to read. + + +[Carbs Linux] <https://carbslinux.org> + + +1 Copying +========= + + Copyright (c) 2020 Cem Keylan + + 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." + + +2 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 + <https://carbslinux.org/docs/install.txt>. + + +2.1 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: + + - tar + - wget + - xz + - some form of base utilities (coreutils, sbase, busybox, etc.) + + Rest of these instructions will assume that you have set all of these + up, and will continue on that point. + + +2.1.1 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 `x86_64' with `i686'. We are setting this in a + URL variable so that we don't have to write it every time. + + ,---- + | wget $URL/carbs-rootfs.tar.xz.sha256 + | sha256sum -c carbs-rootfs.tar.xz.sha256 + `---- + + +2.1.2 Signature verification +---------------------------- + + It is highly recommended to verify the signature of the tarball. You + will need GPG for this. + + ,---- + | wget $URL/carbs-rootfs.tar.xz.sig + | gpg --recv-keys FF484BDFEFCEF8FF + | gpg --verify carbs-rootfs.tar.xz.sig + `---- + + +2.1.3 Extracting the tarball +---------------------------- + + You will need to extract the tarball to your desired location. For + partitioning, you can follow [this guide]. This will assume that you + will be mounting your root partition to `/mnt'. + + ,---- + | mount /dev/sdx1 /mnt + | tar xf carbs-rootfs.tar.xz -C /mnt + `---- + + +[this guide] <https://wiki.archlinux.org/index.php/Partitioning> + + +2.1.4 Obtain the chroot helper +------------------------------ + + You can obtain the `cpt-chroot' script in order to do a simple chroot + into your new root filesystem. + + ,---- + | wget https://dl.carbslinux.org/distfiles/cpt-chroot + | chmod a+x cpt-chroot + `---- + + +2.2 Chroot +~~~~~~~~~~ + + Chroot into Carbs Linux! + + ,---- + | ./cpt-chroot /mnt + `---- + + +2.2.1 Setting up repositories +----------------------------- + + Newest tarballs do not come with repositories, so you will need to + manually obtain them, and set your `CPT_PATH' environment + variable. Carbs Linux repositories can either be obtained by `git' or + `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 `git' itself. + + The following guide will assume that you put the repositories into + `~/repos/' directory, but you can put the repositories into any + directory you want. So go ahead and create that directory: + + ,---- + | mkdir -p $HOME/repos + `---- + + +* 2.2.1.1 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. + + - git://git.carbslinux.org/repository + - <https://github.com/carbslinux/repository> + + ,---- + | git clone git://git.carbslinux.org/repository $HOME/repos/carbs + `---- + + +* 2.2.1.2 Obtaining from rsync + + Carbs Linux rsync repositories live in rsync://carbslinux.org/repo. In + order to obtain it, run the following: + + ,---- + | rsync -avc rsync://carbslinux.org/repo $HOME/repos/carbs + `---- + + +* 2.2.1.3 Making the package manager use the repositories + + In your shell's configuration file, or in your `~/.profile' file, add + the following lines: + + ,---- + | 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 + `---- + + +2.2.2 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. + + ,---- + | cpt-update && cpt-update + `---- + + +2.2.3 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. + + ,---- + | cpt-build package + | cpt-install package + `---- + + +2.2.4 Essential Software +------------------------ + + Here is a list of software that you might want to have on your system. + + *BOOTLOADERS* + + - efibootmgr + - grub + + *FILESYSTEMS* + + - e2fsprogs + - dosfstools + - ntfs-3g + + *NETWORKING* + + - dhcpcd + - wpa_supplicant + + *TEXT EDITORS* + + - nano + - vim + - neatvi + - emacs + - emacs-nox (terminal-only version of emacs) + + *USER SHELLS* + + - bash + - zsh + - oksh + - rc + + *POSIX BASE UTILITIES* + + - busybox + - sbase + - coreutils + + *DOCUMENTATION* + + - carbs-docs + - man-pages + - man-pages-posix + + +2.2.5 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. + + ,---- + | # 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 + `---- + + +2.3 System Configuration +~~~~~~~~~~~~~~~~~~~~~~~~ + + After you have finished installing some extra packages, you can + configure your system to your liking. + + +2.3.1 Configuring hostname +-------------------------- + + You might want to add a hostname, especially in a networked + environment. Your hostname will default to 'carbslinux' unless you set + this. + + ,---- + | echo your-hostname > /etc/hostname + `---- + + +2.3.2 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. + + ,---- + | 127.0.0.1 localhost.localdomain localhost + | ::1 localhost.localdomain localhost ip6-localhost + `---- + + +2.4 Kernel +~~~~~~~~~~ + + Kernel isn't managed under the main repositories, even though you + could package one for your personal use. Here is an [example kernel + package], which you will need to reconfigure for your specific setup + if you want to make use of it. + + +[example kernel package] +<https://github.com/cemkeylan/kiss-repository/tree/master/personal/linux> + +2.4.1 Obtaining the kernel sources +---------------------------------- + + You can visit the <https://kernel.org> website to choose a kernel that + you want to install. Though only the latest stable and longterm (LTS) + versions are supported. + + ,---- + | # 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 + `---- + + +2.4.2 Kernel dependencies +------------------------- + + In order to compile the kernel you will need to install some + dependencies. You will need `libelf' to compile the kernel. If you + want to configure using the menu interface you will also need + `ncurses'. + + ,---- + | # 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 + `---- + + 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 [E5ten]. You will need to obtain and apply + the patch in the kernel source directory. + + ,---- + | wget https://dl.carbslinux.org/distfiles/kernel-no-perl.patch + | patch -p1 < kernel-no-perl.patch + `---- + + +[E5ten] <https://github.com/E5ten> + + +2.4.3 Building the kernel +------------------------- + + Next step is configuring and building the kernel. You can check + Gentoo's [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. + + ,---- + | make menuconfig + | make + | install -Dm755 $(make -s image_name) /boot/vmlinuz-linux + `---- + + +[kernel configuration guide] +<https://wiki.gentoo.org/wiki/Kernel/Configuration> + + +2.5 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. + + +2.5.1 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). + + +* 2.5.1.1 GRUB BIOS installation + + ,---- + | cpt b grub && cpt i grub + | grub-install --target=i386-pc /dev/sdX + | grub-mkconfig -o /boot/grub/grub.cfg + `---- + + +* 2.5.1.2 GRUB UEFI installation + + ,---- + | 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 + `---- + + +2.5.2 Init scripts +------------------ + + Only thing left to do is installing the init-scripts, and now you are + almost ready to boot your system! + + ,---- + | cpt b carbs-init && cpt i carbs-init + `---- + + +2.5.3 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: + + ,---- + | wget https://github.com/cemkeylan/genfstab/raw/master/genfstab + | chmod +x genfstab + | ./genfstab -U /mnt >> /mnt/etc/fstab + `---- + + +2.6 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. + + +2.6.1 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. + + +3 Init System +============= + + Carbs Linux init scripts are run by the init daemon (`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. + + +3.1 Configuring Init +~~~~~~~~~~~~~~~~~~~~ + + There are three ways you can change the behaviour of the init + system. Those are: + + - Kernel Command Line + - `/etc/init/rc.conf' file + - Init Hooks + + +3.1.1 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. + + ,---- + | BOOT_IMAGE=/boot/vmlinuz root=/dev/sda2 rw loglevel=3 quiet + `---- + + This command line will be parsed to set the following variables: + + ,---- + | BOOT_IMAGE=/boot/vmlinuz + | root=/dev/sda2 + | rw=1 + | loglevel=3 + | quiet=1 + `---- + + Some of these variables, such as `rw=/=ro', `loglevel', and `quiet', + will be used by the init system to change the behaviour of the + startup. + + +3.1.2 `/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. + + +3.1.3 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 + `/etc/init' directory with the hook name as the suffix. For example, a + boot script will be placed as `/etc/init/my-hook.boot'. Currently, + there are 4 hooks that the user can use. + + early-boot + Run after pseudo-filesystems are mounted. + boot + Run before the boot stage is completed. + pre.shutdown + Run first when shutting down. + umount + Run just before filesystems are unmounted. + post.shutdown + Run just before the system is halted. + + +3.2 Changing Init Program +~~~~~~~~~~~~~~~~~~~~~~~~~ + + By default, Carbs Linux comes preinstalled with `busybox-init', but + this can easily be replaced without any issues. Currently, available + init systems are: + + - `sinit' + - `busybox' + - `runit' + - `shinit' + + This example is for runit, but it will work with all init systems + packaged in the distribution repositories. See the + `cpt-alternatives(1)' manual page for more details. + + ,---- + | cpt a runit /usr/bin/init + | cpt a runit /usr/bin/poweroff + | cpt a runit /usr/bin/reboot + `---- + + +3.2.1 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. + + Program Command + -------------------------------- + busybox `busybox reboot' + runit `runit-init 6' + shinit/sinit `kill -s INT 1' + + +4 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. + + +4.1 Conventions +~~~~~~~~~~~~~~~ + + [0010] + Try to keep the file readable. + [0011] + Characters on a line shouldn't exceed 100 characters. + [0012] + Make sure you don't have code commented out during + commit. Uncomment them or remove them completely. + [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: + + ,---- + | # Good way of commenting. + | your code goes here + | + | your code goes here # Avoid this way of commenting. + `---- + + +4.1.1 Shell Conventions +----------------------- + + Shell is central to Carbs Linux projects. Most of the tools and + packages are written in POSIX sh. + + [1010] + Use 4 spaces for indentation, don't use tabs. + [1020] + Make sure you don't use bash-specific code. + [1030] + Make sure you lint your code with `shellcheck' and if you are + new to POSIX sh, use `checkbashisms'. + [1040] + Don't spawn new processes if you don't absolutely need to, + especially during string manipulation. + [1041] + Never use a program for text manupilation that isn't + defined in the POSIX standard. This includes `gawk' and + `perl'. + [1042] + Instead of `$(basename $file)', use `${file##*}'. + [1043] + Instead of `$(dirname $file)', use `${file%/*}'. + + ,---- + | # 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 + `---- + [1050] + Instead of backticks, use `$(..)'. + + +4.1.2 Repository Conventions +---------------------------- + + Repository conventions are important in order to ensure every package + resemble themselves. Here are the things to keep in mind: + + [2010] + Prefer tarballs over git packages unless there is a sensible + reason. Here are some: + - Every patch is a new release. (See [vim]) + - There are no releases. (See [sbase]) + - Following a development branch. + - There has been a long time since the latest release, but + upstream is far ahead. + [2020] + Prefer sources without a dependency to `automake'. There are + usually distribution tarballs that are `autoconf''ed. Don't + submit tarballs with an automake dependency unless you are + `sure' there is no alternative. + [2030] + Avoid these packages: + dbus + Usually can be disabled by `--disable-dbus'. + gettext + Usually can be disabled by `--disable-nls'. + [2040] + - Always install a package to the `/usr' prefix. + - All binaries should go to `/usr/bin', not `/usr/sbin' or any + other directory. + - All libraries should go to `/usr/lib'. + [2050] + All build files on the repository should be a POSIX shell + script, and must start with `#!/bin/sh -e'. + + 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. + + +[vim] <https://github.com/vim/vim> + +[sbase] <https://git.suckless.org/sbase> + +* 4.1.2.1 Make [2210] + + ,---- + | #!/bin/sh -e + | + | make + | make DESTDIR="$1" PREFIX=/usr install + `---- + + +* 4.1.2.2 Configure/Make [2211] + + ,---- + | #!/bin/sh -e + | + | ./configure \ + | --prefix=/usr \ + | --disable-option \ + | --enable-option + | + | make + | make DESTDIR="$1" install + `---- + + +* 4.1.2.3 Autoconf/Automake [2212] + + ,---- + | #!/bin/sh -e + | + | autoreconf -fi + | + | ./configure \ + | --prefix=/usr \ + | --disable-option \ + | --enable-option + | + | make + | make DESTDIR="$1" install + `---- + + +* 4.1.2.4 Meson [2220] + + ,---- + | #!/bin/sh -e + | + | export DESTDIR=$1 + | + | meson \ + | --prefix=/usr \ + | -Doption=false \ + | -Doption2=true \ + | . output + | + | ninja -C output + | ninja -C output install + `---- + + +* 4.1.2.5 Cmake [2230] + + ,---- + | #!/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 + `---- + + +* 4.1.2.6 Go [2240] + + ,---- + | #!/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" + `---- + + +* 4.1.2.7 Python [2241] + + ,---- + | #!/bin/sh -e + | + | python setup.py build + | python setup.py install --prefix=/usr --root="$1" + `---- + + +5 GNU Free Documentation License +================================ + + Version 1.3, 3 November 2008 + + Copyright (c) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + <http://fsf.org/> + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document 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. + + 1. 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. + + 2. 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. + + 3. 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. + + 4. 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: + + 1. 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. + + 2. 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. + + 3. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + 4. Preserve all the copyright notices of the Document. + + 5. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + 6. 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. + + 7. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + 8. Include an unaltered copy of this License. + + 9. 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. + + 10. 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. + + 11. 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. + + 12. 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. + + 13. Delete any section Entitled "Endorsements". Such a section may + not be included in the Modified Version. + + 14. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + 15. Preserve any Warranty Disclaimers. + + 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. + + 5. 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." + + 6. 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. + + 7. 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. + + 8. 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. + + 9. 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. + + 10. 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 + <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. + + 11. 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. + + +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: + + ,---- + | 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''. + `---- + + If you have Invariant Sections, Front-Cover Texts and Back-Cover + Texts, replace the "with...Texts." line with this: + + ,---- + | with the Invariant Sections being LIST THEIR TITLES, with + | the Front-Cover Texts being LIST, and with the Back-Cover Texts + | being LIST. + `---- + + 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. |