LEARN SHANTY™

A MARKUP LANGUAGE FOR WRITING E-BOOKS

Saturday Night at Sea by Thomas Dibdin, an illustration of sailors singing a sea shanty.
Saturday Night at Sea by Thomas Dibdin, taken from Wikimedia Commons.

Copyright © - Nantucket E-Books LLC

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

Logo for the GNU Free Documentation License.

OVERVIEW

SHANTY™ is a markup language that makes writing e-books easier. With minimal markup, anything from a short story to a novel can be easily converted into my Nantucket e-book platform.

Nantucket E-Books™ is an e-book platform that is mobile-friendly, and will work in any modern browser. It includes interactive features like note-taking, dark mode, bookmarking, and audiobook integration.

Here's an example of a Nantucket E-Book™.

To publish a Nantucket E-Book™, simply format your text with the Shanty™ syntax. You can use any text editor you wish: Notepad, Word, Google Docs, Pages, OpenOffice.org, you name it. Since Shanty™ is plain-text, it's lightweight and future-proof. Then, run it through the browser-based text editor, Arrowhead, and you'll receive a Nantucket E-Book™in HTML format.

If you're a writer, Shanty™ makes it a snap to convert your text files into a Nantucket E-Book™. Eliminate the tedious task of adding HMTL tags to a document, and spend your opportunity costs on more writing!

TABLE OF CONTENTS


BASICS

If you're publishing for nantucketebooks.com, you are required to include three pieces of metadata: a title, an author, and a keyword for favoriting. If your text does not include all three, the parsing program will return an error and quit.

ADDING A TITLE AND AUTHOR

To add a title and author to your e-book, add the following lines:

Title and Subtitle as they appear in markup Title and Subtitle as they appear after rendering From November in America by Nicholas Bernhard

You can also add a link to your the author's name like so:

ADDING CHAPTERS

Breaking down your e-book into chapters is easy. Place # before the name of each chapter.

If your chapter has a subtitle, use ## and put it on the next line.

The program will look for these symbols, and use them to build your table of contents.

Chapters as they appear in markup Chapters as they appear after rendering

Make sure every chapter title is unique!

Hyperlinks are what make digital documents truly powerful. To add a link to a paragraph, use the following syntax:

Links will open in a new tab, unless it's a link within the e-book itself, or a download link.

If you add an id to your link, make sure there are no spaces.

To specify the download option, type download.

You may want to give an id to a specific bit of text, which you can then link to. To do this, use the following syntax:

You should use the footnote functionality to add a footnote.

If you are linking to text within the e-book itself, be sure you add a # symbol before the hyperlink.

EXTRAS

BREAKS

To add a section break, also known as a dinkus, just add four asterisks, ****, on a new line.

Breaks as they appear in markup Breaks as they appear after rendering From Then A Skeleton Popped Out by Nicholas Bernhard

To add an empty space, add the following on a new line:

To use an image as a break, check out the section on adding an image.

BOLD AND ITALICIZED TEXT

To add bold text to your e-book, put two asterisks (**) on either side of the word(s).

To add italicized text to your e-book, put one asterisk (*) on either side of the word(s).

Italicized text in markup Italicized text as it appears after rendering From November in America by Nicholas Bernhard

Want to make text bold and italicized? Use three asterisks!

DROP CAPS

A drop cap is the first letter of the first paragraph of a book, or chapter, that is printed much larger than the rest of the text. It is used for ornamentation.

To begin any paragraph of your text with a drop cap, put the following syntax at the beginning of the paragraph:

Drop caps in markup Drop caps after rendering From The Great Gatsby, Chapter I, by F. Scott Fitzgerald

UNDERLINES, HIGHLIGHTS, STRIKETHROUGHS, AND CODE TEXT

You can further stylize paragraphs using underlined text, highlighted text, strikethroughs, and code text.

Images of syntax for underlining, highlighting, strikethrough text, and code text Images of underlined, highlighted, struck-through, and code text after rendering

Code text is helpful if you are writing software documentation.

You can combine this syntax, but if you do, make sure the syntax is properly nested. Whatever order you put the syntax at the beginning, put it in reverse order at the end.

