Hyperdrive.el User Manual

Hyperdrive.el User Manual

Hyperdrive.el User Manual

Hyperdrive is a P2P, real-time, local-first, versioned filesystem designed for easy peer-to-peer file sharing. hyperdrive.el is an independent project built by USHIN which provides an Emacs interface for managing hyperdrives.

hyperdrive.el is in early development. If something breaks, please see Troubleshooting.

This manual is for hyperdrive.el version 0.2-pre.

1 Freedom to copy

Copyright © 2023 USHIN, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License.”

(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and modify this GNU manual.”

2 Installation

2.1 Emacs

hyperdrive.el requires GNU Emacs version 27.1 or later.

2.2 hyper-gateway

NOTICE: Soon hyperdrive.el will depend on hyper-sdk-rpc instead of hyper-gateway.

hyperdrive.el relies on hyper-gateway for talking to the hypercore network (installation instructions).

2.3 hyperdrive.el

There are three recommended options for installing hyperdrive.el: NonGNU ELPA, MELPA, and package-vc.

2.3.1 NonGNU ELPA

hyperdrive.el is available on NonGNU ELPA. On Emacs 28 or later, installation is as simple as M-x package-refresh-contents then M-x package-install RET hyperdrive RET.

On Emacs 27, you’ll first have to add the NonGNU ELPA repository: 

(with-eval-after-load 'package
  (add-to-list 'package-archives '("nongnu" . "https://elpa.nongnu.org/nongnu/")))

After installing with NonGNU ELPA, you can later upgrade to a newer version of hyperdrive.el by running M-x package-refresh-contents then M-x package-upgrade RET hyperdrive. If package-upgrade is not available as a command, display the list of packages with M-x list-packages, select hyperdrive, and click the Install button.

2.3.2 MELPA

hyperdrive.el is also available on MELPA. First add the MELPA repository: 

(with-eval-after-load 'package
  (add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/")))

Then follow the NonGNU ELPA installation instructions.

2.3.3 package-vc

package-vc is only available on Emacs 29.1 or later.

  1. Ensure you have git, makeinfo (part of the texinfo package), and Emacs 29.1 or newer.
  2. Add the following lines to your init.el startup file: 
(unless (package-installed-p 'hyperdrive)
  (require 'package-vc)
  ;; In Emacs 30, `ispell-buffer-session-localwords' will be marked as safe by default.
  (put 'ispell-buffer-session-localwords 'safe-local-variable #'list-of-strings-p)
  (package-vc-install '(hyperdrive
                        :url "https://git.sr.ht/~ushin/hyperdrive.el"
                        :doc "doc/hyperdrive-manual.org")))

Alternatively, if you have already cloned the hyperdrive.el repository, you can use the following snippet to install from that repository: 

(unless (package-installed-p 'hyperdrive)
  (require 'package-vc)
  ;; In Emacs 30, `ispell-buffer-session-localwords' will be marked as safe by default.
  (put 'ispell-buffer-session-localwords 'safe-local-variable #'list-of-strings-p)
  (add-to-list 'package-vc-selected-packages
               '(hyperdrive
                        :url "https://git.sr.ht/~ushin/hyperdrive.el"
                        :doc "doc/hyperdrive-manual.org"))
  ;; Change the path below to the location of your local hyperdrive.el repository.
  (package-vc-install-from-checkout "~/.local/src/hyperdrive.el" "hyperdrive"))

In your init.el, type M-x eval-buffer RET.

If all goes well, hyperdrive.el commands like M-x hyperdrive-start should now be available. The documentation for hyperdrive.el should also be installed.

After installing with package-vc, you can later upgrade to a newer version of hyperdrive.el by running M-x package-vc-upgrade RET hyperdrive RET.

3 Usage

Be careful what you publish! Anyone with your public key can download your published files from you, your friend, or anyone else who has them.

3.1 Start/stop the gateway

To connect with peers, you’ll need to start hyper-gateway. If you install hyper-gateway as a SystemD service, you can connect and disconnect from the network with M-x hyperdrive-start and M-x hyperdrive-stop. Otherwise, follow these instructions to run hyper-gateway manually.

3.2 Create a hyperdrive

You can have multiple hyperdrives, each one containing its own set of files. Run M-x hyperdrive-new then type in a seed (see Seeds) to create a new hyperdrive. That seed will be combined with your secret master key, which is generated for you by hyper-gateway, to produce a public key (see Public keys) that uniquely identifies that hyperdrive. hyperdrive-new is idempotent since the same seed will always produce the same public key. For this reason, a hyperdrive’s seed cannot be changed.

3.3 Open a hyperdrive

You can open a hyperdrive folder or file by pasting in a hyper:// URL after M-x hyperdrive-open-url. Alternatively, M-x hyperdrive-find-file remembers hyperdrives you have already created or visited. It will prompt you for a known hyperdrive and a path inside it. hyperdrive-view-file is like hyperdrive-find-file, but it opens the file in (emacs)view-mode.

3.3.1 Directory view

The following keybindings are available inside the directory view by default:

  • n and p move between entries
  • RET opens file or directory at point
  • ^ goes up to the parent directory
  • g refreshes the directory to display potential updates
  • o sorts directory contents by column (you can also click on the column headers)
  • d downloads the file at point to disk
  • D deletes the file or directory (recursively) at point
  • w copies the URL of the file or directory at point
  • j opens imenu to quickly jump to a file in the current directory
  • ? opens a buffer describing the current hyperdrive

3.3.2 File view

The following keybindings are available inside the directory view by default:

  • C-x x g refreshes the file to display potential updates

If you have bound dired-jump in the global keymap (people often choose C-x C-j), you can use the same binding to jump to the parent hyperdrive directory from any hyperdrive file or directory buffer.

3.3.3 Unknown paths

When you attempt to load a file or folder that doesn’t appear to exist, hyperdrive.el will prompt you to take action:

  • h (history) to open the version history for that file. (This only works for files, not folders)
  • u (up) to open the parent directory containing that file or folder
  • r (recurse) to go up the directory tree until a directory is found or until you get to the root directory.
  • q (exit) to exit,
  • ? (help) to show a help message.

If you attempt to load the root directory (hyper://PUBLIC-KEY/) of a hyperdrive with a valid-looking public key which you’ve never loaded before and for which no peers are currently found, hyperdrive.el should warn you that no peers were found for that drive. This might mean that the drive doesn’t exist or just that you’re not connected to anyone who knows about it.

If you attempt to load a file or directory for a hyperdrive with a malformed public key, hyperdrive.el should ask you to double-check the URL.

3.4 Write to a hyperdrive

You can write a buffer to a hyperdrive with hyperdrive-write-buffer, which will prompt you for one of hyperdrives you have created as well as the path in that hyperdrive where you want to store the file. If you are editing an existing hyperdrive file, save-buffer will silently update the current hyperdrive entry with the new content.

hyperdrive.el will prompt to save modified hyperdrive files before exiting Emacs. If you want the command save-some-buffers to always prompt to save hyperdrive files in addition to regular files, set save-some-buffers-default-predicate to t.

3.6 View the hyperdrive version history

Hyperdrives are versioned (see Versioning). To view the previous/next version of a hyperdrive file, run hyperdrive-previous-version or hyperdrive-next-version inside the file’s buffer.

3.6.1 History buffer

To view the entire known history of a file, use hyperdrive-history. For an explanation of the history buffer, see Partial version data.

The following keybindings are available inside the directory view by default:

  • + loads version history for unknown ranges
  • RET opens the file at the start of the range at point
  • w copies the URL of the file at the start of the range at point
  • d downloads the file at the start of the range at point
  • = displays the differences between the version at point and the prior version

To act on the latest known version of the file, use these keybindings on the header line displaying the file description.

3.7 Describe a hyperdrive

To see information about a hyperdrive, such as its public key, seed, petname, nickname, domains, writable, or other metadata, run hyperdrive-describe-hyperdrive. For more on what this information means, see Naming.

It is possible to purge a hyperdrive from the hyperdrive-describe-mode buffer (see Purge a hyperdrive).

3.8 Bookmark a hyperdrive

You can use the built-in bookmark-set, bookmark-jump, and bookmark-list functions to store and jump to a hyperdrive file or directory. To jump to or view only hyperdrive bookmarks, use hyperdrive-bookmark-jump and hyperdrive-bookmark-list.

3.9 Stream audio and video

When you use hyperdrive-find-file or some other command to open a streamable audio/video file, Emacs will use an external program to stream that video from the network. After the stream finishes, the audio/video file is stored locally.

3.10 Download hyperdrive files

You can download a hyperdrive file to your local filesystem. Download the current hyperdrive file with hyperdrive-download-entry or paste in a hyper:// URL after hyperdrive-download-url.

3.11 Upload files from your filesystem

To upload a single file from your filesystem, use hyperdrive-upload-file. By default, the selected file will be placed in your hyperdrive’s root directory, but you can edit the filepath before uploading.

hyperdrive-upload-files lets you upload multiple files from your filesystem to a hyperdrive. As with the cp command, uploaded files will be placed into the same TARGET-DIRECTORY.

On Emacs 29 or later, you can upload an image which you previously copied to your clipboard from an external program with yank-media.

3.11.1 Mirror a whole directory

hyperdrive-mirror uploads a directory, mirroring its subdirectory structure in your hyperdrive. It is an interactive command, but the following example shows its non-interactive use.

Let’s say you have some files on your filesystem in the ~/blog/ directory, and you want to upload them all into a hyperdrive you already created with the petname “foo”. The following snippet will show you the list of files which will be uploaded as well as the hyper URL at which they will be available after upload. To upload the files, run hyperdrive-mirror-do-upload (bound to C-c C-c by default) in the *hyperdrive-mirror* buffer which opens. 

(hyperdrive-mirror "~/blog/" (hyperdrive-by-slot 'petname "foo")
                   :target-dir "/blog/")

To upload the same files without confirming, add :no-confirm t. Interactively, use two universal prefix arguments C-u C-u.

3.11.2 Mirror files by tag or other attributes

hyperdrive-mirror can accept a PREDICATE argument, which you can use to upload only certain files. Interactively, one universal prefix argument C-u make this command prompt you for PREDICATE.

Let’s say that you have some files on your filesystem in the ~/blog/ directory, but you only want to upload those files which have been tagged as “public” using Protesilaos Stavrou’s Denote file-naming scheme.

The following snippet includes a PREDICATE key whose value is a regular expression against which every expanded filename inside will be tested. 

(hyperdrive-mirror "~/blog/" (hyperdrive-by-slot 'petname "foo")
                   :target-dir "/blog/"
                   :predicate ".*_public.*")

Alternatively, you could select files by tag with Karl Voit’s filetags. Either way allows for a “non-splitting” approach where public and private files exist in the same directory.

PREDICATE may also be a function, which receives the expanded filename as its only argument. For example, the following snippet will mirror only those files in ~/blog/ which are smaller than 5MB: 

(hyperdrive-mirror "~/blog/" (hyperdrive-by-slot 'petname "foo")
                   :target-dir "/blog/"
                   :predicate (lambda (file) (> (* 5 1024 1024)
                                              (file-attribute-size (file-attributes file)))))

3.12 Purge a hyperdrive

To remove all data related to a hyperdrive, run hyperdrive-purge. This command will first prompt for confirmation. In addition to the hyperdrive’s file content and metadata, hyperdrive-purge also removes relevant data inside hyperdrive-hyperdrives and hyperdrive-version-ranges.

Data which has been purged from your local machine may still be available on the network.

3.13 Non-interactive use

In writing your own functions to extend hyperdrive.el, you can use hyperdrive-by-slot to access a hyperdrive entry by its seed, petname, or public key.

For examples, see Mirror a whole directory and Mirror files by tag or other attributes.

4 Customization

You can customize the following variables settings by running M-x customize-group RET hyperdrive RET:

hyperdrive-storage-location

Location to store Hypercore data. Defaults to "~/.local/share/hyper-gateway-nodejs/".

hyperdrive-hyper-gateway-port

Port on which to run the hyper-gateway server. Defaults to 4973.

hyperdrive-honor-auto-mode-alist

If non-nil, use file extension of hyperdrive file to set major-mode. Defaults to t.

hyperdrive-persist-location

Location where persist will store data, currently hyperdrive-hyperdrives and hyperdrive-version-ranges. By default, uses the default persist location.

hyperdrive-download-directory

Location where hyperdrive-download-url will download files. Defaults to eww-download-directory or, if not bound, the home directory.

hyperdrive-timestamp-format

Format string used for timestamps. Passed to format-time-string, which see.

hyperdrive-directory-display-buffer-action

Display buffer action for hyperdrive directories. Passed to display-buffer, which see.

hyperdrive-directory-sort

Column by which directory entries are sorted.

Internally, a cons cell of (COLUMN . DIRECTION), the COLUMn being one of the directory listing columns (name, size, or mtime) and DIRECTION being one of :ascending or :descending.

hyperdrive-history-display-buffer-action

Display buffer action for hyperdrive history buffers. Passed to display-buffer, which see.

hyperdrive-default-host-format

Default format for displaying hyperdrive hostnames. See Naming section for what this means.

hyperdrive-stream-player-command

Command used to play streamable URLs externally. Default uses mpv. There also exists a preconfigured option for VLC media player.

hyperdrive-queue-limit

Default number of request sent to hyper-gateway at a time in a queues. Defaults to 20.

hyperdrive-queue-limit

Default maximum number of requests when filling version history. Defaults to 10.

hyperdrive-render-html

Control how HTML hyperdrive files are displayed. By default, HTML pages are rendered in Emacs with (eww)EWW. If nil, raw HTML will be displayed.

hyperdrive-reuse-buffers

How to reuse buffers when showing entries. By default (any-version), opening a hyperdrive file or directory reuses a buffer that is already visiting it, regardless of version. To have separate buffers for each version of a file/directory, use same-version.

5 Concepts

5.1 Hyperdrive

Hyperdrive is a virtual filesystem which you can use to share files on the peer-to-peer (P2P) hyper network. It’s a special folder with a long, unique link starting with hyper:// that you can put files into and other peers can pull files out of (if they have the link).

Anyone with that link can download its contents directly from your computer. There’s no need to make an account or rely on a third party to pass the data along. What’s more, anyone who has a copy of the content in your hyperdrive can serve it to others. This means that your hyperdrive can circulate on the hyper network even when you’re offline.

Hyperdrive is single-writer, since only one peer (one machine) can make changes to a hyperdrive. No one can pretend to be you, since files in a hyperdrive are cryptographically signed to ensure their integrity and authenticity.

You can make as many hyperdrives as you like; the only limitation is your own disk space.

Hyperdrive is offline-first, since you can view files which were previously downloaded even when disconnected from the rest of the network. It’s also local-first, since you can connect with peers on a LAN even without an internet connection.

Unlike BitTorrent, another protocol for sharing files, hyperdrives are mutable. You can add, update, or delete files inside a hyperdrive, and peers will be able to access the latest version of the hyperdrive at the same link. However, old versions of your hyperdrive can still be accessed. See Versioning for more information.

5.1.1 Sparse replication

Hyperdrive is sparsely replicated, meaning that peers can download particular files from a hyperdrive without having to get the whole drive. This reduces both load times and disk usage.

5.1.2 Versioning

Hyperdrives are versioned, meaning that it is possible to explore a hyperdrive as it was in the past. Version numbers indicate the hyperdrive’s version. For example, hyper://PUBLIC-KEY/$/version/50/ refers to the fiftieth version of the hyperdrive identified by PUBLIC-KEY. Loading a hyperdrive entry without specifying a version number always loads the most recent version of that hyperdrive. If you pass hyper://PUBLIC-KEY/foo.org to hyperdrive-open-url, hyperdrive.el will always attempt to find /foo.org inside the latest version of that hyperdrive.

Whenever you update an entry, the hyperdrive’s version number gets incremented by 1. The version number tells you how many times the hyperdrive has been modified, not how many times a particular entry has been modified. For example, let’s say that the current version of your hyperdrive at hyper://PUBLIC-KEY/ is 50. If you add a new entry at hyper://PUBLIC-KEY/bar.org, the latest version of your hyperdrive will become 51.

Since /bar.org did not exist before version 51, hyperdrive.el should warn you that nothing exists at hyper://PUBLIC-KEY/$/version/50/bar.org. If you add another file hyper://PUBLIC-KEY/quux.org, your hyperdrive’s latest version will become 52. For the moment, hyper://PUBLIC-KEY/bar.org, hyper://PUBLIC-KEY/$/version/51/bar.org, and hyper://PUBLIC-KEY/$/version/52/bar.org, all point to the same version of /bar.org. If you then make a change to /bar.org, your hyperdrive’s latest version will become 53. Now hyper://PUBLIC-KEY/bar.org and hyper://PUBLIC-KEY/$/version/53/bar.org will point to the latest version of /bar.org, while the 51- and 52-versioned URLs will continue to point to the original version.

Here’s the history of /bar.org so far (the hyperdrive’s latest version is 53):

Version rangeexists
1-50no
51-52yes
53yes

The table shows that /bar.org did not exist from the beginning of the hyperdrive history until version 51 (when it was created) and that it was modified at version 53. Since the final range number in the table is 53, we also know that the hyperdrive’s latest version is 53.

If you delete /bar.org, hyper://PUBLIC-KEY/bar.org will no longer point to anything, but the versioned URLs will still work.

Since only the current version of a hyperdrive entry can be updated, hyperdrive.el sets the buffer to read-only whenever a version number is specified in a hyper URL.

5.1.2.1 Partial version data

Because hyperdrives are sparsely replicated (see Sparse replication), you might not know the full version history of a file. For example, when you load the most recent version of /bar.org, the gateway (see Hyper-gateway) will also return the start of the version range containing the most recent version of /bar.org. Since we also know the latest version of the hyperdrive, the version ranges table with the same data from the prior section would look like this:

Version rangeexists
1-52unknown
53yes

Running hyperdrive-previous inside of the buffer for the latest version of /bar.org will load /bar.org at version 52. The gateway will inform us that the version range for /bar.org that contains version 52 started at 51:

Version rangeexists
1-50unknown
51-52yes
53yes

Running hyperdrive-previous inside of the buffer for /bar.org at version 51 or 52 will attempt to load /bar.org at version 50. /bar.org does not exist at version 50, so the table will now look like:

Version rangeexists
1-49unknown
50no
51-52yes
53yes

Crucially, when a file does not exist at a particular version, the gateway does not tell us whether it ever existed in the past. In theory, /bar.org could have been created at version 6 and deleted again at version 8. The only way to determine that a file is nonexistent for some version range is to query the network for that file at every single version in the range.

5.1.2.2 No directory version history

Version history for directories is not implemented for a design reason and technical reason:

  • Directories have neither mtime nor size metadata, so a history view for directories wouldn’t be that useful.
  • Implementation of directory history would be somewhat ugly, since it requires either
    1. storing an entry for each directory in hyperdrive-version-ranges, which doesn’t optimally normalize version history data, or
    2. generating directory history based on the history of the files it contains, which can never prove that a directory doesn’t exist.

5.2 Hyper-gateway

Hyper-gateway handles interactions with hyperdrive under the hood, and it runs a local HTTP server which offers a Fetch API to access the Hyperdrive network. In hyperdrive.el, P2P interactions consist mostly of, e.g., GET requests to download files and PUT requests to write files to a hyperdrive.

5.3 Naming

Inspired by Marc Stiegler’s An Introduction to Petname Systems, hyperdrive.el names drives in a three different ways:

Public key

public, globally unique, not human-memorable

Nickname

public, not necessarily unique, human-memorable

Petname

private, locally unique, human-memorable

If hyperdrive.el is like a phonebook, then public keys are phone numbers, nicknames are how your contacts introduce themselves, and petnames are the names you actually write down.

Each drive may also have one or both of the following attributes:

Seed

string used to generate public key

DNS domain

public, globally unique, human-memorable

5.3.1 Public keys

Public keys are 52-character-long, z-base-32 encoded keys generated from your secret master key and a seed string. hyper-gateway generates the secret key for you, and you provide a seed (see Seeds) when generating a new drive with hyperdrive-new.

Public keys allow for permanent links to hyperdrive content. When sharing a hyperdrive with someone else, you will need to copy its full URL. Peers can load your hyperdrive files directly from your computer or from other peers who previously loaded those files.

5.3.2 Nicknames

Nicknames are public, memorable names which users can give to their own hyperdrives. Other users can see the nicknames you give to your hyperdrives.

Nicknames are stored in each hyperdrive inside /.well-known/host-meta.json under the name key, as specified in RFC6415. You can only assign a nickname to hyperdrives which you have created. Nicknames can be changed with hyperdrive-set-nickname.

5.3.3 Petnames

Petnames are locally unique hyperdrive identifiers. You can give a petname to any hyperdrive you load, whether you created it or not.

When creating a new drive, your chosen seed (see Seeds) is used as its petname by default. Petnames can be changed with hyperdrive-set-petname, but drives cannot share a petname.

5.3.4 Seeds

Along with your secret master key, seeds are used to generate public keys (see Public keys). A seed has a one-to-one relationship with a drive. Seeds are local but not secret. To share a drive, you must use a public key or DNS domain (see DNS domains).

5.3.5 DNS domains

It is possible to use DNSLink to link to a hyperdrive with a domain name instead of a public key (see Public keys), like hyper://example.org/path/to/file. Create a TXT record at _dnslink.example.org with the contents /hyper/PUBLIC-KEY (no trailing slash). Note: relying on DNS adds another point of centralization, reducing the durability of your link. hyperdrive.el somewhat mitigates this issue by remembering which public key the DNS record resolved to, so that peers can use the stored public key itself for subsequent connections.

DNS domains are checked for suspicious characters (see (elisp)Suspicious Text).

6 Known limitations

6.1 No empty directories

Instead of files and folders, Hyperdrive technically has entries and entry prefixes. In other words, folders don’t exist unless they contain files. This results in potentially unexpected behavior:

  • it is not possible to create empty directories
  • deleting the last file in a folder deletes the folder as well

When a hyperdrive file or folder is not found, hyperdrive.el prompts you for an action (see Unknown paths).

6.2 Files and folders can have the same name

In the current implementation of Hyperdrive, it’s possible for an entry (folder) and an entry prefix (folder) to have the same name, e.g., hyper://PUBLIC-KEY/foo/bar/ and hyper://PUBLIC-KEY/foo/bar. In this case, the folder listing for hyper://PUBLIC-KEY/foo/ would display the bar entry but not the bar/ entry prefix.

7 Tips

7.1 Quick documentation access

You can open the hyperdrive.el manual with M-x hyperdrive-info-manual.

To view documentation for hyperdrive.el commands, functions, and variables, press C-h o (describe-symbol). Inside the *Help* buffer that pops open, you can press i (help-goto-info) to jump to the relevant section in the hyperdrive.el manual.

8 Troubleshooting

If you run into issues, please first try resetting the value of hyperdrive-hyperdrives: 

(progn
  (setf hyperdrive-hyperdrives (make-hash-table :test #'equal))
  (persist-save 'hyperdrive-hyperdrives))

Please ensure that your version of hyper-gateway (M-x hyperdrive-hyper-gateway-version) is the latest version (releases).

9 Contributing/Getting help

You’re welcome to join our public XMPP chat room!

Bugs can be submitted to the ushin issue tracker. Patches, comments or questions can be submitted to the ushin public inbox.

10 Acknowledgments

Adam Porter for rewriting hyperdrive.el and for his work on plz.el.

Mauve Signweaver for their guidance into the world of p2p as well as the development of hyper-gateway.

Protesilaos Stavrou for design input and user-testing hyperdrive.el.

Karl Voit for his feedback, especially the suggestion that we allow for a non-splitting approach for uploading files from the filesystem.

Steve Purcell and Akira Komamura for suggestion to improve our CI build manifests.

11 Indices

11.4 Concept index

Jump to:   D   H   N   P   S   V  
Index Entry  Section
D
DNS domains: DNS domains
H
Hyper-gateway: Hyper-gateway
N
Naming: Naming
Nicknames: Nicknames
P
Petnames: Petnames
Public keys: Public keys
S
Seeds: Seeds
Sparse replication: Sparse replication
V
Versioning: Versioning
Jump to:   D   H   N   P   S   V  

12 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.
  1. PREAMBLE

    The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

    This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

    We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

  2. APPLICABILITY AND DEFINITIONS

    This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

    A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

    A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

    The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

    The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

    A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.

    Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

    The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.

    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.

  3. VERBATIM COPYING

    You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

    You may also lend copies, under the same conditions stated above, and you may publicly display copies.

  4. COPYING IN QUANTITY

    If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

    If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

    If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

    It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

  5. MODIFICATIONS

    You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

    1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
    2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
    3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
    4. Preserve all the copyright notices of the Document.
    5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
    6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
    7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license notice.
    8. Include an unaltered copy of this License.
    9. Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
    10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
    11. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
    12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
    13. Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version.
    14. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section.
    15. Preserve any Warranty Disclaimers.

    If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.

    You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

    You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

    The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

  6. COMBINING DOCUMENTS

    You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

    The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

    In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”

  7. COLLECTIONS OF DOCUMENTS

    You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

    You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

  8. AGGREGATION WITH INDEPENDENT WORKS

    A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

    If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

  9. TRANSLATION

    Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

    If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

  10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document except as expressly provided 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.

  11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See https://www.gnu.org/copyleft/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document.

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

Last updated 2023-08-28 Mon 03:01 PDT. History | Sitemap