diff options
Diffstat (limited to 'docs/docs/carbslinux.txt')
| -rw-r--r-- | docs/docs/carbslinux.txt | 1356 |
1 files changed, 0 insertions, 1356 deletions
diff --git a/docs/docs/carbslinux.txt b/docs/docs/carbslinux.txt deleted file mode 100644 index a969c74..0000000 --- a/docs/docs/carbslinux.txt +++ /dev/null @@ -1,1356 +0,0 @@ - _________________________ - - 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/install.txt>. - - ,---- - | curl -sL https://carbslinux.org/install.txt | less - `---- - - .. 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 - - -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', and `bison' 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. |