TEXT-ALIGN

Nantucket will default to justified paragraphs: each line has the same width.

If you want to align the text a different way, put the following syntax at the beginning of your paragraphs:

Text-align markup Specially-aligned text after rendering

SUB-TITLES

To add a sub-title to your book, just add a !!SUBTITLE line to the beginning of your text:

Subtitle as it appears in markup Subtitle as it appears in markup From November in America by Nicholas Bernhard

SPECIAL CREDITS

The program will automatically credit the e-book as "By author's name."

If you want to specify a different credit, use a !!CREDIT line.

Special credits as they appear in markup Special credits as they appear after rendering

ADDING LINKS TO CREDITS

When crediting someone's work on an e-book, you may want to include a link for that person. For example, the official Nantucket E-Books™ site has a directory for writers, illustrators, and voiceover artists to find and contact each other.

Here is a link of Shanty™ markup tags that can include links for artists:

To add a link to an artist credit, just add the :link attribute to the tag.

To add a link to !!AUTHOR, !!COVERART, and !!ILLUSTRATOR tags, add the following to the end of the line:

To add a link to the !!AUDIOCREDITS tag, use this syntax:

Finally, to add a link for an illustration (@@ILLO), use the :link attribute, as described in the section on adding illustrations.

LINKING TO THE NANTUCKET E-BOOKS™ DIRECTORY

To link to a listing in the Nantucket E-Books™ directory, all you have to do is provide the ID for the listing. The ID for a listing is just under the listing's name.

LINKING TO AN EXTERNAL WEB PAGE

If you want to link to another web page entirely, just provide the full link to the web page. Links to external web pages must begin with 'https'.

DATES AND LOCATIONS

You may want to end your piece with some information on when and where you wrote it. This helps ground your work in a specific time and place. To do so, use the following format:

The date must be either YYYY-MM-DD, YYYY-MM, or YYYY.

Location and Date as they appear in markup Location and Date as they appear after rendering From Then A Skeleton Popped Out by Nicholas Bernhard

Nice. Just like Stephen King!

The location and date are both optional, you can use either, neither, or both.

These will always be placed towards the end of your document.

DEDICATIONS

To add a dedication to your e-book, add the following line:

Dedication as it appears in markup Dedication as it appears after rendering From November in America by Nicholas Bernhard

QUOTES AND EPIGRAPHS

An epigraph is a quote at the beginning of your book that sets the tone, or provides the context, for the rest of the work.

To add an epigraph, or any other special quote, use the following lines:

Blockquote as it appears in markup Blockquote as it appears after rendering From Sweet Relief by Nicholas Bernhard

WORKING WITH LONG WORDS

If a word is too long, the word can push outside of its boundaries, and mess up the page layout.

The quick solution for this is to tell your page where words should be broken up, and then add the markup @wbr@, which stands for word break.

Markup for long words Finished result after markup for long words was added From Then A Skeleton Popped Out by Nicholas Bernhard

The above example was taken from an e-book being displayed on a smartphone, which is where this problem often crops up. As you can see, you can use @wbr@ more than once within a word, and it does not conflict with other markup, such as the asterisk for italicization.

FOOTNOTES

One of the great benefits for e-books is hyperlinked footnotes. To add footnotes to your Nantucket E-Book, follow these steps:

1) Include the notation <FN> for your footnote.

2) At the end of the paragraph containing the footnote, include the following:

Footnotes will appear in the Footnotes section of the e-book. Each footnote includes a link back to the original paragraph.

As long as the order of the <FN>'s is the same as the @@FN's, each footnote link will match with the intended footnote text. This is made easier by adding the footnote text directly below the corresponding paragraph.

NOTE: You can add more than one <FN> tag to a paragraph.

NOTE: You can use the markup for bold text, italicized text, and hyperlinks in a footnote.

You should use the hyperlink functionality to link to other parts of the document.

THE END

To end your prose piece with The End, add the following on a new line:

If no alternate text is provided, the e-book will default to THE END, otherwise, the alternate text will be used.

LYRICS AND POETRY

