$Id: user-guide.xml 2194 2011-04-24 12:41:05Z roskakori $
Copyright © 2004-2011 Thomas Aglassinger
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 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".
Table of Contents
List of Figures
List of Tables
List of Examples
Jomic is a viewer for comic books stored in CBZ, CBR, and PDF files. Features include a two page mode, caching and support for several image formats (PNG, JFIF/JPEG, TIFF, and GIF). It is Open Source software distributed under the GNU General Public License.
To find out what is new in this version, see the revision history. For updates and support, visit the Jomic homepage at http://jomic.sourceforge.net.
Table of Contents
This section describes how to install and run Jomic. There are several flavors of the application, with different steps required to set it up. Essentially, there is a version for Mac OS X offering unique features such as Finder integration, a Webstart release that can be installed and launched by simply clicking a link and finally a traditional installer with launcher scripts for Unix and Windows.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
Mac OS X 10.4 or later.
Java 1.4 or newer. Until Mac OS X 10.6, Java should already be installed. For Mac OS X 10.7 you can get it using Software Update from the Apple menu.
Perform the following steps to install Jomic:
Download
Jomic-x.y.z.dmg, where x, y, and z indicate the version number.Extract the archive and mount the volume contained in it (unless it already happened automatically after the download).
Copy the Jomic application to wherever you like, for example
~/Applications.
To start Jomic from the Finder, simply double-click it in the Finder, or drop a comic on the icon.
To start Jomic in the terminal, use the open command as usual, for example: open -a ~/Applications/Jomic stuff/comics/example.cbz. If you are unfamiliar with open, type man open to learn more about it.
If you want to use all options Jomic's command line interface
supports, things take some effort. The open command
does not allow to pass options to the application. To work around
this, the Jomic application bundle includes a little Python script to launch it from
the command line using the Java ressources of the application bundle.
As the script is located inside the bundle, its location depends on
the place where Jomic is installed. Assuming Jomic is located in
~/Applications/Jomic.app, you can run the script
using for example: python
~/Applications/Jomic.app/Contents/Resources/jomic.py
--continue.
Tip
Although you can also use the installer, the single JAR or Web Start to start Jomic under Mac OS X, there is not much point to it. They do not support many convenient features such as dragging and dropping comics on the icon, or assigning icons to CBZ and CBR files.
The easiest way to run Jomic on platforms other than Mac OS X is to use Webstart, a standard way to launch applications by simply clicking a link on a home page.
Java 1.4 or newer, available from http://java.com/.
About 1 GB of memory. Less should work, but might limit performance.
Open http://jomic.sourceforge.net/webstart/ in your web browser and click on "Start Jomic!". A window should pop up and inform about the download progress. This will take a while. When done, Jomic automatically launches.
To start Jomic, you can reuse the link mentioned above. However, this is a bit tedious because you have to start the web browser, select a bookmark and click the link.
Most Web Start setups come with an application launcher that makes it easy to start any of the installed Web Start applications.
Pressing "Launch Online" will check for possible updates and download them. If there are no updates the applications launches a lot faster then during the installation. Pressing "Launch Offline" will launch the application immediately. This even works without any network connection.
If you prefer the command line and are using Sun's Web Start implementation, the following should do the trick:
javaws http://jomic.sourceforge.net/webstart/jomic.jnlp
Without any network connection, use the "-offline" switch:
javaws -offline http://jomic.sourceforge.net/webstart/jomic.jnlp
Unfortunately Web Start does not allow to specify any application specific command line options, so you cannot pass a comic file name here.
Java 1.4 or newer, available from http://java.com/.
Optionally Java Advanced Imaging, available from http://java.sun.com/products/java-media/jai/current.html. The installer includes all files essential for JAI, but lacks platform dependent native libraries. This will reduce performance for some image related operations, most notably reading of TIFF images.
In case you need want the best performance, you need to download and install JAI optimized for your platform. In case you do that after having installed the generic JAI package included with Jomic, make sure to remove all
lib/jai_*.jarfiles from the Jomic installation directory. Otherwise, Jomic will keep disabling the native libraries.Optionally Java Advanced Imaging-Image I/O Tools, (again) available from http://java.sun.com/products/java-media/jai/current.html. You only need this if you want to view additional image formats such as JPEG 2000 or BMP.
Download
Jomic-Installer-x.y.z.jar, where x, y, and z indicate the version number.Start the installer from your desktop. If this does not work, you cannot use the Installer release. Use the Single-JAR release instead (see below).
Follow the instructions given by the installer. In particular, choose a directory to which all the Jomic related files will be copied during installation.
The installer should have copied a script in the specified
installation directory. Depending on your platform, the name is
jomic.sh or jomic.bat. Just
start the script without any parameters to get the "Open comic"
dialog, or use any of the options described on the manpage.
If you regularly run Jomic from the command line, consider extending $PATH (or %PATH%), or creating an alias for it.
This chapter gives a quick overview of the things you can do with Jomic.
To open a comic book, use → from the menu. To open the next issue (if there is any), use → .
To browse the pages, press Page down, Page up, or Space. Alternatively, you can use the icons in the toolbar.
To conveniently read the comic, use → . That way, you can see the whole page without scrolling.
To get a "real" comic feeling, use → . Note that the front page always is shown as a single page (like with a real comic). To read eastern comics from right to left, use → .
To see every pixel and drool over the art, use → .
Table of Contents
This opens a dialog where you can create a new comic. For
example, you could have a folder
~/drafts/s00paman_v01 containing the files
01.png, 02.png,
03.png, 04-05.png (which
contains two pages in a single image using landscape layout),
06.png, and 07.png. To
create a comic in ~/comics/s00paman_v01.cbz enter
the following values in the dialog:
Source image folder: ~/drafts/s00paman_v01
Target comic folder: ~/comics/ (The name of the actual comic file,
s00paman_v01.cbz, is automatically computed from the name of the source folder and selected comic file format.)
The options in the right part of the dialog allow to specify how to new comic and the images in it should be handled. For details, refer to the section called “Convert”. Additionally you can specify the following settings:
Open new comic: When enabled, after creating the new comic it will be opened automatically in the viewer.
Create comic for each sub folder: When enabled and the source folder contains images spread over multiple sub folder, a separate comic file will be created for each folder.
Image files naming conventions
On first sight it does not really matter how the image files are called. To ensure that your comic works with as many viewers as possible, they should follow the following guidelines:
Use leading zeros. Name your images
01.pnginstead of just1.png(or even001.pngin case there are more than 99 pages).If you combine two pages in one image using landscape layout, seperate the numbers with a hyphen (-). For example, page 9 and 10 should be
09-10.pnginstead of0910.png. Otherwise many viewers (including Jomic) would consider it to be page 910, and display it after most other pages.Use lower case letters only. For instance, use
hugo_01.pnginstead ofHugo_01.png. That way you avoid possibly improperly sorted images on platforms with case sensitive file systems (such as Linux).Use only character in file and folder names that are know to work on all platforms. Officially, these are: letters A-Z, numbers 0-9, hyphen (-) and underscore (_). One reason again is that these names work on all common file systems. Another is that neither ZIP nor RAR specify which character encoding archives use, so Umlauts, Kanji and other special character can easily get screwed up or result in broken file names.
This opens a dialog where you can select the comic to read.
The dialog also shows a preview image of the currently selected comic (which might take a while to compute when selected the first time) and offers a few options:
Open in full screen - If enabled, after opening a comic the view changes to full screen. For more information on full screen, see .
Adjust file extension - If enabled Jomic will check if the comic file has a proper comic extension (.cbr, .cbz, or .pdf). If not, it will be changed. This applies to too generic and wrong extensions. For a example, a genric .zip file will be changed to a more specific .cbz file, and so will a zipped comic improperly ending in .cbr.
The file will only be renamed if the comic could be opened successfully. In case you accidentally attempt to open a ZIP archive without any images Jomic will show an error and not rename it to .cbz.
It the comic files is located on a read only device (such as a CD) or write protected, the renaming will silently fail and the extension retains.
Once you selected a comic, Jomic extracts all images in it to a temporary directory. Next, it analyses the sizes of the images and uses this information to compute the page layout. Because all this can take a while, a progress bar informs you of the current state of affairs.
You can view only one comic at a time, so opening another comic automatically closes the current one.
In case you attempt to open an archive without any images in it, Jomic scans it for comics. If it can find any, it opens a dialog offering to extract the comics from the archive (to the same directory the archive resides in), and open one of them.
Jomic remembers the last few comics you read. This menu item lets you choose one again. If this item is disabled, it means that you have not read any comics (for example, if you just installed Jomic), or that you cleared it recently. To clear the list of recent comics, use → → .
Single issues of a comic series are often stored in the same directory, with a naming convention indicating the order of release.
For example, the directory
~/Comics/s00paman could contain the comics
s00paman_v1_c001.cbz,
s00paman_v1_c002.cbz,
s00paman_v1_c003.cbz, and
s00paman_v1_c004.cbz. If you are right now
viewing s00paman_v1_c002.cbz, then → opens the next issue, which would be
s00paman_v1_c003.cbz.
If this item is disabled, it means that you are already viewing the last comic in this directory.
This item acts similar to → , but opens the previous issue. For the example given
above, it opens s00paman_v1_c001.cbz.
If this item is disabled, it means that you are viewing the first comic in this directory.
Close the comic window. This is available only under Mac OS X because closing the window does not quit the application. Instead a framless menu remaims and the application keeps running.
Comics and images can use different formats, which may be useful in one situation but inefficient in another. Among the reasons to convert them to something else are:
You just scanned and cleaned up a comic using lossless PNG images. Now you want to save storage space and convert the images to the lossy but compact JFIF/JPEG fomat, and limit the size to 1200 x 1600 pixels.
You want to read comics on a computer without a comic reader. A PDF reader is installed though.
You accidentally created comics or images in "evil" formats such as CBR and GIF. Now that you realized your mistake, you want to remedy this and convert them to CBZ and PNG.
To convert comics, you first have to specify what you want to convert.
In particular, you can specify:
Comics to convert: Click the "Add" button to, and a file dialog open to let you choose the comics to convert. You can select multiple files and directories. In case you added an item accidentally, just select it in the list and click "Remove". Click "Clear" to start over with an empty list of files.
If you select a whole directory to convert, all files and directories are scheduled for conversion. Furthermore, the directory structure will be preserved in the output directory.
To directory: This specified the target directory where the converted comics should end up. You can either enter it directly in the text field, or click "..." and select it in a directory dialog.
Comic format: Choose "CBZ", which is the standard format for comics but requires a special reader such as Jomic.
Choose PDF, which is short for "Portable document format". Almost all current computers include a reader for PDF documents.
Caution
PDF only supports very few image formats. So when Jomic encounters an unsupported format during the conversion, it automatically converts such images to JFIF/JPEG before adding them to the document. As always with this format keep in mind that it might slightly reduce the image quality and its lossyness makes editing the image later not a good idea. In case of doubt keep the zipped comic around.
Image format: Choose what happens to the images the target comics:
Keep format: the target image has the same format as the image in the source comic. Because no image has to be converted, this will be faster than the other choices.
PNG: This is short for "Portable network graphics" and stand for a powerful and flexible image format that makes sure no information is lost. However, because every pixel is preserved, more space is required than for an image stored in a lossy format such as JFIF/JPEG (see below).
JFIF/JPEG: This is a lossy format that saves quite some space by removing pixels considered less important. This is particular useful if you are sure you are not going to edit the images anymore.
Limit page size to: When enabled, you can enter a maximum width and high in the fields below. If a comic contains an image that is bigger, it will be shrunken to these limits. Note that the size refers to images in portait size. Landscape sized images are automaticall recognized an can have twice the specified width before they are shrunken.
Add only images: When enabled, files in the source comic that are not recognized as images are removed from the target comic. For example, text files.
After clicking "Convert", a new window opens and informs about the progress.
This reveals the current comic in the Finder. This can be useful if after reading the comic, you decided to move or delete it.
If this item is disabled, you did not open a comic yet.
Use this item to export single images to a directory of you choice.
If this item is disabled, it means that you have to open a comic and view a page first.
Caution
In two page mode, this item can be confusing: If the current page consists of two images, only the left one is exported. If you expected the page to be one wide image, exporting will not yield the desired result. To avoid such surprises, switch to viewing single pages by disabling .
Tip
You can actually export broken images. This works because Jomic does not consider the rendered image in the view rather the file it came from. As a matter of fact, this action simply copies a file.
Unlike , this menu item exports all images of the comic.
It does not preserve the file name of the archive. Instead, files are
named according to the page number the would appear on, for example
01.jpg, 02+03.jpg,
04.png and so on. Again, even broken images are
exported.
Preserve names and directories from archives
If you need to preserve the directory structure and file names of the original archive, note that CBZ is a ZIP, and CBR a RAR archive. Thus you can change the file suffix to ZIP or RAR, and extract them using normal archive utilities.
If selected, images are shown in their actual size. If they do not fit the window, you have to scroll the image.
If selected, images fit the window. This removes the need for scrolling, but makes the comic difficult to read on smaller displays.
If selected, images fit the window. This removes the need for horizontal scrolling.
Switches display to full screen, removing all user interface elements and maximizing the image area. To exit full screen, press the Escape or any other menu shortcut key that issues a command that cannot be processed while in full screen (for example the one for → . These shortcuts still work despite the menus being invisible.
Full screen has several limitations you should be aware of:
All you can do in full screen is navigate the pages. Pretty much everything else causes full screen to exit.
Error dialog cause full screen to exit.
Some platforms do not support full screen in Java.
This commands rotates the whole comic to the left (90 degree counter clockwise). You can apply it several times to rotate further.
If enabled, images are blurred. This is useful if the original images were printed using a very cheap or old printing process.
This switch lets you decide if you prefer having a toolbar around, or rather have some more space on the screen for the images.
Enable this to see thumb nails for all the pages in the right part of the window. Clicking a thumbnail will go to the respective page.
Most of the time, you will give as much screen space to Jomic as possible. While a typical display is wider than higher, with images of single comic pages it just the other way round. Consequently, a large part of the window is unused.
In order to not waste this space, this option shows two images at the same time, resulting in a much improved comic feeling.
Note
The front page always shows as single page, just like with a real comic. Furthermore, sometimes comic archives contain a mix of single and double images. If a double image follows an uneven number of single images, the last single image has no next image that would fit on the screen together. Consequently, such an image also results in a single page to be shown.
This item swaps the left and right image in order to read for example mangas from right to left. Furthermore, when switching to a page that does not fit the window, you can start reading at the top right corner instead of the top left.
Use this to show or hide the information panel at the bottom of the viewer window. This panel contains details about the image, such as the filename, the image dimension, and possible encoding errors.
In case → has been enabled, you can adjust certain options to improve the image quality. Radius specifies the range of other pixels to include when blurring a certain pixel. Threshold specifies after which level pixels should be blurred; the higher the value, the less pixels are effected. Mode lets you choose between different blur algorithms.
Use this to go to the previous page.
If this item is disabled you are already at the first page.
This opens the user guide you are reading right now.
The viewer used is the standard JavaHelp viewer, which is a bit awkward but essentially works similar to a web browser.
One notable feature is is the search function, which you can use by clicking on the magnifier glass icon.
This open a window displaying the following information:
Platform name and version (for example Mac OS X-10.3.5-ppc), Java version (for example 1.4.2_05).
Cache and Memory status.
Image file suffixes recognized, and details about the Java ImageIO plug-in that deals that deals with the respective suffix.
This opens the the Jomic homepage at http://jomic.sourceforge.net.
This opens a web form in your browser where you can report a bug. A decent bug report should attempt to answer the following questions:
Which version of Jomic are you using?
What steps are necessary to reproduce the bug? The easiest way to describe this is as list of sentences worded as commands, for example "enter this", "click that", "wait for this to open", ...)
What was the result of these steps, and what would you have expected?
The bug report form is hosted on SourceForge, but you do not
need to register and login. Still, it is recommended to register and
login because it makes it easier to track where a bug came from.
Otherwise, your username simply is
nobody.
This opens a web form in your browser where you can issue a request for functionality currently missing in Jomic.
The feature request form is hosted on SourceForge, but you do
not need to register and login. Still, it is recommended to register
and login because it makes it easier to track where a request came
from. Otherwise, your username simply is
nobody.
Most menu items have a keyboard shortcut you can find out by looking at the right part of the respective item. For your convenience, there are some additional shortcuts that do not show up in the menu. Here's a list of them:
Table 3.1. Additional keyboard shortcuts
| Action to perform | Keyboard shortcuts | Internal command |
|---|---|---|
| Go to first page | Home | goFirst |
| Go a few pages backwards, skipping some | Alt-Page up | goPreviousFew |
| Go to previous page | Page down | goPrevious |
| Go to next page | Space, Page down | goNext |
| Go a few pages forward, skipping some | Alt-Page down | goNextFew |
| Go to last page | End | goLast |
| Scroll the current page (when using → ) | Cursor down, Cursor left, Cursor right, Cursor up | scrollDown, scrollLeft, scrollRight, scrollUp |
You can also use the mouse to navigate between pages:
To go to the next page, click the left button while the pointer hovers over the image.
To go to the previous page, keep the left button pushed and click the right button while the pointer hovers over the image.
This chapter describes how to adjust a few things not accessible from the graphical user interface. For most people, there is no real need to touch any of these.
Many of Jomic's settings can changed by a menu item or check box
in a dialog, but there are some for which there is no user interface
item. To change these, you have to manually modify a file called
jomic.properties. Keep in mind that you can
really screw things up when tinkering around here. In case you render
Jomic unable to launch without error message, remember that you can
reset it by removing jomic.properties. If Jomic
can not find this file, it uses internal defaults for all settings
that are known to work. After exiting the application, a new
jomic.properties can be found with the default
values stored in it.
The actual location of this file depends on your platform and
user name as shown in Table 3.2, “Location of jomic.properties”.
Table 3.2. Location of jomic.properties
| Platform | General location | Example location with user name "me" |
|---|---|---|
| Mac OS X | ~/Library/Preferences/jomic.properties | /Users/me/Library/Preferences/jomic.properties |
| Unix-like, Web Start | ~/.jomic/jomic.properties | /homes/me/.jomic/jomic.properties |
| Windows | %APPDATA%/jomic.properties | C:\Documents and Settings\me\Application Data\jomic.properties |
Example 3.1, “Sample jomic.properties” shows the first few
lines of such a file.
Example 3.1. Sample jomic.properties
#Settings for Jomic #Mon Jul 09 19:20:05 CEST 2007 scaleMode=fit showThumbs=false lastExportedImageDir=/Users/me/Desktop window.comic=[0, 22, 1305, 1178] showToolbar=false fillColor=\#ededed ...
The first two lines are comments generated when Jomic saves the settings on application exit. There is no point in modifying these lines because they are discarded during application startup.
The other lines however specify a setting and its value
apparently using the pattern setting=value. Table 3.3, “Possibly useful settings in
jomic.properties” describes some of the properties that
have no equivalent in the graphical user interface. Note that the
value uses Java escape sequences, which means some special characters
have to be "escaped" using a backslash (\). In particular:
Use \\ to get a single backslash. This is especially important when spefifying Windows folders. For example,
C:\Stuff\SomeFolderhas to be specified asC:\\Stuff\\SomeFolder.Common characters that need a backslash in front: quote (type
\") and hash (type\#).Non-ASCII characters such as Umlauts and Kanji need to be unicode-escaped. This is somewhat unfunny for non-geeks, so better avoid it or get used to typing stuff like \U009f to get an Umlaut-U.
Table 3.3. Possibly useful settings in
jomic.properties
| Purpose | Property name | Description of value | Example |
|---|---|---|---|
| Set the folder where the cache is located. This is particular useful if you have a seperate (usually older) hard drive for you caches and temporary data. | cacheDir | The folder where the cache (and its sub folders) are located. If the folder does not exist yet, Jomic attempts to create it. |
|
| Set the maximum size of the disk cache. . If the current comic is bigger than this value, the maximum size might be exeeded temporarily. | archiveCacheSizeInMb | The maximum size of the cache in Megabyte. |
|
| Set location and size of windows and dialog. Normally there is no need to edit these manually because Jomic remembers windows and dialogs on application exit. However, in case on of the windows ends up in an invisible location, you can fix this by removing or changing its corresponding property. | window.* | [x, y, width, hight] | [32, 32, 800, 480] |
Jomic logs all actions it performs. This log can be viewed using /Application/Utilities/Console.
This log can be helpful to trace back problems. Furthermore its useful to include relevant parts of the whole log in bugs reports. By default, the log only contains basic information about initialization and user interaction. For most practical purpose, this is all you need to know about it.
If you are familiar with log4j, you can also mess around with it
by providing
~/Library/Preferences/jomic-logging.properties.
For example, it might contain the following lines:
Example 3.2. Sample jomic-logging.properties
log4j.rootLogger=DEBUG, stdout log4j.appender.stdout=org.apache.log4j.ConsoleAppender log4j.logger.net.sf.jomic.tools=INFO
For details on log4j, see http://logging.apache.org/log4j/docs/index.html.
If you do not mind the hassle of subscribing, the jomic-users mailing list is the preferred place to ask questions, report bugs, suggest features, or discuss other issues related to Jomic.
As Jomic is hosted on Sourceforge, so you can also use the following facilities to:
download updates
post a question to the help forum
report and track bugs
look what new features are already planned
access the source code
If you want to play with the code or contribute, read the notes on development. This explains how to setup an environment in which you can compile and run Jomic.
To contact me directly, use my SourceForge user page.
The following people and tools were very helpful for the development of Jomic:
junrar, a Java package to extract
*.rar(and*.cbr) archives.pdfbox, which provides the means to parse PDF comics.
MRJ Adapter, which makes it easier for Java applications to behave like nice Mac OS X applications while retaining portability
IzPack, an installer generator for Java applications.
John Munsch for nagging about the lack of a Web Start release and posting code how to do it.
Thomas Kutschera for creating the Jomic icon.
Log4j, which logs internal messages and simplifies tracking problems both for users and developers.
Several tools that help to assure quality:
Emma analyzes code coverage of the test programs.
CheckStyle , JDepend, and FindBugs analyze the source code and help detecting problems early on.
JRefactory's pretty printer ensures consistent formating of the source code
Abbot provides a framework and a script editor for UI testing.
JUnit simplifies writting test cases.
Creation of the documentation was supported by:
The DocBook open repository features transformations to convert the documentation to HTML, JavaHelp, PDF, and some other formats.
The official DocBook homepage has all the documentation and tutorials you need to write manuals in this format.
Tidy has the monopoly on being the only XML parser in the world producing human readable error messages - at least sometimes.
Sven Van Caekenberghe for his article on "Tuning Java Swing applications for Mac OS X", and the related example code. This saved me an awful lot of time.
Table of Contents
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
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.
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.
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.
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.
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:
- 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.
- 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.
- State on the Title page the name of the publisher of the Modified Version, as the publisher.
- Preserve all the copyright notices of the Document.
- Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
- 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.
- Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
- Include an unaltered copy of this License.
- 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.
- 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.
- 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.
- 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.
- Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version.
- Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section.
- 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.
You may combine the Document with other documents released under this License, under the terms defined in section 4above 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".
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.
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.
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.
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.
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.
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.2 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.
| Revision History | |
|---|---|
| Revision 0.9.34 | 08-Oct-2011 |
| |
| Revision 0.9.33 | 01-Aug-2011 |
| |
| Revision 0.9.32 | 30-Jul-2011 |
| |
| Revision 0.9.31 | 21-Apr-2011 |
| |
| Revision 0.9.30 | 20-Apr-2008 |
| |
| Revision 0.9.29 | 29-Dec-2007 |
| |
| Revision 0.9.28 | 15-Dec-2007 |
| |
| Revision 0.9.27 | 21-Oct-2007 |
| |
| Revision 0.9.26 | 31-May-2007 |
| |
| Revision 0.9.25 | 19-Mar-2007 |
| |
| Revision 0.9.24 | 07-Jan-2007 |
| |
| Revision 0.9.23 | 12-Nov-2006 |
| |
| Revision 0.9.22 | 31-Jul-2006 |
| |
| Revision 0.9.21 | 25-May-2006 |
| |
| Revision 0.9.20 | 11-Apr-2006 |
| |
| Revision 0.9.19 | 27-Mar-2006 |
| |
| Revision 0.9.18 | 27-Mar-2006 |
| |
| Revision 0.9.17 | 12-Mar-2006 |
| |
| Revision 0.9.16 | 01-Jan-2006 |
| |
| Revision 0.9.15 | 20-Dec-2005 |
| |
| Revision 0.9.14 | 25-Sep-2005 |
| |
| Revision 0.9.13 | 16-Sep-2005 |
| |
| Revision 0.9.12 | 02-Jul-2005 |
| |
| Revision 0.9.11 | 28-Jun-2005 |
| |
| Revision 0.9.10 | 19-Jun-2005 |
| |
| Revision 0.9.9 | 23-May-2005 |
| |
| Revision 0.9.8 | 16-Mar-2005 |
| |
| Revision 0.9.7 | 13-Mar-2005 |
| |
| Revision 0.9.6 | 03-Jan-2005 |
| |
| Revision 0.9.5 | 27-Dec-2004 |
| |
| Revision 0.9.4 | 15-Nov-2004 |
| |
| Revision 0.9.3 | 01-Nov-2004 |
| |
| Revision 0.9.2 | 17-Oct-2004 |
| |
| Revision 0.9.1 | 08-Aug-2004 |
| |
| Revision 0.9.0 | 21-Jul-2004 |
| |
| Revision 0.8.13 | 15-Jul-2004 |
| |
| Revision 0.8.12 | 11-Jul-2004 |
| |
| Revision 0.8.11 | 15-Jun-2004 |
| |
| Revision 0.8.10 | 05-Jun-2004 |
| |
| Revision 0.8.9 | 02-May-2004 |
| |
| Revision 0.8.8 | 20-Apr-2004 |
| |
| Revision 0.8.7 | 19-Apr-2004 |
| |
| Revision 0.8.6 | 09-Apr-2004 |
| |
| Revision 0.8.5 | 01-Apr-2004 |
| |
| Revision 0.8.4 | 28-Mar-2004 |
| |
| Revision 0.8.3 | 25-Mar-2004 |
| |
| Revision 0.8.2 | 15-Mar-2004 |
| |
| Revision 0.8.1 | 14-Mar-2004 |
| |