Merge pull request #242 from josephmturner/document-network-extensions

Improve/correct network extension documentation

NEWS

@@ -2,14 +2,12 @@
 
   - Features ::
 
-    Allows for a transclusion workflow with hyper:// links (see
-    hyperdrive.el) or http:// links. Splitting the org-transclusion-add
-    into two parts enables functions in org-transclusion-add-functions
-    to be asynchronous. With this change, content can be transcluded
-    over a network, using http://, hyper://, or other protocols.
-
-    For a proof-of-concept integration with hyperdrive.el, see this file:
-    https://git.sr.ht/~ushin/hyperdrive.el/tree/org-transclusion/item/hyperdrive-org-transclusion.el.
+    Transclude content over network protocols like http:// (with
+    org-transclusion-http: https://git.sr.ht/ushin/org-transclusion-http) and
+    hyper:// (with hyperdrive-org-transclusion:
+    https://git.sr.ht/~ushin/hyperdrive-org-transclusion).  Splitting
+    org-transclusion-add into two parts enables functions in
+    org-transclusion-add-functions to be asynchronous.
 
     - chg: #213 Allow making transclusion links from any protocol link
     - refactor: #209 Split -add-payload from -add to enable async transclusion

README.org

@@ -73,7 +73,7 @@ Main Features:
 
 - Work with any text file such as program source code, plain text, Markdown, or other Org files
 
-- With version 1.4, a transclusion works with hyper:// links (see [[https://git.sr.ht/~ushin/hyperdrive.el][hyperdrive.el]]) or http:// links. Splitting the org-transclusion-add into two parts enables  functions in org-transclusion-add-functions to be asynchronous. With this change, content can be transcluded over a network, using http://, hyper://, or other protocols. For a proof-of-concept integration with hyperdrive.el, see [[https://git.sr.ht/~ushin/hyperdrive.el/tree/org-transclusion/item/hyperdrive-org-transclusion.el][this file]].
+- With version 1.4, transclude content over network protocols like ~http://~ (with [[https://git.sr.ht/~ushin/org-transclusion-http][org-transclusion-http]]) and ~hyper://~ (with [[https://git.sr.ht/~ushin/hyperdrive-org-transclusion][hyperdrive-org-transclusion]]).  Splitting ~org-transclusion-add~ into two parts enables functions in ~org-transclusion-add-functions~ to be asynchronous.
 
 - Keep the file system clear of the copies of text content -- Org-transclusion tries hard to save only the links to the file system
 

docs/org-transclusion-manual.org

