[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/org-transclusion c33f39988b: docs: add org-transclusion
|
From: |
ELPA Syncer |
|
Subject: |
[elpa] externals/org-transclusion c33f39988b: docs: add org-transclusion.texi |
|
Date: |
Wed, 18 Sep 2024 15:58:54 -0400 (EDT) |
branch: externals/org-transclusion
commit c33f39988b246ac042c7d3c93d508e56dd074a4f
Author: Noboru Ota <me@nobiot.com>
Commit: Noboru Ota <me@nobiot.com>
docs: add org-transclusion.texi
---
org-transclusion.texi | 1150 +++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 1150 insertions(+)
diff --git a/org-transclusion.texi b/org-transclusion.texi
new file mode 100644
index 0000000000..e0a96920ea
--- /dev/null
+++ b/org-transclusion.texi
@@ -0,0 +1,1150 @@
+\input texinfo @c -*- texinfo -*-
+@c %**start of header
+@setfilename org-transclusion.info
+@settitle Org-transclusion User Manual
+@documentencoding UTF-8
+@documentlanguage en
+@c %**end of header
+
+@copying
+Copyright (C) 2021 Free Software Foundation, 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
+@end copying
+
+@dircategory Emacs
+@direntry
+* Org-transclusion: (org-transclusion). Transclusion in Org mode.
+@end direntry
+
+@finalout
+@titlepage
+@title Org-transclusion User Manual
+@author Noboru Ota <me@@nobiot.com>
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@ifnottex
+@node Top
+@top Org-transclusion User Manual
+
+@paragraphindent asis
+
+This manual is for Org-transclusion version 1.3.x.
+
+Last updated: 05 April 2024.
+
+Org-transclusion lets you insert a copy of text content via a file link or ID
link within an Org file. It lets you have the same content present in different
buffers at the same time without copy-and-pasting it. Edit the source of the
content, and you can refresh the transcluded copies to the up-to-date state.
Org-transclusion keeps your files clear of the transcluded copies, leaving only
the links to the original content.@anchor{whatis}
+
+
+@insertcopying
+@end ifnottex
+
+@menu
+* Example Use Cases & Main Features::
+* Installation::
+* Getting Started::
+* Usage:: Features in detail
+* Customizing::
+* Known Limitations::
+* Credits::
+* Contributing::
+* Index - Features:: Key concepts & features
+* Index - Commands:: Interactive functions
+* Index - User Options:: Customizable variables & faces
+* GNU Free Documentation License::
+
+@detailmenu
+--- The Detailed Node Listing ---
+
+Usage
+
+* Org-transclusion mode, activate, and deactivate: Org-transclusion mode
activate and deactivate.
+* Org links supported::
+* Transclude over a network with @code{hyper//}, @code{http//}, etc.:
Transclude over a network with @code{hyper//} @code{http//} etc.
+* Control levels of headlines per transclusion::
+* Filter Org elements per transclusion::
+* Detach transclusion and copy source buffer::
+* Live-sync edit::
+* Transclude source file into src-block::
+* Transclude range of lines for text and source files::
+* Extensions::
+
+Filter Org elements per transclusion
+
+* Notes on excluding the headline element::
+
+Transclude range of lines for text and source files
+
+* @samp{lines} property to specify a range of lines::
+* @samp{end} property to specify a search term to dynamically look for the end
of a range::
+* @samp{thing-at-point} or @samp{thingatpt} property to specify a ``thing'' to
transclude from the source.: @samp{thing-at-point} or @samp{thingatpt} property
to specify a ``thing'' to transclude from the source.
+* Transclude HTML content with Pandoc::
+
+Customizing
+
+* Customizable filter to exclude certain Org elements::
+* Include the section before the first headline (Org file only)::
+* Faces & fringe bitmap::
+* Keybindings::
+
+Faces & fringe bitmap
+
+* Face for the @samp{#+transclude} keyword::
+* Faces for the fringes next to transcluded region and source region::
+
+Credits
+
+* Original idea by John Kitchin::
+* Text-Clone::
+
+@end detailmenu
+@end menu
+
+@node Example Use Cases & Main Features
+@chapter Example Use Cases & Main Features
+
+Here are some real use cases that users have shared with the author, including
his own.
+
+@table @asis
+@item Book writing
+You have a collection of notes. You can quickly transclude paragraphs and
sections from your notes and put together a draft. As transclusions are links,
it's easy to re-organize them into different sequences to see which way works
the best.
+
+@item Academic writing
+You have a collection of quotes and notes from your research and literature
review. Transclude relevant elements of quotes and notes into different papers.
You can keep your collection as the central repository of your research.
+
+@item Technical writing
+You write technical documents for software. Transclude relevant lines of code
into the document. As the code is only transcluded, you can keep the document
up-to-date as the code evolves.
+
+@item Project status reports
+You work on multiple projects at the same time and need to report to different
project managers. Transclude relevant parts of your work notes and logs into
respective project reports. You can keep a single collection of your work notes
and logs.
+@end table
+
+Main Features:
+
+@itemize
+@item
+Insert a copy of text content via a file link or ID link into an Org file
+
+@item
+Work with any text file such as program source code, plain text, Markdown, or
other Org files
+
+@item
+With version 1.4, transclude content over network protocols like
@code{http://} (with @uref{https://git.sr.ht/~ushin/org-transclusion-http,
org-transclusion-http}) and @code{hyper://} (with
@uref{https://git.sr.ht/~ushin/hyperdrive-org-transclusion,
hyperdrive-org-transclusion}). Splitting @code{org-transclusion-add} into two
parts enables functions in @code{org-transclusion-add-functions} to be
asynchronous.
+
+@item
+Keep the file system clear of the copies of text content -- Org-transclusion
tries hard to save only the links to the file system
+
+@item
+For Org files, use different headline levels from the source Org file
+
+@item
+For Org files, use filters to include only relevant elements (e.g. filter out
properties in the transclusions)
+
+@item
+For program source and plain text files, transclude a certain lines or
dynamically specify the from/to lines to keep the transclusion always
up-to-date with the evolving source files
+
+@item
+For program source files, transclude parts or whole code directly into Org's
source block to leverage the rich Org features including noweb style syntax
+
+@item
+Extend Org-transclusion with its extension framework
+@end itemize
+
+@node Installation
+@chapter Installation
+
+This package is available on:
+
+@itemize
+@item
+@uref{https://elpa.gnu.org/packages/org-transclusion.html, GNU ELPA} (releases
only; equivalent to MELPA-Stable)
+@item
+@uref{https://elpa.gnu.org/devel/org-transclusion.html, GNU-devel ELPA}
(unreleased development branch; equivalent to MELPA)
+@end itemize
+
+GNU ELPA should be already set up in your Emacs by default. If you wish to add
GNU-devel ELPA, simply add its URL to @code{package-archives} like this:
+
+@lisp
+(add-to-list 'package-archives
+ '("gnu-devel" . "https://elpa.gnu.org/devel/";) :append)
+@end lisp
+
+Refresh the archive with @code{M-x package-refresh-contents RET} and you can
do @code{M-x package-install RET org-transclusion} to install it.
Alternatively, you can use @code{package-list-packages}.
+
+After installation, you can start using Org-transclusion with no additional
configuration. Below are some example keybindings that can be put into your
Emacs configuration.
+
+@lisp
+(define-key global-map (kbd "<f12>") #'org-transclusion-add)
+(define-key global-map (kbd "C-n t") #'org-transclusion-mode)
+@end lisp
+
+For Doom users, you would need to do something like this below to install the
package and configure the keybindings.
+
+@lisp
+;; ~/.doom.d/package.el
+(package! org-transclusion)
+@end lisp
+
+@lisp
+;; ~/.doom.d/config.el
+(use-package! org-transclusion
+ :after org
+ :init
+ (map!
+ :map global-map "<f12>" #'org-transclusion-add
+ :leader
+ :prefix "n"
+ :desc "Org Transclusion Mode" "t" #'org-transclusion-mode))
+@end lisp
+
+@node Getting Started
+@chapter Getting Started
+
+@findex org-transclusion-add
+@findex org-transclusion-add-all
+@findex org-transclusion-make-from-link
+@findex org-transclusion-open-source
+@findex org-transclusion-move-to-source
+@findex org-transclusion-refresh
+@vindex org-transclusion-map
+
+The basic idea of Org-transclusion is simple: insert a copy of text content
via a file link or ID link within an Org file. This is an Org Mode version of
transclusion.
+
+To transclude content via a link, use one of the following commands:
+
+@itemize
+@item
+@code{org-transclusion-add}
+
+@item
+@code{org-transclusion-add-all}
+
+@item
+@code{org-transclusion-make-from-link}
+@end itemize
+
+For example, if you have an ID link in your Org file like this:
+
+@example
+[[id:20210501T171427.051019][Bertrand Russell]]
+@end example
+
+Simply type to add @samp{#+transclude:} in front of the link like the example
below.
+
+@example
+#+transclude: [[id:20210501T171427.051019][Bertrand Russell]]
+@end example
+
+Put your cursor somewhere on this keyword line and type @code{M-x
org-transclusion-add RET}, and you will see the text content that the ID points
to replace the whole line. If you have multiple links with a transclude
keyword, you can type @code{M-x org-transclusion-add-all RET} to add all
transclusions in the current buffer.
+
+Alternatively, you can also put cursor somewhere on the link and type
@code{M-x org-transclusion-make-from-link RET}. That will insert another line
with @code{#+transclusion:} keyword added in front of a copy of the original
link in the next empty line.
+
+The transcluded paragraphs will be visually marked with a vertical line ``| ''
in the fringe (on graphical display) or in the beginning of line (on a
text-only terminal) by default. The source (original) of the transcluded
paragraphs will be also visually marked with an overlay. The appearance of
these visual elements can be customized (refer to section @ref{Faces & fringe
bitmap}).
+
+The transcluded text is @strong{read-only} but you can copy it and export it
as normal text. Org-transclusion remembers where it has transcluded the text
from (its source buffer).
+
+You can call a number of useful commands with a single letter (by default).
For example, you can press @samp{o} to open the source buffer of the
transclusion at point, or @samp{O} (capital ``o'') to open and move to it.
Press @samp{g} to refresh the transclusion. Press @samp{e} to start live-sync
edit. For more detail, inspect the documentation of each command. Press
@samp{d} to remove the transcluded content, putting the original
@samp{#+transclude: [[id:id-of-the-content]]}.
+
+This single-letter-context-menu is defined in @code{org-transclusion-map}. The
default keybindings are shown below. Adapt them to your liking, especially if
you use Vim keybindings with Evil Mode, etc.
+
+@example
+key binding
+--- -------
+
+C-c Prefix Command
+TAB org-cycle
+D org-transclusion-demote-subtree
+O org-transclusion-move-to-source
+P org-transclusion-promote-subtree
+d org-transclusion-remove
+C-d org-transclusion-detach
+e org-transclusion-live-sync-start
+g org-transclusion-refresh
+o org-transclusion-open-source
+
+ † Also inherits ‘org-mode-map’ as of development version
1.1.1.0.20220106.203639
+ and planned to be part of 1.2.0
+
+@end example
+
+This should get you started with Org-transclusion. There are more options and
customizing options available for you to fine-tune the text content you
transclude. Explore the rest of the user manual and play with Org-transclusion
to get familiar with it.
+
+@node Usage
+@chapter Usage
+
+@menu
+* Org-transclusion mode, activate, and deactivate: Org-transclusion mode
activate and deactivate.
+* Org links supported::
+* Transclude over a network with @code{hyper//}, @code{http//}, etc.:
Transclude over a network with @code{hyper//} @code{http//} etc.
+* Control levels of headlines per transclusion::
+* Filter Org elements per transclusion::
+* Detach transclusion and copy source buffer::
+* Live-sync edit::
+* Transclude source file into src-block::
+* Transclude range of lines for text and source files::
+* Extensions::
+@end menu
+
+@node Org-transclusion mode activate and deactivate
+@section Org-transclusion mode, activate, and deactivate
+
+@cindex Activate / Deactivate
+@findex org-transclusion-mode
+@findex org-transclusion-activate
+@findex org-transclusion-deactivate
+@cindex Properties
+@cindex Property - :disable-auto
+@vindex org-transclusion-add-all-on-activate
+
+Org-transclusion is a local minor mode; however, you do not need to explicitly
call @code{org-transclusion-mode}. The minor mode is intended to be just a
convenient wrapper to let you easily toggle between @samp{activate} and
@samp{deactivate}.
+
+As you saw in the @ref{Getting Started, , Getting Started section} above,
calling @code{org-transclusion-add} or @code{org-transclusion-add-all} is
enough to add transclusions in your current buffer.
+
+The minor mode is automatically turned on locally for your current buffer
through one of these commands. All it does is to call
@code{org-transclusion-activate} to activate hooks and some other variables.
Their main purpose is to keep files in the filesystem clear of the transcluded
content.
+
+Turn off the minor mode or use @code{org-transclusion-deactivate}; you will
remove all the transclusions in the current buffer and clear the hooks and
other setup variables.
+
+If you prefer, you can use @code{org-transclusion-mode} as your entry command
for transclusion. When customizable variable
@code{org-transclusion-add-all-on-activate} is non-nil (it is @samp{t} by
default), turning on the minor mode calls the @code{org-transclusion-add-all}
command to attempt to add all transclusions automatically in the current buffer.
+
+You can control whether or not transclusions are to be added automatically per
transclude keyword. By default, @code{org-transclusion-add-all} (it is also
used by @code{org-transclusion-mode}) will work on every transclude keyword in
the buffer. Add @samp{:disable-auto} property to a keyword as shown in the
example below; @samp{add-all} skips transclude keywords with it.
+
+@example
+#+transclude: [[file:path/to/file.org]] :disable-auto
+@end example
+
+You can override the @samp{:disable-auto} property by manually calling
@code{org-transclusion-add} at point. There are various properties like
@samp{:disable-auto} to control each transclusion (refer to @ref{Index -
Features} for a list).
+
+@node Org links supported
+@section Org links supported
+
+@cindex Org Links Supported
+@cindex Property - :only-contents
+
+Transclusion has been tested to work for the following types of links:
+
+@itemize
+@item
+File link for an entire org file/buffer; e.g. @samp{[[file:~/org/file.org][My
Org Notes]]}
+@item
+File link with @samp{::*heading}
+@item
+File link with @samp{::#custom-id}
+@item
+File link with @samp{::name} for blocks (e.g. blocked quotations), tables, and
links
+@item
+File link with @samp{::dedicated-target}; this is intended for linking to a
paragraph. See below.
+@item
+ID link @samp{id:uuid}
+@item
+File link for non-org files (tested with @samp{.txt} and @samp{.md}); for
these, the whole buffer gets transcluded
+@end itemize
+
+@quotation Note
+Search-options @samp{::/regex/} and @samp{::number} do not work as intended.
+
+@end quotation
+
+
+For transcluding a specific paragraph, there are two main ways: Org Mode's
@uref{https://orgmode.org/manual/Internal-Links.html#Internal-Links,
dedicated-target} and @samp{:only-contents} property.
+
+For dedicated targets, the target paragraph must be identifiable by a
dedicated target with a @samp{<<paragraph-id>>}:
+
+@example
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+Suspendisse ac velit fermentum, sodales nunc in,
+tincidunt quam. <<paragraph-id>>
+@end example
+
+It is generally assumed that the @samp{paragraph-id} is placed after its
content, but it is not an absolute requirement; it can be in the beginning
(before the content) or in the middle of it.
+
+For the @samp{:only-contents} property, refer to sub-section @ref{Filter Org
elements per transclusion, , Filtering Org elements per transclusion}.
+
+@node Transclude over a network with @code{hyper//} @code{http//} etc
+@section Transclude over a network with @code{hyper://}, @code{http://}, etc.
+
+@cindex Links with hyper://, http://, and other protocols
+
+Version 1.4 includes changes which make it possible for asynchronously
+transclude content, e.g., over a network. To transclude content via
+@samp{http://}, first install the @code{org-transclusion-http} extension (see
+@ref{Extensions, , extensions}), then run @code{M-x org-transclusion-add} on
the following link
+to transclude the HTML element with the ``#emacs'' id:
+
+@example
+#+transclude: [[https://ushin.org/software.html#emacs]]
+@end example
+
+To transclude content via @samp{hyper://}, first install the
+@code{hyperdrive-org-transclusion} extension (see @ref{Extensions, ,
extensions}), then run @code{M-x
+org-transclusion-add} on the following link to transclude the Org
+heading with the property @code{CUSTOM_ID: emacs} inside the
@code{/software.org}
+file inside the USHIN hyperdrive:
+
+@example
+#+transclude:
[[hyper://aaj45d88g4eenu76rpmwzjiabsof1w8u6fufq6oogyhjk1ubygxy/software.org#%3A%3A%23emacs]]
+@end example
+
+@node Control levels of headlines per transclusion
+@section Control levels of headlines per transclusion
+
+@cindex Property - :level
+@findex org-transclusion-demote-subtree
+@findex org-transclusion-promote-subtree
+@findex org-transclusion-make-from-link
+
+When you transclude Org contents, you can specify a different headline level
than those of the source Org file.
+
+Use the @samp{:level} property with a value of single digit number from 1 to 9
like this example below.
+
+@example
+#+transclude: [[file:path/to/file.org::*Headline]] :level 2
+@end example
+
+The top level of the transcluded headline will be set to the value of
@samp{:level} property -- in this example, level 2 regardless of that in the
source. When the headline contains sub-headlines, they will be all
automatically promoted or demoted to align according to how many levels the top
of the subtree will move.
+
+When you transclude an entire Org file, it may contain multiple subtrees. In
such cases, the top-most level among the subtrees will be set according to the
@samp{:level} property; the rest of headlines in the buffer will align
accordingly.
+
+Other ways to control include the following.
+
+@table @asis
+@item @code{org-transclusion-make-from-link}
+Make a transclusion keyword from a link at point. If you pass a positive
number 1-9 with @samp{digit-argument} (e.g. prefix @code{M-x} with @code{C-2}
to pass ``2''), this function automatically puts the @samp{:level} property to
the resultant transclusion keyword.
+
+@item @code{org-transclusion-promote-subtree}
+Promote transcluded subtree at point. Mapped to ``P'' (capital ``p'') by
default in @code{org-transclusion-map}
+
+@item @code{org-transclusion-demote-subtree}
+Demote transcluded subtree at point. Mapped to ``D'' (capital ``d'') by
default in @code{org-transclusion-map}
+@end table
+
+@node Filter Org elements per transclusion
+@section Filter Org elements per transclusion
+
+@cindex Filters
+@vindex org-transclusion-exclude-elements
+@vindex org-transclusion-include-first-section
+@cindex Property - :only-contents
+
+You can control what elements to include in many different ways with using
various filters. The filters work in two layers: customizable variable and
properties per transclude keyword.
+
+The following two customizable variables are applicable to all transclusions
globally. You can think of them as the global default.
+
+@table @asis
+@item @samp{org-transclusion-exclude-elements}
+This customizable variable globally defines the exclusion filter for elements.
It is a list of symbols; the acceptable values can be seen by inspecting
@samp{org-element-all-elements}. The default is to exclude
@samp{property-drawer}.
+
+Refer also to the @ref{Customizable filter to exclude certain Org elements, ,
sub-section on this user option}.
+
+@item @samp{org-transclusion-include-first-section}
+This customizing variable globally defines whether or not to include the first
section of the source Org file. The first section is the part before the first
headline -- that's the section that typically contains @samp{#+title},
@samp{#+author}, and so on. Many people also write notes in it without adding
any headlines. Note that this user option's default is now @samp{t} (changed
from @samp{nil} as users seem to spend time to ``correct'' this issue). Turn it
to @samp{t} if you wish to t [...]
+
+Refer also to the @ref{Include the section before the first headline (Org file
only), , sub-section on this user option}.
+@end table
+
+In addition to the global user options above, you can fine-tune the default
exclusion filter per transclusion. Add following properties to transclusions
you wish to apply additional filters.
+
+@table @asis
+@item @samp{:only-contents}
+This property lets you exclude titles of headlines when you transclude a
subtree (headline); you transclude only the contents. When the subtree contains
sub-headlines, all the contents will be transcluded.
+
+Add @samp{:only-contents} without any value like this example:
+@end table
+
+@example
+#+transclude: [[file:path/to/file.org]] :only-contents
+@end example
+
+@table @asis
+@item @samp{:exclude-elements}
+This property lets you @strong{add} elements to exclude per transclusion on
top of the variable @code{org-transclusion-exclude-elements} defines. You
cannot @strong{remove} the ones defined by it; thus, it is intended that you
use the customizable variable as your global default and fine-tune it by the
property per transclusion.
+
+Add @samp{:exclude-elements} with a list of elements (each one as defined by
@samp{org-element-all-elements}) separated by a space inside double quotation
marks like this example:
+@end table
+
+@example
+#+transclude: [[file:path/to/file.org]] :exclude-elements "drawer keyword"
+@end example
+
+You can combine @samp{:only-contents} and @samp{:exclude-elements} to control
how you transclude a subtree. With these properties, you can really have great
control over what to include and exclude. It might be a little overwhelming at
a time but the changes via properties are easy to change -- simply press
@samp{d} to remove the transclusion, change the properties, and transclude
again to see a new result.
+
+@table @asis
+@item @samp{:expand-links}
+This property lets you expand the file names in links to absolute file names.
+@end table
+
+You can use the property in the following way.
+
+@example
+#+transclude: [[file:path/to/file.org]] :expand-links
+@end example
+
+As an exanmple if you have the content of this source file like this:
+
+@example
+This is a sample file link to [[file:test2.org]].
+@end example
+
+For this source file, you will get the following transclusion with the link
expanded @footnote{``Expanding'' in Emacs means converting a relative file name
to an absolute one. Info node `(elisp) File-Name-Expansion'}
+
+@example
+This is a sample file link to [[file:/home/user/org/test2.org]].
+@end example
+
+@menu
+* Notes on excluding the headline element::
+@end menu
+
+@node Notes on excluding the headline element
+@subsection Notes on excluding the headline element
+
+If you add @samp{headline} as a list of elements to exclude, you exclude
sub-headlines within your subtrees and you will still transclude the content of
the top-most headline of the subtrees.
+
+If you are transcluding only one subtree, this should be intuitive. If you
transclude a whole buffer, you might be transcluding multiple subtrees. In some
cases, this can be a little anti-intuitive. In the following examples, you will
be transcluding three subtrees -- even though the first headline levels are
lower than the third one, the first two are still the top-most level of their
own respective subtrees.
+
+@example
+** Headline 1
+ Content of Headline 1
+** Headline 2
+ Content of Headline 2
+* Headline 3
+ Content of Headline
+@end example
+
+@node Detach transclusion and copy source buffer
+@section Detach transclusion and copy source buffer
+
+@cindex Detach transclusion
+@findex org-transclusion-detach
+
+Detach is added to the current development version and is planned to be part
of release version 1.4.0, and thus available only in GNU-devel ELPA@. If you
are using GNU ELPA, it will be available with the release of 1.4.0.
+
+@itemize
+@item
+New command @code{org-transclusion-detach} can be used on the transclusion
+at point. It turns it into a normal, edtitable text content.
+
+You can undo this operation.
+
+In addition, you can press @code{C-d} directly on the transclusion at point
+to detach it. This is because the command is bound to @code{C-d} by
+default in 'org-transclusion-map'.
+
+@item
+@code{org-transclusion-refresh} now accepts universal argument such as
+@code{C-u M-x org-transclusion-refresh} and detaches the transclusion at
+point.
+
+You can undo this operation.
+
+@item
+@code{org-transclusion-add} now accepts universal argument such as 'C-u M-x
+org-transclusion-add' and copies the source content rather than
+transclude it.
+
+You can undo this operation.
+@end itemize
+
+@node Live-sync edit
+@section Live-sync edit
+
+@cindex Live-sync edit
+@findex org-transclusion-live-sync-start
+@findex org-transclusion-live-sync-exit
+@findex org-transclusion-live-sync-paste
+@vindex org-transclusion-live-sync-map
+
+@strong{Experimental.} You can start live-sync edit by pressing @samp{e} (by
default) on a text element you want to edit. This will call
@code{org-transclusion-live-sync-start} and put a colored overlay on top of the
region being live-synced and brings up another buffer that visits the source
file of the transclusion. The source buffer will also have a corresponding
overlay to the region being edited and live-synced.
+
+If you have other windows open, they will be temporarily hidden --
Org-transclusion will remembers your current window layout and attempts to
recover it when you exit live-sync edit.
+
+In the live-sync edit region, you can freely type to edit the transclusion or
source regions; they will sync simultaneously.
+
+Once done with editing, press @samp{C-c C-c} to exit live-sync edit. The key
is bound to @code{org-transclusion-live-sync-exit}. It will turn off the live
sync edit but keep the transclusion on.
+
+In the live-sync edit region, the normal @code{yank} command (@code{C-y}) is
replaced with a special command @code{org-transclusion-live-sync-paste}. This
command lets the pasted text inherit the text-properties of the transcluded
region correctly; the normal yank does not have this feature and thus causes
some inconvenience in live-sync edit. If you use vim keybindings (e.g.
@code{evil-mode}), it is advised that you review the default keybindings. You
can customize the local keybindings [...]
+
+@strong{Note}: During live-sync edit, file's content gets saved to the file
system as is -- i.e. the transcluded text will be saved instead of the
@samp{#+transclude:} keyword. If you kill buffer or quit Emacs, other hooks
will still remove the transclusion to keep the file clear of the transcluded
copy, leaving only the keyword in the file system.
+
+@lisp
+(substitute-command-keys "\\@{org-transclusion-live-sync-map@}")
+@end lisp
+
+@example
+key binding
+--- -------
+
+C-c Prefix Command
+C-y org-transclusion-live-sync-paste
+
+C-c C-c org-transclusion-live-sync-exit
+
+ † Also inherits ‘org-mode-map’
+@end example
+
+@node Transclude source file into src-block
+@section Transclude source file into src-block
+
+@cindex Transclude into Org's src-block
+@cindex Property - :src
+@cindex Property - :rest
+
+This feature is provided as an @ref{Extensions, , extension} (default on).
+
+You can transclude a source file into an Org's src block. Use the @samp{:src}
property and specify the language you would like to use like this:
+
+@example
+#+transclude: [[file:../../test/python-1.py]] :src python
+@end example
+
+The content you specify in the link gets wrapped into a src-block with the
language like this:
+
+@example
+#+begin_src python
+[... content of python-1.py]
+#+end_src
+@end example
+
+Use @samp{:rest} property to define additional properties you would like to
add for the src-block. The double quotation marks are mandatory for the
@samp{:rest} property.
+
+@example
+#+transclude: [[file:../../test/python-3.py]] :src python :rest ":session
:results value"
+@end example
+
+The source block will have the additional properties:
+@example
+#+begin_src python :session :results value
+@end example
+
+With since 2023-03-28 update, you can also use live-sync the source code
+transcluded into src-block. It is planned to be added to the next stable
+release.
+
+@node Transclude range of lines for text and source files
+@section Transclude range of lines for text and source files
+
+@cindex Transclude range of lines
+
+This feature is provided as an @ref{Extensions, , extension} (default on).
+
+When you transclude text files other than Org files, you can use following
properties to specify a range of lines to transclude.
+
+@menu
+* @samp{lines} property to specify a range of lines::
+* @samp{end} property to specify a search term to dynamically look for the end
of a range::
+* @samp{thing-at-point} or @samp{thingatpt} property to specify a ``thing'' to
transclude from the source.: @samp{thing-at-point} or @samp{thingatpt} property
to specify a ``thing'' to transclude from the source.
+* Transclude HTML content with Pandoc::
+@end menu
+
+@node @samp{lines} property to specify a range of lines
+@subsection @samp{:lines} property to specify a range of lines
+
+@cindex Property - :lines
+
+You can specify a range of lines to transclude from a source and text file.
Use the @samp{:lines} property like this.
+
+@example
+#+transclude: [[file:../../test/test.txt]] :lines 3-5
+@end example
+
+The rage is specified by the number ``3-5''; in this case, lines from 3 to 5,
both lines inclusive.
+
+To transclude a single line, have the the same number in both places (e.g.
10-10, meaning line 10 only).
+
+One of the numbers can be omitted. When the first number is omitted (e.g.
-10), it means from the beginning of the file to line 10. Likewise, when the
second number is omitted (e.g. 10-), it means from line 10 to the end of file.
+
+You can combine @samp{:lines} with @samp{:src} to transclude only a certain
range of source files (Example 1 below).
+
+For Org's file links, you can use
@uref{https://orgmode.org/manual/Search-Options.html, search options} specified
by the ``::'' (two colons) notation. When a search finds a line that includes
the string, the Org-transclude counts it as the starting line 1 for the
@samp{:lines} property.
+
+Example 1: This transcludes the four lines of the source file from the line
that contains string ``id-1234'' (including that line counted as line 1).
+@example
+#+transclude: [[file:../../test/python-1.py::id-1234]] :lines 1-4 :src python
+@end example
+
+Example 2: This transcludes only the single line that contains the line found
by the search option for text string ``Transcendental Ontology''
+@example
+#+transclude: [[file:../../test/test.txt::Transcendental Ontology]] :lines 1-1
+@end example
+
+@quotation Note
+Search-options @samp{::/regex/} and @samp{::number} do not work as intended.
+
+@end quotation
+
+@node @samp{end} property to specify a search term to dynamically look for the
end of a range
+@subsection @samp{:end} property to specify a search term to dynamically look
for the end of a range
+
+@cindex Property - :end
+
+You can add @samp{:end} property and specify the search term as its value.
Surround the search term with double quotation marks (mandatory).
+
+See Example 3 below. This transclusion will look for @samp{id-1234} as the
beginning line of the range as specified by the search option @samp{::id-1234}
in the link. With the @samp{:end} property, the search string @samp{id-1234 end
here} defines the end of the range. The search looks for @samp{id-123 end here}
in the body text. When found, the line one before the search string is used as
the ending line (thus, the transcluded range will not contain string
@samp{id-1234 end here}).
+
+You can also combine @samp{:lines} with @samp{:end}. It will only displace
the beginning, and the end part of the range (the second number after the
hyphen ``-'') is ignored. In the same example, the beginning of the range is
the next line after ``id-1234'' (line 2). Instead of transcluding all the text
until the end of the buffer, the end is defined by the @samp{:end} property
(one line before the string @samp{id-1234 end here} is found).
+
+Example 3:
+@example
+#+transclude: [[file:../../test/python-1.py::id-1234]] :lines 2- :src python
:end "id-1234 end here"
+@end example
+
+@node @samp{thing-at-point} or @samp{thingatpt} property to specify a
``thing'' to transclude from the source
+@subsection @samp{:thing-at-point} or @samp{:thingatpt} property to specify a
``thing'' to transclude from the source.
+
+@cindex Property - :thing-at-point
+@cindex Property - :thingatpt
+
+You can add @samp{:thing-at-point} or @samp{:thingatpt} (they are synonyms
with each other and both work) property to transclude a certain ``thing'' at
point to be transcluded. The following text elements have been tested to work:
+
+@itemize
+@item
+sentence
+@item
+paragraph
+@item
+defun
+@item
+sexp
+@end itemize
+
+@quotation Note
+As it stands now, you cannot use @samp{:thing-at-point} or @samp{:thingatpt}
to specify the precise beginning of the thing within a line -- it is always the
beginning of the line.
+
+@end quotation
+
+@quotation Note
+The definition of sentence is controlled by various variables in Emacs. It is
suggested to consult the documentation of function @code{sentence-end}. For
those who do not use double-space after a period (in the language this is
relevant), it is probably more intuitive to turn off customizing
@code{sentence-end-double-space}. The default behavior is this: ``Non-nil means
a single space does not end a sentence.''
+
+@end quotation
+
+See Example 4. When you have a text file for prose, you can use paragraph or
sentence as a ``thing'' to transclude. In this example, the beginning of the
source of transclude is specified by the search option with ``::Once upon a
time''. The two colons ``::'' immediately following the file name denote the
search option, which is a built-in Org syntax. Then the paragraph or sentence
beginning ``Once upon a time'' is transcluded. When the source file contains
multiple occurrences of ``Onc [...]
+
+Example 4:
+@example
+#+transclude: [[./things-at-point-dir/story.txt::Once upon a time][story]]
:thing-at-point paragraph
+
+#+transclude: [[./things-at-point-dir/story.txt::Once upon a time][story]]
:thingatpt sentence
+@end example
+
+You can combine @samp{:thing-at=point} (or @samp{:thingatpt}) with @samp{:src}
property so that the transcluded text is wrapped in Org's source block. Example
5 shows a way to do so. id:1234567890 is assumed to be present as comment in
the source file.
+
+Example 5:
+@example
+#+transclude: [[./things-at-point-dir/baz.el::id:1234567890][barz-baz-fuzz]]
:src elisp
+
+#+transclude: [[./things-at-point-dir/baz.el::foo][barz-baz-fuzz]] :src elisp
:thing-at-point sexp
+
+#+transclude: [[./things-at-point-dir/baz.el::id:1234567890][barz-baz-fuzz]]
:src elisp :thingatpt defun
+@end example
+
+@node Transclude HTML content with Pandoc
+@subsection Transclude HTML content with Pandoc
+
+@cindex Transclude HTML content with Pandoc
+
+If you have Pandoc installed, you can transclude local HTML files
+as Org documents.
+
+This feature is provided as an @ref{Extensions, , extension} (default off).
+
+@example
+#+transclude: [[file:../test/source-html-no-ext]]
+@end example
+
+Since it's not currently possible to add anchor links to local @samp{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 @uref{https://git.sr.ht/~ushin/hyperdrive-org-transclusion,
hyperdrive-org-transclusion} and
@uref{https://git.sr.ht/~ushin/org-transclusion-http, org-transclusion-http},
are
+able to render specific HTML elements by tag (see @ref{Transclude over a
network with @code{hyper//} @code{http//} etc, , subsection}).
+
+@node Extensions
+@section Extensions
+
+@cindex Extensions
+@vindex org-transclusion-extensions
+@cindex Extension - org-transclusion-indent-mode
+@cindex Extension - org-transclusion-src-lines
+@cindex Extension - org-transclusion-font-lock
+@cindex Extension - org-transclusion-html
+
+Org-transclusion provides a simple extension framework, where you can use
@code{customize} to selectively add new features.
+
+If you use @code{customize}, the features are loaded automatically. Note that
it does not ``unload'' the feature until you relaunch Emacs.
+
+If you do not use @code{customize} (e.g. Doom), you may need to explicitly
require an extension. For example, to activate
@code{org-transclusion-indent-mode}, you might need to add something like this
in your configuration file.
+
+@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/")
+(with-eval-after-load 'org-transclusion
+ (add-to-list 'org-transclusion-extensions 'org-transclusion-indent-mode)
+ (require 'org-transclusion-indent-mode))
+@end lisp
+
+Currently, the following extensions are available.
+
+@table @asis
+@item (off by default) @code{org-transclusion-indent-mode}
+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.
+
+@item (on by default) @code{org-transclusion-src-lines}
+Add features for @samp{:src} and @samp{:lines} properties to
@samp{#+transclude}. It is meant for non-Org files such as program source and
text files
+
+@item (on by default) @code{org-transclusion-font-lock}
+Add font-lock for @samp{#+transclude}. Org mode's standard syntax treats the
combination of a @samp{#+transclude:} keyword and a link used by
Org-transclusion as a keyword. This means it applies the @code{org-meta-line}
face and the link part cannot be toggled as a normal link. This extension adds
@code{org-transclusion-keyword} face to the keyword part and lets the link part
to be treated as a normal link for @code{org-toggle-link-display}.
+
+@item (off by default) @code{org-transclusion-html}
+Transclude local HTML files by converting them to Org with Pandoc.
+
+@item (off by default) @code{org-transclusion-http}
+Asynchronously transclude remote HTML files (and other file types)
+over HTTP@. To use this feature, first install
@uref{https://git.sr.ht/~ushin/org-transclusion-http, org-transclusion-http}
+and then add the following snippet to your configuration:
+@end table
+
+@lisp
+(with-eval-after-load 'org-transclusion
+ (add-to-list 'org-transclusion-extensions 'org-transclusion-http)
+ (require 'org-transclusion-http))
+@end lisp
+
+@table @asis
+@item (off by default) @code{hyperdrive-org-transclusion}
+Asynchronously transclude remote hyperdrive files over HTTP@. To use this
+feature, first install
@uref{https://git.sr.ht/~ushin/hyperdrive-org-transclusion,
hyperdrive-org-transclusion} and then add the following
+snippet to your configuration:
+@end table
+
+@lisp
+(with-eval-after-load 'org-transclusion
+ (add-to-list 'org-transclusion-extensions 'hyperdrive-org-transclusion)
+ (require 'hyperdrive-org-transclusion))
+@end lisp
+
+@node Customizing
+@chapter Customizing
+
+@vindex org-transclusion-extensions
+@vindex org-transclusion-add-all-on-activate
+@vindex org-transclusion-mode-lighter
+@vindex org-transclusion-open-source-display-action-list
+@vindex org-transclusion-after-add-functions
+@cindex Hooks - org-transclusion-after-add-functions
+
+You can customize settings in the customization group `org-transclusion'.
+
+@table @asis
+@item @code{org-transclusion-extensions}
+Defines extensions to be loaded with
+org-transclusion.el. If you use @code{customize}, the extensions are loaded by
it.
+If you don't, you likely need to explicitly use @code{require} to load them.
See @ref{Extensions, , sub-section}
+
+@item @code{org-transclusion-add-all-on-activate}
+Defines whether or not all the
+active transclusions (with @samp{t}) get automatically transcluded on minor
mode
+activation (@code{org-transclusion-mode}). This does not affect the manual
+activation when you directly call @code{org-transclusion-activate}
+
+@item @code{org-transclusion-exclude-elements}
+See @ref{Customizable filter to exclude certain Org elements, , sub-section}
+
+@item @code{org-transclusion-include-first-section}
+See @ref{Include the section before the first headline (Org file only), ,
sub-section}
+
+@item @code{org-transclusion-open-source-display-action-list}
+You can customize the
+way the @code{org-transclusion-open-source} function displays the source
buffer for
+the transclusion. You specify the ``action'' in the way defined by the built-in
+@code{display-buffer} function. Refer to its in-system documentation (with
@code{C-h f})
+for the accepted values. @code{M-x customize} can also guide you on what types
of
+values are accepted.
+
+@item @code{org-transclusion-mode-lighter}
+Define the lighter for Org-transclusion
+minor mode. The default is `` OT''.
+
+@item @code{org-transclusion-after-add-functions}
+Functions to be called after a
+transclusion content has been added. The hook runs after the content and the
+read-only text property have been added so it is not supposed to manipulate
+the content but to add further text properties. For example, it is used by
+the `org-transclusion-indent-mode' extension to support `org-indent-mode'.
+The functions are called with arguments beg and end, pointing to the
+beginning and end of the transcluded content.
+@end table
+
+The hook can be also used to activate @code{org-latex-preview} for
transclusions:
+
+@lisp
+(add-hook 'org-transclusion-after-add-functions
+ #'(lambda (_beg _end) (org-latex-preview '(16))))
+@end lisp
+
+@menu
+* Customizable filter to exclude certain Org elements::
+* Include the section before the first headline (Org file only)::
+* Faces & fringe bitmap::
+* Keybindings::
+@end menu
+
+@node Customizable filter to exclude certain Org elements
+@section Customizable filter to exclude certain Org elements
+
+@vindex org-transclusion-exclude-elements
+
+Set customizable variable @code{org-transclusion-exclude-elements} to define
which elements to be @strong{excluded} in the transclusion.
+
+The filter works for all supported types of links within an Org file when
transcluding an entire Org file, and parts of it (headlines, custom ID, etc.).
There is no filter for non-Org files.
+
+It is a list of symbols, and the default is @samp{(property-drawer)}. The
accepted values are the ones defined by @code{org-element-all-elements} (Org's
standard set of elements; refer to its documentation for an exhaustive list).
+
+You can also fine-tune the exclusion filter per transclusion. Refer to the
sub-section on @ref{Filter Org elements per transclusion, , filtering Org
elements per transclusion}.
+
+@node Include the section before the first headline (Org file only)
+@section Include the section before the first headline (Org file only)
+
+@vindex org-transclusion-include-first-section
+
+You can include the first section (section before the first headline) of an
Org file. It is toggled via customizable variable
@code{org-transclusion-include-first-section}. Its default value is @samp{t}.
Set it to @samp{t} (or non-nil) to transclude the first section. It also works
when the first section is followed by headlines.
+
+@node Faces & fringe bitmap
+@section Faces & fringe bitmap
+
+@vindex org-transclusion-keyword
+@vindex org-transclusion-source-fringe
+@vindex org-transclusion-fringe
+@vindex org-transclusion-source
+@vindex org-transclusion-source-edit
+@vindex org-transclusion
+@vindex org-transclusion-edit
+@vindex org-transclusion-fringe-bitmap
+
+@menu
+* Face for the @samp{#+transclude} keyword::
+* Faces for the fringes next to transcluded region and source region::
+@end menu
+
+@node Face for the @samp{#+transclude} keyword
+@subsection Face for the @samp{#+transclude} keyword
+
+This feature is provided as an @ref{Extensions, , extension} (default on).
+
+@table @asis
+@item @code{org-transclusion-keyword}
+You can set your own face to the @samp{#+transclude} keyword with using the
@code{org-transclusion-keyword} face.
+@end table
+
+@node Faces for the fringes next to transcluded region and source region
+@subsection Faces for the fringes next to transcluded region and source region
+
+If the fringes that indicate transcluding and source regions are not visible
in your system (e.g. Doom), try adding background and/or foreground colors to
these custom faces.
+
+@itemize
+@item
+@code{org-transclusion-source-fringe}
+@item
+@code{org-transclusion-fringe}
+@end itemize
+
+To customize a face, it's probably the easiest to use @code{M-x
customize-face}. If you want to use Elisp for some reason (e.g. on Doom),
something like this below should set faces. Experiment with the colors of your
choice. By default, the faces above have no values.
+
+@lisp
+(set-face-attribute
+ 'org-transclusion-fringe nil
+ :foreground "green"
+ :background "green")
+@end lisp
+
+For colors, where ``green'' is, you can also use something like ``#62c86a''
(Emacs calls it ``RGB triple''; you can refer to in-system manual Emacs >
Colors). You might also like to refer to a list of currently defined faces in
your Emacs by @code{list-faces-display}.
+
+Other faces:
+
+The default for faces @code{org-transclusion} and
@code{org-transclusion-source} is no color or any other specification
(transparent). An intended use of these faces is when you use packages such as
@code{org-indent-mode} or @code{org-modern}, which might override the fringe
@code{org-transclusion} places. To make the translusion and its source visible,
you might like to put some background color to source and transclusion.
+
+@table @asis
+@item @code{org-transclusion-source}
+The default is no color specification (transparent).
+@item
+@code{org-transclusion-source-edit}
+@item @code{org-transclusion}
+The default is no color specification (transparent).
+@item
+@code{org-transclusion-edit}
+@item @code{org-transclusion-fringe-bitmap}
+It is used for the fringe that indicates the transcluded region. It works only
in on a graphical display (not on a text-only terminal).
+@end table
+
+@node Keybindings
+@section Keybindings
+
+@vindex org-transclusion-map
+@vindex org-transclusion-live-sync-map
+
+@itemize
+@item
+@code{org-transclusion-map}
+@end itemize
+@example
+key binding
+--- -------
+
+C-c Prefix Command
+TAB org-cycle
+D org-transclusion-demote-subtree
+O org-transclusion-move-to-source
+P org-transclusion-promote-subtree
+d org-transclusion-remove
+C-d org-transclusion-detach
+e org-transclusion-live-sync-start
+g org-transclusion-refresh
+o org-transclusion-open-source
+
+ † Also inherits ‘org-mode-map’ as of development version
1.1.1.0.20220106.203639
+ and planned to be part of 1.2.0
+@end example
+
+
+@itemize
+@item
+@code{org-transclusion-live-sync-map}
+@end itemize
+@example
+key binding
+--- -------
+
+C-c Prefix Command
+C-y org-transclusion-live-sync-paste
+
+C-c C-c org-transclusion-live-sync-exit
+
+ † Also inherits ‘org-mode-map’
+@end example
+
+@node Known Limitations
+@chapter Known Limitations
+
+Note this section is still incomplete, not exhaustive for ``known''
limitations.
+
+@itemize
+@item
+Org link's search-options @samp{::/regex/} and @samp{::number} do not work as
intended.
+
+@item @code{org-transclusion-live-sync-start} does not support all Org elements
+For transclusions of Org elements or buffers, live-sync works only on the
following elements:
+@samp{center-block}, @samp{drawer}, @samp{dynamic-block},
@samp{latex-environment}, @samp{paragraph}, @samp{plain-list},
@samp{quote-block}, @samp{special-block}, @samp{table}, and @samp{verse-block}.
+
+It is known that live-sync does not work for the other elements; namely:
+@samp{comment-block}, @samp{export-block}, @samp{example-block},
@samp{fixed-width}, @samp{keyword}, @samp{src-block}, and
@samp{property-drawer}.
+
+More technical reason for this limitation is documented in the docstring of
function @code{org-transclusion-live-sync-enclosing-element}.
+
+Work is in progress to lift this limitation but I'm still experimenting
different ideas.
+
+@item @code{org-indent-mode} may not work well with Org-transclusion
+A new extension has been added to support @code{org-indent-mode} Refer to
@ref{Extensions, , this section}.
+
+@item Doom's customization may interfere with Org-transclusion
+Refer to issue @uref{https://github.com/nobiot/org-transclusion/issues/52,
#52}. The symptom is that in Doom you get an error message that includes this:
``progn: ‘recenter’ing a window that does not display current-buffer.'' Adding
this in your configuration has been reported to fix the issue:
+
+@code{(advice-remove 'org-link-search '+org--recenter-after-follow-link-a)}
+
+It is probably rather drastic a measure. I will appreciate it if you find a
less drastic way that works. Thank you.
+
+@item Org refile does not work ``properly'' on the transcluded headlines
+Refer to issue @uref{https://github.com/nobiot/org-transclusion/issues/20,
#20}. I don't intend to support this -- refile the source, not the transcluded
copy.
+
+@item Undo detach does not add the overlay back on the source
+This should not break any feature. You can safely refresh the transclusion and
recover the source overlay. You can also safely open or moved to the source
while the source overlay is not present.
+
+@item
+For @samp{:thing-at-point} or @samp{:thingatpt}, you cannot use them to
specify the precise beginning of the thing within a line -- it is always the
beginning of the line.
+@end itemize
+
+@node Credits
+@chapter Credits
+
+@menu
+* Original idea by John Kitchin::
+* Text-Clone::
+@end menu
+
+@node Original idea by John Kitchin
+@section Original idea by John Kitchin
+
+@uref{https://github.com/alphapapa/transclusion-in-emacs#org-mode}
+
+@quotation
+@{O@} transcluding some org-elements in multiple places
+@emph{[2016-12-09 ven.] } John Kitchin asks:
+
+I have an idea for how I could transclude “copies” or links to org-elements in
multiple places and keep them up to date. A prototypical example of this is I
have a set of org-contacts in one place, and I want to create a new list of
people for a committee in a new place made of “copies” of the contact
headlines. But I do not really want to duplicate the headlines, and if I modify
one, I want it reflected in the other places. I do not want just links to those
contacts, because then I can [...]
+
+This idea was inspired by @uref{https://github.com/gregdetre/emacs-freex}.
+
+The idea starts with creating (wait for it…) a new link ;) In a document where
I want to transclude a headline, I would enter something like:
+
+transclude:some-file.org::*headline title
+
+Then, I would rely on the font-lock system to replace that link with the
headline and its contents (via the :activate-func link property), and to put an
overlay on it with a bunch of useful properties, including modification hooks
that would update the source if I change the the element in this document, and
some visual indication that it is transcluded (e.g. light gray
background/tooltip).
+
+I would create a kill-buffer hook function that would replace that transcluded
content with the original link. A focus-in hook function would make sure the
transcluded content is updated when you enter the frame. So when the file is
not open, there is just a transclude link indicating what should be put there,
and when it is open, the overlay modification hooks and focus hook should
ensure everything stays synchronized (as long as external processes are not
modifying the contents).
+
+It seems like this could work well for headlines, and named tables, src
blocks, and probably any other element that can be addressed by a name/ID@.
+
+@end quotation
+
+@node Text-Clone
+@section Text-Clone
+
+@samp{text-clone.el} is an extension of text-clone functions written as part
of GNU Emacs in @samp{subr.el}. The first adaption to extend text-clone
functions to work across buffers was published in StackExchange by the user
named Tobias in March 2020. It can be found at
@uref{https://emacs.stackexchange.com/questions/56201/is-there-an-emacs-package-which-can-mirror-a-region/56202#56202}.
The text-clone library takes this line of work further.
+
+@node Contributing
+@chapter Contributing
+
+@itemize
+@item
+Get involved in a discussion in
@uref{https://org-roam.discourse.group/t/prototype-transclusion-block-reference-with-emacs-org-mode/830,
Org-roam forum} (the package is originally aimed for its users, the author
included)
+
+@item
+Create issues, discussion, and/or pull requests. All welcome.
+@end itemize
+
+Org-transclusion is part of GNU ELPA and thus copyrighted by the
@uref{http://fsf.org, Free Software Foundation} (FSF). This means that anyone
who is making a substantive code contribution will need to ``assign the
copyright for your contributions to the FSF so that they can be included in GNU
Emacs'' (@uref{https://orgmode.org/contribute.html#copyright, Org Mode
website}).
+
+Thank you.
+
+@node Index - Features
+@appendix Index - Features
+
+@printindex cp
+
+@node Index - Commands
+@appendix Index - Commands
+
+@printindex fn
+
+@node Index - User Options
+@appendix Index - User Options
+
+@printindex vr
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+
+@include fdl.texi
+
+@bye
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [elpa] externals/org-transclusion c33f39988b: docs: add org-transclusion.texi,
ELPA Syncer <=