Next: , Previous: (dir), Up: (dir)

Stephe's introduction and customization for GNU emacs

Release 1.8, 18 Aug 2006.

       Copyright (C) 2001 - 2007 Stephen Leake
       Permission is granted to copy, distribute and/or modify this document
       under the terms of the GNU Free Documentation License, Version 1.1
       or any later version published by the Free Software Foundation;
       with no Invariant Sections, with no Front-Cover Texts, and with no
       Back-Cover Texts. A copy of the license is included in the section
       entitled ``GNU Free Documentation License''.


Next: , Previous: Top, Up: Top

1 Introduction

GNU Emacs is a very powerful editing environment. It takes a long time to learn how to use it well; I've been using it for over 10 years, and I'm still learning new things Emacs can do, or better ways to use it.

I've developed a set of customizations (function definitions and key bindings) that make Emacs work more easily for me. Here I describe some of the rationale for these customizations, and give a reference of what they do. I assume you are on a Windows platform, but most of this is valid for other platforms as well.

This will also serve as an introduction to Emacs for new users, replacing some of the Emacs Tutorial.

The standard Emacs keybindings are designed to let you keep your hands in the "home" position on the keyboard. As such, they do not use function keys, cursor keys, or any other keys on modern keyboards. One advantage of this is that if you move to another computer with a different keyboard, you will be able to use Emacs comfortably. A disadvantage is that you often need three or more keystrokes to invoke one command.

I have a hard time remembering three key sequences, and most computers (even laptops) either use a PC keyboard or can be configured to emulate one. So I use the function keys, the cursor keys, and the 6-key "edit" keys. I don't use any of the "numeric keypad" keys, because they usually are not present on laptops. I also try to use the Control, Shift and Meta key modifiers consistently.

The menu contains the most useful commands, and shows the keyboard equivalents. To access the menu from the keyboard, use the left "Windows" key.


Next: , Previous: Introduction, Up: Top

2 Fonts

You can choose the font Emacs uses; this can have a significant effect on the number of characters you can fit on the screen, as well as on how easy it is to read those characters.

S-down-mouse-1 (shift left mouse) brings up a font selection dialog, and sets the current font to the one chosen.

