branch: externals/org-transclusion
commit 664b973d0d2c6697be704e0703897865c281a0cd
Author: Noboru Ota <m...@nobiot.com>
Commit: Noboru Ota <m...@nobiot.com>
doc:WIP:testing doc generation of ELPA
When org-transclusion.texi is missing, README.org is exported to *.texi
file. ELPA then generates *.info and *.html from it. You can define "*" in
README.org with `#+export_file_name:` meta data. It is not clear what
happens
when a filename `org-transclusion.texi` already present in the repository?
In this commit, org-transclusion.org and org-transclusion.texi is present
with
license preambles. README.org is specified as the doc by ELPA setting.
Which file is used for the *.html and *.info?
---
.elpaignore | 5 +-
README.org | 15 -
README.org => org-transclusion.org | 85 +--
org-transclusion.texi | 751 +++++++++++++++++++++
.../test-clone/test-clone-1.txt | 0
.../test-clone/test-clone-2.txt | 0
.../test-clone/test-clone-original.txt | 0
.../test-clone/test-text-clone.el.test | 0
{docs => text-clone-docs}/text-clone.md | 0
9 files changed, 775 insertions(+), 81 deletions(-)
diff --git a/.elpaignore b/.elpaignore
index e2b74e8..64e8de6 100644
--- a/.elpaignore
+++ b/.elpaignore
@@ -1,5 +1,6 @@
test
-docs
+docs/*.md
resources
Makefile
-.gitignore
\ No newline at end of file
+.gitignore
+text-clone-docs
\ No newline at end of file
diff --git a/README.org b/README.org
index bca3ad3..399dac1 100644
--- a/README.org
+++ b/README.org
@@ -1,16 +1,5 @@
#+title: Org-transclusion
#+author: Noboru Ota <m...@nobiot.com>
-#+language: en
-#+export_file_name: org-transclusion.texi
-#+texinfo_dir_category: Emacs
-#+texinfo_dir_title: Org-transclusion: (org-transclusion).
-#+texinfo_dir_desc: Transclusion in Org mode
-#+property: LOGGING nil
-
-#+html: <a href="https://www.gnu.org/software/emacs/";><img alt="GNU Emacs"
src="https://img.shields.io/static/v1?logo=gnuemacs&logoColor=fafafa&label=Made%20for&message=GNU%20Emacs&color=7F5AB6&style=flat"/></a>
-#+html: <a href="http://elpa.gnu.org/packages/org-transclusion.html";><img
alt="GNU ELPA" src="https://elpa.gnu.org/packages/org-transclusion.svg"/></a>
-#+html: <a href="http://elpa.gnu.org/devel/org-transclusion.html";><img
alt="GNU-devel ELPA" src="https://elpa.gnu.org/devel/org-transclusion.svg"/></a>
-#+html: <img alt="GPLv3"
src="https://img.shields.io/badge/License-GPLv3-blue.svg";>
# Note: I use the readme template that alphapapa shares on his GitHub repo
<https://github.com/alphapapa/emacs-package-dev-handbook#template>. It works
with the org-make-toc <https://github.com/alphapapa/org-make-toc> package,
which automatically updates the table of contents.
@@ -639,10 +628,6 @@ Thank you.
Org-transclusion is licensed under a GPLv3 license. For a full copy of the
license, refer to [[./LICENSE][LICENSE]].
-This documentation is licensed under the GNU Free Documentation License,
version 1.3.
-
-#+include "./docs/fdl.texi"
-
# Local Variables:
# eval: (require 'org-make-toc)
# before-save-hook: org-make-toc
diff --git a/README.org b/org-transclusion.org
similarity index 87%
copy from README.org
copy to org-transclusion.org
index bca3ad3..86f91ce 100644
--- a/README.org
+++ b/org-transclusion.org
@@ -5,6 +5,8 @@
#+texinfo_dir_category: Emacs
#+texinfo_dir_title: Org-transclusion: (org-transclusion).
#+texinfo_dir_desc: Transclusion in Org mode
+#+texinfo: @insertcopying
+
#+property: LOGGING nil
#+html: <a href="https://www.gnu.org/software/emacs/";><img alt="GNU Emacs"
src="https://img.shields.io/static/v1?logo=gnuemacs&logoColor=fafafa&label=Made%20for&message=GNU%20Emacs&color=7F5AB6&style=flat"/></a>
@@ -12,41 +14,26 @@
#+html: <a href="http://elpa.gnu.org/devel/org-transclusion.html";><img
alt="GNU-devel ELPA" src="https://elpa.gnu.org/devel/org-transclusion.svg"/></a>
#+html: <img alt="GPLv3"
src="https://img.shields.io/badge/License-GPLv3-blue.svg";>
-# Note: I use the readme template that alphapapa shares on his GitHub repo
<https://github.com/alphapapa/emacs-package-dev-handbook#template>. It works
with the org-make-toc <https://github.com/alphapapa/org-make-toc> package,
which automatically updates the table of contents.
-
-* Contents :noexport:
+* COPYING
:PROPERTIES:
-:TOC: :include siblings
-:END:
-:CONTENTS:
-- [[#introduction][Introduction]]
-- [[#installation][Installation]]
-- [[#getting-started][Getting Started]]
-- [[#usage][Usage]]
- - [[#org-transclusion-mode-activate-and-deactivate][Org-transclusion mode,
activate, and deactivate]]
- - [[#org-links-supported][Org links supported]]
- - [[#controlling-levels-of-headlines-in-transclusions][Controlling levels of
headlines in transclusions]]
- - [[#filtering-org-elements-per-transclusion][Filtering Org elements per
transclusion]]
- - [[#live-sync-edit][Live-sync edit]]
- - [[#transclude-source-file-into-src-block][Transclude source file into
src-block]]
- - [[#transclude-range-of-lines-for-text-and-source-files][Transclude range
of lines for text and source files]]
- - [[#extensions---support-org-indent-mode][Extensions - Support
org-indent-mode]]
-- [[#customizing][Customizing]]
- - [[#customizable-filter-to-exclude-certain-org-elements][Customizable
filter to exclude certain Org elements]]
- - [[#include-the-section-before-the-first-headline-org-file-only][Include
the section before the first headline (Org file only)]]
- - [[#faces--fringe-bitmap][Faces & fringe bitmap]]
- - [[#face-for-the-transclude-keyword][Face for the #+transclude keyword]]
- -
[[#faces-for-the-fringes-next-to-transcluded-region-and-source-region][Faces
for the fringes next to transcluded region and source region]]
- - [[#keybindings][Keybindings]]
-- [[#known-limitations][Known Limitations]]
-- [[#credits][Credits]]
- - [[#original-idea-by-john-kitchin][Original idea by John Kitchin]]
- - [[#text-clone][Text-Clone]]
-- [[#development][Development]]
- -
[[#notes-on-pull-requests-and-free-software-foundation-fsf-copy-right-assignment][Notes
on pull requests and Free Software Foundation (FSF) copy right assignment]]
-- [[#license][License]]
+:COPYING: t
:END:
+Copyright (C) 2021 Free Software Foundation, Inc.
+
+#+begin_quote
+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_quote
+
+
* Introduction
:PROPERTIES:
:CUSTOM_ID: introduction
@@ -55,31 +42,6 @@
Transclusion [fn:1:https://en.wikipedia.org/wiki/Transclusion] is the ability
to include content from one file into another by reference. Org-transclusion is
an Org Mode version of it. It lets you insert a copy of text content via a file
link or ID link within an Org file. It is my take on the
[[#original-idea-by-john-kitchin][idea by John Kitchin]].
-When I start writing a long-form material, I want to begin with looking
through my notes and assemble relevant ones to form a basis of the first draft
quickly. As I organise my notes in a repository, I also want to avoid having
multiple copies of notes flying around.
-
-Transclusion helps me do this.
-
-I am dabbling in the Zettelkasten
[fn:2:https://writingcooperative.com/zettelkasten-how-one-german-scholar-was-so-freakishly-productive-997e4e0ca125]
method with using Org-roam [fn:3:https://www.orgroam.com/] to feed my ideas
into the repository. As such, although Org-transclusion is a standalone
package, I would like to keep workflow seamless between Org-roam and
Org-transclusion.
-
-#+caption: Animation to show creation of a transclusion from an ID link
-[[./resources/2021-09-10-transclusion.gif]]
-
-#+caption: Animation to show live sync from transclusion to source
-[[./resources/2021-05-01-org-transclusion-0.1.0-live-sync.gif]]
-
-#+caption: Video demo on v0.2.1 on YouTube demonstrating new features to
transclude a source file into a src-block and function to specify a range of
text/source line
-[[./resources/demo9-title.png]]
-
-- Recent videos
-
- + [[https://youtu.be/ueaPiA622wA][Video demo on v0.2.1 on YouTube]]
demonstrating new features to transclude a source file into a src-block and
function to specify a range of text/source lines
-
- + [[https://youtu.be/idlFzWeygwA][Video demo on v0.2.0 on YouTube]]
featuring minor breaking changes and new transclusion filters
-
-- Older videos
-
- + [[https://youtu.be/idlFzWeygwA][Video demo on v0.1.1 on YouTube]]
featuring basic syntax and live-sync edit
-
* Installation
:PROPERTIES:
:TOC: :depth 0
@@ -641,11 +603,6 @@ Org-transclusion is licensed under a GPLv3 license. For a
full copy of the licen
This documentation is licensed under the GNU Free Documentation License,
version 1.3.
-#+include "./docs/fdl.texi"
+* GNU Free Documentation License
-# Local Variables:
-# eval: (require 'org-make-toc)
-# before-save-hook: org-make-toc
-# org-export-with-properties: ()
-# org-export-with-title: t
-# End:
+#+texinfo: @include docs/fdl.texi
diff --git a/org-transclusion.texi b/org-transclusion.texi
new file mode 100644
index 0000000..3d9142d
--- /dev/null
+++ b/org-transclusion.texi
@@ -0,0 +1,751 @@
+\input texinfo @c -*- texinfo -*-
+@c %**start of header
+@setfilename org-transclusion.info
+@settitle Org-transclusion
+@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
+@author Noboru Ota <me@@nobiot.com>
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top Org-transclusion
+
+@insertcopying
+
+@end ifnottex
+
+@menu
+* Introduction::
+* Installation::
+* Getting Started::
+* Usage::
+* Customizing::
+* Known Limitations::
+* Credits::
+* Development::
+* License::
+* 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::
+* Controlling levels of headlines in transclusions::
+* Filtering Org elements per transclusion::
+* Live-sync edit::
+* Transclude source file into src-block::
+* Transclude range of lines for text and source files::
+* Extensions - Support @samp{org-indent-mode}::
+
+Filtering Org elements per transclusion
+
+* Combining @samp{only-contents} and @samp{exclude-elements}::
+* 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::
+
+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::
+
+Development
+
+* Notes on pull requests and Free Software Foundation (FSF) copy right
assignment::
+
+@end detailmenu
+@end menu
+
+@node Introduction
+@chapter Introduction
+
+Transclusion @footnote{@uref{https://en.wikipedia.org/wiki/Transclusion}} is
the ability to include content from one file into another by reference.
Org-transclusion is an Org Mode version of it. It lets you insert a copy of
text content via a file link or ID link within an Org file. It is my take on
the @ref{Original idea by John Kitchin, , idea by John Kitchin}.
+
+@node Installation
+@chapter Installation
+
+This package is available on
@uref{https://elpa.gnu.org/packages/org-transclusion.html, GNU ELPA}. You can
do @samp{M-x package-install RET
+org-transclusion} to install it. After installation, you can start using
+Org-transclusion (refer to the @ref{Getting Started} section). You can define
+keybindings in your configuration like this below.
+
+@lisp
+(define-key global-map (kbd "<f12>") #'org-transclusion-add)
+(define-key global-map (kbd "C-n t") #'org-transclusion-mode)
+@end lisp
+
+If you use Doom, you can do something like this below to install the package.
Then add @samp{use-package!} to load the package in your @samp{config.el} like
an example below.
+
+@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
+
+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
@uref{https://en.wikipedia.org/wiki/Transclusion, transclusion}.
+
+To transclude content via a reference, use one of the following commands:
+
+@itemize
+@item
+@samp{org-transclusion-make-from-link}
+@item
+@samp{org-transclusion-add}
+@item
+@samp{org-transclusion-add-all}
+@end itemize
+
+For example, if you have an ID link in your Org file like this:
+
+@example
+[[id:20210501T171427.051019][Bertrand Russell]]
+@end example
+
+Put your cursor somewhere on this link and call @samp{M-x
org-transclusion-make-from-link}. That inserts a "transclusion" keyword like
this in the next empty line:
+
+@example
+#+transclude: [[id:20210501T171427.051019][Bertrand Russell]]
+@end example
+
+Put your cursor somewhere on this keyword line and call @samp{M-x
org-transclusion-add}, and you will see the content the ID points to be copied
over, replacing the @samp{transclude} keyword.
+
+@image{resources/2021-05-09T190918,,,,png}
+
+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 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.
+
+This single-letter-context-menu is defined in @samp{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
+e org-transclusion-live-sync-start
+g org-transclusion-refresh
+o org-transclusion-open-source
+
+C-c C-c org-ctrl-c-ctrl-c
+
+@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 contents you
transclude. More about them in README below.
+
+As your next step, I recommend the section on @ref{Filtering Org elements per
transclusion, , filtering Org elements per transclusion}, which shows features
that give you the power to control what part of the source to transclude in the
way you like and let you experiment on the fly.
+
+@node Usage
+@chapter Usage
+
+@menu
+* Org-transclusion mode, activate, and deactivate: Org-transclusion mode
activate and deactivate.
+* Org links supported::
+* Controlling levels of headlines in transclusions::
+* Filtering Org elements per transclusion::
+* Live-sync edit::
+* Transclude source file into src-block::
+* Transclude range of lines for text and source files::
+* Extensions - Support @samp{org-indent-mode}::
+@end menu
+
+@node Org-transclusion mode activate and deactivate
+@section Org-transclusion mode, activate, and deactivate
+
+Org-transclusion is a local minor mode; however, you do not need to explicitly
call @samp{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 @samp{org-transclusion-add} or @samp{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
@samp{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 @samp{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 @samp{org-transclusion-mode} as your entry command
for transclusion. When customizable variable
@samp{org-transclusion-add-all-on-activate} is non-nil (it is @samp{t} by
default), turning on the minor mode calls the @samp{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, @samp{org-transclusion-add-all} (it is also
used by @samp{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
@samp{org-transclusion-add} at point.
+
+@node Org links supported
+@section Org links supported
+
+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
+
+Note search-options @samp{::/regex/} and @samp{::number} do not work as
intentended.
+
+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{Filtering
Org elements per transclusion}.
+
+@node Controlling levels of headlines in transclusions
+@section Controlling levels of headlines in transclusions
+
+You can specify a different level of transcluded headlines than that 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 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.
+
+@node Filtering Org elements per transclusion
+@section Filtering Org elements per transclusion
+
+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 tra [...]
+
+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 @samp{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
+
+@menu
+* Combining @samp{only-contents} and @samp{exclude-elements}::
+* Notes on excluding the headline element::
+@end menu
+
+@node Combining @samp{only-contents} and @samp{exclude-elements}
+@subsection Combining @samp{:only-contents} and @samp{:exclude-elements}
+
+You can combine @samp{:only-contents} and @samp{:exclude-elements} to control
how you transclude a subtree. Refer to the example screen shots below (the
colored labels are added to the images for illustration purposes and not part
of the Emacs buffers).
+
+@image{resources/2021-06-05_v0.2.0-01,,,,png}
+@strong{Figure 1}. @strong{Left}. Three transclusions with different
properties; @strong{Right}. Source to be transcluded
+
+@image{resources/2021-06-05_v0.2.0-02,,,,png}
+@strong{Figure 2}. @strong{Left}. Only the root-level headline is transcluded
+
+@image{resources/2021-06-05_v0.2.0-03,,,,png}
+@strong{Figure 3}. @strong{Left}. Content of the entire subtree, including
sub-headlines, is transcluded
+
+@image{resources/2021-06-05_v0.2.0-04,,,,png}
+@strong{Figure 3}. @strong{Left}. Combined; only the content of top-level
headline is transcluded
+
+@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. You will still transclude the contents of
the top-most level 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 Live-sync edit
+@section Live-sync edit
+
+@strong{Experimental.} You can start live-sync edit by pressing @samp{e} (by
default) on a text element you want to edit. This will 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 @samp{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 @samp{yank} command (@samp{C-y}) is
replaced with a special command @samp{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.
@samp{evil-mode}), it is advised that you review the default keybindings. You
can customize the local keybindings [...]
+
+@strong{Note}: that during live-sync edit, file's content gets saved to the
filesystem 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
+
+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
+
+@node Transclude range of lines for text and source files
+@section Transclude range of lines for text and source files
+
+@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::
+@end menu
+
+@node @samp{lines} property to specify a range of lines
+@subsection @samp{:lines} property to specify a range of 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 the @samp{:lines} property with the @samp{:src} property 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
+
+Note search-options @samp{::/regex/} and @samp{::number} do not work as
intended.
+
+@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
+
+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 term @samp{id-1234 end
here} defines the end of the range. The search looks for @samp{id-123 end here}
in the body text, and use the line one before the one where the text is find
(thus, the transcluded range will not contain @samp{id-1234 end here}).
+
+You can also combined @samp{:lines} property with @samp{:end} property. 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 one line after the line where "id-1234" is found; it's the
"second line, or line 2". Instead of transcluding until the end of the buffer,
the end is defined by the @samp{:end} property.
+
+Example 3:
+@example
+#+transclude: [[file:../../test/python-1.py::id-1234]] :lines 2- :src python
:end "id-1234 end here"
+@end example
+
+@node Extensions - Support @samp{org-indent-mode}
+@section Extensions - Support @samp{org-indent-mode}
+
+Org-transclusion provides a simple extension framework, where you can use
@samp{customize} to selectively add new features. Currently there are two
extensions provided. Support for @samp{org-indent-mode} is an extension, which
is inactive by default.
+
+@table @asis
+@item (on by default) org-transclusion-src-lines
+Add features for @samp{:src} and @samp{:lines} properties to #+transclude. It
is meant for non-Org files such as program source and text files
+@item (off by default) org-transclusion-indent-mode
+Support org-indent-mode
+@end table
+
+@image{resources/2021-09-05T164930,,,,png}
+
+If you use @samp{customize}, the features are loaded automatically. Note that
it does not "unload" the feature until you relaunch Emacs.
+
+If you do not use @samp{customize} (e.g. Doom), you may need to explicitly
require an extension. For example, to activate
@samp{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
+;; (add-to-list 'load-path "path/to/org-transclusion/")
+(add-to-list 'org-transclusion-extensions 'org-transclusion-indent-mode)
+(require 'org-transclusion-indent-mode)
+@end lisp
+
+@node Customizing
+@chapter Customizing
+
+You can customize settings in the @samp{org-transclusion} group.
+
+@table @asis
+@item @samp{org-transclusion-extensions}
+Defines extensions to be loaded with
+org-transclusion.el. If you use @samp{customize}, the extensions are loaded by
it.
+If you don't, you likely need to explicitly use @samp{require} to load them.
+
+@item @samp{org-transclusion-add-all-on-activate}
+Defines whether or not all the
+active transclusions (with @samp{t}) get automatically transcluded on minor
mode
+activation (@samp{org-transclusion-mode}). This does not affect the manual
+activation when you directly call @samp{org-transclusion-activate}
+
+@item @samp{org-transclusion-exclude-elements}
+See @ref{Customizable filter to exclude certain Org elements, , sub-section}
below
+
+@item @samp{org-transclusion-include-first-section}
+See @ref{Include the section before the first headline (Org file only), ,
sub-section} below
+
+@item @samp{org-transclusion-open-source-display-action-list}
+You can customize the
+way the @samp{org-transclusion-open-source} function displays the source
buffer for
+the transclusion. You specify the "action" in the way defined by the built-in
+@samp{display-buffer} function. Refer to its in-system documentation (with
@samp{C-h f})
+for the accepted values. @samp{M-x customize} can also guide you with the
types of
+values with the widget.
+
+@item @samp{org-transclusion-mode-lighter}
+Define the lighter for Org-transclusion
+minor mode. The default is " OT".
+@end table
+
+@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
+
+Set customizable variable @samp{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 @samp{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{Filtering 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)
+
+You can include the first section (section before the first headline) of an
Org file. It is toggled via customizable variable
@samp{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
+
+@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
+
+You can set your own face to the @samp{#+transclude} keyword with using the
@samp{org-transclusion-keyword} face.
+
+@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
+org-transclusion-source-fringe
+@item
+org-transclusion-fringe
+@end itemize
+
+Here is an example image from
@uref{https://github.com/nobiot/org-transclusion/issues/75, this issue}:
+
+@uref{https://user-images.githubusercontent.com/12507865/118443158-de6a2480-b6eb-11eb-81d0-a2778ed5f779.png}
+
+To customize a face, it's probably the easiest to use @samp{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 @samp{list-faces-display}.
+
+Other faces:
+@itemize
+@item
+org-transclusion-source
+@item
+org-transclusion-source-edit
+@item
+org-transclusion
+@item
+org-transclusion-edit
+@end itemize
+
+I do not know if bitmap can be customizable after it's been defined (TBC).
+@table @asis
+@item org-transclusion-fringe-bitmap
+It is used for the fringe that indicates the transcluded region. It works only
in a graphical environment (not in terminal).
+@end table
+
+@node Keybindings
+@section Keybindings
+
+@itemize
+@item
+@samp{org-transclusion-map}
+@item
+@samp{org-transclusion-live-sync-map}
+@end itemize
+
+@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 @samp{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-drawerd}.
+
+More technical reason for this limitation is documented in the docstring of
function @samp{org-transclusion-live-sync-enclosing-element}.
+
+Work is in progress to lift this limitation but I'm still experimenting
different ideas.
+
+@item @samp{org-indent-mode} may not work well with Org-transclusion
+A new extension has been added to support @samp{org-indent-mode}
+Refer to @ref{Extensions - Support @samp{org-indent-mode}, , this section}.
+
+@item Doom's customization may interfere with Org-transclusion
+Refer to issue
#52@footnote{@uref{https://github.com/nobiot/org-transclusion/issues/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:
+
+@samp{(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
#20@footnote{@uref{https://github.com/nobiot/org-transclusion/issues/20}}. I
don't intend to support this -- refile the source, not the transcluded copy.
+
+@item Org-transclusion does not support expansion of noweb references when a
transcluded source block code has them
+Refer to issue
#86@footnote{@uref{https://github.com/nobiot/org-transclusion/issues/86}}. You
will get "Text read-only" error when export tries to expand the noweb
references into the source code. †noweb
reference@footnote{@uref{https://orgmode.org/manual/Noweb-Reference-Syntax.html}}
+@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 Development
+@chapter Development
+
+@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, me included)
+
+@item
+Create issues, discussion, and/or pull requests. All welcome.
+@end itemize
+
+@menu
+* Notes on pull requests and Free Software Foundation (FSF) copy right
assignment::
+@end menu
+
+@node Notes on pull requests and Free Software Foundation (FSF) copy right
assignment
+@section Notes on pull requests and Free Software Foundation (FSF) copy right
assignment
+
+Org-transclusion is part of GNU ELPA and thus copyrighted by the Free Software
Foundation@footnote{@uref{http://fsf.org}} (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" (Org
Mode website@footnote{@uref{https://orgmode.org/contribute.html#copyright}}).
+
+Thank you.
+
+@node License
+@chapter License
+
+Org-transclusion is licensed under a GPLv3 license. For a full copy of the
license, refer to @uref{./LICENSE, LICENSE}.
+
+This documentation is licensed under the GNU Free Documentation License,
version 1.3.
+
+@node GNU Free Documentation License
+@chapter GNU Free Documentation License
+
+@include docs/fdl.texi
+
+@bye
\ No newline at end of file
diff --git a/docs/test-clone/test-clone-1.txt
b/text-clone-docs/test-clone/test-clone-1.txt
similarity index 100%
rename from docs/test-clone/test-clone-1.txt
rename to text-clone-docs/test-clone/test-clone-1.txt
diff --git a/docs/test-clone/test-clone-2.txt
b/text-clone-docs/test-clone/test-clone-2.txt
similarity index 100%
rename from docs/test-clone/test-clone-2.txt
rename to text-clone-docs/test-clone/test-clone-2.txt
diff --git a/docs/test-clone/test-clone-original.txt
b/text-clone-docs/test-clone/test-clone-original.txt
similarity index 100%
rename from docs/test-clone/test-clone-original.txt
rename to text-clone-docs/test-clone/test-clone-original.txt
diff --git a/docs/test-clone/test-text-clone.el.test
b/text-clone-docs/test-clone/test-text-clone.el.test
similarity index 100%
rename from docs/test-clone/test-text-clone.el.test
rename to text-clone-docs/test-clone/test-text-clone.el.test
diff --git a/docs/text-clone.md b/text-clone-docs/text-clone.md
similarity index 100%
rename from docs/text-clone.md
rename to text-clone-docs/text-clone.md
![https://elpa.gnu.org/packages/org-transclusion.svg"/](https://elpa.gnu.org/packages/org-transclusion.svg"/){kind=link}
![https://elpa.gnu.org/devel/org-transclusion.svg"/](https://elpa.gnu.org/devel/org-transclusion.svg"/){kind=link}
![https://img.shields.io/badge/License-GPLv3-blue.svg"](https://img.shields.io/badge/License-GPLv3-blue.svg"){kind=link}
