[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[nongnu] elpa/hyperdrive 3c0129e851 1/2: Remove: doc/hyperdrive-manual.t
|
From: |
ELPA Syncer |
|
Subject: |
[nongnu] elpa/hyperdrive 3c0129e851 1/2: Remove: doc/hyperdrive-manual.texi |
|
Date: |
Sun, 8 Oct 2023 07:00:47 -0400 (EDT) |
branch: elpa/hyperdrive
commit 3c0129e851493ac248965354f4e6c42d4131f9a6
Author: Joseph Turner <joseph@ushin.org>
Commit: Joseph Turner <joseph@ushin.org>
Remove: doc/hyperdrive-manual.texi
This is a further attempt to resolve the formatting issue in the
info (dir)Top node.
---
doc/hyperdrive-manual.texi | 1905 --------------------------------------------
1 file changed, 1905 deletions(-)
diff --git a/doc/hyperdrive-manual.texi b/doc/hyperdrive-manual.texi
deleted file mode 100644
index d03d5ef74d..0000000000
--- a/doc/hyperdrive-manual.texi
+++ /dev/null
@@ -1,1905 +0,0 @@
-\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 Communication
-@direntry
-* 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::
-* Customization::
-* Concepts::
-* 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
-
-* hyperdrive-menu::
-* Start/stop the gateway::
-* Create a hyperdrive::
-* Open 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 is only available on Emacs 29.1 or later.}
-
-@enumerate
-@item
-Ensure you have @code{git}, @code{makeinfo} (part of the @code{texinfo}
package), and
-Emacs 29.1 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 to make the keyboard short
@code{C-c
-h} (hold the @code{Control} key and tap @code{c}, then release both and tap
@code{h}) to
-open @ref{hyperdrive-menu}:
-
-@lisp
-(global-set-key (kbd "C-c h") #'hyperdrive-menu)
-@end lisp
-
-With @ref{Top,use-package,,use-package,}:
-
-@lisp
-(use-package hyperdrive
- :bind ("C-c h" . hyperdrive-menu))
-@end lisp
-
-@node Usage
-@chapter Usage
-
-@strong{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.
-
-@menu
-* hyperdrive-menu::
-* Start/stop the gateway::
-* Create a hyperdrive::
-* Open 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 hyperdrive-menu
-@section hyperdrive-menu
-
-@findex hyperdrive-menu
-
-@code{M-x hyperdrive-menu} offers quick access 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 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 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}. 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} 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{o} 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})
-@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 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} 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 Customization
-@chapter Customization
-
-You can customize the following variables settings by running @code{M-x
-customize-group RET hyperdrive RET}:
-
-@vindex hyperdrive-storage-location
-@table @asis
-@item @code{hyperdrive-storage-location}
-Location to store Hypercore
-data. Defaults to @code{"~/.local/share/hyper-gateway-nodejs/"}.
-@end table
-
-@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 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 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 suggestion to improve our
CI
-build manifests.
-
-@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