If you need to add a few lines of a song or poetry to your e-book, preface each line with a grave accent (`), like this:

To add a bit of space between verses, preface the last line of each verse with two grave accents (``):

Poetry as it appears in markup Poetry as it appears in markup From November in America by Nicholas Bernhard

INDENTING LINES OF POETRY

If you want to stylize a stanza with indentation, use two grave accents, with the number of tabs in-between them, e.g. `1`.

You may use any number between 1 and 6.

If you want a stanza to end on an indented line, use two grave accents, the number of lines you wish to indent, and a third grave accent.

Indented lines as they appears in markup Indented lines as they appear in final e-book

Here's an example of the line indentation put into practice:

The Owl And The Pussycat, third stanza, with indentations, in markup The Owl And The Pussycat, third stanza, with indentations, in final e-book From The Owl And The Pussycat, third stanza, by Edward Lear

COMMENTS

If you start a line with two slashes, (//) it will be ignored by the parser.

BACK TO HOME


ADDING ART TO YOUR E-BOOK

Since our media environment is almost entirely visual, it is recommended that you include images in your e-books.

For all images, remember to choose an image resolution and compression that minimizes file size, and maximizes quality. A bit of experimenting is a great help.

Here are the general guidelines for which file types to use:

The official Nantucket E-Book™website will only accept JPG, PNG, GIF, and SVG.

Please be very reserved about using moving images in your e-book, including GIFs and SVGs. Part of the joy of reading is the escape from doo-dads and flashing lights. Moving GIFs can also be hard on bandwidth. However, if they aren't abused, moving images can add a certain effect to your e-book. For example, some subtle movement in an illustration might create atmosphere for a horror story. I only ask for you to be smart about it.

I highly encourage use of SVG. SVG images have small file sizes, and will scale to any screen size. The audio player and menu icons for the Nantucket e-book platform are SVG images that I created by hand in my text editor, after designing them with paper and pencil. SVGs also support motion and interactivity, though be careful with those features. It's a very, very powerful format, and since it's an open standard, it's free to experiment with. Free and open-source vector graphics software programs are available online for creating SVG images.

Host your image files locally. As a matter of nettiquette, avoid linking to an image on someone else's site without the site's approval, even if the image's licensing and copyright status allow it (for example, a public domain image on Wikimedia Commons).

NOTE: for information how to add paths to your image files, see the section on file paths.

ADDING A COVER IMAGE

Can you say pizzaz? If you want to add a cover image to your e-book, add the following line:

Markup for a cover image

The cover image will always come first in the e-book.

If you want to include a description of the cover image, and the artist's name, include the following lines at the beginning of your document:

Cover art metadata as it appears in markup Cover art description as it appears in markup From Then A Skeleton Popped Out by Nicholas Bernhard

!!COVERART will add a credit to your title section, and to the Credits section at the end of the e-book.

!!COVERDESC will add title and alt text to your image, which is helpful for accessibility, and makes your e-book more attractive to search engines.

You can add a link to the cover art credit like so:

For more information, please see the section on adding links to credits.

For cover images, I recommend settings their dimensions to five units wide by eight units tall. This is an aspect ratio of 1.6. For e-books on the official Nantucket E-Book™website, these dimensions are mandatory.

ADDING ILLUSTRATIONS

You can add an indefinite number of illustrations to your e-book. To add an illustration, include the following line in your text:

Only the :source attribute is required, and if :caption is used, it must come last.

The file path to your illustration cannot contain any spaces.

Markup for illustrations How illustrations appear after rendering From November in America by Nicholas Bernhard

If your book has one illustrator, you may want to credit them at the beginning. To do so, use the following line at the beginning of your text:

Markup for metadata about illustrator Illustrator markup after rendering From Sweet Relief by Nicholas Bernhard

The !!ILLUSTRATOR can include a link to a page with more information about the author, like so:

For more information, see the section on adding links to credits.

If you use the !!ILLUSTRATOR tag, do not use the :illustrator attribute in the @@ILLO tag. Use one or the other.

ADDING AN IMAGE

If you want to add a plain ol' image to your e-book, use the following syntax:

The file path to your illustration cannot contain any spaces.

The :ornament attribute is optional, and lets the program know if the image is being used in place of a line break.

The :title attribute is optional, though it is always recommended to descriptions of images on web pages. If you do make use of the :title attribute, make sure it comes after :source.

Images will be centered on the page. A small image is an excellent way to break up a text, and makes for a good alternative to the **** break described earlier. You will need to add your own styling to ensure the image displays at the intended size on various devices.

Markup for plain images Plain images after rendering From Then A Skeleton Popped Out by Nicholas Bernhard

FLIPPABLE IMAGES

Images using a PNG file can have transparent background, like so:

An image of a signature (in black ink) with a transparent background. From Stoddard Lectures, Volume I by John L. Stoddard

PNGs like this are good for images with one color, like an image of a sketch or handwriting, since it gives a sense that the image is part of the book.

If you set it up right, you can have the image be affected by dark mode. Here's how to do it:

Make two copies of the PNG file: one with black on a transparent backgroud, and one with white on a transparent background. Give them the exact same name, except end one with _flip_black.png, and end the other one with _flip_white.png.

For example, if I had two files of a sketch, one would be named sketch_flip_black.png, and the other would be named sketch_flip_white.png.

When you add the image to your manuscript, using either the @@ILLO or @@IMG markup, use the one ending with flip_black.png. For example:

When the reader activates dark mode, the e-book will automatically swap between the black image and the white image.

Here's how it looks with the signature example (taken from Stoddard's Lectures) used earlier:

A 'flippable' as it would be added in markup A 'flippable' image switching with dark mode, from 
                black on a seashell background, to white on a black background The image changes alongside other dark mode elements. Image is from Stoddard Lectures, Volume I by John L. Stoddard

BACK TO HOME


ADDING AN AUDIOBOOK

One of the most powerful features of the Nantucket E-Book™format is the ability to have a book's text, and an audio version, together. Adding audiobooks to your e-book is much the same as adding an illustration.

PREPARING THE AUDIO SECTION

Before adding audio files to your e-book, start by adding an !!AUDIO tag at the beginning of your text:

Neither parameter is required. If no copyright information is specified for the audiobook, the e-book will say so.

If a background image is specified, it will be blurred and brightened to separate it from the foreground elements. If no background is specified, the program will default to a plain seashell background, like the rest of the e-book.

NOTE: for information how to adding the path to your audiobook background, see the section on file paths.

ADDING AUDIO FILES

Any number of audio files can be included.

Audiobooks should be in one of two formats: MP3 or OGG/Vorbis. Both are open formats, meaning anyone can create a file in that format without paying royalties. MP3 is supported by all current major browsers, while OGG may not work in Apple's Safari browser.

Audiobooks on the official Nantucket E-Book™website may use either OGG or MP3.

Longer works, such as novels, should break the audiobook into several short audio files.

Add the following line to your text to include an audio file:

The file path to your illustration cannot contain any spaces.

NOTE: for information how to add paths to your audio files, see the section on file paths.

ADDING CREDITS FOR AN AUDIOBOOK

To credit the people involved in your audiobook's recording, use !!AUDIOCREDITS to begin adding audiobook credits. Add each credit line in the order you want, using two slashes (//) between each one (this is very important).

BACK TO HOME


METADATA AND SEARCH ENGINE OPTIMIZATION

This section covers things that will make your website look more appealing to search engines, plus copyright info.

Most of this information will be placed in the <head> section of the HTML document, where readers won't see it, but search engines can.

COPYRIGHT INFORMATION

It's a very, very good idea to include the copyright info for your e-book, even if it's 100% public domain. This furthers the legal protection for your e-book, and lets the reader know how they can share it.

To add copyright info, add the following line to the beginning of your document:

Markup for copyright info on a book Copyright info after rendering From November in America by Nicholas Bernhard

If your work is public domain, use:

Markup for designating a Nantucket E-Book's text as Public Domain A public-domain symbol in a Nantucket E-Book

This will put a strikethrough on the copyright symbol.

ADDING A CONTENT RATING

You may add a content rating to your e-book. These ratings are for the benefit of readers, who may use the rating to determine if your book is right for them.

E-Books are unrated by default. If you do choose to add a rating, you will be asked to consider if the rating would be appropriate for the specific audience.

An e-book is added with the following syntax:

The following ratings are supported:

U, for Unrated. This means your e-book does not have an official rating. If no rating is given for an e-book, it will default to Unrated. A rating of U is also recommended for technical documentation.

AA for All Ages.

13+ for readers aged 13 and up.

17+ for readers aged 17 and up.

A for Adults only.

X for pornography.

The official Nantucket E-Books™ website does not allow pornography, which is defined as a work that depicts sexual content in a graphic manner, and is "about the money shot." The X rating exists to clarify that the A rating is not pornography.

Ratings for e-books on nantucketebooks.com are voluntary, however, if you choose to rate your e-book, the rating must not outrage reason. The purpose of ratings are to inform readers, and a wildly misleading ratings fails this purpose. Misleading ratings will be changed to a U rating.

SEARCH KEYWORDS

Search engines will look for keywords associated with a web page. For example, if your work is about baseball, you'd better include the keyword 'baseball.'

On the offical Nantucket E-Book™website, readers may use these keywords to search for e-books as well.

To include keywords for your e-book, include !!KEYWORDS at the beginning of your text, followed by all the necessary keywords.

Try to think of words people might search for, where your e-book would be a good result.

Markup for adding keywords to a Nantucket E-Book From November in America by Nicholas Bernhard

PAGE DESCRIPTIONS

Search engines will also look for descriptions of web pages. Use this part to include a brief summary of your e-book that search engines will see.

Markup for giving a description to a Nantucket E-Book From November in America by Nicholas Bernhard

NOTE: Do not use double-quotes in your descriptions ("). Double-quotes will mess things up, so the text-parser will automatically replace them with single-quotes.

PAGE LANGUAGE

Lastly, search engines will try to figure out which language your e-book is in. While the search engine can make an educated guess, make it easy, and just tell it what the language is.

Markup for specifying the language for a Nantucket E-Book

If you don't include this line, the program will automatically default to English, "EN"

Here are the language codes for the top ten most-spoken languages, according to Wikipedia:

Chinese ZH
Spanish ES
English EN
Hindi HI
Bengali BN
Portuguese PT
Russian RU
Japanese JP
Punjabi PA
Marathi MR

BACK TO HOME


MONETIZING YOUR E-BOOK

You may want to include some way for people to financially support your work. You can include a call-to-action at the end of your page.

Add a call-to-action section as you would add any other chapter in your e-book.

Don't forget to include a link to your monetization site.

LISTING SUPPORTERS

At the end of your e-book, you may want to recognize the people who have supported your book through crowdfunding platforms.

Shanty™ currently allows you to import a CSV file from Patreon or Ko-Fi. You may do so using the following steps:

1) To download the CSV file:

1a) In Patreon, export the Membership Report as a CSV file. This CSV file will be downloaded to your computer.

1b) In Ko-Fi, go to ko-fi.com/manage/supportreceived and click the button labeled Download CSV.

2) Open the downloaded file in either a text editor (Notepad, Gedit, et al) or by dragging it into Google Chrome.

3) Select all the text (Ctrl + a), and then copy it (Ctrl + c).

4) In your Shanty™ document, create the tag @@DONORSTART, followed by the platform you're listing donations from.

5) On a new line, add the tag @@DONOREND. Paste your copied text between these two tags.

For example, if you're using Patreon, it should look like this:

The list of Patrons from Patreon will be sorted into their tiers, starting with the most-expensive tier and moving down from there.

Donors from Ko-Fi will be sorted by donation amount, in descending order.

If you receive donations from both Patreon and Ko-Fi, you may list both. All you need to do is repeat the above steps for each platform.

BACK TO HOME


CUSTOMIZATION

REMOVING TABLE OF CONTENTS FOR SMALL E-BOOKS

The Nantucket E-Book™ format includes three tables of contents:

The first one is within the document itself. This one is ideal for accessibility, since it can be easily accessed with the TAB key on your keyboard. It also gives first-time readers a sense of the structure of your e-book, and its contents, just like a table of contents should.

The second one is intended for mobile users, and is a full-screen window which is accessed from the menu.

The last one is intended for desktop users. It is a drop-down list that can be accessed from the menu.

If your e-book is small, like a short story, for example, it may not make sense to include the first one. To remove it, just add the following line to the beginning of your text:

REMOVING ILLUSTRATIONS FROM TABLE OF CONTENTS

If your e-book includes a large number of illustrations, you may not want to include them in your table of contents. To disable the illustration section of your table of contents, add the following line at the beginning of your text:

ADDING DATESTAMPS TO FILE NAMES

While testing out your e-book, you may find it useful to include the date the e-book was created in its file name. To add a datestamp, add the following line at the beginning of your text:

This will append the current date to the end of the file name, using the YYYY-MM-DD format.

For example, if the date was 2020-11-05, the file Trash_Man,_The.html would instead be named Trash_Man,_The2020-11-05.html

NOTE: !!DATESTAMP will not work in Arrowhead.

ADDING PATHS TO YOUR FILES

When you are writing a Nantucket E-Book™, you don't have to worry about what directories/folders your images and audiobook files are going into. All you have to provide is the name of the file.

If you are planning to run Nantucket E-Books™ on your own server, this section will provide some information on setting up the folders to work with the software's file structure.

Nantucket E-Books™ is currently configured to use a specific folder setup.

This section assumes you have a good understanding of how file paths work on computers. If you are new to the concept, this article on the W3Schools website offers a good introduction.

Rather than tell you what the folder setup is, it may be more informative to show you how it looks in practice. You can look at this site's folder setup for e-books by looking in the directory ./ebooks/. If you explore the folders and sub-folders there enough, you'll get a feel for how to set it up on your own.

If you are using the Offline Reader, there are instructions in the index.html file included in the Offline Reader, which will tell you where to place downloaded e-book files (and any downloaded images or audiobook files).

BACK TO HOME


FAVORITES

It is possible to include a "FAVORITES" button in the menu. This button allows the reader to save a list of their favorite e-books into the local storage of their device's browser.

If you have a web page listing all your e-books, it is possible to have this page highlight all of a user's favorited books.

Because this feature uses local storage, the information is more secure than if it were stored on a server.

First, you must create a unique keyword for your e-book. NOTE: all e-books published on the official Nantucket E-Book™s site will require a special keyword.

Second, if you are publishing on your own site, you must create a name for your list of favorite e-books. If someone hits the favorite button for your e-book, this specifies where it should be saved.

If you are publishing your e-book on nantucketebooks.com, and using the site's e-book generator text field, you do not need to add the !!FAVORITES line. It will automatically default to 'nantucketFavorites'.

If you are publishing to your own website, you may have a page listing all your e-books. You can then write a simple JavaScript program to access this list, and have the user's favorite e-books listed or highlighted. Much of the necessary code may be found in the file favorites.js on this website.

BACK TO HOME


EXAMPLES

I thought it would be educational to show some Nantucket E-Books™ I have written, alongside their original Shanty™ text files.

This way, you can directly compare how the Shanty™ markup for a Nantucket E-Book™translates into the finished product.

All books by Nicholas Bernhard.

BACK TO HOME


CONTRIBUTE AND SUPPORT

The Nantucket E-Book™project is the result of many, many hours of work, with the goal of providing the very best experience for my readers.

You can support my work on Patreon. Your voluntary financial support will allow me to continue developing the best e-books on the planet, and new ways of sharing this technology with the world.


UPDATE LOG


GNU FREE DOCUMENTATION LICENSE

Version 1.3, 3 November 2008

Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. <https://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:

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 https://www.gnu.org/licenses/.

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.

CONTACT

Questions? Comments? Suggestions? You may e-mail me at njb@nantucketebooks.com

IRC: nantucketebooks.com/6667

Twitter: @nantucketebooks

PO BOX 596 Broomfield, CO 80038

BACK TO HOME