branch: elpa/hyperdrive commit 18a59bb07a7d03c2b89a007b0a0973342d20a63f Author: Joseph Turner <jos...@ushin.org> Commit: Joseph Turner <jos...@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{jos...@ushin.org} +@set MAINTAINERCONTACT @uref{mailto:jos...@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