@@ -203,18 +203,19 @@ For the =:only-contents= property, refer to sub-section [[#filtering-org-element
 
 Version 1.4 includes changes which make it possible for asynchronously
 transclude content, e.g., over a network.  To transclude content via
-=http://=, first install [[https://git.sr.ht/~ushin/org-transclusion-http][org-transclusion-http]], then run ~M-x
-org-transclusion-add~ on the following link to transclude the HTML
-element with the "#emacs" id:
+=http://=, first install the ~org-transclusion-http~ extension (see
+[[#extensions][extensions]]), then run ~M-x org-transclusion-add~ on the following link
+to transclude the HTML element with the "#emacs" id:
 
 #+begin_example
 #+transclude: [[https://ushin.org/software.html#emacs]]
 #+end_example
 
-To transclude content via =hyper://=, first install [[https://ushin.org/hyperdrive/hyperdrive-manual.org][hyperdrive.el]], then
-run ~M-x org-transclusion-add~ on the following link to transclude the
-the Org heading with the property ~CUSTOM_ID: emacs~ inside the
-~/software.org~ file inside the USHIN hyperdrive:
+To transclude content via =hyper://=, first install the
+~hyperdrive-org-transclusion~ extension (see [[#extensions][extensions]]), then run ~M-x
+org-transclusion-add~ on the following link to transclude the Org
+heading with the property ~CUSTOM_ID: emacs~ inside the ~/software.org~
+file inside the USHIN hyperdrive:
 
 #+begin_example
 #+transclude: [[hyper://aaj45d88g4eenu76rpmwzjiabsof1w8u6fufq6oogyhjk1ubygxy/software.org#%3A%3A%23emacs]]
@@ -563,11 +564,11 @@ This feature is provided as an [[#extensions][extension]] (default off).
 #+transclude: [[file:../test/source-html-no-ext]]
 #+end_example
 
-Since it's not currently possible to add anchor links to local =file:=
-Org links, HTML transclusions always render the entire document as
-Org.  However, packages which transclude HTML documents over a
-network, such as [[https://git.sr.ht/~ushin/hyperdrive.el][hyperdrive.el]] and [[https://git.sr.ht/~ushin/org-transclusion-http][org-transclusion-http]], are able to
-render specific HTML elements by tag.
+Since it's not currently possible to add anchor links to local =file:= Org links,
+HTML transclusions always render the entire document as Org.  However, packages
+which transclude HTML documents over a network protocol that supports link
+fragments, such as [[https://git.sr.ht/~ushin/hyperdrive-org-transclusion][hyperdrive-org-transclusion]] and [[https://git.sr.ht/~ushin/org-transclusion-http][org-transclusion-http]], are
+able to render specific HTML elements by tag (see [[#network-transclusion][subsection]]).
 
 ** Extensions
 :PROPERTIES:
@@ -588,11 +589,12 @@ If you use ~customize~, the features are loaded automatically. Note that it does
 If you do not use ~customize~ (e.g. Doom), you may need to explicitly require an extension. For example, to activate ~org-transclusion-indent-mode~, you might need to add something like this in your configuration file.
 
  #+BEGIN_SRC emacs-lisp
- ;; Ensure that load-path to org-transclusion is already added
- ;; If you installed it with the built-in package.el, this should be already done.
- ;; (add-to-list  'load-path "path/to/org-transclusion/")
- (add-to-list 'org-transclusion-extensions 'org-transclusion-indent-mode)
- (require 'org-transclusion-indent-mode)
+   ;; Ensure that load-path to org-transclusion is already added
+   ;; If you installed it with the built-in package.el, this should be already done.
+   ;; (add-to-list  'load-path "path/to/org-transclusion/")
+   (with-eval-after-load 'org-transclusion
+     (add-to-list 'org-transclusion-extensions 'org-transclusion-indent-mode)
+     (require 'org-transclusion-indent-mode))
  #+END_SRC
 
 Currently, the following extensions are available.
@@ -602,14 +604,41 @@ Currently, the following extensions are available.
   Support org-indent-mode. Known limitation: when transcluded, the source will temporarily lose the indentation. When the transclusion is removed, the source will regain the indentation.
 
 - (on by default) ~org-transclusion-src-lines~ ::
+
   Add features for =:src= and =:lines= properties to =#+transclude=. It is meant for non-Org files such as program source and text files
 
 - (on by default) ~org-transclusion-font-lock~ ::
+
   Add font-lock for =#+transclude=. Org mode's standard syntax treats the combination of a =#+transclude:= keyword and a link used by Org-transclusion as a keyword. This means it applies the ~org-meta-line~ face and the link part cannot be toggled as a normal link. This extension adds ~org-transclusion-keyword~ face to the keyword part and lets the link part to be treated as a normal link for ~org-toggle-link-display~.
 
 - (off by default) ~org-transclusion-html~ ::
+
   Transclude local HTML files by converting them to Org with Pandoc.
 
+- (off by default) ~org-transclusion-http~ ::
+
+  Asynchronously transclude remote HTML files (and other file types)
+  over HTTP.  To use this feature, first install [[https://git.sr.ht/~ushin/org-transclusion-http][org-transclusion-http]]
+  and then add the following snippet to your configuration:
+
+#+BEGIN_SRC emacs-lisp
+  (with-eval-after-load 'org-transclusion
+    (add-to-list 'org-transclusion-extensions 'org-transclusion-http)
+    (require 'org-transclusion-http))
+#+END_SRC
+
+- (off by default) ~hyperdrive-org-transclusion~ ::
+
+  Asynchronously transclude remote hyperdrive files over HTTP.  To use this
+  feature, first install [[https://git.sr.ht/~ushin/hyperdrive-org-transclusion][hyperdrive-org-transclusion]] and then add the following
+  snippet to your configuration:
+
+#+BEGIN_SRC emacs-lisp
+  (with-eval-after-load 'org-transclusion
+    (add-to-list 'org-transclusion-extensions 'hyperdrive-org-transclusion)
+    (require 'hyperdrive-org-transclusion))
+#+END_SRC
+
 * Customizing
 
 #+vindex: org-transclusion-extensions

org-transclusion.el

@@ -59,7 +59,7 @@ Intended for :set property for `customize'."
   (when (featurep 'org-transclusion)
     (org-transclusion-load-extensions-maybe 'force)))
 
- (defcustom org-transclusion-extensions '(org-transclusion-src-lines org-transclusion-font-lock)
+(defcustom org-transclusion-extensions '(org-transclusion-src-lines org-transclusion-font-lock)
   "Extensions to be loaded with org-transclusion.el."
   :set #'org-transclusion-set-extensions
   :type