[nongnu] elpa/hyperdrive 18a59bb07a 05/14: Docs: Add .texi manual back

[ELPA Syncer]

branch: elpa/hyperdrive
commit 18a59bb07a7d03c2b89a007b0a0973342d20a63f
Author: Joseph Turner <joseph@ushin.org>
Commit: Joseph Turner <joseph@ushin.org>

    Docs: Add .texi manual back
    
    This allows the manual to be installed with MELPA.
---
 doc/hyperdrive-manual.texi | 1929 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 1929 insertions(+)

diff --git a/doc/hyperdrive-manual.texi b/doc/hyperdrive-manual.texi
new file mode 100644
index 0000000000..b68bac7953
--- /dev/null
+++ b/doc/hyperdrive-manual.texi
@@ -0,0 +1,1929 @@
+\input texinfo    @c -*- texinfo -*-
+@c %**start of header
+@setfilename hyperdrive-manual.info
+@settitle Hyperdrive.el User Manual
+@documentencoding UTF-8
+@documentlanguage en
+@set txicodequoteundirected
+@set txicodequotebacktick
+@set MAINTAINERSITE @uref{https://ushin.org,maintainers webpage}
+@set MAINTAINER Joseph Turner
+@set MAINTAINEREMAIL @email{joseph@ushin.org}
+@set MAINTAINERCONTACT @uref{mailto:joseph@ushin.org,contact the maintainer}
+@c %**end of header
+
+@dircategory Emacs
+@direntry
+* Hyperdrive: (hyperdrive). P2P filesystem in Emacs.
+@end direntry
+
+@finalout
+@titlepage
+@title Hyperdrive.el User Manual
+@subtitle Release 0.2-pre
+@author Joseph Turner and Adam Porter
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top Hyperdrive.el User Manual
+
+@uref{https://docs.holepunch.to/building-blocks/hyperdrive, Hyperdrive} is a 
P2P, real-time, local-first, versioned filesystem
+designed for easy peer-to-peer file sharing.  @code{hyperdrive.el} is an
+independent project built by @uref{https://ushin.org, USHIN} which provides an 
Emacs interface
+for managing hyperdrives.
+
+@code{hyperdrive.el} is in early development. If something breaks, please see
+@ref{Troubleshooting}.
+
+@itemize
+@item
+Homepage: @uref{https://ushin.org/hyperdrive/hyperdrive-manual.html}
+@item
+Repository: @uref{https://git.sr.ht/~ushin/hyperdrive.el}
+@end itemize
+
+This manual is for @code{hyperdrive.el} version 0.2-pre.
+@end ifnottex
+
+@menu
+* Freedom to copy::
+* Installation::
+* Example configuration::
+* Usage::
+* Concepts::
+* Customization::
+* Known limitations::
+* Tips::
+* Troubleshooting::
+* Contributing/Getting help::
+* Acknowledgments::
+* Indices::
+* GNU Free Documentation License::
+
+@detailmenu
+--- The Detailed Node Listing ---
+
+Installation
+
+* Emacs::
+* hyper-gateway::
+* hyperdrive.el: hyperdriveel. 
+
+hyperdrive.el
+
+* NonGNU ELPA::
+* MELPA::
+* package-vc::
+
+Usage
+
+* Menu bar support::
+* Hyperdrive menu command::
+* Start/stop the gateway::
+* Open a hyperdrive::
+* Create a hyperdrive::
+* Write to a hyperdrive::
+* Link to a hyperdrive::
+* Delete a hyperdrive file::
+* View the hyperdrive version history::
+* Describe a hyperdrive::
+* Bookmark a hyperdrive::
+* Stream audio and video::
+* Download hyperdrive files::
+* Upload files from your filesystem::
+* Purge a hyperdrive::
+* Non-interactive use::
+
+Open a hyperdrive
+
+* Directory view::
+* File view::
+* Unknown paths::
+
+Link to a hyperdrive
+
+* Org mode links::
+
+View the hyperdrive version history
+
+* History buffer::
+
+Upload files from your filesystem
+
+* Mirror a whole directory::
+* Mirror files by tag or other attributes::
+
+Concepts
+
+* Hyperdrive::
+* Hyper-gateway::
+* Naming::
+
+Hyperdrive
+
+* Sparse replication::
+* Versioning::
+
+Versioning
+
+* Partial version data::
+* No directory version history::
+
+Naming
+
+* Public keys::
+* Nicknames::
+* Petnames::
+* Seeds::
+* DNS domains::
+
+Known limitations
+
+* No empty directories::
+* Files and folders can have the same name::
+
+Tips
+
+* Quick documentation access::
+
+Indices
+
+* Keystroke index::
+* Function index::
+* Variable index::
+* Concept index::
+
+@end detailmenu
+@end menu
+
+@node Freedom to copy
+@chapter Freedom to copy
+
+Copyright @copyright{} 2023 USHIN, Inc.
+
+@quotation
+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.''
+
+@end quotation
+
+@node Installation
+@chapter Installation
+
+@menu
+* Emacs::
+* hyper-gateway::
+* hyperdrive.el: hyperdriveel. 
+@end menu
+
+@node Emacs
+@section Emacs
+
+@code{hyperdrive.el} requires @uref{https://www.gnu.org/software/emacs/, GNU 
Emacs} version 27.1 or later.
+
+@node hyper-gateway
+@section hyper-gateway
+
+@strong{NOTICE}: Soon @code{hyperdrive.el} will depend on 
@uref{https://github.com/RangerMauve/hyper-sdk-rpc, hyper-sdk-rpc} instead of
+hyper-gateway.
+
+@code{hyperdrive.el} relies on 
@uref{https://github.com/RangerMauve/hyper-gateway/, hyper-gateway} for talking 
to the hypercore
+network 
(@uref{https://github.com/RangerMauve/hyper-gateway#how-do-i-install-hyper-gateway,
 installation instructions}).
+
+@node hyperdriveel
+@section hyperdrive.el
+
+There are three recommended options for installing @code{hyperdrive.el}:
+NonGNU ELPA, MELPA, and @code{package-vc}.
+
+@menu
+* NonGNU ELPA::
+* MELPA::
+* package-vc::
+@end menu
+
+@node NonGNU ELPA
+@subsection NonGNU ELPA
+
+@code{hyperdrive.el} is available on 
@uref{https://elpa.nongnu.org/nongnu/hyperdrive.html, NonGNU ELPA}. On Emacs 28 
or later,
+installation is as simple as @code{M-x package-refresh-contents} then @code{M-x
+package-install RET hyperdrive RET}.
+
+On Emacs 27, you'll first have to add the NonGNU ELPA repository:
+
+@lisp
+(with-eval-after-load 'package
+  (add-to-list 'package-archives '("nongnu" . 
"https://elpa.nongnu.org/nongnu/";)))
+@end lisp
+
+After installing with NonGNU ELPA, you can later upgrade to a newer
+version of @code{hyperdrive.el} by running @code{M-x package-refresh-contents}
+then @code{M-x package-upgrade RET hyperdrive}. If @code{package-upgrade} is 
not
+available as a command, display the list of packages with @code{M-x
+list-packages}, select @code{hyperdrive}, and click the @code{Install} button.
+
+@node MELPA
+@subsection MELPA
+
+@code{hyperdrive.el} is also available on
+@uref{https://melpa.org/#/hyperdrive, MELPA}. First add the MELPA repository:
+
+@lisp
+(with-eval-after-load 'package
+  (add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/";)))
+@end lisp
+
+Then follow the @ref{NonGNU ELPA} installation instructions.
+
+@node package-vc
+@subsection package-vc
+
+@emph{package-vc only works on Emacs 29.2 or later.}
+
+@enumerate
+@item
+Ensure you have @code{git}, @code{makeinfo} (part of the @code{texinfo} 
package), and
+Emacs 29.2 or newer.
+
+@item
+Add the following lines to your @code{init.el} startup file:
+@end enumerate
+
+@lisp
+(unless (package-installed-p 'hyperdrive)
+  ;; 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))
+@end lisp
+
+Alternatively, if you have already cloned the @code{hyperdrive.el} repository,
+you can use the following snippet to install from that repository:
+
+@lisp
+(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)
+  ;; Change the path below to the location of your local hyperdrive.el 
repository.
+  (package-vc-install-from-checkout "~/.local/src/hyperdrive.el" "hyperdrive"))
+@end lisp
+
+In your @code{init.el}, type @code{M-x eval-buffer RET}.
+
+If all goes well, @code{hyperdrive.el} commands like @code{M-x 
hyperdrive-start}
+should now be available.  The documentation for @code{hyperdrive.el} should
+also be installed.
+
+After installing with @code{package-vc}, you can later upgrade to a newer
+version of @code{hyperdrive.el} by running @code{M-x package-vc-upgrade RET
+hyperdrive RET}.
+
+@node Example configuration
+@chapter Example configuration
+
+After following the @ref{Installation, , installation instructions}, you can 
add this
+snippet to your @code{~/.emacs.d/init.el} file.  This code will make the
+keyboard shortcut @code{C-c h} (hold the @code{Control} key and tap @code{c}, 
then release
+both and tap @code{h}) open @ref{Hyperdrive menu command, , the hyperdrive 
menu command}.  It will also enable
+the @ref{Menu bar support, , ``Hyperdrive'' menu bar}:
+
+@lisp
+(when (package-installed-p 'hyperdrive)
+  (global-set-key (kbd "C-c h") #'hyperdrive-menu)
+  (hyperdrive-menu-bar-mode 1))
+@end lisp
+
+With @ref{Top,use-package,,use-package,}:
+
+@lisp
+(use-package hyperdrive
+  :bind ("C-c h" . hyperdrive-menu)
+  :init (hyperdrive-menu-bar-mode 1))
+@end lisp
+
+@node Usage
+@chapter Usage
+
+@example
+Be careful about what you share!
+When you upload a file, beware:
+  You may delete your own copy,
+  But gone it may not be.
+On the network it still may be there.
+@end example
+
+@menu
+* Menu bar support::
+* Hyperdrive menu command::
+* Start/stop the gateway::
+* Open a hyperdrive::
+* Create a hyperdrive::
+* Write to a hyperdrive::
+* Link to a hyperdrive::
+* Delete a hyperdrive file::
+* View the hyperdrive version history::
+* Describe a hyperdrive::
+* Bookmark a hyperdrive::
+* Stream audio and video::
+* Download hyperdrive files::
+* Upload files from your filesystem::
+* Purge a hyperdrive::
+* Non-interactive use::
+@end menu
+
+@node Menu bar support
+@section Menu bar support
+
+@findex hyperdrive-menu-bar-mode
+@findex menu-bar-mode
+
+If you enabled @code{hyperdrive-menu-bar-mode} (either in your @ref{Example 
configuration, , configuration}
+or with @code{M-x hyperdrive-menu-bar-mode}), the ``Hyperdrive'' menu should
+appear inside the ``Tools'' menu at the top of the screen.  When the
+current buffer is visiting a hyperdrive file/directory, the
+``Hyperdrive'' menu will also be displayed as a top-level menu.  If you
+don't see the menu bar, please double check that @code{menu-bar-mode} is
+enabled (it is enabled by default).
+
+@node Hyperdrive menu command
+@section Hyperdrive menu command
+
+@findex hyperdrive-menu
+
+@code{M-x hyperdrive-menu} is a keyboard-driven interface to many
+@code{hyperdrive.el} commands.  With the menu open, press one of highlit keys
+or key combinations to invoke the command displayed next to it.
+Different commands are available in @code{hyperdrive-menu} when you're inside
+a hyperdrive file, directory, or neither.
+
+While inside the @code{hyperdrive-menu}, press @code{?} twice to open this
+@code{hyperdrive.el} info manual.  You can also press @code{?} followed by a
+command's key sequence to get help for that command. (@ref{Quick documentation 
access, , more tips on
+getting help})
+
+If you press @code{C-u} (universal prefix argument) before a key sequence,
+the command may behave differently, e.g., by prompting for more
+information.  You can jump between @code{hyperdrive-menu} commands with the
+@code{up} and @code{down} arrow keys.  Press @code{C-g} to close the menu.
+
+For more on this type of user interface, please refer to the 
@ref{Introduction,Transient
+documentation,,transient,}.  To learn about the commands available in
+@code{hyperdrive-menu}, read on!
+
+@node Start/stop the gateway
+@section Start/stop the gateway
+
+@findex hyperdrive-start
+@findex hyperdrive-stop
+
+To connect with peers, you'll need to start @code{hyper-gateway}. If you
+@uref{https://github.com/RangerMauve/hyper-gateway#how-do-i-run-hyper-gateway-as-a-background-process-on-gnulinux--systemd,
 install @code{hyper-gateway} as a SystemD
+service},
+you can connect and disconnect from the network with @code{M-x
+hyperdrive-start} and @code{M-x hyperdrive-stop}. Otherwise, follow 
@uref{https://github.com/RangerMauve/hyper-gateway#usage, these
+instructions} to
+run @code{hyper-gateway} manually.
+
+@node Open a hyperdrive
+@section Open a hyperdrive
+
+@findex hyperdrive-open-url
+@findex hyperdrive-find-file
+@findex hyperdrive-view-file
+
+You can open a hyperdrive folder or file by pasting in a @code{hyper://} URL
+after @code{M-x hyperdrive-open-url}.  Try loading USHIN's hyperdrive:
+
+@example
+hyper://aaj45d88g4eenu76rpmwzjiabsof1w8u6fufq6oogyhjk1ubygxy/
+@end example
+
+Alternatively, @code{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.  @code{hyperdrive-view-file} is like
+@code{hyperdrive-find-file}, but it opens the file in @ref{View 
Mode,view-mode,,emacs,}.
+
+@menu
+* Directory view::
+* File view::
+* Unknown paths::
+@end menu
+
+@node Directory view
+@subsection Directory view
+
+The following keybindings are available inside the directory view by
+default:
+
+@kindex hyperdrive-dir-previous
+@kindex hyperdrive-dir-next
+@itemize
+@item
+@code{n} and @code{p} move between entries
+@end itemize
+@kindex hyperdrive-dir-find-file
+@itemize
+@item
+@code{RET} or left click opens file or directory at point
+@end itemize
+@kindex hyperdrive-dir-view-file
+@itemize
+@item
+@code{v} opens file or directory at point in @ref{View Mode,view-mode,,emacs,}.
+@end itemize
+@kindex hyperdrive-up
+@itemize
+@item
+@code{^} goes up to the parent directory
+@end itemize
+@kindex revert-buffer
+@itemize
+@item
+@code{g} refreshes the directory to display potential updates
+@end itemize
+@kindex hyperdrive-dir-sort
+@itemize
+@item
+@code{s} sorts directory contents by column (to sort by a different
+column, click on the column header or use the `C-u` universal
+prefix argument)
+@end itemize
+@kindex hyperdrive-dir-download-file
+@itemize
+@item
+@code{d} downloads the file at point to disk
+@end itemize
+@kindex hyperdrive-delete
+@itemize
+@item
+@code{D} deletes the file or directory (recursively) at point
+@end itemize
+@kindex hyperdrive-dir-history
+@itemize
+@item
+@code{H} opens the @ref{View the hyperdrive version history, , version 
history} of file at point
+@end itemize
+@kindex hyperdrive-dir-copy-url
+@itemize
+@item
+@code{w} copies the URL of the file or directory at point
+@end itemize
+@kindex imenu
+@itemize
+@item
+@code{j} opens @code{imenu} to quickly jump to a file in the current directory
+@end itemize
+@kindex hyperdrive-menu
+@itemize
+@item
+@code{?} opens @code{hyperdrive-menu} (see @ref{Hyperdrive menu command})
+@end itemize
+@kindex hyperdrive-create-directory-no-op
+@itemize
+@item
+@code{+} signals an error, because you cannot create empty directories 
(@ref{No empty directories})
+@end itemize
+
+@node File view
+@subsection File view
+
+The following keybindings are available inside the directory view by
+default:
+
+@kindex revert-buffer-quick
+@itemize
+@item
+@code{C-x x g} refreshes the file to display potential updates
+@end itemize
+
+If you have bound @code{dired-jump} in the global keymap (people often choose
+@code{C-x C-j}), you can use the same binding to jump to the parent
+hyperdrive directory from any hyperdrive file or directory buffer.
+
+@node Unknown paths
+@subsection Unknown paths
+
+When you attempt to load a file or folder that doesn't appear to
+exist, @code{hyperdrive.el} will prompt you to take action:
+
+@itemize
+@item
+@code{h} (history) to open the @ref{View the hyperdrive version history, , 
version history} for that file. (This only
+works for files, not folders)
+@item
+@code{u} (up) to open the parent directory containing that file or folder
+@item
+@code{r} (recurse) to go up the directory tree until a directory is found
+or until you get to the root directory.
+@item
+@code{q} (exit) to exit,
+@item
+@code{?} (help) to show a help message.
+@end itemize
+
+If you attempt to load the root directory (@code{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, @code{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, @code{hyperdrive.el} should ask you to double-check the
+URL@.
+
+@node Create a hyperdrive
+@section Create a hyperdrive
+
+@findex hyperdrive-new
+
+You can have multiple hyperdrives, each one containing its own set of
+files. Run @code{M-x hyperdrive-new} then type in a @code{seed} (see 
@ref{Seeds}) to
+create a new hyperdrive. That seed will be combined with your secret
+master key, which is generated for you by @code{hyper-gateway}, to produce a
+public key (see @ref{Public keys}) that uniquely identifies that
+hyperdrive. @code{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.
+
+@node Write to a hyperdrive
+@section Write to a hyperdrive
+
+@findex hyperdrive-write-buffer
+@findex save-buffer
+@findex save-some-buffers
+@vindex save-some-buffers-default-predicate
+
+You can write a buffer to a hyperdrive with @code{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, @code{save-buffer} will
+silently update the current hyperdrive entry with the new content.
+
+@code{hyperdrive.el} will prompt to save modified hyperdrive files before
+exiting Emacs. If you want the command @code{save-some-buffers} to always
+prompt to save hyperdrive files in addition to regular files, set
+@code{save-some-buffers-default-predicate} to @code{t}.
+
+@node Link to a hyperdrive
+@section Link to a hyperdrive
+
+@findex hyperdrive-copy-url
+@findex hyperdrive-dir-copy-url
+
+In the directory view, you can copy the URL at point with
+@code{hyperdrive-dir-copy-url} (see @ref{Directory view}). Additionally, you 
can
+run @code{hyperdrive-copy-url} to copy the URL of the current hyperdrive
+file or directory.
+
+@menu
+* Org mode links::
+@end menu
+
+@node Org mode links
+@subsection Org mode links
+
+If the current file is an org-mode file, @code{org-store-link} will store a
+link to the hyperdrive file, and if point is inside a heading, its
+@code{CUSTOM_ID}, @code{ID}, or heading text will be appended to the stored 
URL@.
+
+Relative links are supported; within @code{hyper://PUBLIC-KEY/foo.org}, links
+to @code{bar.org}, @code{./bar.org}, and @code{/bar.org} will all point to
+@code{hyper://PUBLIC-KEY/bar.org}. A version number can also be specified;
+@code{/$/version/42/bar.org} will point to
+@code{hyper://PUBLIC-KEY/$/version/42/bar.org}.
+
+To link from a hyperdrive-mode org buffer to a file on the local
+filesystem, explicitly add the @code{file:} link type prefix:
+@code{file:~/.emacs.d/init.el}.
+
+Org-mode hyperdrive link completion allows you to interactively link
+to a hyperdrive file/folder by running @code{M-x org-insert-link} (or 
@code{C-c C-l}
+in org-mode), then typing @code{hyper:} and @code{RET}.  To change how
+@code{org-insert-link} inserts links to files within the same hyperdrive,
+adjust @code{hyperdrive-org-link-full-url} and @code{org-link-file-path-type}.
+
+@node Delete a hyperdrive file
+@section Delete a hyperdrive file
+
+@findex hyperdrive-delete
+
+You can use @code{hyperdrive-delete} to delete the hyperdrive file in the
+current buffer.  This command has a keybinding in the @ref{Directory view, , 
directory view}.
+
+@strong{Note that deleted files can be accessed by @ref{View the hyperdrive 
version history, , loading a prior version} of
+the hyperdrive.}
+
+@node View the hyperdrive version history
+@section View the hyperdrive version history
+
+@findex hyperdrive-previous-version
+@findex hyperdrive-next-version
+
+Hyperdrives are versioned (see @ref{Versioning}).  To view the previous/next
+version of a hyperdrive file, run @code{hyperdrive-previous-version} or
+@code{hyperdrive-next-version} inside the file's buffer.
+
+@menu
+* History buffer::
+@end menu
+
+@node History buffer
+@subsection History buffer
+
+@findex hyperdrive-history
+
+To view the entire known history of a file, use @code{hyperdrive-history}.
+For an explanation of the history buffer, see @ref{Partial version data}.
+
+The following keybindings are available inside the directory view by
+default:
+
+@kindex hyperdrive-history-fill-version-ranges
+@itemize
+@item
+@code{+} loads version history for unknown ranges
+@end itemize
+@kindex hyperdrive-history-find-file
+@itemize
+@item
+@code{RET} or left click opens the file at the start of the range at point
+@end itemize
+@kindex hyperdrive-history-view-file
+@itemize
+@item
+@code{v} opens the file at the start of the range at point in @ref{View 
Mode,view-mode,,emacs,}
+@end itemize
+@kindex hyperdrive-history-copy-url
+@itemize
+@item
+@code{w} copies the URL of the file at the start of the range at point
+@end itemize
+@kindex hyperdrive-history-download-file
+@itemize
+@item
+@code{d} downloads the file at the start of the range at point
+@end itemize
+@kindex hyperdrive-history-diff
+@itemize
+@item
+@code{=} displays the differences between the version at point and the
+prior version
+@end itemize
+
+To act on the latest known version of the file, use these keybindings
+on the header line displaying the file description.
+
+@node Describe a hyperdrive
+@section Describe a hyperdrive
+
+@findex hyperdrive-describe-hyperdrive
+
+To see information about a hyperdrive, such as its public key, seed,
+petname, nickname, domains, writable, or other metadata, run
+@code{hyperdrive-describe-hyperdrive}. For more on what this information
+means, see @ref{Naming}.
+
+@node Bookmark a hyperdrive
+@section Bookmark a hyperdrive
+
+@findex hyperdrive-bookmark-jump
+@findex hyperdrive-bookmark-list
+
+You can use the built-in @code{bookmark-set}, @code{bookmark-jump}, and
+@code{bookmark-list} functions to store and jump to a hyperdrive file or
+directory. To jump to or view only hyperdrive bookmarks, use
+@code{hyperdrive-bookmark-jump} and @code{hyperdrive-bookmark-list}.
+
+@node Stream audio and video
+@section Stream audio and video
+
+When you use @code{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.
+
+@node Download hyperdrive files
+@section Download hyperdrive files
+
+@findex hyperdrive-download
+@findex hyperdrive-download-url
+
+You can download a hyperdrive file to your local filesystem. Download
+the current hyperdrive file with @code{hyperdrive-download} or paste
+in a @code{hyper://} URL after @code{hyperdrive-download-url}.
+
+@node Upload files from your filesystem
+@section Upload files from your filesystem
+
+@findex hyperdrive-upload-file
+@findex hyperdrive-upload-files
+@findex yank-media
+
+To upload a single file from your filesystem, use
+@code{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.
+
+@code{hyperdrive-upload-files} lets you upload multiple files from your
+filesystem to a hyperdrive. As with the @code{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 @code{yank-media}.
+
+@menu
+* Mirror a whole directory::
+* Mirror files by tag or other attributes::
+@end menu
+
+@node Mirror a whole directory
+@subsection Mirror a whole directory
+
+@findex hyperdrive-mirror
+@findex hyperdrive-mirror-do-upload
+
+@code{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 @code{~/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 @code{hyper}
+URL at which they will be available after upload. To upload the files,
+run @code{hyperdrive-mirror-do-upload} (bound to @code{C-c C-c} by default) in 
the
+@code{*hyperdrive-mirror*} buffer which opens.
+
+@lisp
+(hyperdrive-mirror "~/blog/" (hyperdrive-by-slot 'petname "foo")
+                   :target-dir "/blog/")
+@end lisp
+
+To upload the same files without confirming, add @code{:no-confirm
+t}.  Interactively, use two universal prefix arguments @code{C-u C-u}.
+
+@node Mirror files by tag or other attributes
+@subsection Mirror files by tag or other attributes
+
+@code{hyperdrive-mirror} can accept a @code{PREDICATE} argument, which you can
+use to upload only certain files.  Interactively, one universal prefix
+argument @code{C-u} make this command prompt you for @code{PREDICATE}.
+
+Let's say that you have some files on your filesystem in the @code{~/blog/}
+directory, but you only want to upload those files which have been
+tagged as ``public'' using Protesilaos Stavrou's 
@uref{https://protesilaos.com/emacs/denote, Denote} file-naming
+scheme.
+
+The following snippet includes a @code{PREDICATE} key whose value is a
+regular expression against which every expanded filename inside will
+be tested.
+
+@lisp
+(hyperdrive-mirror "~/blog/" (hyperdrive-by-slot 'petname "foo")
+                   :target-dir "/blog/"
+                   :predicate ".*_public.*")
+@end lisp
+
+Alternatively, you could select files by tag with Karl Voit's
+@uref{https://github.com/novoid/filetags/, filetags}. Either way allows for a 
``non-splitting'' approach where
+public and private files exist in the same directory.
+
+@code{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 @code{~/blog/} which are smaller than 5MB:
+
+@lisp
+(hyperdrive-mirror "~/blog/" (hyperdrive-by-slot 'petname "foo")
+                   :target-dir "/blog/"
+                   :predicate (lambda (file) (> (* 5 1024 1024)
+                                              (file-attribute-size 
(file-attributes file)))))
+@end lisp
+
+@node Purge a hyperdrive
+@section Purge a hyperdrive
+
+@findex hyperdrive-purge
+
+To remove all data related to a hyperdrive, run @code{hyperdrive-purge}. This
+command will first prompt for confirmation.  In addition to the
+hyperdrive's file content and metadata, @code{hyperdrive-purge} also removes
+relevant data inside @code{hyperdrive-hyperdrives} and 
@code{hyperdrive-version-ranges}.
+
+@strong{Data which has been purged from your local machine may still be
+available on the network.}
+
+@node Non-interactive use
+@section Non-interactive use
+
+@findex hyperdrive-by-slot
+
+In writing your own functions to extend @code{hyperdrive.el}, you can use
+@code{hyperdrive-by-slot} to access a hyperdrive entry by its seed, petname,
+or public key.
+
+For examples, see @ref{Mirror a whole directory} and @ref{Mirror files by tag 
or other attributes}.
+
+@node Concepts
+@chapter Concepts
+
+@menu
+* Hyperdrive::
+* Hyper-gateway::
+* Naming::
+@end menu
+
+@node Hyperdrive
+@section Hyperdrive
+
+@uref{https://docs.holepunch.to/building-blocks/hyperdrive, Hyperdrive} is a 
virtual filesystem which you can use to share files on
+the peer-to-peer (P2P) @code{hyper} network.  It's a special folder with a
+long, unique link starting with @code{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 @code{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 @ref{Versioning} for more information.
+
+@menu
+* Sparse replication::
+* Versioning::
+@end menu
+
+@node Sparse replication
+@subsection Sparse replication
+
+@cindex 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.
+
+@node Versioning
+@subsection Versioning
+
+@cindex 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, @code{hyper://PUBLIC-KEY/$/version/50/}
+refers to the fiftieth version of the hyperdrive identified by
+@code{PUBLIC-KEY}. Loading a hyperdrive entry without specifying a version
+number always loads the most recent version of that hyperdrive. If you
+pass @code{hyper://PUBLIC-KEY/foo.org} to @code{hyperdrive-open-url}, 
@code{hyperdrive.el}
+will always attempt to find @code{/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 @code{hyper://PUBLIC-KEY/} is 50. If you add a new entry
+at @code{hyper://PUBLIC-KEY/bar.org}, the latest version of your hyperdrive
+will become 51.
+
+Since @code{/bar.org} did not exist before version 51, @code{hyperdrive.el} 
should
+warn you that nothing exists at
+@code{hyper://PUBLIC-KEY/$/version/50/bar.org}. If you add another file
+@code{hyper://PUBLIC-KEY/quux.org}, your hyperdrive's latest version will
+become 52. For the moment, @code{hyper://PUBLIC-KEY/bar.org},
+@code{hyper://PUBLIC-KEY/$/version/51/bar.org}, and
+@code{hyper://PUBLIC-KEY/$/version/52/bar.org}, all point to the same
+version of @code{/bar.org}. If you then make a change to @code{/bar.org}, your
+hyperdrive's latest version will become 53. Now
+@code{hyper://PUBLIC-KEY/bar.org} and
+@code{hyper://PUBLIC-KEY/$/version/53/bar.org} will point to the latest
+version of @code{/bar.org}, while the 51- and 52-versioned URLs will continue
+to point to the original version.
+
+Here's the history of @code{/bar.org} so far (the hyperdrive's latest version
+is 53):
+
+@multitable {aaaaaaaaaaaaa} {aaaaaa}
+@headitem Version range
+@tab exists
+@item 1-50
+@tab no
+@item 51-52
+@tab yes
+@item 53
+@tab yes
+@end multitable
+
+The table shows that @code{/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 @code{/bar.org}, @code{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,
+@code{hyperdrive.el} sets the buffer to read-only whenever a version number
+is specified in a hyper URL@.
+
+@menu
+* Partial version data::
+* No directory version history::
+@end menu
+
+@node Partial version data
+@subsubsection Partial version data
+
+Because hyperdrives are sparsely replicated (see @ref{Sparse replication}), you
+might not know the full version history of a file.  For example, when
+you load the most recent version of @code{/bar.org}, the gateway
+(see @ref{Hyper-gateway}) will also return the start of the version range
+containing the most recent version of @code{/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:
+
+@multitable {aaaaaaaaaaaaa} {aaaaaaa}
+@headitem Version range
+@tab exists
+@item 1-52
+@tab unknown
+@item 53
+@tab yes
+@end multitable
+
+Running @code{hyperdrive-previous} inside of the buffer for the latest
+version of @code{/bar.org} will load @code{/bar.org} at version 52. The 
gateway will
+inform us that the version range for @code{/bar.org} that contains version 52
+started at 51:
+
+@multitable {aaaaaaaaaaaaa} {aaaaaaa}
+@headitem Version range
+@tab exists
+@item 1-50
+@tab unknown
+@item 51-52
+@tab yes
+@item 53
+@tab yes
+@end multitable
+
+Running @code{hyperdrive-previous} inside of the buffer for @code{/bar.org} at
+version 51 or 52 will attempt to load @code{/bar.org} at
+version 50. @code{/bar.org} does not exist at version 50, so the table will
+now look like:
+
+@multitable {aaaaaaaaaaaaa} {aaaaaaa}
+@headitem Version range
+@tab exists
+@item 1-49
+@tab unknown
+@item 50
+@tab no
+@item 51-52
+@tab yes
+@item 53
+@tab yes
+@end multitable
+
+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, @code{/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.
+
+@node No directory version history
+@subsubsection No directory version history
+
+Version history for directories is not implemented for a design reason
+and technical reason:
+
+@itemize
+@item
+Directories have neither mtime nor size metadata, so a history view
+for directories wouldn't be that useful.
+@item
+Implementation of directory history would be somewhat ugly, since it
+requires either
+@enumerate
+@item
+storing an entry for each directory in @code{hyperdrive-version-ranges},
+which doesn't optimally normalize version history data, or
+@item
+generating directory history based on the history of the files it
+contains, which can never prove that a directory doesn't exist.
+@end enumerate
+@end itemize
+
+@node Hyper-gateway
+@section Hyper-gateway
+
+@cindex Hyper-gateway
+
+@uref{https://github.com/RangerMauve/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 @code{hyperdrive.el}, P2P interactions consist
+mostly of, e.g., @code{GET} requests to download files and @code{PUT} requests
+to write files to a hyperdrive.
+
+@node Naming
+@section Naming
+
+@cindex Naming
+
+Inspired by Marc Stiegler's 
@uref{http://www.skyhunter.com/marcs/petnames/IntroPetNames.html, An 
Introduction to Petname Systems},
+@code{hyperdrive.el} names drives in a three different ways:
+
+@table @asis
+@item Public key
+public, globally unique, not human-memorable
+@item Nickname  
+public, not necessarily unique, human-memorable
+@item Petname   
+private, locally unique, human-memorable
+@end table
+
+If @code{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:
+
+@table @asis
+@item Seed      
+string used to generate public key
+@item DNS domain
+public, globally unique, human-memorable
+@end table
+
+@menu
+* Public keys::
+* Nicknames::
+* Petnames::
+* Seeds::
+* DNS domains::
+@end menu
+
+@node Public keys
+@subsection Public keys
+
+@cindex Public keys
+@findex hyperdrive-new
+
+Public keys are 52-character-long, 
@uref{https://en.wikipedia.org/wiki/Base32#z-base-32, z-base-32} encoded keys 
generated
+from your secret master key and a seed string. @code{hyper-gateway} generates
+the secret key for you, and you provide a seed (see @ref{Seeds}) when
+generating a new drive with @code{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.
+
+@node Nicknames
+@subsection Nicknames
+
+@cindex Nicknames
+@findex hyperdrive-set-nickname
+
+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
+@code{/.well-known/host-meta.json} under the @code{name} key, as specified in
+RFC6415. You can only assign a nickname to hyperdrives which you have
+created. Nicknames can be changed with @code{hyperdrive-set-nickname}.
+
+@node Petnames
+@subsection Petnames
+
+@cindex Petnames
+@findex hyperdrive-set-petname
+
+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 @ref{Seeds}) is used as its
+petname by default. Petnames can be changed with
+@code{hyperdrive-set-petname}, but drives cannot share a petname.
+
+@node Seeds
+@subsection Seeds
+
+@cindex Seeds
+
+Along with your secret master key, seeds are used to generate public
+keys (see @ref{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 @ref{DNS domains}).
+
+@node DNS domains
+@subsection DNS domains
+
+@cindex DNS domains
+
+It is possible to use @uref{https://dnslink.io/, DNSLink} to link to a 
hyperdrive with a domain
+name instead of a public key (see @ref{Public keys}), like
+@code{hyper://example.org/path/to/file}. Create a TXT record at
+@code{_dnslink.example.org} with the contents @code{/hyper/PUBLIC-KEY} (no 
trailing
+slash). Note: relying on DNS adds another point of centralization,
+reducing the durability of your link. @code{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
+@ref{Suspicious Text,,,elisp,}).
+
+@node Customization
+@chapter Customization
+
+You can customize the following variables settings by running @code{M-x
+customize-group RET hyperdrive RET}:
+
+@vindex hyperdrive-hyper-gateway-port
+@table @asis
+@item @code{hyperdrive-hyper-gateway-port}
+Port on which to run the
+hyper-gateway server. Defaults to @code{4973}.
+@end table
+
+@vindex hyperdrive-honor-auto-mode-alist
+@table @asis
+@item @code{hyperdrive-honor-auto-mode-alist}
+If non-nil, use file extension
+of hyperdrive file to set @code{major-mode}. Defaults to @code{t}.
+@end table
+
+@vindex hyperdrive-persist-location
+@table @asis
+@item @code{hyperdrive-persist-location}
+Location where @code{persist} will store
+data, currently @code{hyperdrive-hyperdrives} and 
@code{hyperdrive-version-ranges}.
+By default, uses the default @code{persist} location.
+@end table
+
+@vindex hyperdrive-download-directory
+@table @asis
+@item @code{hyperdrive-download-directory}
+Location where
+@code{hyperdrive-download-url} will download files. Defaults to
+@code{eww-download-directory} or, if not bound, the home directory.
+@end table
+
+@vindex hyperdrive-timestamp-format
+@table @asis
+@item @code{hyperdrive-timestamp-format}
+Format string used for
+timestamps. Passed to @code{format-time-string}, which see.
+@end table
+
+@vindex hyperdrive-directory-display-buffer-action
+@table @asis
+@item @code{hyperdrive-directory-display-buffer-action}
+Display buffer action
+for hyperdrive directories. Passed to @code{display-buffer}, which see.
+@end table
+
+@vindex hyperdrive-directory-sort
+@table @asis
+@item @code{hyperdrive-directory-sort}
+Column by which directory entries are sorted.
+@end table
+Internally, a cons cell of (COLUMN . DIRECTION), the COLUMn being one
+of the directory listing columns (@code{name}, @code{size}, or @code{mtime}) 
and
+DIRECTION being one of @code{:ascending} or @code{:descending}.
+
+@vindex hyperdrive-history-display-buffer-action
+@table @asis
+@item @code{hyperdrive-history-display-buffer-action}
+Display buffer action
+for hyperdrive history buffers. Passed to @code{display-buffer}, which see.
+@end table
+
+@vindex hyperdrive-default-host-format
+@table @asis
+@item @code{hyperdrive-default-host-format}
+Default format for displaying
+hyperdrive hostnames. See @ref{Naming} section for what this means.
+@end table
+
+@vindex hyperdrive-stream-player-command
+@table @asis
+@item @code{hyperdrive-stream-player-command}
+Command used to play streamable
+URLs externally. Default uses @uref{https://mpv.io/, mpv}. There also exists a 
preconfigured
+option for @uref{https://www.videolan.org/vlc/, VLC media player}.
+@end table
+
+@vindex hyperdrive-queue-limit
+@table @asis
+@item @code{hyperdrive-queue-limit}
+Default number of request sent to
+@code{hyper-gateway} at a time in a queues. Defaults to @code{20}.
+@end table
+
+@vindex hyperdrive-fill-version-ranges-limit
+@table @asis
+@item @code{hyperdrive-queue-limit}
+Default maximum number of requests when
+filling version history. Defaults to @code{10}.
+@end table
+
+@vindex hyperdrive-render-html
+@table @asis
+@item @code{hyperdrive-render-html}
+Control how HTML hyperdrive files are
+displayed. By default, HTML pages are rendered in Emacs with 
@ref{Top,EWW,,eww,}. If
+@code{nil}, raw HTML will be displayed.
+@end table
+
+@vindex hyperdrive-reuse-buffers
+@table @asis
+@item @code{hyperdrive-reuse-buffers}
+How to reuse buffers when showing entries.
+By default (@code{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 @code{same-version}.
+@end table
+
+@node Known limitations
+@chapter Known limitations
+
+@menu
+* No empty directories::
+* Files and folders can have the same name::
+@end menu
+
+@node No empty directories
+@section 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:
+
+@itemize
+@item
+it is not possible to create empty directories
+@item
+deleting the last file in a folder deletes the folder as well
+@end itemize
+
+When a hyperdrive file or folder is not found, @code{hyperdrive.el} prompts
+you for an action (see @ref{Unknown paths}).
+
+@node Files and folders can have the same name
+@section 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., @code{hyper://PUBLIC-KEY/foo/bar/} and 
@code{hyper://PUBLIC-KEY/foo/bar}. In
+this case, the folder listing for @code{hyper://PUBLIC-KEY/foo/} would
+display the @code{bar} entry but not the @code{bar/} entry prefix.
+
+@node Tips
+@chapter Tips
+
+@menu
+* Quick documentation access::
+@end menu
+
+@node Quick documentation access
+@section Quick documentation access
+
+You can open the @code{hyperdrive.el} info manual from @code{hyperdrive-menu} 
by
+pressing @code{?} twice.
+
+To view documentation for @code{hyperdrive.el} commands, functions, and
+variables, press @code{C-h o} (@code{describe-symbol}). Inside the 
@code{*Help*}
+buffer that pops open, you can press @code{i} (@code{help-goto-info}) to jump 
to
+the relevant section in the @code{hyperdrive.el} manual.
+
+@node Troubleshooting
+@chapter Troubleshooting
+
+If you run into issues, please first try resetting the value of
+@code{hyperdrive-hyperdrives}:
+
+@lisp
+(progn
+  (setf hyperdrive-hyperdrives (make-hash-table :test #'equal))
+  (persist-save 'hyperdrive-hyperdrives))
+@end lisp
+
+Please ensure that your version of @code{hyper-gateway} (@code{M-x
+hyperdrive-hyper-gateway-version}) is the latest version
+(@uref{https://github.com/RangerMauve/hyper-gateway/releases/, releases}).
+
+@node Contributing/Getting help
+@chapter Contributing/Getting help
+
+You're welcome to join our public XMPP chat room!
+
+@itemize
+@item
+@code{xmpp:discuss@@conference.ushin.org} 
(@uref{https://anonymous.cheogram.com/discuss@@conference.ushin.org, Join 
anonymously from your browser})
+@item
+@code{#_bifrost_discuss_conference.ushin.org:aria-net.org} (Matrix bridge)
+@end itemize
+
+Bugs can be submitted to the @uref{https://todo.sr.ht/~ushin/ushin, ushin 
issue tracker}. Patches, comments or
+questions can be submitted to the @uref{https://lists.sr.ht/~ushin/ushin, 
ushin public inbox}.
+
+@node Acknowledgments
+@chapter Acknowledgments
+
+@uref{https://github.com/alphapapa/, Adam Porter} for rewriting
+@code{hyperdrive.el} and for his work on @code{plz.el}.
+
+@uref{https://mauve.moe/, Mauve Signweaver} for their guidance into the
+world of p2p as well as the development of @code{hyper-gateway}.
+
+@uref{https://protesilaos.com, Protesilaos Stavrou} for design input and 
user-testing @code{hyperdrive.el}.
+
+@uref{https://karl-voit.at/, Karl Voit} for his feedback, especially the
+suggestion that we allow for a non-splitting approach for uploading
+files from the filesystem.
+
+@uref{https://www.sanityinc.com/, Steve Purcell} and 
@uref{https://github.com/akirak, Akira Komamura} for suggestions to improve our 
CI
+build manifests.
+
+@uref{https://eshelyaron.com/, Eshel Yaron} for the suggestion to add on 
@code{hyperdrive-menu-bar-mode}.
+
+@node Indices
+@chapter Indices
+
+@menu
+* Keystroke index::
+* Function index::
+* Variable index::
+* Concept index::
+@end menu
+
+@node Keystroke index
+@section Keystroke index
+
+@printindex ky
+
+@node Function index
+@section Function index
+
+@printindex fn
+
+@node Variable index
+@section Variable index
+
+@printindex vr
+
+@node Concept index
+@section Concept index
+
+@printindex cp
+
+@node GNU Free Documentation License
+@chapter GNU Free Documentation License
+
+@center Version 1.3, 3 November 2008
+
+@display
+Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, 
Inc.
+@uref{https://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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:
+
+@enumerate A
+@item
+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.
+
+@item
+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.
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+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.
+
+@item
+Preserve in that license notice the full lists of Invariant
+Sections and required Cover Texts given in the Document's
+license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+Delete any section Entitled ``Endorsements''. Such a section may
+not be included in the Modified Version.
+
+@item
+Do not retitle any existing section to be Entitled
+``Endorsements'' or to conflict in title with any Invariant
+Section.
+
+@item
+Preserve any Warranty Disclaimers.
+@end enumerate
+
+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.
+
+@item
+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.''
+
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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
+@uref{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.
+
+@item
+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.
+@end enumerate
+
+@page
+
+@anchor{ADDENDUM How to use this License for your documents}
+@heading 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:
+
+@example
+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''.
+@end example
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with@dots{}Texts.''@tie{}line with this:
+
+@example
+with the Invariant Sections being LIST THEIR TITLES, with
+the Front-Cover Texts being LIST, and with the Back-Cover Texts
+being LIST.
+@end example
+
+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.
+
+@bye
\ No newline at end of file