branch: elpa/hyperdrive
commit 30943e9b8dc8f8a9d6abb386db4f016d27e1762e
Author: Joseph Turner <[email protected]>
Commit: Joseph Turner <[email protected]>
Docs: Document changes
---
CHANGELOG.org | 30 +++++++++++++++---
doc/hyperdrive.org | 73 +++++++++++++++++++++++++++++++++-----------
doc/hyperdrive.texi | 87 ++++++++++++++++++++++++++++++++++++++++++-----------
3 files changed, 151 insertions(+), 39 deletions(-)
diff --git a/CHANGELOG.org b/CHANGELOG.org
index 01b78482fe..1711e059c0 100644
--- a/CHANGELOG.org
+++ b/CHANGELOG.org
@@ -6,6 +6,9 @@ This project adheres to
[[https://semver.org/spec/v2.0.0.html][Semantic Versioni
* 0.4-pre
+Version ~0.4~ features
[[https://ushin.org/hyperdrive/hyperdrive-manual.html#Org_002dtransclusion-integration][org-transclusion
integration]], easy gateway
+installation with ~M-x hyperdrive-install~, and a faster directory UI!
+
** Security
- By default, don't automatically load major mode when browsing
@@ -14,8 +17,13 @@ This project adheres to
[[https://semver.org/spec/v2.0.0.html][Semantic Versioni
** Added
-- Simplified installation: After ~M-x package-install hyperdrive.el~,
- run ~M-x hyperdrive-install~ to install the gateway.
+- Easy installation: After ~M-x package-install hyperdrive.el~, run ~M-x
+ hyperdrive-install~ to install the gateway.
+- Cancel installation in progress with ~hyperdrive-cancel-install~.
+- Add ~hyperdrive-install~ and ~hyperdrive-cancel-install~ bindings to
+ ~hyperdrive-menu~ and menu bar.
+- Add ~hyperdrive-restart~ to restart the gateway, also bound in
+ ~hyperdrive-menu~ and menu bar.
- When visiting an old version of a hyperdrive file, press ~n~ and ~p~ to
traverse the version history. Press ~q~ to kill the current buffer.
@@ -25,11 +33,24 @@ This project adheres to
[[https://semver.org/spec/v2.0.0.html][Semantic Versioni
follow the [installation
instructions](https://git.sr.ht/~ushin/hyper-gateway-ushin#installation).
- Directory listings load faster
-- Improved defcustom types
+- Improve gateway status indicators in ~hyperdrive-menu~ to update
+ asynchronously with "starting", "installing", "upgrading", etc.
+- Improve messages and errors when starting and stopping gateway.
+- Remove gateway status indicator in hyperdrive menu bar since menu
+ bar labels cannot be updated while the menu bar is open.
- Better error message when the gateway is not installed.
Thanks to ~magnum~ on XMPP for reporting.
-- Removed ~hyperdrive-reuse-buffers~ user option to ensure consistent
+- Remove ~hyperdrive-reuse-buffers~ user option to ensure consistent
behavior when uniquifying buffer names.
+- Remove ~hyperdrive-gateway-process-type~ user option. To customize
+ gateway startup, see options ~hyperdrive-gateway-start-function~,
+ ~hyperdrive-gateway-stop-function~, ~hyperdrive-gateway-live-predicate~.
+- Remove ~hyperdrive-gateway-command~ user option. To customize gateway
+ command, see options ~hyperdrive-gateway-directory~,
+ ~hyperdrive-gateway-program~, ~hyperdrive-gateway-command-args~.
+- Rename and alias ~hyperdrive-hyper-gateway-ushin-port~ to
+ ~hyperdrive-gateway-port~. Alias will be removed in a later version.
+- Improve defcustom types
** Fixed
@@ -37,6 +58,7 @@ This project adheres to
[[https://semver.org/spec/v2.0.0.html][Semantic Versioni
- More reliably kill intermediate buffers when generating a diff.
- Avoid unnecessarily updating ~hyperdrive-version-ranges~.
- Include the first file in a directory as an ~imenu~ candidate.
+- Start gateway subprocess on ~hyperdrive-gateway-port~.
** Internal
diff --git a/doc/hyperdrive.org b/doc/hyperdrive.org
index b902ee015a..71af6491f3 100644
--- a/doc/hyperdrive.org
+++ b/doc/hyperdrive.org
@@ -96,6 +96,20 @@ When you upload a file, beware:
On the network it still may be there.
#+end_verse
+** Install the gateway
+
+Run ~M-x hyperdrive-install~ to download and install the gateway program
+(see [[*hyper-gateway-ushin]]):
+
+- Command: hyperdrive-install ::
+
+ Download and install the gateway. Prompts for confirmation before
+ downloading.
+
+- Command: hyperdrive-cancel-install ::
+
+ Cancel installation in progress.
+
** Menu bar support
#+findex: menu-bar-mode
@@ -146,32 +160,38 @@ and in the "Hyperdrive" menu bar (see [[*Menu bar
support]]).
Start the gateway.
+- User Option: hyperdrive-gateway-ready-hook ::
+
+ Hook run when the gateway becomes responsive after ~hyperdrive-start~.
+ One of the default hooks, ~hyperdrive-check-gateway-version~, will
+ warn you if you're running an outdated version of the gateway.
+
- Command: hyperdrive-stop ::
Stop the gateway.
-- User Option: hyperdrive-gateway-process-type ::
+- Command: hyperdrive-restart ::
- How to start and stop the gateway. By default, ~hyperdrive.el~ will
- autodetect the appropriate process type. If you have configured
-
[[https://git.sr.ht/~ushin/hyper-gateway-ushin#how-do-i-run-hyper-gateway-ushin-as-a-background-process-on-gnulinux--systemd][hyper-gateway-ushin
- to run as a systemd service]], then ~hyperdrive.el~ will automatically
- use ~systemd~ to manage the gateway. Otherwise, ~hyperdrive.el~ will
- start the gateway as an Emacs subprocess.
+ Restart the gateway.
-- User Option: hyperdrive-gateway-command ::
+- Command: hyperdrive-gateway-version ::
- The command run to start the gateway as an Emacs subprocess. This
- option only takes effect when ~hyperdrive-gateway-process-type~ is
- set to ~subprocess~.
+ Say the version of the gateway which is running.
-Alternatively, you can start the gateway manually by running:
+*** Advanced gateway customization
-#+begin_src sh
-hyper-gateway-ushin run --writable true
-#+end_src
+- User Option: hyperdrive-gateway-start-function ::
-For full usage instructions, see the
[[https://git.sr.ht/~ushin/hyper-gateway-ushin#usage][hyper-gateway-ushin
README]].
+ Function run to start the gateway. By default, ~hyperdrive.el~ will
+ start the gateway as an Emacs subprocess.
+
+- User Option: hyperdrive-gateway-stop-function ::
+
+ Function run to stop the gateway.
+
+- User Option: hyperdrive-gateway-live-predicate ::
+
+ Function run to check that the gateway process is live.
** Open a hyperdrive
@@ -1057,10 +1077,29 @@ DNS domains are checked for suspicious characters (see
You can adjust the following options in the customization interface by
running ~M-x customize-group RET hyperdrive RET~:
+- User Option: hyperdrive-gateway-program ::
+
+ Name of executable to run when starting the gateway with
+ ~hyperdrive-gateway-start-function~. ~hyperdrive-install~ will install
+ the gateway to this file in ~hyperdrive-gateway-directory~.
+
+- User Option: hyperdrive-gateway-directory ::
+
+ Filesystem directory in which the gateway is expected to be found.
+ ~hyperdrive-install~ will install the gateway to this location. When
+ starting the gateway, if ~hyperdrive-gateway-program~ is not found in
+ this directory, Emacs searches ~PATH~ for ~hyperdrive-gateway-program~.
+
+- User Option: hyperdrive-gateway-command-args ::
+
+ Command line arguments passed to the gateway when starting the
+ gateway with the default ~hyperdrive-gateway-start-function~.
+
- User Option: hyperdrive-gateway-port ::
~hyperdrive.el~ will send HTTP requests to the gateway on this port.
- Defaults to ~4973~.
+ Defaults to ~4973~. The default ~hyperdrive-gateway-start-function~
+ will start the gateway on this port.
- User Option: hyperdrive-persist-location ::
diff --git a/doc/hyperdrive.texi b/doc/hyperdrive.texi
index 5c5050d37b..ec7c194f66 100644
--- a/doc/hyperdrive.texi
+++ b/doc/hyperdrive.texi
@@ -75,6 +75,7 @@ Installation
Usage
+* Install the gateway::
* Menu bar support::
* Hyperdrive menu command::
* Start/stop the gateway::
@@ -95,6 +96,10 @@ Usage
* Org-transclusion integration::
* Miscellaneous features::
+Start/stop the gateway
+
+* Advanced gateway customization::
+
Open a hyperdrive
* Directory view::
@@ -266,6 +271,7 @@ On the network it still may be there.
@end display
@menu
+* Install the gateway::
* Menu bar support::
* Hyperdrive menu command::
* Start/stop the gateway::
@@ -287,6 +293,21 @@ On the network it still may be there.
* Miscellaneous features::
@end menu
+@node Install the gateway
+@section Install the gateway
+
+Run @code{M-x hyperdrive-install} to download and install the gateway program
+(see @ref{hyper-gateway-ushin}):
+
+@deffn Command hyperdrive-install
+Download and install the gateway. Prompts for confirmation before
+downloading.
+@end deffn
+
+@deffn Command hyperdrive-cancel-install
+Cancel installation in progress.
+@end deffn
+
@node Menu bar support
@section Menu bar support
@@ -341,32 +362,43 @@ and in the ``Hyperdrive'' menu bar (see @ref{Menu bar
support}).
Start the gateway.
@end deffn
+@defopt hyperdrive-gateway-ready-hook
+Hook run when the gateway becomes responsive after @code{hyperdrive-start}.
+One of the default hooks, @code{hyperdrive-check-gateway-version}, will
+warn you if you're running an outdated version of the gateway.
+@end defopt
+
@deffn Command hyperdrive-stop
Stop the gateway.
@end deffn
-@defopt hyperdrive-gateway-process-type
-How to start and stop the gateway. By default, @code{hyperdrive.el} will
-autodetect the appropriate process type. If you have configured
-@uref{https://git.sr.ht/~ushin/hyper-gateway-ushin#how-do-i-run-hyper-gateway-ushin-as-a-background-process-on-gnulinux--systemd,
hyper-gateway-ushin
-to run as a systemd service}, then @code{hyperdrive.el} will automatically
-use @code{systemd} to manage the gateway. Otherwise, @code{hyperdrive.el} will
+@deffn Command hyperdrive-restart
+Restart the gateway.
+@end deffn
+
+@deffn Command hyperdrive-gateway-version
+Say the version of the gateway which is running.
+@end deffn
+
+@menu
+* Advanced gateway customization::
+@end menu
+
+@node Advanced gateway customization
+@subsection Advanced gateway customization
+
+@defopt hyperdrive-gateway-start-function
+Function run to start the gateway. By default, @code{hyperdrive.el} will
start the gateway as an Emacs subprocess.
@end defopt
-@defopt hyperdrive-gateway-command
-The command run to start the gateway as an Emacs subprocess. This
-option only takes effect when @code{hyperdrive-gateway-process-type} is
-set to @code{subprocess}.
+@defopt hyperdrive-gateway-stop-function
+Function run to stop the gateway.
@end defopt
-Alternatively, you can start the gateway manually by running:
-
-@example
-hyper-gateway-ushin run --writable true
-@end example
-
-For full usage instructions, see the
@uref{https://git.sr.ht/~ushin/hyper-gateway-ushin#usage, hyper-gateway-ushin
README}.
+@defopt hyperdrive-gateway-live-predicate
+Function run to check that the gateway process is live.
+@end defopt
@node Open a hyperdrive
@section Open a hyperdrive
@@ -1456,9 +1488,28 @@ DNS domains are checked for suspicious characters (see
You can adjust the following options in the customization interface by
running @code{M-x customize-group RET hyperdrive RET}:
+@defopt hyperdrive-gateway-program
+Name of executable to run when starting the gateway with
+@code{hyperdrive-gateway-start-function}. @code{hyperdrive-install} will
install
+the gateway to this file in @code{hyperdrive-gateway-directory}.
+@end defopt
+
+@defopt hyperdrive-gateway-directory
+Filesystem directory in which the gateway is expected to be found.
+@code{hyperdrive-install} will install the gateway to this location. When
+starting the gateway, if @code{hyperdrive-gateway-program} is not found in
+this directory, Emacs searches @code{PATH} for
@code{hyperdrive-gateway-program}.
+@end defopt
+
+@defopt hyperdrive-gateway-command-args
+Command line arguments passed to the gateway when starting the
+gateway with the default @code{hyperdrive-gateway-start-function}.
+@end defopt
+
@defopt hyperdrive-gateway-port
@code{hyperdrive.el} will send HTTP requests to the gateway on this port.
-Defaults to @code{4973}.
+Defaults to @code{4973}. The default @code{hyperdrive-gateway-start-function}
+will start the gateway on this port.
@end defopt
@defopt hyperdrive-persist-location