To set the font permanently, execute (assoc 'font (frame-parameters)) in the scratch buffer; it returns the string name of the font. Include that string on the command line that starts Emacs (for example, in ~/bin/emacs.sh); emacs --font="...".


Next: , Previous: Fonts, Up: Top

3 Buffers, windows, and files.

Each file you read into Emacs is kept in a 'buffer'. All editing is done in the buffer; the file is not changed on the disk until the buffer is 'saved'. You can have as many buffers as you want (up to the virtual memory limit on your machine).

Buffers are displayed on the display in 'windows'. Windows are normally stacked vertically within the Emacs display, but they can be side by side as well. Windows never overlap. You can have many windows visible at once, but the practical limit is about 4. Any window can display any buffer, and a buffer can be visible in more than one window (this is handy for seeing two different parts of a file).

There are also buffers that are not associated with any file; they display messages, or help information, etc.


Next: , Previous: Buffers windows and files, Up: Top

4 Modes

Each buffer has a 'mode'. The mode determines what each keystroke does, how the text is highlighted with color, what characters delimit words, what some of the function keys do, and some other things.

Emacs determines the mode of a buffer based on the file extension of the file associated with the buffer. So Ada files, which have the extension '.ads' or '.adb', are in Ada mode; C files ('.c', '.h') are in C mode, etc.

There are many key bindings that are global; they are common to all modes. There are other keys (such as <tab> and <F5>) that invoke different functions in each mode, but do basically the same thing (indent and compile, respectively). There are also sometimes keys that are specific to each mode.


Next: , Previous: Modes, Up: Top

5 Point and mark

The current cursor location is called 'point'. Every buffer has another named location, called 'mark'. Many commands set the location of mark to the point, and then move point. So going to mark is an easy way of getting back to where you were; <M-C-home> goes to mark. <C-u C-SPC> also goes to mark, and rotates the ring of saved mark locations; hitting <C-u C-SPC> repeatedly takes to the list of places you've been recently.

An important use of point and mark is defining the 'region'; the region is the text between point and mark. When you select text, it is the 'active region', and is highlighted. Many commands act on the current region, if it is active.

To select text, hit <C-SPC> (or select menu Edit | Start Select). This sets the mark, and labels the region active. Then move the cursor using the normal cursor movement keys; the text between point and mark will be highlighted. To cancel the selection, hit <C-SPC> again.

For more information on using text selections, See Cutting and pasting.


Next: , Previous: Point and mark, Up: Top

6 Moving around

The arrow keys move the cursor in the indicated direction. When the cursor reaches the top or bottom edge of a window, the buffer is scrolled within the window to keep the cursor visible. When the cursor reaches the beginning or end of a line, it moves to the next line.

Modifying the arrow keys with the Meta key moves the cursor farther; <M-left> and <M-right> move by words, <M-up> and <M-down> move by paragraph (paragraphs are mostly useful in text modes, rather than programming language modes).

The <page up> and <page down> (called <prior> and <next>) keys also move the cursor large distances; the exact motion depends on the mode. In most programming language modes, these move to the next function definition.

<M-page-up> and <M-page-down> move larger distances; by chapter in LaTeX and TeXinfo modes, by major sections in Ada source code (defined by special comments), etc.

The <home> and <end> keys move to the beginning and end of the current line; repeating them moves to the previous or next line. <M-home> goes to the beginning of the buffer; <M-end> goes to the end. <M-C-home> usually brings you back to where you where when you did <M-home> or <M-end> (Point and mark); this is an easy way to quickly check on a file header.

<M-C-end> prompts for a line number, and goes there. This is not often needed; the programming language modes provide a way to go to the line for an error message automatically.

<M-C-up> goes to the window above the current one, <M-C-down> goes to the window below the current one. You can also click in another window with the mouse. If there are windows side by side, <M-C-down> and <M-C-up> cycle thru them as well.

<M-C-left> and <M-C-right> do not change windows; they change the indentation of the active region instead. This is an easy way to adjust the indentation of blocks of text.

Adding the shift modifier to the cursor keys does deletion; <S-right> deletes the character to the right of the cursor, <M-S-right> deletes the word to the right, <S-up> deletes the line to the right. <S-left>, <M-S-left>, <S-down> work similarly. Note that <M-S-up> is not a valid key (at least in Microsoft Windows). You can select a large portion of text, then delete it with the <delete> key. See Cutting and pasting.


Next: , Previous: Moving around, Up: Top

7 Managing windows, buffers and files

To read a file into a new buffer, and show it in the current window, use <F12> (or menu Files | Open File...). <C-u F12> opens in another window. You are prompted for a file name, with the default at the current file's directory. You can use tab to complete directory and file names. When you find the file you want, hit return. If you select a directory (without the trailing slash), it is shown in 'dired' mode (directory edit); this is convenient for seeing all the files in a directory, and copying, moving, or renaming them.

To create a new file, use <F12> or menu Files | Open File... , and enter a new file name. Note that there is no menu “Files | New File”.

To create a “shortcut”, type a file name into a buffer. Then position the point in the file name, and hit <C-F12>. Note this is a modification of <F12>, which is “goto file”; in this case, the file name is taken from the text around point.

To change the buffer visible in a window, you can use the Buffer menu, or the <F11> key. <C-u F11> switches to a buffer in another window. You are prompted with the list of buffers; typing a string will restrict the list to buffer names containing the string. <left> and <right> rotate the list. Hitting return selects the first element in the list (highlighted).

To split the current window in two, use <M-2>. To delete the current window, use <M-0>. To make the current window fill the screen, use <M-1>. To make all the windows approximately the same size, use <M-=>.

To convert a file format from Unix to DOS line endings (or vice versa), use <C-x ret f>, and specify “unix” or “dos”.


Next: , Previous: Managing windows buffers and files, Up: Top

8 Cutting and pasting

To see how to select text, See Point and mark.

To cut the current selection, use <delete> (in the edit keypad, not the numeric keypad) (or the Edit | Cut menu). This saves the deleted text in the kill ring, and in the Windows clipboard on Windows, and in the X clipboard on X windows. <C-x> does not cut (as it does in other Windows applications), because many Emacs keybindings use <C-x> as a prefix key.

To copy the current selection, use <M-delete>.

To paste the top item in the kill ring, use <insert> (or the Edit | Paste menu). You can paste other selections from the kill ring using the Edit | Select and Paste menu. Or use <C-insert> to replace the last paste with the next item in the kill ring, or <C-M-insert> to replace with the previous item in the kill ring. These last two operations let you keep several items in the kill ring, and access them easily.

To replace the current selection, use <M-insert>.

You can undo any edit action with <C-/>.


Next: , Previous: Cutting and pasting, Up: Top

9 Find and Replace

Finding or searching for text is done interactively. To start, type <C-s>. You are prompted for the search string. As you type each letter, the buffer is searched for the string entered so far, and point is moved to the first match found.

By default, searching is case insensitive; if you type lowercase letters, both upper and lower case are found. However, if you type uppercase letters, or a mixed case string, only exact case matches are found.

To replace text, start by typing <M-%>. You are prompted for the search string (not interactive) and the replace string. History is supported on both; type <up> at the prompt to retrieve previous search and replace strings.

If you search for a lowercase string, both uppercase and lowercase are found. The case of the replace string is adjusted to match the found text.


Next: , Previous: Find and Replace, Up: Top

10 Keyboard Macros

It is often useful to record a sequence of keystrokes and then play them back at different points in a buffer.

To start recording, type <F2>. Then type the keystrokes you want to record. To stop recording, type <M-F2>. To playback the keystrokes, type <F3>.

You can also assign the keystrokes to another key, so you can save a second sequence, and playback either one. Type <C-F2>, which prompts for the key to assign. <M-F3> and <C-F3> are available for this purpose.


Next: , Previous: Keyboard Macros, Up: Top

11 Editing source code

Emacs is often used to edit source code in various programming languages, and has many powerful features to make that editing process more productive.

I always use Makefiles to compile code, since makefiles allow executing multiple processing steps automatically. Processing steps may include an external pre-processor, compiling, linking, running test code, comparing test outputs.

To run 'make' from a Makefile, use <F5>, and specify the target. To invoke the current Makefile again from a language file, use <F5>. To go to the next error in the compilation output, use <F6>.

I also use the 'Else' package (not part of standard Emacs yet). This provides a powerful template language, based on Digital Equipment Corp's Language Sensitive Editor language. Most language keywords are defined as 'tokens'; they can be expanded into a template statement by <C-e>. 'placeholders' in the template are indicated by brackets {}; they can also be expanded by <C-e>. <C-e> usually pops up a menu buffer; use the cursor keys to select the appropriate expansion, and hit return. To abort a menu, use 'q'.


Previous: Editing source code, Up: Editing source code

11.1 Ada

In Ada, package specifications have corresponding package bodies. <C-F11> switches between these corresponding files, and in addition places the cursor at the corresponding subprogram spec or body. <C-u C-F11> puts it in the other window. This makes it very easy to see the spec or body corresponding to the code you are currently looking at.

Gnu Ada also has a powerful cross-reference facility. With point on an identifier in a file that has been compiled, <C-c C-d> will goto the declaration of that identifier. <F7> lists all uses of the identifier under point.

There are several constructs in Ada that are easier to read if they are aligned in columns; object or record component declarations, assignments, comments, with/use statements, aggregate and parameter associations, subprogram parameter lists. These are all aligned automatically by <M-[>; just place point somewhere within the structure, and hit <M-[>.

Emacs will automatically indent Ada code properly (according to style rules that are customizable). To indent a single line, hit <tab>. To indent a region, hit <C-M-\>.

Emacs will automatically create a subprogram body skeleton from a subprogram spec. First write the subrogram spec in the package spec, then copy it to the body. Then place the cursor after the final semicolon, and hit <C-c C-b>. This will insert the “is begin end name;” for you.

To make it easy to move around in an Ada file, the page up and page down keys are used with meta and control. Note that Emacs calls the page up key <prior>, and the page down key <next>. The movement keys will stop at the following list of items in a file: subprogram, block, task, type, or package beginning, even if nested one level (higher nested items are skipped); a comment line starting with 10 or more dashes; the beginning or end of the file. Meta and control skip some things, to move farther faster.

<prior, next>
Move to the previous/next item
<M-prior, M-next>
Move to previous/next non-nested item.
<C-prior, C-next>
Move to dashes or top level items only.
<M-C-prior, M-C-next>
Skip dashes; top level items only.


Next: , Previous: Editing source code, Up: Top

12 Debugging

Emacs serves as a nice interface to the Gnu debugger 'gdb'. To start the debugger, first navigate to the Makefile that built the executable (or any buffer that has the build directory as its default directory). Then run <M-x gdb>. This prompts for the name of the executable to debug (with tab completion). Then it opens a window with the command line interface to gdb.

To set break points, navigate to the desired source line, and hit <C-x SPC>.

In source languages that support exceptions, you can set breakpoints on exceptions with <break exception> or <break exception <name>>.

To start the program running, type <run> at the gdb prompt. When a breakpoint is hit, Emacs brings up the corresponding source line.

To step to the next line, use <n>. To step into a subprogram, use <s>.

To display variables, use <print <name>>. This can be abbreviated to just <p <name>>.

To move up or down the call stack, use <up>, <down>.

To quit the debugger, use <quit>.

For more help on gdb, see the Emacs info.


Next: , Previous: Debugging, Up: Top

13 Key summary

<tab>
In most modes, indent current line, according to mode. In other modes, tab to next tab stop.
<M-tab>
On Microsoft Windows and some X-Windows managers, cycle among the window manager windows. This is not an Emacs key.
<M-0>
Delete the current window.
<M-1>
Make current window the only window.
<M-2>
Split the current window in two.
<M-=>
Make all windows about the same size.
<M-[>
Align an Ada construct (object or record component declarations, subprogram parameter lists, aggregates, etc).
<C-/>
Undo last edit action. Repeatable for a long time.
<C-M-\>
Indent the current region.
<M-$>
Spell-check the word under point. Requires aspell from Cygwin.
<C-u C-SPC>
Goto mark, rotate mark ring.
<C-SPC>
Toggle mark activation; this starts or cancels text selection.
<C-c C-b>
In Ada, create an empty body from a subprogram spec.
<C-c C-d>
In Ada, goto the declaration of the identifier under point.
<C-e>
Expand an Else token or placeholder.
<C-x ret f>
Change the line-ending format of a file
<F5>
In most modes, compile the file, usually by re-running the most recent make command. In lisp modes, execute the previous sexp.
<F6>
Goto the next error message in the compiler output.
<C-u F6>
Reparse the compiler error messages, and goto the first one. Useful if the error parser gets confused, or if you reset the compiler search path (from a project file).
<F7>
In Ada, list all uses of identifier under point (files must be compiled).
<F11>
Goto another buffer. The prompt filters the buffer list to buffer names containing the text you type. <left>, <right> rotate the list.
<C-F11>
Goto the “corresponding file”. This is meaningful only in programming language buffers; in C, headers and bodies correspond; in Ada, package specs and package bodies correspond. So if you are in an Ada package spec, and hit <C-f11>, you will go to the corresponding Ada package body.

The cursor is placed on the corresponding subprogram spec or body.

However, if you are on a “special line”, the file found is different:

with Foo;
Goto the Foo package spec.
package Foo.Bar is
Goto the parent spec (Foo, in this case).
#include
Goto the included header file.

<C-u F11>
Goto another buffer in another window.
<C-u C-F11>
Goto the corresponding file in another window.
<F12>
Open (or create) a file. The prompt supports tab completion.
<C-u F12>
Open a file in another window.
<C-F12>
Open the filename under point; this is an Emacs “shortcut”.
<left, right, up, down>
Move point one character left, right, up, down.
<M-left, M-right>
Move point one word left, right.
<S-left, S-right>
Delete one character left, right.
<M-S-left, M-S-right>
Delete one word left, right.
<M-C-left, M-C-right>
Change indentation of active region left or right.
<M-up, M-down>
Move point one paragraph up, down.
<S-up, S-down>
Delete one line up, down.
<M-C-up, M-C-down>
Move to previous/next Emacs window.
<prior, next>
In text modes, move one screen's worth up or down. In programming modes, move to previous/next function or other declaration.
<M-prior, M-next>
Move up/down larger distances, depending on mode.
<M-C-prior, M-C-next>
Move up/down even larger distances, depending on mode.
<home, end>
Move to beginning/end of current line. If at beginning/end, move to previous/next line.
<M-home, M-end>
Goto beginning/end of buffer.
<M-C-home>
Goto mark.
<M-C-end>
Prompt for line number, go there.
<delete>
Cut selected text to the clipboard (both Emacs and Windows or X clipboards). If no selection is active, delete one character to the left.
<M-delete>
Copy selected text to the kill ring (both Emacs and Windows or X clipboards).
<insert>
Insert text from the kill ring (clipboard).
<M-insert>
Replace the selected text with the kill ring text.
<C-insert>
Replace the previous pasted string with the next string in the kill ring.
<C-M-insert>
Replace the previous pasted string with the previous string in the kill ring.


Next: , Previous: Key summary, Up: Top

14 Installation

My customizations are kept in a Goddard CVS server accessed via ssh. Alternately, you can get a snapshot from my webpage http://stephe-leake.org/.


Next: , Previous: Installation, Up: Installation


Next: , Previous: CVS installation, Up: Installation

14.2 Standalone installation

If you know your way around Emacs, you can pick and choose from my additions.

Many people want just the pcvs and Ada mode enhancements. Here's details for that, assuming Cygwin on Windows (I assume you can adapt to your OS and shell). For concreteness, I assume you have Emacs installed at c:/Gnu/Emacs/emacs-21.3.


Previous: Standalone installation, Up: Installation

14.3 Gnus installation

I use Gnus for reading email and newsgroups; Gnus is distributed as part of Emacs, so installation is simple.

I use the add-on Insidious Big Brother Database (bbdb) with Gnus, to manage email addresses. Installation for that on Windows is given here. For some reason, the bbdb Makefile doesn't work properly.


Previous: Installation, Up: Top

Appendix A GNU Free Documentation License

Version 1.2, November 2002
     Copyright © 2000,2001,2002 Free Software Foundation, Inc.
     51 Franklin St, Fifth Floor, Boston, MA  02110-1301, USA

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.
  1. 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.

  2. 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.

    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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.”

  7. 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.

  8. 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.

  9. 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.

  10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

  11. 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.