[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/org-transclusion 8f5f714 2/5: docs: add User Manual .te
|
From: |
ELPA Syncer |
|
Subject: |
[elpa] externals/org-transclusion 8f5f714 2/5: docs: add User Manual .texi, .info, and .html |
|
Date: |
Thu, 23 Dec 2021 12:57:39 -0500 (EST) |
branch: externals/org-transclusion
commit 8f5f714faef23d134e4de7da900e3414d9d0c8c9
Author: Noboru Ota <me@nobiot.com>
Commit: Noboru Ota <me@nobiot.com>
docs: add User Manual .texi, .info, and .html
---
docs/index.html | 1681 ++++++++++++++++++++++++++++++++++++++++++++
docs/resources/manual.css | 71 ++
org-transclusion.info | 1689 +++++++++++++++++++++++++++++++++++++++++++++
org-transclusion.org | 56 +-
org-transclusion.texi | 351 +++++++---
5 files changed, 3723 insertions(+), 125 deletions(-)
diff --git a/docs/index.html b/docs/index.html
new file mode 100644
index 0000000..741237f
--- /dev/null
+++ b/docs/index.html
@@ -0,0 +1,1681 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
+<html>
+<!-- Copyright (C) 2021 Free Software Foundation, Inc.
+
+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.”
+
-->
+<!-- Created by GNU Texinfo 6.7, http://www.gnu.org/software/texinfo/ -->
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<title>Org-transclusion User Manual</title>
+
+<meta name="description" content="Org-transclusion User Manual">
+<meta name="keywords" content="Org-transclusion User Manual">
+<meta name="resource-type" content="document">
+<meta name="distribution" content="global">
+<meta name="Generator" content="makeinfo">
+<link href="#Top" rel="start" title="Top">
+<link href="#Index-_002d-Features" rel="index" title="Index - Features">
+<style type="text/css">
+<!--
+a.summary-letter {text-decoration: none}
+blockquote.indentedblock {margin-right: 0em}
+div.display {margin-left: 3.2em}
+div.example {margin-left: 3.2em}
+div.lisp {margin-left: 3.2em}
+kbd {font-style: oblique}
+pre.display {font-family: inherit}
+pre.format {font-family: inherit}
+pre.menu-comment {font-family: serif}
+pre.menu-preformatted {font-family: serif}
+span.nolinebreak {white-space: nowrap}
+span.roman {font-family: initial; font-weight: normal}
+span.sansserif {font-family: sans-serif; font-weight: normal}
+ul.no-bullet {list-style: none}
+-->
+</style>
+<link rel="stylesheet" type="text/css" href="resources/manual.css">
+
+
+</head>
+
+<body lang="en">
+<h1 class="settitle" align="center">Org-transclusion User Manual</h1>
+
+
+
+
+<span id="Top"></span><div class="header">
+<p>
+Next: <a href="#Example-Use-Cases-_0026-Main-Features" accesskey="n"
rel="next">Example Use Cases & Main Features</a> [<a
href="#Index-_002d-Features" title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="Org_002dtransclusion-User-Manual"></span><h1
class="top">Org-transclusion User Manual</h1>
+
+
+<p>This manual is for Org-transclusion version 1.0.x.
+</p>
+<p>last updated 23 December 2021.
+</p>
+<p>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.
+</p>
+<p>Copyright (C) 2021 Free Software Foundation, Inc.
+</p>
+<blockquote>
+<p>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.”
+</p>
+<p>(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
+modify this GNU manual.”
+</p>
+</blockquote>
+
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top">• <a
href="#Example-Use-Cases-_0026-Main-Features" accesskey="1">Example Use Cases
& Main Features</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a href="#Installation"
accesskey="2">Installation</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a href="#Getting-Started"
accesskey="3">Getting Started</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a href="#Usage"
accesskey="4">Usage</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a href="#Customizing"
accesskey="5">Customizing</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a href="#Known-Limitations"
accesskey="6">Known Limitations</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a href="#Credits"
accesskey="7">Credits</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a href="#Contributing"
accesskey="8">Contributing</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a href="#Index-_002d-Features"
rel="index" accesskey="9">Index - Features</a></td><td> </td><td
align="left" valign="top">Key concepts & features
+</td></tr>
+<tr><td align="left" valign="top">• <a href="#Index-_002d-Commands"
rel="index">Index - Commands</a></td><td> </td><td align="left"
valign="top">Interactive functions
+</td></tr>
+<tr><td align="left" valign="top">• <a href="#Index-_002d-User-Options"
rel="index">Index - User Options</a></td><td> </td><td align="left"
valign="top">Customizable variables & faces
+</td></tr>
+<tr><td align="left" valign="top">• <a
href="#GNU-Free-Documentation-License">GNU Free Documentation
License</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+</pre></th></tr><tr><th colspan="3" align="left" valign="top"><pre
class="menu-comment">— The Detailed Node Listing —
+
+Usage
+
+</pre></th></tr><tr><td align="left" valign="top">• <a
href="#Org_002dtransclusion-mode-activate-and-deactivate">Org-transclusion
mode, activate, and deactivate</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a href="#Org-links-supported">Org
links supported</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a
href="#Control-levels-of-headlines-per-transclusion">Control levels of
headlines per transclusion</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a
href="#Filter-Org-elements-per-transclusion">Filter Org elements per
transclusion</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a
href="#Live_002dsync-edit">Live-sync edit</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a
href="#Transclude-source-file-into-src_002dblock">Transclude source file into
src-block</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a
href="#Transclude-range-of-lines-for-text-and-source-files">Transclude range of
lines for text and source files</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a
href="#Extensions">Extensions</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Filter Org elements per transclusion
+
+</pre></th></tr><tr><td align="left" valign="top">• <a
href="#Notes-on-excluding-the-headline-element">Notes on excluding the headline
element</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Transclude range of lines for text and source files
+
+</pre></th></tr><tr><td align="left" valign="top">• <a
href="#lines-property-to-specify-a-range-of-lines">‘<samp>lines</samp>’
property to specify a range of lines</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a
href="#end-property-to-specify-a-search-term-to-dynamically-look-for-the-end-of-a-range">‘<samp>end</samp>’
property to specify a search term to dynamically look for the end of a
range</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Customizing
+
+</pre></th></tr><tr><td align="left" valign="top">• <a
href="#Customizable-filter-to-exclude-certain-Org-elements">Customizable filter
to exclude certain Org elements</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a
href="#Include-the-section-before-the-first-headline-_0028Org-file-only_0029">Include
the section before the first headline (Org file
only)</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a
href="#Faces-_0026-fringe-bitmap">Faces & fringe
bitmap</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a
href="#Keybindings">Keybindings</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Faces & fringe bitmap
+
+</pre></th></tr><tr><td align="left" valign="top">• <a
href="#Face-for-the-_0023_002btransclude-keyword">Face for the
‘<samp>#+transclude</samp>’
keyword</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a
href="#Faces-for-the-fringes-next-to-transcluded-region-and-source-region">Faces
for the fringes next to transcluded region and source
region</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Credits
+
+</pre></th></tr><tr><td align="left" valign="top">• <a
href="#Original-idea-by-John-Kitchin">Original idea by John
Kitchin</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a
href="#Text_002dClone">Text-Clone</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Contributing
+
+</pre></th></tr><tr><td align="left" valign="top">• <a
href="#Notes-on-pull-requests-and-Free-Software-Foundation-_0028FSF_0029-copy-right-assignment">Notes
on pull requests and Free Software Foundation (FSF) copy right
assignment</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+</pre></th></tr></table>
+
+<hr>
+<span id="Example-Use-Cases-_0026-Main-Features"></span><div class="header">
+<p>
+Next: <a href="#Installation" accesskey="n" rel="next">Installation</a>,
Previous: <a href="#Top" accesskey="p" rel="prev">Top</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#Index-_002d-Features"
title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="Example-Use-Cases-_0026-Main-Features-1"></span><h2
class="chapter">1 Example Use Cases & Main Features</h2>
+
+<p>Example Use Cases:
+</p>
+<dl compact="compact">
+<dt>Book writing</dt>
+<dd><p>You have a collection of notes. You can quickly transclude paragraphs
and sections from them into a draft. As they are links, it’s easy to
re-organize them into different sequences to see which way works the best.
+</p>
+</dd>
+<dt>Academic writing</dt>
+<dd><p>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.
+</p>
+</dd>
+<dt>Technical writing</dt>
+<dd><p>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.
+</p>
+</dd>
+<dt>Project status reports</dt>
+<dd><p>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.
+</p></dd>
+</dl>
+
+<p>Main Features:
+</p>
+<ul>
+<li> Insert a copy of text content via a file link or ID link into an Org file
+
+</li><li> Work with any text file such as program source cod, plain text,
Markdown, or other Org files
+
+</li><li> Keep the file system clear of the copies of text content –
Org-transclusion tries hard to save only the links to the file system
+
+</li><li> For Org files, use different headline levels from the source Org file
+
+</li><li> For Org files, use filters to include only relevant elements (e.g.
filter out properties in the transclusions)
+
+</li><li> 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
+
+</li><li> For program source files, transclude parts or whole code directly
into Org’s source block to leverage the rich Org features
+
+</li><li> Extend Org-transclusion with its extension framework
+</li></ul>
+
+<hr>
+<span id="Installation"></span><div class="header">
+<p>
+Next: <a href="#Getting-Started" accesskey="n" rel="next">Getting Started</a>,
Previous: <a href="#Example-Use-Cases-_0026-Main-Features" accesskey="p"
rel="prev">Example Use Cases & Main Features</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#Index-_002d-Features"
title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="Installation-1"></span><h2 class="chapter">2 Installation</h2>
+
+<p>This package is available on <a
href="https://elpa.gnu.org/packages/org-transclusion.html";>GNU ELPA</a>. You
can do ‘<samp>M-x package-install RET
+org-transclusion</samp>’ to install it. After installation, you can
start using
+Org-transclusion (refer to the <a href="#Getting-Started">Getting Started</a>
section). You can define
+keybindings in your configuration like this below.
+</p>
+<div class="lisp">
+<pre class="lisp">(define-key global-map (kbd "<f12>")
#'org-transclusion-add)
+(define-key global-map (kbd "C-n t") #'org-transclusion-mode)
+</pre></div>
+
+<p>If you use Doom, you can do something like this below to install the
package. Then add ‘<samp>use-package!</samp>’ to load the package
in your ‘<samp>config.el</samp>’ like an example below.
+</p>
+<div class="lisp">
+<pre class="lisp">;; ~/.doom.d/package.el
+(package! org-transclusion)
+</pre></div>
+
+
+<div class="lisp">
+<pre class="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))
+</pre></div>
+
+<hr>
+<span id="Getting-Started"></span><div class="header">
+<p>
+Next: <a href="#Usage" accesskey="n" rel="next">Usage</a>, Previous: <a
href="#Installation" accesskey="p" rel="prev">Installation</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a
href="#Index-_002d-Features" title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="Getting-Started-1"></span><h2 class="chapter">3 Getting Started</h2>
+
+<span id="index-org_002dtransclusion_002dadd"></span>
+<span id="index-org_002dtransclusion_002dadd_002dall"></span>
+<span id="index-org_002dtransclusion_002dmake_002dfrom_002dlink"></span>
+<span id="index-org_002dtransclusion_002dopen_002dsource"></span>
+<span id="index-org_002dtransclusion_002dmove_002dto_002dsource"></span>
+<span id="index-org_002dtransclusion_002drefresh"></span>
+<span id="index-org_002dtransclusion_002dmap"></span>
+
+<p>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.
+</p>
+<p>To transclude content via a link, use one of the following commands:
+</p>
+<ul>
+<li> ‘<samp>org-transclusion-add</samp>’
+
+</li><li> ‘<samp>org-transclusion-add-all</samp>’
+
+</li><li> ‘<samp>org-transclusion-make-from-link</samp>’
+</li></ul>
+
+<p>For example, if you have an ID link in your Org file like this:
+</p>
+<div class="example">
+<pre class="example">[[id:20210501T171427.051019][Bertrand Russell]]
+</pre></div>
+
+<p>Simply type to add ‘<samp>#+transclude:</samp>’ in front of the
link like the example below.
+</p>
+<div class="example">
+<pre class="example">#+transclude: [[id:20210501T171427.051019][Bertrand
Russell]]
+</pre></div>
+
+<p>Put your cursor somewhere on this keyword line and type ‘<samp>M-x
org-transclusion-add RET</samp>’, and you will see the text content that
the ID points replace the whole line. If you have multiple links with a
transclude keyword, you can type ‘<samp>M-x org-transclusion-add-all
RET</samp>’ to do all transclusions in the current buffer.
+</p>
+<p>Alternatively, you can also put cursor somewhere on the link and call
‘<samp>M-x org-transclusion-make-from-link</samp>’. That will
insert another line with ‘<samp>#+transclusion:</samp>’ keyword
appended in front of a copy of the original link in the next empty line.
+</p>
+<p>The transcluded text is <strong>read-only</strong> 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).
+</p>
+<p>For example, you can press ‘<samp>o</samp>’ to open the source
buffer of the transclusion at point, or ‘<samp>O</samp>’ (capital
"o") to open and move to it. Press ‘<samp>g</samp>’ to
refresh the transclusion. Press ‘<samp>e</samp>’ to start live-sync
edit. For more detail, inspect the documentation of each command. Press
‘<samp>d</samp>’ to remove the transcluded content, putting the
original ‘<samp>#+transcl [...]
+</p>
+<p>This single-letter-context-menu is defined in
‘<samp>org-transclusion-map</samp>’. The default keybindings are
shown below. Adapt them to your liking, especially if you use vim keybindings
with Evil Mode, etc.
+</p>
+<div class="example">
+<pre class="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
+
+</pre></div>
+
+<p>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.
+</p>
+<hr>
+<span id="Usage"></span><div class="header">
+<p>
+Next: <a href="#Customizing" accesskey="n" rel="next">Customizing</a>,
Previous: <a href="#Getting-Started" accesskey="p" rel="prev">Getting
Started</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a
href="#Index-_002d-Features" title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="Usage-1"></span><h2 class="chapter">4 Usage</h2>
+
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top">• <a
href="#Org_002dtransclusion-mode-activate-and-deactivate"
accesskey="1">Org-transclusion mode, activate, and
deactivate</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a href="#Org-links-supported"
accesskey="2">Org links supported</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a
href="#Control-levels-of-headlines-per-transclusion" accesskey="3">Control
levels of headlines per transclusion</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a
href="#Filter-Org-elements-per-transclusion" accesskey="4">Filter Org elements
per transclusion</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a href="#Live_002dsync-edit"
accesskey="5">Live-sync edit</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a
href="#Transclude-source-file-into-src_002dblock" accesskey="6">Transclude
source file into src-block</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a
href="#Transclude-range-of-lines-for-text-and-source-files"
accesskey="7">Transclude range of lines for text and source
files</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a href="#Extensions"
accesskey="8">Extensions</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+</table>
+
+<hr>
+<span id="Org_002dtransclusion-mode-activate-and-deactivate"></span><div
class="header">
+<p>
+Next: <a href="#Org-links-supported" accesskey="n" rel="next">Org links
supported</a>, Up: <a href="#Usage" accesskey="u" rel="up">Usage</a> [<a
href="#Index-_002d-Features" title="Index" rel="index">Index</a>]</p>
+</div>
+<span
id="Org_002dtransclusion-mode_002c-activate_002c-and-deactivate"></span><h3
class="section">4.1 Org-transclusion mode, activate, and deactivate</h3>
+
+<span id="index-Activate-_002f-Deactivate"></span>
+<span id="index-org_002dtransclusion_002dmode"></span>
+<span id="index-org_002dtransclusion_002dactivate"></span>
+<span id="index-org_002dtransclusion_002ddeactivate"></span>
+<span id="index-Transclusion-Properties"></span>
+<span id="index-Property-_002d-_003adisable_002dauto"></span>
+<span
id="index-org_002dtransclusion_002dadd_002dall_002don_002dactivate"></span>
+
+<p>Org-transclusion is a local minor mode; however, you do not need to
explicitly call ‘<samp>org-transclusion-mode</samp>’. The minor
mode is intended to be just a convenient wrapper to let you easily toggle
between ‘<samp>activate</samp>’ and
‘<samp>deactivate</samp>’.
+</p>
+<p>As you saw in the <a href="#Getting-Started">Getting Started section</a>
above, calling ‘<samp>org-transclusion-add</samp>’ or
‘<samp>org-transclusion-add-all</samp>’ is enough to add
transclusions in your current buffer.
+</p>
+<p>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</samp>’ to activate hooks and
some other variables. Their main purpose is to keep files in the filesystem
clear of the transcluded content.
+</p>
+<p>Turn off the minor mode or use
‘<samp>org-transclusion-deactivate</samp>’; you will remove all the
transclusions in the current buffer and clear the hooks and other setup
variables.
+</p>
+<p>If you prefer, you can use ‘<samp>org-transclusion-mode</samp>’
as your entry command for transclusion. When customizable variable
‘<samp>org-transclusion-add-all-on-activate</samp>’ is non-nil (it
is ‘<samp>t</samp>’ by default), turning on the minor mode calls
the ‘<samp>org-transclusion-add-all</samp>’ command to attempt to
add all transclusions automatically in the current buffer.
+</p>
+<p>You can control whether or not transclusions are to be added automatically
per transclude keyword. By default,
‘<samp>org-transclusion-add-all</samp>’ (it is also used by
‘<samp>org-transclusion-mode</samp>’) will work on every transclude
keyword in the buffer. Add ‘<samp>:disable-auto</samp>’ property to
a keyword as shown in the example below; ‘<samp>add-all</samp>’
skips transclude keywords with it.
+</p>
+<div class="example">
+<pre class="example">#+transclude: [[file:path/to/file.org]] :disable-auto
+</pre></div>
+
+<p>You can override the ‘<samp>:disable-auto</samp>’ property by
manually calling ‘<samp>org-transclusion-add</samp>’ at point.
+</p>
+<hr>
+<span id="Org-links-supported"></span><div class="header">
+<p>
+Next: <a href="#Control-levels-of-headlines-per-transclusion" accesskey="n"
rel="next">Control levels of headlines per transclusion</a>, Previous: <a
href="#Org_002dtransclusion-mode-activate-and-deactivate" accesskey="p"
rel="prev">Org-transclusion mode activate and deactivate</a>, Up: <a
href="#Usage" accesskey="u" rel="up">Usage</a> [<a
href="#Index-_002d-Features" title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="Org-links-supported-1"></span><h3 class="section">4.2 Org links
supported</h3>
+
+<span id="index-Org-Links-Supported"></span>
+<span id="index-Property-_002d-_003aonly_002dcontents"></span>
+
+<p>Transclusion has been tested to work for the following types of links:
+</p>
+<ul>
+<li> File link for an entire org file/buffer; e.g.
‘<samp>[[file:~/org/file.org][My Org Notes]]</samp>’
+</li><li> File link with ‘<samp>::*heading</samp>’
+</li><li> File link with ‘<samp>::#custom-id</samp>’
+</li><li> File link with ‘<samp>::name</samp>’ for blocks (e.g.
blocked quotations), tables, and links
+</li><li> File link with ‘<samp>::dedicated-target</samp>’; this
is intended for linking to a paragraph. See below.
+</li><li> ID link ‘<samp>id:uuid</samp>’
+</li><li> File link for non-org files (tested with
‘<samp>.txt</samp>’ and ‘<samp>.md</samp>’); for these,
the whole buffer gets transcluded
+</li></ul>
+
+<p>Note search-options ‘<samp>::/regex/</samp>’ and
‘<samp>::number</samp>’ do not work as intended.
+</p>
+<p>For transcluding a specific paragraph, there are two main ways: Org
Mode’s <a
href="https://orgmode.org/manual/Internal-Links.html#Internal-Links";>dedicated-target</a>
and ‘<samp>:only-contents</samp>’ property.
+</p>
+<p>For dedicated targets, the target paragraph must be identifiable by a
dedicated target with a ‘<samp><<paragraph-id>></samp>’:
+</p>
+<div class="example">
+<pre class="example">Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+Suspendisse ac velit fermentum, sodales nunc in,
+tincidunt quam. <<paragraph-id>>
+</pre></div>
+
+<p>It is generally assumed that the ‘<samp>paragraph-id</samp>’ 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.
+</p>
+<p>For the ‘<samp>:only-contents</samp>’ property, refer to
sub-section <a href="#Filter-Org-elements-per-transclusion">Filtering Org
elements per transclusion</a>.
+</p>
+<hr>
+<span id="Control-levels-of-headlines-per-transclusion"></span><div
class="header">
+<p>
+Next: <a href="#Filter-Org-elements-per-transclusion" accesskey="n"
rel="next">Filter Org elements per transclusion</a>, Previous: <a
href="#Org-links-supported" accesskey="p" rel="prev">Org links supported</a>,
Up: <a href="#Usage" accesskey="u" rel="up">Usage</a> [<a
href="#Index-_002d-Features" title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="Control-levels-of-headlines-per-transclusion-1"></span><h3
class="section">4.3 Control levels of headlines per transclusion</h3>
+
+<span id="index-Property-_002d-_003alevel"></span>
+<span id="index-org_002dtransclusion_002ddemote_002dsubtree"></span>
+<span id="index-org_002dtransclusion_002dpromote_002dsubtree"></span>
+<span id="index-org_002dtransclusion_002dmake_002dfrom_002dlink-1"></span>
+
+<p>When you transclude Org contents, you can specify a different headline
level than those of the source Org file.
+</p>
+<p>Use the ‘<samp>:level</samp>’ property with a value of single
digit number from 1 to 9 like this example below.
+</p>
+<div class="example">
+<pre class="example">#+transclude: [[file:path/to/file.org::*Headline]] :level
2
+</pre></div>
+
+<p>The top level of the transcluded headline will set to the value of
‘<samp>:level</samp>’ 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.
+</p>
+<p>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</samp>’ property; the rest of headlines in the
buffer will align accordingly.
+</p>
+<p>Other ways to control include the following.
+</p>
+<dl compact="compact">
+<dt>‘<samp>org-transclusion-make-from-link</samp>’</dt>
+<dd><p>Make a transclusion keyword from a link at point. If you pass a
positive number 1-9 with ‘<samp>digit-argument</samp>’ (e.g. prefix
‘<samp>M-x</samp>’ with ‘<samp>C-2</samp>’ to pass
"2"), this function automatically puts the
‘<samp>:level</samp>’ property to the resultant transclusion
keyword.
+</p>
+</dd>
+<dt>‘<samp>org-transclusion-promote-subtree</samp>’</dt>
+<dd><p>Promote transcluded subtree at point. Mapped to "P" (capital
"p") by default in ‘<samp>org-transclusion-map</samp>’
+</p>
+</dd>
+<dt>‘<samp>org-transclusion-demote-subtree</samp>’</dt>
+<dd><p>Demote transcluded subtree at point. Mapped to "D" (capital
"D") by default in ‘<samp>org-transclusion-map</samp>’
+</p></dd>
+</dl>
+
+<hr>
+<span id="Filter-Org-elements-per-transclusion"></span><div class="header">
+<p>
+Next: <a href="#Live_002dsync-edit" accesskey="n" rel="next">Live-sync
edit</a>, Previous: <a href="#Control-levels-of-headlines-per-transclusion"
accesskey="p" rel="prev">Control levels of headlines per transclusion</a>, Up:
<a href="#Usage" accesskey="u" rel="up">Usage</a> [<a
href="#Index-_002d-Features" title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="Filter-Org-elements-per-transclusion-1"></span><h3
class="section">4.4 Filter Org elements per transclusion</h3>
+
+<span id="index-Filters"></span>
+<span id="index-org_002dtransclusion_002dexclude_002delements"></span>
+<span id="index-org_002dtransclusion_002dinclude_002dfirst_002dsection"></span>
+<span id="index-Property-_002d-_003aonly_002dcontent"></span>
+
+<p>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.
+</p>
+<p>The following two customizable variables are applicable to all
transclusions globally. You can think of them as the global default.
+</p>
+<dl compact="compact">
+<dt>‘<samp>org-transclusion-exclude-elements</samp>’</dt>
+<dd><p>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</samp>’. The default is
to exclude ‘<samp>property-drawer</samp>’.
+</p>
+<p>Refer also to the <a
href="#Customizable-filter-to-exclude-certain-Org-elements">sub-section on this
user option</a>.
+</p>
+</dd>
+<dt>‘<samp>org-transclusion-include-first-section</samp>’</dt>
+<dd><p>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>’, ‘<samp>#+author</samp>’, 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</samp>’ (changed
from ‘<samp>nil</s [...]
+</p>
+<p>Refer also to the <a
href="#Include-the-section-before-the-first-headline-_0028Org-file-only_0029">sub-section
on this user option</a>.
+</p></dd>
+</dl>
+
+<p>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.
+</p>
+<dl compact="compact">
+<dt>‘<samp>:only-contents</samp>’</dt>
+<dd><p>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.
+</p>
+<p>Add ‘<samp>:only-contents</samp>’ without any value like this
example:
+</p></dd>
+</dl>
+
+<div class="example">
+<pre class="example">#+transclude: [[file:path/to/file.org]] :only-contents
+</pre></div>
+
+<dl compact="compact">
+<dt>‘<samp>:exclude-elements</samp>’</dt>
+<dd><p>This property lets you <strong>add</strong> elements to exclude per
transclusion on top of the variable
‘<samp>org-transclusion-exclude-elements</samp>’ defines. You
cannot <strong>remove</strong> 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.
+</p>
+<p>Add ‘<samp>:exclude-elements</samp>’ with a list of elements
(each one as defined by ‘<samp>org-element-all-elements</samp>’)
separated by a space inside double quotation marks like this example:
+</p></dd>
+</dl>
+
+<div class="example">
+<pre class="example">#+transclude: [[file:path/to/file.org]] :exclude-elements
"drawer keyword"
+</pre></div>
+
+<p>You can combine ‘<samp>:only-contents</samp>’ and
‘<samp>:exclude-elements</samp>’ 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</samp>’ to remove the transclusion, change the properties,
and transclude again to see a new result.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top">• <a
href="#Notes-on-excluding-the-headline-element" accesskey="1">Notes on
excluding the headline element</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+</table>
+
+<hr>
+<span id="Notes-on-excluding-the-headline-element"></span><div class="header">
+<p>
+Up: <a href="#Filter-Org-elements-per-transclusion" accesskey="u"
rel="up">Filter Org elements per transclusion</a> [<a
href="#Index-_002d-Features" title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="Notes-on-excluding-the-headline-element-1"></span><h4
class="subsection">4.4.1 Notes on excluding the headline element</h4>
+
+<p>If you add ‘<samp>headline</samp>’ 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.
+</p>
+<p>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.
+</p>
+<div class="example">
+<pre class="example">** Headline 1
+ Content of Headline 1
+** Headline 2
+ Content of Headline 2
+* Headline 3
+ Content of Headline
+</pre></div>
+
+<hr>
+<span id="Live_002dsync-edit"></span><div class="header">
+<p>
+Next: <a href="#Transclude-source-file-into-src_002dblock" accesskey="n"
rel="next">Transclude source file into src-block</a>, Previous: <a
href="#Filter-Org-elements-per-transclusion" accesskey="p" rel="prev">Filter
Org elements per transclusion</a>, Up: <a href="#Usage" accesskey="u"
rel="up">Usage</a> [<a href="#Index-_002d-Features" title="Index"
rel="index">Index</a>]</p>
+</div>
+<span id="Live_002dsync-edit-1"></span><h3 class="section">4.5 Live-sync
edit</h3>
+
+<span id="index-Live_002dsync-edit"></span>
+<span id="index-org_002dtransclusion_002dlive_002dsync_002dstart"></span>
+<span id="index-org_002dtransclusion_002dlive_002dsync_002dexit"></span>
+<span id="index-org_002dtransclusion_002dlive_002dsync_002dpaste"></span>
+<span id="index-org_002dtransclusion_002dlive_002dsync_002dmap"></span>
+
+<p><strong>Experimental.</strong> You can start live-sync edit by pressing
‘<samp>e</samp>’ (by default) on a text element you want to edit.
This will call ‘<samp>org-transclusion-live-sync-start</samp>’ 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.
+</p>
+<p>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.
+</p>
+<p>In the live-sync edit region, you can freely type to edit the transclusion
or source regions; they will sync simultaneously.
+</p>
+<p>Once done with editing, press ‘<samp>C-c C-c</samp>’ to exit
live-sync edit. The key is bound to
‘<samp>org-transclusion-live-sync-exit</samp>’. It will turn off
the live sync edit but keep the transclusion on.
+</p>
+<p>In the live-sync edit region, the normal ‘<samp>yank</samp>’
command (‘<samp>C-y</samp>’) is replaced with a special command
‘<samp>org-transclusion-live-sync-paste</samp>’. 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</samp>’), it is advis [...]
+</p>
+<p><strong>Note</strong>: 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:</samp>’ 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.
+</p>
+<div class="lisp">
+<pre class="lisp">(substitute-command-keys
"\\{org-transclusion-live-sync-map}")
+</pre></div>
+
+<div class="example">
+<pre class="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’
+</pre></div>
+
+<hr>
+<span id="Transclude-source-file-into-src_002dblock"></span><div
class="header">
+<p>
+Next: <a href="#Transclude-range-of-lines-for-text-and-source-files"
accesskey="n" rel="next">Transclude range of lines for text and source
files</a>, Previous: <a href="#Live_002dsync-edit" accesskey="p"
rel="prev">Live-sync edit</a>, Up: <a href="#Usage" accesskey="u"
rel="up">Usage</a> [<a href="#Index-_002d-Features" title="Index"
rel="index">Index</a>]</p>
+</div>
+<span id="Transclude-source-file-into-src_002dblock-1"></span><h3
class="section">4.6 Transclude source file into src-block</h3>
+
+<span id="index-Transclude-into-Org_0027s-src_002dblock"></span>
+<span id="index-Property-_002d-_003asrc"></span>
+<span id="index-Property-_002d-_003arest"></span>
+
+<p>This feature is provided as an <a href="#Extensions">extension</a> (default
on).
+</p>
+<p>You can transclude a source file into an Org’s src block. Use the
‘<samp>:src</samp>’ property and specify the language you would
like to use like this:
+</p>
+<div class="example">
+<pre class="example">#+transclude: [[file:../../test/python-1.py]] :src python
+</pre></div>
+
+<p>The content you specify in the link gets wrapped into a src-block with the
language like this:
+</p>
+<div class="example">
+<pre class="example">#+begin_src python
+[... content of python-1.py]
+#+end_src
+</pre></div>
+
+<p>Use ‘<samp>:rest</samp>’ property to define additional
properties you would like to add for the src-block. The double quotation marks
are mandatory for the ‘<samp>:rest</samp>’ property.
+</p>
+<div class="example">
+<pre class="example">#+transclude: [[file:../../test/python-3.py]] :src
python :rest ":session :results value"
+</pre></div>
+
+<p>The source block will have the additional properties:
+</p><div class="example">
+<pre class="example">#+begin_src python :session :results value
+</pre></div>
+
+<hr>
+<span id="Transclude-range-of-lines-for-text-and-source-files"></span><div
class="header">
+<p>
+Next: <a href="#Extensions" accesskey="n" rel="next">Extensions</a>, Previous:
<a href="#Transclude-source-file-into-src_002dblock" accesskey="p"
rel="prev">Transclude source file into src-block</a>, Up: <a href="#Usage"
accesskey="u" rel="up">Usage</a> [<a href="#Index-_002d-Features"
title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="Transclude-range-of-lines-for-text-and-source-files-1"></span><h3
class="section">4.7 Transclude range of lines for text and source files</h3>
+
+<span id="index-Transclude-range-of-lines"></span>
+
+<p>This feature is provided as an <a href="#Extensions">extension</a> (default
on).
+</p>
+<p>When you transclude text files other than Org files,
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top">• <a
href="#lines-property-to-specify-a-range-of-lines"
accesskey="1">‘<samp>lines</samp>’ property to specify a range of
lines</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a
href="#end-property-to-specify-a-search-term-to-dynamically-look-for-the-end-of-a-range"
accesskey="2">‘<samp>end</samp>’ property to specify a search term
to dynamically look for the end of a range</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+</table>
+
+<hr>
+<span id="lines-property-to-specify-a-range-of-lines"></span><div
class="header">
+<p>
+Next: <a
href="#end-property-to-specify-a-search-term-to-dynamically-look-for-the-end-of-a-range"
accesskey="n" rel="next">‘<samp>end</samp>’ property to specify a
search term to dynamically look for the end of a range</a>, Up: <a
href="#Transclude-range-of-lines-for-text-and-source-files" accesskey="u"
rel="up">Transclude range of lines for text and source files</a> [<a
href="#Index-_002d-Features" title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="g_t_003alines-property-to-specify-a-range-of-lines"></span><h4
class="subsection">4.7.1 ‘<samp>:lines</samp>’ property to specify
a range of lines</h4>
+
+<span id="index-Property-_002d-_003alines"></span>
+
+<p>You can specify a range of lines to transclude from a source and text file.
Use the ‘<samp>:lines</samp>’ property like this.
+</p>
+<div class="example">
+<pre class="example">#+transclude: [[file:../../test/test.txt]] :lines 3-5
+</pre></div>
+
+<p>The rage is specified by the number "3-5"; in this case, lines
from 3 to 5, both lines inclusive.
+</p>
+<p>To transclude a single line, have the the same number in both places (e.g.
10-10, meaning line 10 only).
+</p>
+<p>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.
+</p>
+<p>You can combine the ‘<samp>:lines</samp>’ property with the
‘<samp>:src</samp>’ property to transclude only a certain range of
source files (Example 1 below).
+</p>
+<p>For Org’s file links, you can use <a
href="https://orgmode.org/manual/Search-Options.html";>search options</a>
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</samp>’ property.
+</p>
+<p>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).
+</p><div class="example">
+<pre class="example">#+transclude: [[file:../../test/python-1.py::id-1234]]
:lines 1-4 :src python
+</pre></div>
+
+<p>Example 2: This transcludes only the single line that contains the line
found by the search option for text string "Transcendental Ontology"
+</p><div class="example">
+<pre class="example">#+transclude: [[file:../../test/test.txt::Transcendental
Ontology]] :lines 1-1
+</pre></div>
+
+<p>Note search-options ‘<samp>::/regex/</samp>’ and
‘<samp>::number</samp>’ do not work as intended.
+</p>
+<hr>
+<span
id="end-property-to-specify-a-search-term-to-dynamically-look-for-the-end-of-a-range"></span><div
class="header">
+<p>
+Previous: <a href="#lines-property-to-specify-a-range-of-lines" accesskey="p"
rel="prev">‘<samp>lines</samp>’ property to specify a range of
lines</a>, Up: <a href="#Transclude-range-of-lines-for-text-and-source-files"
accesskey="u" rel="up">Transclude range of lines for text and source files</a>
[<a href="#Index-_002d-Features" title="Index" rel="index">Index</a>]</p>
+</div>
+<span
id="g_t_003aend-property-to-specify-a-search-term-to-dynamically-look-for-the-end-of-a-range"></span><h4
class="subsection">4.7.2 ‘<samp>:end</samp>’ property to specify a
search term to dynamically look for the end of a range</h4>
+
+<span id="index-Property-_002d-_003aend"></span>
+
+<p>You can add ‘<samp>:end</samp>’ property and specify the search
term as its value. Surround the search term with double quotation marks
(mandatory).
+</p>
+<p>See Example 3 below. This transclusion will look for
‘<samp>id-1234</samp>’ as the beginning line of the range as
specified by the search option ‘<samp>::id-1234</samp>’ in the
link. With the ‘<samp>:end</samp>’ property, the search term
‘<samp>id-1234 end here</samp>’ defines the end of the range. The
search looks for ‘<samp>id-123 end here</samp>’ in the body text,
and use the line one before the one where the text is find [...]
+</p>
+<p>You can also combined ‘<samp>:lines</samp>’ property with
‘<samp>:end</samp>’ 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 [...]
+</p>
+<p>Example 3:
+</p><div class="example">
+<pre class="example">#+transclude: [[file:../../test/python-1.py::id-1234]]
:lines 2- :src python :end "id-1234 end here"
+</pre></div>
+
+<hr>
+<span id="Extensions"></span><div class="header">
+<p>
+Previous: <a href="#Transclude-range-of-lines-for-text-and-source-files"
accesskey="p" rel="prev">Transclude range of lines for text and source
files</a>, Up: <a href="#Usage" accesskey="u" rel="up">Usage</a> [<a
href="#Index-_002d-Features" title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="Extensions-1"></span><h3 class="section">4.8 Extensions</h3>
+
+<span id="index-Extensions"></span>
+<span id="index-org_002dtransclusion_002dextensions"></span>
+<span
id="index-Extension-_002d-org_002dtransclusion_002dindent_002dmode"></span>
+<span id="index-Extension-_002d-org_002dtransclusion_002dsrc_002dlines"></span>
+<span id="index-Extension-_002d-org_002dtransclusion_002dfont_002dlock"></span>
+
+<p>Org-transclusion provides a simple extension framework, where you can use
‘<samp>customize</samp>’ to selectively add new features.
+</p>
+<p>If you use ‘<samp>customize</samp>’, the features are loaded
automatically. Note that it does not "unload" the feature until you
relaunch Emacs.
+</p>
+<p>If you do not use ‘<samp>customize</samp>’ (e.g. Doom), you may
need to explicitly require an extension. For example, to activate
‘<samp>org-transclusion-indent-mode</samp>’, you might need to add
something like this in your configuration file.
+</p>
+<div class="lisp">
+<pre class="lisp">;; Ensure that load-path to org-transclusion is already added
+;; If you installed it with the built-in package.el, this should be already
done.
+;; (add-to-list 'load-path "path/to/org-transclusion/")
+(add-to-list 'org-transclusion-extensions 'org-transclusion-indent-mode)
+(require 'org-transclusion-indent-mode)
+</pre></div>
+
+<p>Currently, the following extensions are available.
+</p>
+<dl compact="compact">
+<dt>(off by default)
‘<samp>org-transclusion-indent-mode</samp>’</dt>
+<dd><p>Support org-indent-mode.
+</p>
+</dd>
+<dt>(on by default) ‘<samp>org-transclusion-src-lines</samp>’</dt>
+<dd><p>Add features for ‘<samp>:src</samp>’ and
‘<samp>:lines</samp>’ properties to
‘<samp>#+transclude</samp>’. It is meant for non-Org files such as
program source and text files
+</p>
+</dd>
+<dt>(on by default) ‘<samp>org-transclusion-font-lock</samp>’</dt>
+<dd><p>Add font-lock for ‘<samp>#+transclude</samp>’. Org
mode’s standard syntax treats the combination of a
‘<samp>#+transclude:</samp>’ keyword and a link used by
Org-transclusion as a keyword. This means it applies the
‘<samp>org-meta-line</samp>’ face and the link part cannot be
toggled as a normal link. This extension adds
‘<samp>org-transclusion-keyword</samp>’ face to the keyword part
and lets the link part to be treated as a n [...]
+</p></dd>
+</dl>
+
+<hr>
+<span id="Customizing"></span><div class="header">
+<p>
+Next: <a href="#Known-Limitations" accesskey="n" rel="next">Known
Limitations</a>, Previous: <a href="#Usage" accesskey="p" rel="prev">Usage</a>,
Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a
href="#Index-_002d-Features" title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="Customizing-1"></span><h2 class="chapter">5 Customizing</h2>
+
+<span id="index-org_002dtransclusion_002dextensions-1"></span>
+<span
id="index-org_002dtransclusion_002dadd_002dall_002don_002dactivate-1"></span>
+<span id="index-org_002dtransclusion_002dmode_002dlighter"></span>
+<span
id="index-org_002dtransclusion_002dopen_002dsource_002ddisplay_002daction_002dlist"></span>
+
+<p>You can customize settings in the
‘<samp>org-transclusion</samp>’ group.
+</p>
+<dl compact="compact">
+<dt>‘<samp>org-transclusion-extensions</samp>’</dt>
+<dd><p>Defines extensions to be loaded with
+org-transclusion.el. If you use ‘<samp>customize</samp>’, the
extensions are loaded by it.
+If you don’t, you likely need to explicitly use
‘<samp>require</samp>’ to load them. See <a
href="#Extensions">seb-section</a>
+</p>
+</dd>
+<dt>‘<samp>org-transclusion-add-all-on-activate</samp>’</dt>
+<dd><p>Defines whether or not all the
+active transclusions (with ‘<samp>t</samp>’) get automatically
transcluded on minor mode
+activation (‘<samp>org-transclusion-mode</samp>’). This does not
affect the manual
+activation when you directly call
‘<samp>org-transclusion-activate</samp>’
+</p>
+</dd>
+<dt>‘<samp>org-transclusion-exclude-elements</samp>’</dt>
+<dd><p>See <a
href="#Customizable-filter-to-exclude-certain-Org-elements">sub-section</a>
+</p>
+</dd>
+<dt>‘<samp>org-transclusion-include-first-section</samp>’</dt>
+<dd><p>See <a
href="#Include-the-section-before-the-first-headline-_0028Org-file-only_0029">sub-section</a>
+</p>
+</dd>
+<dt>‘<samp>org-transclusion-open-source-display-action-list</samp>’</dt>
+<dd><p>You can customize the
+way the ‘<samp>org-transclusion-open-source</samp>’ function
displays the source buffer for
+the transclusion. You specify the "action" in the way defined by the
built-in
+‘<samp>display-buffer</samp>’ function. Refer to its in-system
documentation (with ‘<samp>C-h f</samp>’)
+for the accepted values. ‘<samp>M-x customize</samp>’ can also
guide you on what types of
+values are accepted.
+</p>
+</dd>
+<dt>‘<samp>org-transclusion-mode-lighter</samp>’</dt>
+<dd><p>Define the lighter for Org-transclusion
+minor mode. The default is " OT".
+</p></dd>
+</dl>
+
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top">• <a
href="#Customizable-filter-to-exclude-certain-Org-elements"
accesskey="1">Customizable filter to exclude certain Org
elements</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a
href="#Include-the-section-before-the-first-headline-_0028Org-file-only_0029"
accesskey="2">Include the section before the first headline (Org file
only)</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a href="#Faces-_0026-fringe-bitmap"
accesskey="3">Faces & fringe bitmap</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a href="#Keybindings"
accesskey="4">Keybindings</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+</table>
+
+<hr>
+<span id="Customizable-filter-to-exclude-certain-Org-elements"></span><div
class="header">
+<p>
+Next: <a
href="#Include-the-section-before-the-first-headline-_0028Org-file-only_0029"
accesskey="n" rel="next">Include the section before the first headline (Org
file only)</a>, Up: <a href="#Customizing" accesskey="u"
rel="up">Customizing</a> [<a href="#Index-_002d-Features" title="Index"
rel="index">Index</a>]</p>
+</div>
+<span id="Customizable-filter-to-exclude-certain-Org-elements-1"></span><h3
class="section">5.1 Customizable filter to exclude certain Org elements</h3>
+
+<span id="index-org_002dtransclusion_002dexclude_002delements-1"></span>
+
+<p>Set customizable variable
‘<samp>org-transclusion-exclude-elements</samp>’ to define which
elements to be <strong>excluded</strong> in the transclusion.
+</p>
+<p>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.
+</p>
+<p>It is a list of symbols, and the default is
‘<samp>(property-drawer)</samp>’. The accepted values are the ones
defined by ‘<samp>org-element-all-elements</samp>’ (Org’s
standard set of elements; refer to its documentation for an exhaustive list).
+</p>
+<p>You can also fine-tune the exclusion filter per transclusion. Refer to the
sub-section on <a href="#Filter-Org-elements-per-transclusion">filtering Org
elements per transclusion</a>.
+</p>
+<hr>
+<span
id="Include-the-section-before-the-first-headline-_0028Org-file-only_0029"></span><div
class="header">
+<p>
+Next: <a href="#Faces-_0026-fringe-bitmap" accesskey="n" rel="next">Faces
& fringe bitmap</a>, Previous: <a
href="#Customizable-filter-to-exclude-certain-Org-elements" accesskey="p"
rel="prev">Customizable filter to exclude certain Org elements</a>, Up: <a
href="#Customizing" accesskey="u" rel="up">Customizing</a> [<a
href="#Index-_002d-Features" title="Index" rel="index">Index</a>]</p>
+</div>
+<span
id="Include-the-section-before-the-first-headline-_0028Org-file-only_0029-1"></span><h3
class="section">5.2 Include the section before the first headline (Org file
only)</h3>
+
+<span
id="index-org_002dtransclusion_002dinclude_002dfirst_002dsection-1"></span>
+
+<p>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</samp>’. Its default
value is ‘<samp>t</samp>’. Set it to ‘<samp>t</samp>’
(or non-nil) to transclude the first section. It also works when the first
section is followed by headlines.
+</p>
+<hr>
+<span id="Faces-_0026-fringe-bitmap"></span><div class="header">
+<p>
+Next: <a href="#Keybindings" accesskey="n" rel="next">Keybindings</a>,
Previous: <a
href="#Include-the-section-before-the-first-headline-_0028Org-file-only_0029"
accesskey="p" rel="prev">Include the section before the first headline (Org
file only)</a>, Up: <a href="#Customizing" accesskey="u"
rel="up">Customizing</a> [<a href="#Index-_002d-Features" title="Index"
rel="index">Index</a>]</p>
+</div>
+<span id="Faces-_0026-fringe-bitmap-1"></span><h3 class="section">5.3 Faces
& fringe bitmap</h3>
+
+<span id="index-org_002dtransclusion_002dkeyword"></span>
+<span id="index-org_002dtransclusion_002dsource_002dfringe"></span>
+<span id="index-org_002dtransclusion_002dfringe"></span>
+<span id="index-org_002dtransclusion_002dsource"></span>
+<span id="index-org_002dtransclusion_002dsource_002dedit"></span>
+<span id="index-org_002dtransclusion"></span>
+<span id="index-org_002dtransclusion_002dedit"></span>
+<span id="index-org_002dtransclusion_002dfringe_002dbitmap"></span>
+
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top">• <a
href="#Face-for-the-_0023_002btransclude-keyword" accesskey="1">Face for the
‘<samp>#+transclude</samp>’
keyword</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a
href="#Faces-for-the-fringes-next-to-transcluded-region-and-source-region"
accesskey="2">Faces for the fringes next to transcluded region and source
region</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+</table>
+
+<hr>
+<span id="Face-for-the-_0023_002btransclude-keyword"></span><div
class="header">
+<p>
+Next: <a
href="#Faces-for-the-fringes-next-to-transcluded-region-and-source-region"
accesskey="n" rel="next">Faces for the fringes next to transcluded region and
source region</a>, Up: <a href="#Faces-_0026-fringe-bitmap" accesskey="u"
rel="up">Faces & fringe bitmap</a> [<a href="#Index-_002d-Features"
title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="Face-for-the-_0023_002btransclude-keyword-1"></span><h4
class="subsection">5.3.1 Face for the ‘<samp>#+transclude</samp>’
keyword</h4>
+
+<p>This feature is provided as an <a href="#Extensions">extension</a> (default
on).
+</p>
+<dl compact="compact">
+<dt>‘<samp>org-transclusion-keyword</samp>’</dt>
+<dd><p>You can set your own face to the
‘<samp>#+transclude</samp>’ keyword with using the
‘<samp>org-transclusion-keyword</samp>’ face.
+</p></dd>
+</dl>
+
+<hr>
+<span
id="Faces-for-the-fringes-next-to-transcluded-region-and-source-region"></span><div
class="header">
+<p>
+Previous: <a href="#Face-for-the-_0023_002btransclude-keyword" accesskey="p"
rel="prev">Face for the ‘<samp>#+transclude</samp>’ keyword</a>,
Up: <a href="#Faces-_0026-fringe-bitmap" accesskey="u" rel="up">Faces &
fringe bitmap</a> [<a href="#Index-_002d-Features" title="Index"
rel="index">Index</a>]</p>
+</div>
+<span
id="Faces-for-the-fringes-next-to-transcluded-region-and-source-region-1"></span><h4
class="subsection">5.3.2 Faces for the fringes next to transcluded region and
source region</h4>
+
+<p>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.
+</p>
+<ul>
+<li> ‘<samp>org-transclusion-source-fringe</samp>’
+</li><li> ‘<samp>org-transclusion-fringe</samp>’
+</li></ul>
+
+<p>To customize a face, it’s probably the easiest to use
‘<samp>M-x customize-face</samp>’. 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.
+</p>
+<div class="lisp">
+<pre class="lisp">(set-face-attribute
+ 'org-transclusion-fringe nil
+ :foreground "green"
+ :background "green")
+</pre></div>
+
+<p>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</samp>’.
+</p>
+<p>Other faces:
+</p><ul>
+<li> ‘<samp>org-transclusion-source</samp>’
+</li><li> ‘<samp>org-transclusion-source-edit</samp>’
+</li><li> ‘<samp>org-transclusion</samp>’
+</li><li> ‘<samp>org-transclusion-edit</samp>’
+</li><li> ‘<samp>org-transclusion-fringe-bitmap</samp>’
+It is used for the fringe that indicates the transcluded region. It works only
in a graphical environment (not in terminal).
+</li></ul>
+
+<hr>
+<span id="Keybindings"></span><div class="header">
+<p>
+Previous: <a href="#Faces-_0026-fringe-bitmap" accesskey="p" rel="prev">Faces
& fringe bitmap</a>, Up: <a href="#Customizing" accesskey="u"
rel="up">Customizing</a> [<a href="#Index-_002d-Features" title="Index"
rel="index">Index</a>]</p>
+</div>
+<span id="Keybindings-1"></span><h3 class="section">5.4 Keybindings</h3>
+
+<span id="index-org_002dtransclusion_002dmap-1"></span>
+<span id="index-org_002dtransclusion_002dlive_002dsync_002dmap-1"></span>
+
+<ul>
+<li> ‘<samp>org-transclusion-map</samp>’
+</li></ul>
+<ul>
+<li> ‘<samp>org-transclusion-live-sync-map</samp>’
+</li></ul>
+
+<hr>
+<span id="Known-Limitations"></span><div class="header">
+<p>
+Next: <a href="#Credits" accesskey="n" rel="next">Credits</a>, Previous: <a
href="#Customizing" accesskey="p" rel="prev">Customizing</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a
href="#Index-_002d-Features" title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="Known-Limitations-1"></span><h2 class="chapter">6 Known
Limitations</h2>
+
+<p>Note this section is still incomplete, not exhaustive for "known"
limitations.
+</p>
+<ul>
+<li> Org link’s search-options ‘<samp>::/regex/</samp>’ and
‘<samp>::number</samp>’ do not work as intended.
+
+</li><li> ‘<samp>org-transclusion-live-sync-start</samp>’ 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>’, ‘<samp>drawer</samp>’,
‘<samp>dynamic-block</samp>’,
‘<samp>latex-environment</samp>’,
‘<samp>paragraph</samp>’, ‘<samp>plain-list</samp>’,
‘<samp>quote-block</samp>’,
‘<samp>special-block</samp>’, ‘<samp>table</samp>’, and
‘<samp>verse-block</samp>’.
+
+<p>It is known that live-sync does not work for the other elements; namely:
+‘<samp>comment-block</samp>’,
‘<samp>export-block</samp>’,
‘<samp>example-block</samp>’,
‘<samp>fixed-width</samp>’, ‘<samp>keyword</samp>’,
‘<samp>src-block</samp>’, and
‘<samp>property-drawer</samp>’.
+</p>
+<p>More technical reason for this limitation is documented in the docstring of
function
‘<samp>org-transclusion-live-sync-enclosing-element</samp>’.
+</p>
+<p>Work is in progress to lift this limitation but I’m still
experimenting different ideas.
+</p>
+</li><li> ‘<samp>org-indent-mode</samp>’ may not work well with
Org-transclusion
+A new extension has been added to support
‘<samp>org-indent-mode</samp>’
+Refer to <a href="#Extensions">this section</a>.
+
+</li><li> Doom’s customization may interfere with Org-transclusion
+Refer to issue <a
href="https://github.com/nobiot/org-transclusion/issues/52";>#52</a>. 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:
+
+<p>‘<samp>(advice-remove 'org-link-search
'+org--recenter-after-follow-link-a)</samp>’
+</p>
+<p>It is probably rather drastic a measure. I will appreciate it if you find a
less drastic way that works. Thank you.
+</p>
+</li><li> Org refile does not work "properly" on the transcluded
headlines
+Refer to issue <a
href="https://github.com/nobiot/org-transclusion/issues/20";>#20</a>. I
don’t intend to support this – refile the source, not the
transcluded copy.
+
+</li><li> Org-transclusion does not support expansion of noweb references when
a transcluded source block code has them
+Refer to issue <a
href="https://github.com/nobiot/org-transclusion/issues/86";>#86</a>. You will
get "Text read-only" error when export tries to expand the noweb
references into the source code. †<a
href="https://orgmode.org/manual/Noweb-Reference-Syntax.html";>noweb
reference</a>
+</li></ul>
+
+<hr>
+<span id="Credits"></span><div class="header">
+<p>
+Next: <a href="#Contributing" accesskey="n" rel="next">Contributing</a>,
Previous: <a href="#Known-Limitations" accesskey="p" rel="prev">Known
Limitations</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a
href="#Index-_002d-Features" title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="Credits-1"></span><h2 class="chapter">7 Credits</h2>
+
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top">• <a
href="#Original-idea-by-John-Kitchin" accesskey="1">Original idea by John
Kitchin</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top">• <a href="#Text_002dClone"
accesskey="2">Text-Clone</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+</table>
+
+<hr>
+<span id="Original-idea-by-John-Kitchin"></span><div class="header">
+<p>
+Next: <a href="#Text_002dClone" accesskey="n" rel="next">Text-Clone</a>, Up:
<a href="#Credits" accesskey="u" rel="up">Credits</a> [<a
href="#Index-_002d-Features" title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="Original-idea-by-John-Kitchin-1"></span><h3 class="section">7.1
Original idea by John Kitchin</h3>
+
+<p><a
href="https://github.com/alphapapa/transclusion-in-emacs#org-mode";>https://github.com/alphapapa/transclusion-in-emacs#org-mode</a>
+</p>
+<blockquote>
+<p>{O} transcluding some org-elements in multiple places
+<em>[2016-12-09 ven.] </em> John Kitchin asks:
+</p>
+<p>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 c [...]
+</p>
+<p>This idea was inspired by <a
href="https://github.com/gregdetre/emacs-freex";>https://github.com/gregdetre/emacs-freex</a>.
+</p>
+<p>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:
+</p>
+<p>transclude:some-file.org::*headline title
+</p>
+<p>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).
+</p>
+<p>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).
+</p>
+<p>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.
+</p>
+</blockquote>
+
+<hr>
+<span id="Text_002dClone"></span><div class="header">
+<p>
+Previous: <a href="#Original-idea-by-John-Kitchin" accesskey="p"
rel="prev">Original idea by John Kitchin</a>, Up: <a href="#Credits"
accesskey="u" rel="up">Credits</a> [<a href="#Index-_002d-Features"
title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="Text_002dClone-1"></span><h3 class="section">7.2 Text-Clone</h3>
+
+<p>‘<samp>text-clone.el</samp>’ is an extension of text-clone
functions written as part of GNU Emacs in ‘<samp>subr.el</samp>’.
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 <a
href="https://emacs.stackexchange.com/questions/56201/is-there-an-emacs-package-which-can-mirror-a-region/56202#56202";>https://emacs.stackexchange.com/questions/56201/is-the
[...]
+</p>
+<hr>
+<span id="Contributing"></span><div class="header">
+<p>
+Next: <a href="#Index-_002d-Features" accesskey="n" rel="next">Index -
Features</a>, Previous: <a href="#Credits" accesskey="p"
rel="prev">Credits</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a>
[<a href="#Index-_002d-Features" title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="Contributing-1"></span><h2 class="chapter">8 Contributing</h2>
+
+<ul>
+<li> Get involved in a discussion in <a
href="https://org-roam.discourse.group/t/prototype-transclusion-block-reference-with-emacs-org-mode/830";>Org-roam
forum</a> (the package is originally aimed for its users, me included)
+
+</li><li> Create issues, discussion, and/or pull requests. All welcome.
+</li></ul>
+
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top">• <a
href="#Notes-on-pull-requests-and-Free-Software-Foundation-_0028FSF_0029-copy-right-assignment"
accesskey="1">Notes on pull requests and Free Software Foundation (FSF) copy
right assignment</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+</table>
+
+<hr>
+<span
id="Notes-on-pull-requests-and-Free-Software-Foundation-_0028FSF_0029-copy-right-assignment"></span><div
class="header">
+<p>
+Up: <a href="#Contributing" accesskey="u" rel="up">Contributing</a> [<a
href="#Index-_002d-Features" title="Index" rel="index">Index</a>]</p>
+</div>
+<span
id="Notes-on-pull-requests-and-Free-Software-Foundation-_0028FSF_0029-copy-right-assignment-1"></span><h3
class="section">8.1 Notes on pull requests and Free Software Foundation (FSF)
copy right assignment</h3>
+
+<p>Org-transclusion is part of GNU ELPA and thus copyrighted by the <a
href="http://fsf.org";>Free Software Foundation</a> (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" (<a href="https://orgmode.org/contribute.html#copyright";>Org
Mode website</a>).
+</p>
+<p>Thank you.
+</p>
+<hr>
+<span id="Index-_002d-Features"></span><div class="header">
+<p>
+Next: <a href="#Index-_002d-Commands" accesskey="n" rel="next">Index -
Commands</a>, Previous: <a href="#Contributing" accesskey="p"
rel="prev">Contributing</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a>
[<a href="#Index-_002d-Features" title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="Index-_002d-Features-1"></span><h2 class="appendix">Appendix A Index
- Features</h2>
+
+<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter"
href="#Index-_002d-Features_cp_letter-A"><b>A</b></a>
+
+<a class="summary-letter" href="#Index-_002d-Features_cp_letter-E"><b>E</b></a>
+
+<a class="summary-letter" href="#Index-_002d-Features_cp_letter-F"><b>F</b></a>
+
+<a class="summary-letter" href="#Index-_002d-Features_cp_letter-L"><b>L</b></a>
+
+<a class="summary-letter" href="#Index-_002d-Features_cp_letter-O"><b>O</b></a>
+
+<a class="summary-letter" href="#Index-_002d-Features_cp_letter-P"><b>P</b></a>
+
+<a class="summary-letter" href="#Index-_002d-Features_cp_letter-T"><b>T</b></a>
+
+</td></tr></table>
+<table class="index-cp" border="0">
+<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left">
Section</th></tr>
+<tr><td colspan="4"> <hr></td></tr>
+<tr><th id="Index-_002d-Features_cp_letter-A">A</th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-Activate-_002f-Deactivate">Activate /
Deactivate</a>:</td><td> </td><td valign="top"><a
href="#Org_002dtransclusion-mode-activate-and-deactivate">Org-transclusion mode
activate and deactivate</a></td></tr>
+<tr><td colspan="4"> <hr></td></tr>
+<tr><th id="Index-_002d-Features_cp_letter-E">E</th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-Extension-_002d-org_002dtransclusion_002dfont_002dlock">Extension
- org-transclusion-font-lock</a>:</td><td> </td><td valign="top"><a
href="#Extensions">Extensions</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-Extension-_002d-org_002dtransclusion_002dindent_002dmode">Extension
- org-transclusion-indent-mode</a>:</td><td> </td><td valign="top"><a
href="#Extensions">Extensions</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-Extension-_002d-org_002dtransclusion_002dsrc_002dlines">Extension
- org-transclusion-src-lines</a>:</td><td> </td><td valign="top"><a
href="#Extensions">Extensions</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-Extensions">Extensions</a>:</td><td> </td><td valign="top"><a
href="#Extensions">Extensions</a></td></tr>
+<tr><td colspan="4"> <hr></td></tr>
+<tr><th id="Index-_002d-Features_cp_letter-F">F</th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-Filters">Filters</a>:</td><td> </td><td valign="top"><a
href="#Filter-Org-elements-per-transclusion">Filter Org elements per
transclusion</a></td></tr>
+<tr><td colspan="4"> <hr></td></tr>
+<tr><th id="Index-_002d-Features_cp_letter-L">L</th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#index-Live_002dsync-edit">Live-sync
edit</a>:</td><td> </td><td valign="top"><a
href="#Live_002dsync-edit">Live-sync edit</a></td></tr>
+<tr><td colspan="4"> <hr></td></tr>
+<tr><th id="Index-_002d-Features_cp_letter-O">O</th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#index-Org-Links-Supported">Org Links
Supported</a>:</td><td> </td><td valign="top"><a
href="#Org-links-supported">Org links supported</a></td></tr>
+<tr><td colspan="4"> <hr></td></tr>
+<tr><th id="Index-_002d-Features_cp_letter-P">P</th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-Property-_002d-_003adisable_002dauto">Property -
:disable-auto</a>:</td><td> </td><td valign="top"><a
href="#Org_002dtransclusion-mode-activate-and-deactivate">Org-transclusion mode
activate and deactivate</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-Property-_002d-_003aend">Property -
:end</a>:</td><td> </td><td valign="top"><a
href="#end-property-to-specify-a-search-term-to-dynamically-look-for-the-end-of-a-range">‘<samp>end</samp>’
property to specify a search term to dynamically look for the end of a
range</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-Property-_002d-_003alevel">Property -
:level</a>:</td><td> </td><td valign="top"><a
href="#Control-levels-of-headlines-per-transclusion">Control levels of
headlines per transclusion</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-Property-_002d-_003alines">Property -
:lines</a>:</td><td> </td><td valign="top"><a
href="#lines-property-to-specify-a-range-of-lines">‘<samp>lines</samp>’
property to specify a range of lines</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-Property-_002d-_003aonly_002dcontent">Property -
:only-content</a>:</td><td> </td><td valign="top"><a
href="#Filter-Org-elements-per-transclusion">Filter Org elements per
transclusion</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-Property-_002d-_003aonly_002dcontents">Property -
:only-contents</a>:</td><td> </td><td valign="top"><a
href="#Org-links-supported">Org links supported</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-Property-_002d-_003arest">Property -
:rest</a>:</td><td> </td><td valign="top"><a
href="#Transclude-source-file-into-src_002dblock">Transclude source file into
src-block</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-Property-_002d-_003asrc">Property -
:src</a>:</td><td> </td><td valign="top"><a
href="#Transclude-source-file-into-src_002dblock">Transclude source file into
src-block</a></td></tr>
+<tr><td colspan="4"> <hr></td></tr>
+<tr><th id="Index-_002d-Features_cp_letter-T">T</th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-Transclude-into-Org_0027s-src_002dblock">Transclude into
Org’s src-block</a>:</td><td> </td><td valign="top"><a
href="#Transclude-source-file-into-src_002dblock">Transclude source file into
src-block</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-Transclude-range-of-lines">Transclude range of
lines</a>:</td><td> </td><td valign="top"><a
href="#Transclude-range-of-lines-for-text-and-source-files">Transclude range of
lines for text and source files</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-Transclusion-Properties">Transclusion
Properties</a>:</td><td> </td><td valign="top"><a
href="#Org_002dtransclusion-mode-activate-and-deactivate">Org-transclusion mode
activate and deactivate</a></td></tr>
+<tr><td colspan="4"> <hr></td></tr>
+</table>
+<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter"
href="#Index-_002d-Features_cp_letter-A"><b>A</b></a>
+
+<a class="summary-letter" href="#Index-_002d-Features_cp_letter-E"><b>E</b></a>
+
+<a class="summary-letter" href="#Index-_002d-Features_cp_letter-F"><b>F</b></a>
+
+<a class="summary-letter" href="#Index-_002d-Features_cp_letter-L"><b>L</b></a>
+
+<a class="summary-letter" href="#Index-_002d-Features_cp_letter-O"><b>O</b></a>
+
+<a class="summary-letter" href="#Index-_002d-Features_cp_letter-P"><b>P</b></a>
+
+<a class="summary-letter" href="#Index-_002d-Features_cp_letter-T"><b>T</b></a>
+
+</td></tr></table>
+
+<hr>
+<span id="Index-_002d-Commands"></span><div class="header">
+<p>
+Next: <a href="#Index-_002d-User-Options" accesskey="n" rel="next">Index -
User Options</a>, Previous: <a href="#Index-_002d-Features" accesskey="p"
rel="prev">Index - Features</a>, Up: <a href="#Top" accesskey="u"
rel="up">Top</a> [<a href="#Index-_002d-Features" title="Index"
rel="index">Index</a>]</p>
+</div>
+<span id="Index-_002d-Commands-1"></span><h2 class="appendix">Appendix B Index
- Commands</h2>
+
+<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter"
href="#Index-_002d-Commands_fn_letter-O"><b>O</b></a>
+
+</td></tr></table>
+<table class="index-fn" border="0">
+<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left">
Section</th></tr>
+<tr><td colspan="4"> <hr></td></tr>
+<tr><th id="Index-_002d-Commands_fn_letter-O">O</th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dactivate"><code>org-transclusion-activate</code></a>:</td><td> </td><td
valign="top"><a
href="#Org_002dtransclusion-mode-activate-and-deactivate">Org-transclusion mode
activate and deactivate</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dadd"><code>org-transclusion-add</code></a>:</td><td> </td><td
valign="top"><a href="#Getting-Started">Getting Started</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dadd_002dall"><code>org-transclusion-add-all</code></a>:</td><td> </td><td
valign="top"><a href="#Getting-Started">Getting Started</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002ddeactivate"><code>org-transclusion-deactivate</code></a>:</td><td> </td><td
valign="top"><a
href="#Org_002dtransclusion-mode-activate-and-deactivate">Org-transclusion mode
activate and deactivate</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002ddemote_002dsubtree"><code>org-transclusion-demote-subtree</code></a>:</td><td> </td><td
valign="top"><a href="#Control-levels-of-headlines-per-transclusion">Control
levels of headlines per transclusion</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dlive_002dsync_002dexit"><code>org-transclusion-live-sync-exit</code></a>:</td><td> </td><td
valign="top"><a href="#Live_002dsync-edit">Live-sync edit</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dlive_002dsync_002dpaste"><code>org-transclusion-live-sync-paste</code></a>:</td><td> </td><td
valign="top"><a href="#Live_002dsync-edit">Live-sync edit</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dlive_002dsync_002dstart"><code>org-transclusion-live-sync-start</code></a>:</td><td> </td><td
valign="top"><a href="#Live_002dsync-edit">Live-sync edit</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dmake_002dfrom_002dlink"><code>org-transclusion-make-from-link</code></a>:</td><td> </td><td
valign="top"><a href="#Getting-Started">Getting Started</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dmake_002dfrom_002dlink-1"><code>org-transclusion-make-from-link</code></a>:</td><td> </td><td
valign="top"><a href="#Control-levels-of-headlines-per-transclusion">Control
levels of headlines per transclusion</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dmode"><code>org-transclusion-mode</code></a>:</td><td> </td><td
valign="top"><a
href="#Org_002dtransclusion-mode-activate-and-deactivate">Org-transclusion mode
activate and deactivate</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dmove_002dto_002dsource"><code>org-transclusion-move-to-source</code></a>:</td><td> </td><td
valign="top"><a href="#Getting-Started">Getting Started</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dopen_002dsource"><code>org-transclusion-open-source</code></a>:</td><td> </td><td
valign="top"><a href="#Getting-Started">Getting Started</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dpromote_002dsubtree"><code>org-transclusion-promote-subtree</code></a>:</td><td> </td><td
valign="top"><a href="#Control-levels-of-headlines-per-transclusion">Control
levels of headlines per transclusion</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002drefresh"><code>org-transclusion-refresh</code></a>:</td><td> </td><td
valign="top"><a href="#Getting-Started">Getting Started</a></td></tr>
+<tr><td colspan="4"> <hr></td></tr>
+</table>
+<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter"
href="#Index-_002d-Commands_fn_letter-O"><b>O</b></a>
+
+</td></tr></table>
+
+<hr>
+<span id="Index-_002d-User-Options"></span><div class="header">
+<p>
+Next: <a href="#GNU-Free-Documentation-License" accesskey="n" rel="next">GNU
Free Documentation License</a>, Previous: <a href="#Index-_002d-Commands"
accesskey="p" rel="prev">Index - Commands</a>, Up: <a href="#Top" accesskey="u"
rel="up">Top</a> [<a href="#Index-_002d-Features" title="Index"
rel="index">Index</a>]</p>
+</div>
+<span id="Index-_002d-User-Options-1"></span><h2 class="appendix">Appendix C
Index - User Options</h2>
+
+<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter"
href="#Index-_002d-User-Options_vr_letter-O"><b>O</b></a>
+
+</td></tr></table>
+<table class="index-vr" border="0">
+<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left">
Section</th></tr>
+<tr><td colspan="4"> <hr></td></tr>
+<tr><th id="Index-_002d-User-Options_vr_letter-O">O</th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion"><code>org-transclusion</code></a>:</td><td> </td><td
valign="top"><a href="#Faces-_0026-fringe-bitmap">Faces & fringe
bitmap</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dadd_002dall_002don_002dactivate"><code>org-transclusion-add-all-on-activate</code></a>:</td><td> </td><td
valign="top"><a
href="#Org_002dtransclusion-mode-activate-and-deactivate">Org-transclusion mode
activate and deactivate</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dadd_002dall_002don_002dactivate-1"><code>org-transclusion-add-all-on-activate</code></a>:</td><td> </td><td
valign="top"><a href="#Customizing">Customizing</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dedit"><code>org-transclusion-edit</code></a>:</td><td> </td><td
valign="top"><a href="#Faces-_0026-fringe-bitmap">Faces & fringe
bitmap</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dexclude_002delements"><code>org-transclusion-exclude-elements</code></a>:</td><td> </td><td
valign="top"><a href="#Filter-Org-elements-per-transclusion">Filter Org
elements per transclusion</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dexclude_002delements-1"><code>org-transclusion-exclude-elements</code></a>:</td><td> </td><td
valign="top"><a
href="#Customizable-filter-to-exclude-certain-Org-elements">Customizable filter
to exclude certain Org elements</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dextensions"><code>org-transclusion-extensions</code></a>:</td><td> </td><td
valign="top"><a href="#Extensions">Extensions</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dextensions-1"><code>org-transclusion-extensions</code></a>:</td><td> </td><td
valign="top"><a href="#Customizing">Customizing</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dfringe"><code>org-transclusion-fringe</code></a>:</td><td> </td><td
valign="top"><a href="#Faces-_0026-fringe-bitmap">Faces & fringe
bitmap</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dfringe_002dbitmap"><code>org-transclusion-fringe-bitmap</code></a>:</td><td> </td><td
valign="top"><a href="#Faces-_0026-fringe-bitmap">Faces & fringe
bitmap</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dinclude_002dfirst_002dsection"><code>org-transclusion-include-first-section</code></a>:</td><td> </td><td
valign="top"><a href="#Filter-Org-elements-per-transclusion">Filter Org
elements per transclusion</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dinclude_002dfirst_002dsection-1"><code>org-transclusion-include-first-section</code></a>:</td><td> </td><td
valign="top"><a
href="#Include-the-section-before-the-first-headline-_0028Org-file-only_0029">Include
the section before the first headline (Org file only)</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dkeyword"><code>org-transclusion-keyword</code></a>:</td><td> </td><td
valign="top"><a href="#Faces-_0026-fringe-bitmap">Faces & fringe
bitmap</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dlive_002dsync_002dmap"><code>org-transclusion-live-sync-map</code></a>:</td><td> </td><td
valign="top"><a href="#Live_002dsync-edit">Live-sync edit</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dlive_002dsync_002dmap-1"><code>org-transclusion-live-sync-map</code></a>:</td><td> </td><td
valign="top"><a href="#Keybindings">Keybindings</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dmap"><code>org-transclusion-map</code></a>:</td><td> </td><td
valign="top"><a href="#Getting-Started">Getting Started</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dmap-1"><code>org-transclusion-map</code></a>:</td><td> </td><td
valign="top"><a href="#Keybindings">Keybindings</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dmode_002dlighter"><code>org-transclusion-mode-lighter</code></a>:</td><td> </td><td
valign="top"><a href="#Customizing">Customizing</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dopen_002dsource_002ddisplay_002daction_002dlist"><code>org-transclusion-open-source-display-action-list</code></a>:</td><td> </td><td
valign="top"><a href="#Customizing">Customizing</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dsource"><code>org-transclusion-source</code></a>:</td><td> </td><td
valign="top"><a href="#Faces-_0026-fringe-bitmap">Faces & fringe
bitmap</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dsource_002dedit"><code>org-transclusion-source-edit</code></a>:</td><td> </td><td
valign="top"><a href="#Faces-_0026-fringe-bitmap">Faces & fringe
bitmap</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-org_002dtransclusion_002dsource_002dfringe"><code>org-transclusion-source-fringe</code></a>:</td><td> </td><td
valign="top"><a href="#Faces-_0026-fringe-bitmap">Faces & fringe
bitmap</a></td></tr>
+<tr><td colspan="4"> <hr></td></tr>
+</table>
+<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter"
href="#Index-_002d-User-Options_vr_letter-O"><b>O</b></a>
+
+</td></tr></table>
+
+<hr>
+<span id="GNU-Free-Documentation-License"></span><div class="header">
+<p>
+Previous: <a href="#Index-_002d-User-Options" accesskey="p" rel="prev">Index -
User Options</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a
href="#Index-_002d-Features" title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="GNU-Free-Documentation-License-1"></span><h2
class="appendix">Appendix D GNU Free Documentation License</h2>
+
+<div align="center">Version 1.3, 3 November 2008
+</div>
+
+<div class="display">
+<pre class="display">Copyright © 2000, 2001, 2002, 2007, 2008 Free
Software Foundation, Inc.
+<a href="https://fsf.org/";>https://fsf.org/</a>
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+</pre></div>
+
+<ol start="0">
+<li> PREAMBLE
+
+<p>The purpose of this License is to make a manual, textbook, or other
+functional and useful document <em>free</em> in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+</p>
+<p>This License is a kind of “copyleft”, which means that
derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+</p>
+<p>We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+</p>
+</li><li> APPLICABILITY AND DEFINITIONS
+
+<p>This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The “Document”, below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as “you”. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+</p>
+<p>A “Modified Version” of the Document means any work containing
the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+</p>
+<p>A “Secondary Section” is a named appendix or a front-matter
section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document’s overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject. (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+</p>
+<p>The “Invariant Sections” are certain Secondary Sections whose
titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+</p>
+<p>The “Cover Texts” are certain short passages of text that are
listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+</p>
+<p>A “Transparent” copy of the Document means a machine-readable
copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not “Transparent” is called
“Opaque”.
+</p>
+<p>Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input
+format, SGML or XML using a publicly available
+DTD, and standard-conforming simple HTML,
+PostScript or PDF designed for human modification. Examples
+of transparent image formats include PNG, XCF and
+JPG. Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, SGML or
+XML for which the DTD and/or processing tools are
+not generally available, and the machine-generated HTML,
+PostScript or PDF produced by some word processors for
+output purposes only.
+</p>
+<p>The “Title Page” means, for a printed book, the title page
itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, “Title Page”
means
+the text near the most prominent appearance of the work’s title,
+preceding the beginning of the body of the text.
+</p>
+<p>The “publisher” means any person or entity that distributes
copies
+of the Document to the public.
+</p>
+<p>A section “Entitled XYZ” means a named subunit of the Document
whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as “Acknowledgements”,
+“Dedications”, “Endorsements”, or
“History”.) To “Preserve the Title”
+of such a section when you modify the Document means that it remains a
+section “Entitled XYZ” according to this definition.
+</p>
+<p>The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+</p>
+</li><li> VERBATIM COPYING
+
+<p>You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+</p>
+<p>You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+</p>
+</li><li> COPYING IN QUANTITY
+
+<p>If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document’s license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+</p>
+<p>If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+</p>
+<p>If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+</p>
+<p>It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+</p>
+</li><li> MODIFICATIONS
+
+<p>You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+</p>
+<ol type="A" start="1">
+<li> Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+</li><li> List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
+</li><li> State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+</li><li> Preserve all the copyright notices of the Document.
+
+</li><li> Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+</li><li> Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+</li><li> Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document’s license notice.
+
+</li><li> Include an unaltered copy of this License.
+
+</li><li> Preserve the section Entitled “History”, Preserve its
Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section Entitled “History” in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+</li><li> Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the “History” section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+</li><li> For any section Entitled “Acknowledgements” or
“Dedications”, Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
+
+</li><li> Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
+</li><li> Delete any section Entitled “Endorsements”. Such a
section
+may not be included in the Modified Version.
+
+</li><li> Do not retitle any existing section to be Entitled
“Endorsements” or
+to conflict in title with any Invariant Section.
+
+</li><li> Preserve any Warranty Disclaimers.
+</li></ol>
+
+<p>If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version’s license notice.
+These titles must be distinct from any other section titles.
+</p>
+<p>You may add a section Entitled “Endorsements”, provided it
contains
+nothing but endorsements of your Modified Version by various
+parties—for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+</p>
+<p>You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+</p>
+<p>The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+</p>
+</li><li> COMBINING DOCUMENTS
+
+<p>You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+</p>
+<p>The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+</p>
+<p>In the combination, you must combine any sections Entitled
“History”
+in the various original documents, forming one section Entitled
+“History”; likewise combine any sections Entitled
“Acknowledgements”,
+and any sections Entitled “Dedications”. You must delete all
+sections Entitled “Endorsements.”
+</p>
+</li><li> COLLECTIONS OF DOCUMENTS
+
+<p>You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+</p>
+<p>You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+</p>
+</li><li> AGGREGATION WITH INDEPENDENT WORKS
+
+<p>A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an “aggregate” if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation’s users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+</p>
+<p>If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document’s Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+</p>
+</li><li> TRANSLATION
+
+<p>Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+</p>
+<p>If a section in the Document is Entitled “Acknowledgements”,
+“Dedications”, or “History”, the requirement (section
4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+</p>
+</li><li> TERMINATION
+
+<p>You may not copy, modify, sublicense, or distribute the Document
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense, or distribute it is void, and
+will automatically terminate your rights under this License.
+</p>
+<p>However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+</p>
+<p>Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+</p>
+<p>Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License. If your rights have been terminated and not permanently
+reinstated, receipt of a copy of some or all of the same material does
+not give you any rights to use it.
+</p>
+</li><li> FUTURE REVISIONS OF THIS LICENSE
+
+<p>The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+<a href="https://www.gnu.org/licenses/";>https://www.gnu.org/licenses/</a>.
+</p>
+<p>Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License “or any later version” applies to it, you have the option
of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation. If the Document
+specifies that a proxy can decide which future versions of this
+License can be used, that proxy’s public statement of acceptance of a
+version permanently authorizes you to choose that version for the
+Document.
+</p>
+</li><li> RELICENSING
+
+<p>“Massive Multiauthor Collaboration Site” (or “MMC
Site”) means any
+World Wide Web server that publishes copyrightable works and also
+provides prominent facilities for anybody to edit those works. A
+public wiki that anybody can edit is an example of such a server. A
+“Massive Multiauthor Collaboration” (or “MMC”)
contained in the
+site means any set of copyrightable works thus published on the MMC
+site.
+</p>
+<p>“CC-BY-SA” means the Creative Commons Attribution-Share Alike
3.0
+license published by Creative Commons Corporation, a not-for-profit
+corporation with a principal place of business in San Francisco,
+California, as well as future copyleft versions of that license
+published by that same organization.
+</p>
+<p>“Incorporate” means to publish or republish a Document, in
whole or
+in part, as part of another Document.
+</p>
+<p>An MMC is “eligible for relicensing” if it is licensed under
this
+License, and if all works that were first published under this License
+somewhere other than this MMC, and subsequently incorporated in whole
+or in part into the MMC, (1) had no cover texts or invariant sections,
+and (2) were thus incorporated prior to November 1, 2008.
+</p>
+<p>The operator of an MMC Site may republish an MMC contained in the site
+under CC-BY-SA on the same site at any time before August 1, 2009,
+provided the MMC is eligible for relicensing.
+</p>
+</li></ol>
+
+<span id="ADDENDUM_003a-How-to-use-this-License-for-your-documents"></span><h3
class="heading">ADDENDUM: How to use this License for your documents</h3>
+
+<p>To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+</p>
+<div class="example">
+<pre class="example"> Copyright (C) <var>year</var> <var>your name</var>.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.3
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ Texts. A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
+</pre></div>
+
+<p>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the “with…Texts.” line with this:
+</p>
+<div class="example">
+<pre class="example"> with the Invariant Sections being <var>list their
titles</var>, with
+ the Front-Cover Texts being <var>list</var>, and with the Back-Cover Texts
+ being <var>list</var>.
+</pre></div>
+
+<p>If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+</p>
+<p>If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+</p>
+
+<hr>
+
+
+
+</body>
+</html>
diff --git a/docs/resources/manual.css b/docs/resources/manual.css
new file mode 100644
index 0000000..ad7af47
--- /dev/null
+++ b/docs/resources/manual.css
@@ -0,0 +1,71 @@
+/** Based on Org-roam's css
+ https://github.com/org-roam/org-roam/blob/master/doc/assets/page.css
+ **/
+:root {
+ --border: #526980;
+ --code: #007;
+}
+
+body {
+ margin: 5ex 10ex;
+ max-width: 80ex;
+ line-height: 1.5;
+ font-family: sans-serif;
+}
+
+h1, h2, h3 {
+ font-weight: normal;
+}
+
+pre, code {
+ font-family: x, monospace;
+}
+
+pre {
+ padding: 1ex;
+ background: #eee;
+ border: solid 1px #ddd;
+ min-width: 0;
+ font-size: 80%;
+ overflow: auto;
+}
+
+code {
+ color: var(--code);
+}
+
+img {
+ max-width: 100%;
+}
+
+table {
+ border-collapse: collapse;
+ width: 100%;
+}
+
+pre.menu-comment {
+ background: none;
+ border: none;
+ font-family: sans-serif;
+ padding: 0;
+ margin: 0;
+ font-size: 100%;
+}
+
+thead {
+ border-bottom: 1px solid var(--border);
+}
+
+tfoot {
+ border-top: 1px solid var(--border);
+}
+
+blockquote {
+ margin-left: 1rem;
+ font-style: italic;
+ font-family: serif;
+ border-left: 3px solid;
+ border-left-color: currentcolor;
+ border-color: var(--text-color);
+ padding-left: 1em;
+}
diff --git a/org-transclusion.info b/org-transclusion.info
new file mode 100644
index 0000000..6a63535
--- /dev/null
+++ b/org-transclusion.info
@@ -0,0 +1,1689 @@
+This is org-transclusion.info, produced by makeinfo version 6.7 from
+org-transclusion.texi.
+
+Copyright (C) 2021 Free Software Foundation, Inc.
+
+ 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.”
+
+INFO-DIR-SECTION Emacs
+START-INFO-DIR-ENTRY
+* Org-transclusion: (org-transclusion). Transclusion in Org mode.
+END-INFO-DIR-ENTRY
+
+
+File: org-transclusion.info, Node: Top, Next: Example Use Cases & Main
Features, Up: (dir)
+
+Org-transclusion User Manual
+****************************
+
+
+ This manual is for Org-transclusion version 1.0.x.
+
+ last updated 23 December 2021.
+
+ 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.
+
+ Copyright (C) 2021 Free Software Foundation, Inc.
+
+ 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.”
+
+* Menu:
+
+* Example Use Cases & Main Features::
+* Installation::
+* Getting Started::
+* Usage::
+* Customizing::
+* Known Limitations::
+* Credits::
+* Contributing::
+* Index - Features:: Key concepts & features
+* Index - Commands:: Interactive functions
+* Index - User Options:: Customizable variables & faces
+* GNU Free Documentation License::
+
+— The Detailed Node Listing —
+
+Usage
+
+* Org-transclusion mode, activate, and deactivate: Org-transclusion mode
activate and deactivate.
+* Org links supported::
+* Control levels of headlines per transclusion::
+* Filter Org elements per transclusion::
+* 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
+
+* lines property to specify a range of lines::
+* 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 #+transclude keyword::
+* Faces for the fringes next to transcluded region and source region::
+
+Credits
+
+* Original idea by John Kitchin::
+* Text-Clone::
+
+Contributing
+
+* Notes on pull requests and Free Software Foundation (FSF) copy right
assignment::
+
+
+
+File: org-transclusion.info, Node: Example Use Cases & Main Features, Next:
Installation, Prev: Top, Up: Top
+
+1 Example Use Cases & Main Features
+***********************************
+
+Example Use Cases:
+
+Book writing
+ You have a collection of notes. You can quickly transclude
+ paragraphs and sections from them into a draft. As they are links,
+ it’s easy to re-organize them into different sequences to see which
+ way works the best.
+
+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.
+
+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.
+
+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.
+
+ Main Features:
+
+ • Insert a copy of text content via a file link or ID link into an
+ Org file
+
+ • Work with any text file such as program source cod, plain text,
+ Markdown, or other Org files
+
+ • Keep the file system clear of the copies of text content –
+ Org-transclusion tries hard to save only the links to the file
+ system
+
+ • For Org files, use different headline levels from the source Org
+ file
+
+ • For Org files, use filters to include only relevant elements (e.g.
+ filter out properties in the transclusions)
+
+ • 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
+
+ • For program source files, transclude parts or whole code directly
+ into Org’s source block to leverage the rich Org features
+
+ • Extend Org-transclusion with its extension framework
+
+
+File: org-transclusion.info, Node: Installation, Next: Getting Started,
Prev: Example Use Cases & Main Features, Up: Top
+
+2 Installation
+**************
+
+This package is available on GNU ELPA
+(https://elpa.gnu.org/packages/org-transclusion.html). You can do ‘M-x
+package-install RET org-transclusion’ to install it. After
+installation, you can start using Org-transclusion (refer to the *note
+Getting Started:: section). You can define keybindings in your
+configuration like this below.
+
+ (define-key global-map (kbd "<f12>") #'org-transclusion-add)
+ (define-key global-map (kbd "C-n t") #'org-transclusion-mode)
+
+ If you use Doom, you can do something like this below to install the
+package. Then add ‘use-package!’ to load the package in your
+‘config.el’ like an example below.
+
+ ;; ~/.doom.d/package.el
+ (package! org-transclusion)
+
+ ;; ~/.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))
+
+
+File: org-transclusion.info, Node: Getting Started, Next: Usage, Prev:
Installation, Up: Top
+
+3 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 transclusion.
+
+ To transclude content via a link, use one of the following commands:
+
+ • ‘org-transclusion-add’
+
+ • ‘org-transclusion-add-all’
+
+ • ‘org-transclusion-make-from-link’
+
+ For example, if you have an ID link in your Org file like this:
+
+ [[id:20210501T171427.051019][Bertrand Russell]]
+
+ Simply type to add ‘#+transclude:’ in front of the link like the
+example below.
+
+ #+transclude: [[id:20210501T171427.051019][Bertrand Russell]]
+
+ Put your cursor somewhere on this keyword line and type ‘M-x
+org-transclusion-add RET’, and you will see the text content that the ID
+points replace the whole line. If you have multiple links with a
+transclude keyword, you can type ‘M-x org-transclusion-add-all RET’ to
+do all transclusions in the current buffer.
+
+ Alternatively, you can also put cursor somewhere on the link and call
+‘M-x org-transclusion-make-from-link’. That will insert another line
+with ‘#+transclusion:’ keyword appended in front of a copy of the
+original link in the next empty line.
+
+ The transcluded text is *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 ‘o’ to open the source buffer of the
+transclusion at point, or ‘O’ (capital "o") to open and move to it.
+Press ‘g’ to refresh the transclusion. Press ‘e’ to start live-sync
+edit. For more detail, inspect the documentation of each command.
+Press ‘d’ to remove the transcluded content, putting the original
+‘#+transclude: [[id:id-of-the-content]]’.
+
+ This single-letter-context-menu is defined in ‘org-transclusion-map’.
+The default keybindings are shown below. Adapt them to your liking,
+especially if you use vim keybindings with Evil Mode, etc.
+
+ 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
+
+
+ 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.
+
+
+File: org-transclusion.info, Node: Usage, Next: Customizing, Prev: Getting
Started, Up: Top
+
+4 Usage
+*******
+
+* Menu:
+
+* Org-transclusion mode, activate, and deactivate: Org-transclusion mode
activate and deactivate.
+* Org links supported::
+* Control levels of headlines per transclusion::
+* Filter Org elements per transclusion::
+* Live-sync edit::
+* Transclude source file into src-block::
+* Transclude range of lines for text and source files::
+* Extensions::
+
+
+File: org-transclusion.info, Node: Org-transclusion mode activate and
deactivate, Next: Org links supported, Up: Usage
+
+4.1 Org-transclusion mode, activate, and deactivate
+===================================================
+
+Org-transclusion is a local minor mode; however, you do not need to
+explicitly call ‘org-transclusion-mode’. The minor mode is intended to
+be just a convenient wrapper to let you easily toggle between ‘activate’
+and ‘deactivate’.
+
+ As you saw in the *note Getting Started section: Getting Started.
+above, calling ‘org-transclusion-add’ or ‘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
+‘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 ‘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 ‘org-transclusion-mode’ as your entry
+command for transclusion. When customizable variable
+‘org-transclusion-add-all-on-activate’ is non-nil (it is ‘t’ by
+default), turning on the minor mode calls the ‘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,
+‘org-transclusion-add-all’ (it is also used by ‘org-transclusion-mode’)
+will work on every transclude keyword in the buffer. Add
+‘:disable-auto’ property to a keyword as shown in the example below;
+‘add-all’ skips transclude keywords with it.
+
+ #+transclude: [[file:path/to/file.org]] :disable-auto
+
+ You can override the ‘:disable-auto’ property by manually calling
+‘org-transclusion-add’ at point.
+
+
+File: org-transclusion.info, Node: Org links supported, Next: Control levels
of headlines per transclusion, Prev: Org-transclusion mode activate and
deactivate, Up: Usage
+
+4.2 Org links supported
+=======================
+
+Transclusion has been tested to work for the following types of links:
+
+ • File link for an entire org file/buffer; e.g.
+ ‘[[file:~/org/file.org][My Org Notes]]’
+ • File link with ‘::*heading’
+ • File link with ‘::#custom-id’
+ • File link with ‘::name’ for blocks (e.g. blocked quotations),
+ tables, and links
+ • File link with ‘::dedicated-target’; this is intended for linking
+ to a paragraph. See below.
+ • ID link ‘id:uuid’
+ • File link for non-org files (tested with ‘.txt’ and ‘.md’); for
+ these, the whole buffer gets transcluded
+
+ Note search-options ‘::/regex/’ and ‘::number’ do not work as
+intended.
+
+ For transcluding a specific paragraph, there are two main ways: Org
+Mode’s dedicated-target
+(https://orgmode.org/manual/Internal-Links.html#Internal-Links) and
+‘:only-contents’ property.
+
+ For dedicated targets, the target paragraph must be identifiable by a
+dedicated target with a ‘<<paragraph-id>>’:
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+ Suspendisse ac velit fermentum, sodales nunc in,
+ tincidunt quam. <<paragraph-id>>
+
+ It is generally assumed that the ‘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 ‘:only-contents’ property, refer to sub-section *note
+Filtering Org elements per transclusion: Filter Org elements per
+transclusion.
+
+
+File: org-transclusion.info, Node: Control levels of headlines per
transclusion, Next: Filter Org elements per transclusion, Prev: Org links
supported, Up: Usage
+
+4.3 Control levels of headlines per transclusion
+================================================
+
+When you transclude Org contents, you can specify a different headline
+level than those of the source Org file.
+
+ Use the ‘:level’ property with a value of single digit number from 1
+to 9 like this example below.
+
+ #+transclude: [[file:path/to/file.org::*Headline]] :level 2
+
+ The top level of the transcluded headline will set to the value of
+‘: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 ‘:level’ property; the rest of headlines in the
+buffer will align accordingly.
+
+ Other ways to control include the following.
+
+‘org-transclusion-make-from-link’
+ Make a transclusion keyword from a link at point. If you pass a
+ positive number 1-9 with ‘digit-argument’ (e.g. prefix ‘M-x’ with
+ ‘C-2’ to pass "2"), this function automatically puts the ‘:level’
+ property to the resultant transclusion keyword.
+
+‘org-transclusion-promote-subtree’
+ Promote transcluded subtree at point. Mapped to "P" (capital "p")
+ by default in ‘org-transclusion-map’
+
+‘org-transclusion-demote-subtree’
+ Demote transcluded subtree at point. Mapped to "D" (capital "D")
+ by default in ‘org-transclusion-map’
+
+
+File: org-transclusion.info, Node: Filter Org elements per transclusion,
Next: Live-sync edit, Prev: Control levels of headlines per transclusion, Up:
Usage
+
+4.4 Filter 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.
+
+‘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 ‘org-element-all-elements’. The default is
+ to exclude ‘property-drawer’.
+
+ Refer also to the *note sub-section on this user option:
+ Customizable filter to exclude certain Org elements.
+
+‘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 ‘#+title’, ‘#+author’, and so on. Many
+ people also write notes in it without adding any headlines. Note
+ that this user option’s default is now ‘t’ (changed from ‘nil’ as
+ users seem to spend time to "correct" this issue). Turn it to ‘t’
+ if you wish to transclude the content from the first section of
+ your Org files. If you wish to exclude the "meta data" defined by
+ ‘#+title’ and others, exclude ‘keyword’ as described in this
+ section – these meta data are defined with using the ‘keyword’
+ element of Org Mode.
+
+ Refer also to the *note sub-section on this user option: Include
+ the section before the first headline (Org file only).
+
+ 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.
+
+‘: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 ‘:only-contents’ without any value like this example:
+
+ #+transclude: [[file:path/to/file.org]] :only-contents
+
+‘:exclude-elements’
+ This property lets you *add* elements to exclude per transclusion
+ on top of the variable ‘org-transclusion-exclude-elements’ defines.
+ You cannot *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 ‘:exclude-elements’ with a list of elements (each one as
+ defined by ‘org-element-all-elements’) separated by a space inside
+ double quotation marks like this example:
+
+ #+transclude: [[file:path/to/file.org]] :exclude-elements "drawer keyword"
+
+ You can combine ‘:only-contents’ and ‘: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 ‘d’ to remove the transclusion, change the
+properties, and transclude again to see a new result.
+
+* Menu:
+
+* Notes on excluding the headline element::
+
+
+File: org-transclusion.info, Node: Notes on excluding the headline element,
Up: Filter Org elements per transclusion
+
+4.4.1 Notes on excluding the headline element
+---------------------------------------------
+
+If you add ‘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.
+
+ ** Headline 1
+ Content of Headline 1
+ ** Headline 2
+ Content of Headline 2
+ * Headline 3
+ Content of Headline
+
+
+File: org-transclusion.info, Node: Live-sync edit, Next: Transclude source
file into src-block, Prev: Filter Org elements per transclusion, Up: Usage
+
+4.5 Live-sync edit
+==================
+
+*Experimental.* You can start live-sync edit by pressing ‘e’ (by
+default) on a text element you want to edit. This will call
+‘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 ‘C-c C-c’ to exit live-sync edit. The
+key is bound to ‘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 ‘yank’ command (‘C-y’) is
+replaced with a special command ‘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. ‘evil-mode’), it is advised that you review the
+default keybindings. You can customize the local keybindings for the
+live-sync region by ‘org-transclusion-live-sync-map’.
+
+ *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
+‘#+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.
+
+ (substitute-command-keys "\\{org-transclusion-live-sync-map}")
+
+ 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’
+
+
+File: org-transclusion.info, Node: Transclude source file into src-block,
Next: Transclude range of lines for text and source files, Prev: Live-sync
edit, Up: Usage
+
+4.6 Transclude source file into src-block
+=========================================
+
+This feature is provided as an *note extension: Extensions. (default
+on).
+
+ You can transclude a source file into an Org’s src block. Use the
+‘:src’ property and specify the language you would like to use like
+this:
+
+ #+transclude: [[file:../../test/python-1.py]] :src python
+
+ The content you specify in the link gets wrapped into a src-block
+with the language like this:
+
+ #+begin_src python
+ [... content of python-1.py]
+ #+end_src
+
+ Use ‘:rest’ property to define additional properties you would like
+to add for the src-block. The double quotation marks are mandatory for
+the ‘:rest’ property.
+
+ #+transclude: [[file:../../test/python-3.py]] :src python :rest
":session :results value"
+
+ The source block will have the additional properties:
+ #+begin_src python :session :results value
+
+
+File: org-transclusion.info, Node: Transclude range of lines for text and
source files, Next: Extensions, Prev: Transclude source file into src-block,
Up: Usage
+
+4.7 Transclude range of lines for text and source files
+=======================================================
+
+This feature is provided as an *note extension: Extensions. (default
+on).
+
+ When you transclude text files other than Org files,
+
+* Menu:
+
+* lines property to specify a range of lines::
+* end property to specify a search term to dynamically look for the end of a
range::
+
+
+File: org-transclusion.info, Node: lines property to specify a range of
lines, Next: end property to specify a search term to dynamically look for the
end of a range, Up: Transclude range of lines for text and source files
+
+4.7.1 ‘: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 ‘:lines’ property like this.
+
+ #+transclude: [[file:../../test/test.txt]] :lines 3-5
+
+ 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 ‘:lines’ property with the ‘:src’ property to
+transclude only a certain range of source files (Example 1 below).
+
+ For Org’s file links, you can use search options
+(https://orgmode.org/manual/Search-Options.html) 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
+‘: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).
+ #+transclude: [[file:../../test/python-1.py::id-1234]] :lines 1-4 :src
python
+
+ Example 2: This transcludes only the single line that contains the
+line found by the search option for text string "Transcendental
+Ontology"
+ #+transclude: [[file:../../test/test.txt::Transcendental Ontology]]
:lines 1-1
+
+ Note search-options ‘::/regex/’ and ‘::number’ do not work as
+intended.
+
+
+File: org-transclusion.info, Node: end property to specify a search term to
dynamically look for the end of a range, Prev: lines property to specify a
range of lines, Up: Transclude range of lines for text and source files
+
+4.7.2 ‘:end’ property to specify a search term to dynamically look for the end
of a range
+-----------------------------------------------------------------------------------------
+
+You can add ‘: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 ‘id-1234’ as
+the beginning line of the range as specified by the search option
+‘::id-1234’ in the link. With the ‘:end’ property, the search term
+‘id-1234 end here’ defines the end of the range. The search looks for
+‘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
+‘id-1234 end here’).
+
+ You can also combined ‘:lines’ property with ‘: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
+‘:end’ property.
+
+ Example 3:
+ #+transclude: [[file:../../test/python-1.py::id-1234]] :lines 2- :src
python :end "id-1234 end here"
+
+
+File: org-transclusion.info, Node: Extensions, Prev: Transclude range of
lines for text and source files, Up: Usage
+
+4.8 Extensions
+==============
+
+Org-transclusion provides a simple extension framework, where you can
+use ‘customize’ to selectively add new features.
+
+ If you use ‘customize’, the features are loaded automatically. Note
+that it does not "unload" the feature until you relaunch Emacs.
+
+ If you do not use ‘customize’ (e.g. Doom), you may need to
+explicitly require an extension. For example, to activate
+‘org-transclusion-indent-mode’, you might need to add something like
+this in your configuration file.
+
+ ;; Ensure that load-path to org-transclusion is already added
+ ;; If you installed it with the built-in package.el, this should be
already done.
+ ;; (add-to-list 'load-path "path/to/org-transclusion/")
+ (add-to-list 'org-transclusion-extensions 'org-transclusion-indent-mode)
+ (require 'org-transclusion-indent-mode)
+
+ Currently, the following extensions are available.
+
+(off by default) ‘org-transclusion-indent-mode’
+ Support org-indent-mode.
+
+(on by default) ‘org-transclusion-src-lines’
+ Add features for ‘:src’ and ‘:lines’ properties to ‘#+transclude’.
+ It is meant for non-Org files such as program source and text files
+
+(on by default) ‘org-transclusion-font-lock’
+ Add font-lock for ‘#+transclude’. Org mode’s standard syntax
+ treats the combination of a ‘#+transclude:’ keyword and a link used
+ by Org-transclusion as a keyword. This means it applies the
+ ‘org-meta-line’ face and the link part cannot be toggled as a
+ normal link. This extension adds ‘org-transclusion-keyword’ face
+ to the keyword part and lets the link part to be treated as a
+ normal link for ‘org-toggle-link-display’.
+
+
+File: org-transclusion.info, Node: Customizing, Next: Known Limitations,
Prev: Usage, Up: Top
+
+5 Customizing
+*************
+
+You can customize settings in the ‘org-transclusion’ group.
+
+‘org-transclusion-extensions’
+ Defines extensions to be loaded with org-transclusion.el. If you
+ use ‘customize’, the extensions are loaded by it. If you don’t,
+ you likely need to explicitly use ‘require’ to load them. See
+ *note seb-section: Extensions.
+
+‘org-transclusion-add-all-on-activate’
+ Defines whether or not all the active transclusions (with ‘t’) get
+ automatically transcluded on minor mode activation
+ (‘org-transclusion-mode’). This does not affect the manual
+ activation when you directly call ‘org-transclusion-activate’
+
+‘org-transclusion-exclude-elements’
+ See *note sub-section: Customizable filter to exclude certain Org
+ elements.
+
+‘org-transclusion-include-first-section’
+ See *note sub-section: Include the section before the first
+ headline (Org file only).
+
+‘org-transclusion-open-source-display-action-list’
+ You can customize the way the ‘org-transclusion-open-source’
+ function displays the source buffer for the transclusion. You
+ specify the "action" in the way defined by the built-in
+ ‘display-buffer’ function. Refer to its in-system documentation
+ (with ‘C-h f’) for the accepted values. ‘M-x customize’ can also
+ guide you on what types of values are accepted.
+
+‘org-transclusion-mode-lighter’
+ Define the lighter for Org-transclusion minor mode. The default is
+ " OT".
+
+* Menu:
+
+* Customizable filter to exclude certain Org elements::
+* Include the section before the first headline (Org file only)::
+* Faces & fringe bitmap::
+* Keybindings::
+
+
+File: org-transclusion.info, Node: Customizable filter to exclude certain Org
elements, Next: Include the section before the first headline (Org file only),
Up: Customizing
+
+5.1 Customizable filter to exclude certain Org elements
+=======================================================
+
+Set customizable variable ‘org-transclusion-exclude-elements’ to define
+which elements to be *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 ‘(property-drawer)’. The
+accepted values are the ones defined by ‘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 *note filtering Org elements per transclusion:
+Filter Org elements per transclusion.
+
+
+File: org-transclusion.info, Node: Include the section before the first
headline (Org file only), Next: Faces & fringe bitmap, Prev: Customizable
filter to exclude certain Org elements, Up: Customizing
+
+5.2 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
+‘org-transclusion-include-first-section’. Its default value is ‘t’.
+Set it to ‘t’ (or non-nil) to transclude the first section. It also
+works when the first section is followed by headlines.
+
+
+File: org-transclusion.info, Node: Faces & fringe bitmap, Next: Keybindings,
Prev: Include the section before the first headline (Org file only), Up:
Customizing
+
+5.3 Faces & fringe bitmap
+=========================
+
+* Menu:
+
+* Face for the #+transclude keyword::
+* Faces for the fringes next to transcluded region and source region::
+
+
+File: org-transclusion.info, Node: Face for the #+transclude keyword, Next:
Faces for the fringes next to transcluded region and source region, Up: Faces
& fringe bitmap
+
+5.3.1 Face for the ‘#+transclude’ keyword
+-----------------------------------------
+
+This feature is provided as an *note extension: Extensions. (default
+on).
+
+‘org-transclusion-keyword’
+ You can set your own face to the ‘#+transclude’ keyword with using
+ the ‘org-transclusion-keyword’ face.
+
+
+File: org-transclusion.info, Node: Faces for the fringes next to transcluded
region and source region, Prev: Face for the #+transclude keyword, Up: Faces
& fringe bitmap
+
+5.3.2 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.
+
+ • ‘org-transclusion-source-fringe’
+ • ‘org-transclusion-fringe’
+
+ To customize a face, it’s probably the easiest to use ‘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.
+
+ (set-face-attribute
+ 'org-transclusion-fringe nil
+ :foreground "green"
+ :background "green")
+
+ 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 ‘list-faces-display’.
+
+ Other faces:
+ • ‘org-transclusion-source’
+ • ‘org-transclusion-source-edit’
+ • ‘org-transclusion’
+ • ‘org-transclusion-edit’
+ • ‘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).
+
+
+File: org-transclusion.info, Node: Keybindings, Prev: Faces & fringe bitmap,
Up: Customizing
+
+5.4 Keybindings
+===============
+
+ • ‘org-transclusion-map’
+ • ‘org-transclusion-live-sync-map’
+
+
+File: org-transclusion.info, Node: Known Limitations, Next: Credits, Prev:
Customizing, Up: Top
+
+6 Known Limitations
+*******************
+
+Note this section is still incomplete, not exhaustive for "known"
+limitations.
+
+ • Org link’s search-options ‘::/regex/’ and ‘::number’ do not work as
+ intended.
+
+ • ‘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: ‘center-block’, ‘drawer’,
+ ‘dynamic-block’, ‘latex-environment’, ‘paragraph’, ‘plain-list’,
+ ‘quote-block’, ‘special-block’, ‘table’, and ‘verse-block’.
+
+ It is known that live-sync does not work for the other elements;
+ namely: ‘comment-block’, ‘export-block’, ‘example-block’,
+ ‘fixed-width’, ‘keyword’, ‘src-block’, and ‘property-drawer’.
+
+ More technical reason for this limitation is documented in the
+ docstring of function
+ ‘org-transclusion-live-sync-enclosing-element’.
+
+ Work is in progress to lift this limitation but I’m still
+ experimenting different ideas.
+
+ • ‘org-indent-mode’ may not work well with Org-transclusion A new
+ extension has been added to support ‘org-indent-mode’ Refer to
+ *note this section: Extensions.
+
+ • Doom’s customization may interfere with Org-transclusion Refer to
+ issue #52 (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:
+
+ ‘(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.
+
+ • Org refile does not work "properly" on the transcluded headlines
+ Refer to issue #20
+ (https://github.com/nobiot/org-transclusion/issues/20). I don’t
+ intend to support this – refile the source, not the transcluded
+ copy.
+
+ • Org-transclusion does not support expansion of noweb references
+ when a transcluded source block code has them Refer to issue #86
+ (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
+ (https://orgmode.org/manual/Noweb-Reference-Syntax.html)
+
+
+File: org-transclusion.info, Node: Credits, Next: Contributing, Prev: Known
Limitations, Up: Top
+
+7 Credits
+*********
+
+* Menu:
+
+* Original idea by John Kitchin::
+* Text-Clone::
+
+
+File: org-transclusion.info, Node: Original idea by John Kitchin, Next:
Text-Clone, Up: Credits
+
+7.1 Original idea by John Kitchin
+=================================
+
+<https://github.com/alphapapa/transclusion-in-emacs#org-mode>
+
+ {O} transcluding some org-elements in multiple places _[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 not do things with
+ org-map-entries, and other org-machinery which needs the actual
+ headlines/properties present. Another example might be I want a
+ table in two places, but the contents of them should stay
+ synchronized, ditto for a code block.
+
+ This idea was inspired by
+ <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.
+
+
+File: org-transclusion.info, Node: Text-Clone, Prev: Original idea by John
Kitchin, Up: Credits
+
+7.2 Text-Clone
+==============
+
+‘text-clone.el’ is an extension of text-clone functions written as part
+of GNU Emacs in ‘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
+<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.
+
+
+File: org-transclusion.info, Node: Contributing, Next: Index - Features,
Prev: Credits, Up: Top
+
+8 Contributing
+**************
+
+ • Get involved in a discussion in Org-roam forum
+
(https://org-roam.discourse.group/t/prototype-transclusion-block-reference-with-emacs-org-mode/830)
+ (the package is originally aimed for its users, me included)
+
+ • Create issues, discussion, and/or pull requests. All welcome.
+
+* Menu:
+
+* Notes on pull requests and Free Software Foundation (FSF) copy right
assignment::
+
+
+File: org-transclusion.info, Node: Notes on pull requests and Free Software
Foundation (FSF) copy right assignment, Up: Contributing
+
+8.1 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 (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
+(https://orgmode.org/contribute.html#copyright)).
+
+ Thank you.
+
+
+File: org-transclusion.info, Node: Index - Features, Next: Index - Commands,
Prev: Contributing, Up: Top
+
+Appendix A Index - Features
+***************************
+
+ [index ]
+* Menu:
+
+* Activate / Deactivate: Org-transclusion mode activate and
deactivate.
+ (line 6)
+* Extension - org-transclusion-font-lock: Extensions. (line 6)
+* Extension - org-transclusion-indent-mode: Extensions. (line 6)
+* Extension - org-transclusion-src-lines: Extensions. (line 6)
+* Extensions: Extensions. (line 6)
+* Filters: Filter Org elements per transclusion.
+ (line 6)
+* Live-sync edit: Live-sync edit. (line 6)
+* Org Links Supported: Org links supported. (line 6)
+* Property - :disable-auto: Org-transclusion mode activate and
deactivate.
+ (line 6)
+* Property - :end: end property to specify a search term
to dynamically look for the end of a range.
+ (line 6)
+* Property - :level: Control levels of headlines per
transclusion.
+ (line 6)
+* Property - :lines: lines property to specify a range of
lines.
+ (line 6)
+* Property - :only-content: Filter Org elements per transclusion.
+ (line 6)
+* Property - :only-contents: Org links supported. (line 6)
+* Property - :rest: Transclude source file into src-block.
+ (line 6)
+* Property - :src: Transclude source file into src-block.
+ (line 6)
+* Transclude into Org’s src-block: Transclude source file into src-block.
+ (line 6)
+* Transclude range of lines: Transclude range of lines for text
and source files.
+ (line 6)
+* Transclusion Properties: Org-transclusion mode activate and
deactivate.
+ (line 6)
+
+
+File: org-transclusion.info, Node: Index - Commands, Next: Index - User
Options, Prev: Index - Features, Up: Top
+
+Appendix B Index - Commands
+***************************
+
+ [index ]
+* Menu:
+
+* org-transclusion-activate: Org-transclusion mode activate and
deactivate.
+ (line 6)
+* org-transclusion-add: Getting Started. (line 6)
+* org-transclusion-add-all: Getting Started. (line 6)
+* org-transclusion-deactivate: Org-transclusion mode activate and
deactivate.
+ (line 6)
+* org-transclusion-demote-subtree: Control levels of headlines per
transclusion.
+ (line 6)
+* org-transclusion-live-sync-exit: Live-sync edit. (line 6)
+* org-transclusion-live-sync-paste: Live-sync edit. (line 6)
+* org-transclusion-live-sync-start: Live-sync edit. (line 6)
+* org-transclusion-make-from-link: Getting Started. (line 6)
+* org-transclusion-make-from-link <1>: Control levels of headlines per
transclusion.
+ (line 6)
+* org-transclusion-mode: Org-transclusion mode activate and
deactivate.
+ (line 6)
+* org-transclusion-move-to-source: Getting Started. (line 6)
+* org-transclusion-open-source: Getting Started. (line 6)
+* org-transclusion-promote-subtree: Control levels of headlines per
transclusion.
+ (line 6)
+* org-transclusion-refresh: Getting Started. (line 6)
+
+
+File: org-transclusion.info, Node: Index - User Options, Next: GNU Free
Documentation License, Prev: Index - Commands, Up: Top
+
+Appendix C Index - User Options
+*******************************
+
+ [index ]
+* Menu:
+
+* org-transclusion: Faces & fringe bitmap. (line 6)
+* org-transclusion-add-all-on-activate: Org-transclusion mode activate and
deactivate.
+ (line 6)
+* org-transclusion-add-all-on-activate <1>: Customizing. (line 6)
+* org-transclusion-edit: Faces & fringe bitmap. (line 6)
+* org-transclusion-exclude-elements: Filter Org elements per transclusion.
+ (line 6)
+* org-transclusion-exclude-elements <1>: Customizable filter to exclude
certain Org elements.
+ (line 6)
+* org-transclusion-extensions: Extensions. (line 6)
+* org-transclusion-extensions <1>: Customizing. (line 6)
+* org-transclusion-fringe: Faces & fringe bitmap. (line 6)
+* org-transclusion-fringe-bitmap: Faces & fringe bitmap. (line 6)
+* org-transclusion-include-first-section: Filter Org elements per transclusion.
+ (line 6)
+* org-transclusion-include-first-section <1>: Include the section before the
first headline (Org file only).
+ (line 6)
+* org-transclusion-keyword: Faces & fringe bitmap. (line 6)
+* org-transclusion-live-sync-map: Live-sync edit. (line 6)
+* org-transclusion-live-sync-map <1>: Keybindings. (line 6)
+* org-transclusion-map: Getting Started. (line 6)
+* org-transclusion-map <1>: Keybindings. (line 6)
+* org-transclusion-mode-lighter: Customizing. (line 6)
+* org-transclusion-open-source-display-action-list: Customizing.
+ (line 6)
+* org-transclusion-source: Faces & fringe bitmap. (line 6)
+* org-transclusion-source-edit: Faces & fringe bitmap. (line 6)
+* org-transclusion-source-fringe: Faces & fringe bitmap. (line 6)
+
+
+File: org-transclusion.info, Node: GNU Free Documentation License, Prev:
Index - User Options, Up: Top
+
+Appendix D GNU Free Documentation License
+*****************************************
+
+ Version 1.3, 3 November 2008
+
+ Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
+ <https://fsf.org/>
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+ 0. PREAMBLE
+
+ The purpose of this License is to make a manual, textbook, or other
+ functional and useful document “free” in the sense of freedom: to
+ assure everyone the effective freedom to copy and redistribute it,
+ with or without modifying it, either commercially or
+ noncommercially. Secondarily, this License preserves for the
+ author and publisher a way to get credit for their work, while not
+ being considered responsible for modifications made by others.
+
+ This License is a kind of “copyleft”, which means that derivative
+ works of the document must themselves be free in the same sense.
+ It complements the GNU General Public License, which is a copyleft
+ license designed for free software.
+
+ We have designed this License in order to use it for manuals for
+ free software, because free software needs free documentation: a
+ free program should come with manuals providing the same freedoms
+ that the software does. But this License is not limited to
+ software manuals; it can be used for any textual work, regardless
+ of subject matter or whether it is published as a printed book. We
+ recommend this License principally for works whose purpose is
+ instruction or reference.
+
+ 1. APPLICABILITY AND DEFINITIONS
+
+ This License applies to any manual or other work, in any medium,
+ that contains a notice placed by the copyright holder saying it can
+ be distributed under the terms of this License. Such a notice
+ grants a world-wide, royalty-free license, unlimited in duration,
+ to use that work under the conditions stated herein. The
+ “Document”, below, refers to any such manual or work. Any member
+ of the public is a licensee, and is addressed as “you”. You accept
+ the license if you copy, modify or distribute the work in a way
+ requiring permission under copyright law.
+
+ A “Modified Version” of the Document means any work containing the
+ Document or a portion of it, either copied verbatim, or with
+ modifications and/or translated into another language.
+
+ A “Secondary Section” is a named appendix or a front-matter section
+ of the Document that deals exclusively with the relationship of the
+ publishers or authors of the Document to the Document’s overall
+ subject (or to related matters) and contains nothing that could
+ fall directly within that overall subject. (Thus, if the Document
+ is in part a textbook of mathematics, a Secondary Section may not
+ explain any mathematics.) The relationship could be a matter of
+ historical connection with the subject or with related matters, or
+ of legal, commercial, philosophical, ethical or political position
+ regarding them.
+
+ The “Invariant Sections” are certain Secondary Sections whose
+ titles are designated, as being those of Invariant Sections, in the
+ notice that says that the Document is released under this License.
+ If a section does not fit the above definition of Secondary then it
+ is not allowed to be designated as Invariant. The Document may
+ contain zero Invariant Sections. If the Document does not identify
+ any Invariant Sections then there are none.
+
+ The “Cover Texts” are certain short passages of text that are
+ listed, as Front-Cover Texts or Back-Cover Texts, in the notice
+ that says that the Document is released under this License. A
+ Front-Cover Text may be at most 5 words, and a Back-Cover Text may
+ be at most 25 words.
+
+ A “Transparent” copy of the Document means a machine-readable copy,
+ represented in a format whose specification is available to the
+ general public, that is suitable for revising the document
+ straightforwardly with generic text editors or (for images composed
+ of pixels) generic paint programs or (for drawings) some widely
+ available drawing editor, and that is suitable for input to text
+ formatters or for automatic translation to a variety of formats
+ suitable for input to text formatters. A copy made in an otherwise
+ Transparent file format whose markup, or absence of markup, has
+ been arranged to thwart or discourage subsequent modification by
+ readers is not Transparent. An image format is not Transparent if
+ used for any substantial amount of text. A copy that is not
+ “Transparent” is called “Opaque”.
+
+ Examples of suitable formats for Transparent copies include plain
+ ASCII without markup, Texinfo input format, LaTeX input format,
+ SGML or XML using a publicly available DTD, and standard-conforming
+ simple HTML, PostScript or PDF designed for human modification.
+ Examples of transparent image formats include PNG, XCF and JPG.
+ Opaque formats include proprietary formats that can be read and
+ edited only by proprietary word processors, SGML or XML for which
+ the DTD and/or processing tools are not generally available, and
+ the machine-generated HTML, PostScript or PDF produced by some word
+ processors for output purposes only.
+
+ The “Title Page” means, for a printed book, the title page itself,
+ plus such following pages as are needed to hold, legibly, the
+ material this License requires to appear in the title page. For
+ works in formats which do not have any title page as such, “Title
+ Page” means the text near the most prominent appearance of the
+ work’s title, preceding the beginning of the body of the text.
+
+ The “publisher” means any person or entity that distributes copies
+ of the Document to the public.
+
+ A section “Entitled XYZ” means a named subunit of the Document
+ whose title either is precisely XYZ or contains XYZ in parentheses
+ following text that translates XYZ in another language. (Here XYZ
+ stands for a specific section name mentioned below, such as
+ “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.)
+ To “Preserve the Title” of such a section when you modify the
+ Document means that it remains a section “Entitled XYZ” according
+ to this definition.
+
+ The Document may include Warranty Disclaimers next to the notice
+ which states that this License applies to the Document. These
+ Warranty Disclaimers are considered to be included by reference in
+ this License, but only as regards disclaiming warranties: any other
+ implication that these Warranty Disclaimers may have is void and
+ has no effect on the meaning of this License.
+
+ 2. VERBATIM COPYING
+
+ You may copy and distribute the Document in any medium, either
+ commercially or noncommercially, provided that this License, the
+ copyright notices, and the license notice saying this License
+ applies to the Document are reproduced in all copies, and that you
+ add no other conditions whatsoever to those of this License. You
+ may not use technical measures to obstruct or control the reading
+ or further copying of the copies you make or distribute. However,
+ you may accept compensation in exchange for copies. If you
+ distribute a large enough number of copies you must also follow the
+ conditions in section 3.
+
+ You may also lend copies, under the same conditions stated above,
+ and you may publicly display copies.
+
+ 3. COPYING IN QUANTITY
+
+ If you publish printed copies (or copies in media that commonly
+ have printed covers) of the Document, numbering more than 100, and
+ the Document’s license notice requires Cover Texts, you must
+ enclose the copies in covers that carry, clearly and legibly, all
+ these Cover Texts: Front-Cover Texts on the front cover, and
+ Back-Cover Texts on the back cover. Both covers must also clearly
+ and legibly identify you as the publisher of these copies. The
+ front cover must present the full title with all words of the title
+ equally prominent and visible. You may add other material on the
+ covers in addition. Copying with changes limited to the covers, as
+ long as they preserve the title of the Document and satisfy these
+ conditions, can be treated as verbatim copying in other respects.
+
+ If the required texts for either cover are too voluminous to fit
+ legibly, you should put the first ones listed (as many as fit
+ reasonably) on the actual cover, and continue the rest onto
+ adjacent pages.
+
+ If you publish or distribute Opaque copies of the Document
+ numbering more than 100, you must either include a machine-readable
+ Transparent copy along with each Opaque copy, or state in or with
+ each Opaque copy a computer-network location from which the general
+ network-using public has access to download using public-standard
+ network protocols a complete Transparent copy of the Document, free
+ of added material. If you use the latter option, you must take
+ reasonably prudent steps, when you begin distribution of Opaque
+ copies in quantity, to ensure that this Transparent copy will
+ remain thus accessible at the stated location until at least one
+ year after the last time you distribute an Opaque copy (directly or
+ through your agents or retailers) of that edition to the public.
+
+ It is requested, but not required, that you contact the authors of
+ the Document well before redistributing any large number of copies,
+ to give them a chance to provide you with an updated version of the
+ Document.
+
+ 4. MODIFICATIONS
+
+ You may copy and distribute a Modified Version of the Document
+ under the conditions of sections 2 and 3 above, provided that you
+ release the Modified Version under precisely this License, with the
+ Modified Version filling the role of the Document, thus licensing
+ distribution and modification of the Modified Version to whoever
+ possesses a copy of it. In addition, you must do these things in
+ the Modified Version:
+
+ A. Use in the Title Page (and on the covers, if any) a title
+ distinct from that of the Document, and from those of previous
+ versions (which should, if there were any, be listed in the
+ History section of the Document). You may use the same title
+ as a previous version if the original publisher of that
+ version gives permission.
+
+ B. List on the Title Page, as authors, one or more persons or
+ entities responsible for authorship of the modifications in
+ the Modified Version, together with at least five of the
+ principal authors of the Document (all of its principal
+ authors, if it has fewer than five), unless they release you
+ from this requirement.
+
+ C. State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.
+
+ D. Preserve all the copyright notices of the Document.
+
+ E. Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+
+ F. Include, immediately after the copyright notices, a license
+ notice giving the public permission to use the Modified
+ Version under the terms of this License, in the form shown in
+ the Addendum below.
+
+ G. Preserve in that license notice the full lists of Invariant
+ Sections and required Cover Texts given in the Document’s
+ license notice.
+
+ H. Include an unaltered copy of this License.
+
+ I. Preserve the section Entitled “History”, Preserve its Title,
+ and add to it an item stating at least the title, year, new
+ authors, and publisher of the Modified Version as given on the
+ Title Page. If there is no section Entitled “History” in the
+ Document, create one stating the title, year, authors, and
+ publisher of the Document as given on its Title Page, then add
+ an item describing the Modified Version as stated in the
+ previous sentence.
+
+ J. Preserve the network location, if any, given in the Document
+ for public access to a Transparent copy of the Document, and
+ likewise the network locations given in the Document for
+ previous versions it was based on. These may be placed in the
+ “History” section. You may omit a network location for a work
+ that was published at least four years before the Document
+ itself, or if the original publisher of the version it refers
+ to gives permission.
+
+ K. For any section Entitled “Acknowledgements” or “Dedications”,
+ Preserve the Title of the section, and preserve in the section
+ all the substance and tone of each of the contributor
+ acknowledgements and/or dedications given therein.
+
+ L. Preserve all the Invariant Sections of the Document, unaltered
+ in their text and in their titles. Section numbers or the
+ equivalent are not considered part of the section titles.
+
+ M. Delete any section Entitled “Endorsements”. Such a section
+ may not be included in the Modified Version.
+
+ N. Do not retitle any existing section to be Entitled
+ “Endorsements” or to conflict in title with any Invariant
+ Section.
+
+ O. Preserve any Warranty Disclaimers.
+
+ If the Modified Version includes new front-matter sections or
+ appendices that qualify as Secondary Sections and contain no
+ material copied from the Document, you may at your option designate
+ some or all of these sections as invariant. To do this, add their
+ titles to the list of Invariant Sections in the Modified Version’s
+ license notice. These titles must be distinct from any other
+ section titles.
+
+ You may add a section Entitled “Endorsements”, provided it contains
+ nothing but endorsements of your Modified Version by various
+ parties—for example, statements of peer review or that the text has
+ been approved by an organization as the authoritative definition of
+ a standard.
+
+ You may add a passage of up to five words as a Front-Cover Text,
+ and a passage of up to 25 words as a Back-Cover Text, to the end of
+ the list of Cover Texts in the Modified Version. Only one passage
+ of Front-Cover Text and one of Back-Cover Text may be added by (or
+ through arrangements made by) any one entity. If the Document
+ already includes a cover text for the same cover, previously added
+ by you or by arrangement made by the same entity you are acting on
+ behalf of, you may not add another; but you may replace the old
+ one, on explicit permission from the previous publisher that added
+ the old one.
+
+ The author(s) and publisher(s) of the Document do not by this
+ License give permission to use their names for publicity for or to
+ assert or imply endorsement of any Modified Version.
+
+ 5. COMBINING DOCUMENTS
+
+ You may combine the Document with other documents released under
+ this License, under the terms defined in section 4 above for
+ modified versions, provided that you include in the combination all
+ of the Invariant Sections of all of the original documents,
+ unmodified, and list them all as Invariant Sections of your
+ combined work in its license notice, and that you preserve all
+ their Warranty Disclaimers.
+
+ The combined work need only contain one copy of this License, and
+ multiple identical Invariant Sections may be replaced with a single
+ copy. If there are multiple Invariant Sections with the same name
+ but different contents, make the title of each such section unique
+ by adding at the end of it, in parentheses, the name of the
+ original author or publisher of that section if known, or else a
+ unique number. Make the same adjustment to the section titles in
+ the list of Invariant Sections in the license notice of the
+ combined work.
+
+ In the combination, you must combine any sections Entitled
+ “History” in the various original documents, forming one section
+ Entitled “History”; likewise combine any sections Entitled
+ “Acknowledgements”, and any sections Entitled “Dedications”. You
+ must delete all sections Entitled “Endorsements.”
+
+ 6. COLLECTIONS OF DOCUMENTS
+
+ You may make a collection consisting of the Document and other
+ documents released under this License, and replace the individual
+ copies of this License in the various documents with a single copy
+ that is included in the collection, provided that you follow the
+ rules of this License for verbatim copying of each of the documents
+ in all other respects.
+
+ You may extract a single document from such a collection, and
+ distribute it individually under this License, provided you insert
+ a copy of this License into the extracted document, and follow this
+ License in all other respects regarding verbatim copying of that
+ document.
+
+ 7. AGGREGATION WITH INDEPENDENT WORKS
+
+ A compilation of the Document or its derivatives with other
+ separate and independent documents or works, in or on a volume of a
+ storage or distribution medium, is called an “aggregate” if the
+ copyright resulting from the compilation is not used to limit the
+ legal rights of the compilation’s users beyond what the individual
+ works permit. When the Document is included in an aggregate, this
+ License does not apply to the other works in the aggregate which
+ are not themselves derivative works of the Document.
+
+ If the Cover Text requirement of section 3 is applicable to these
+ copies of the Document, then if the Document is less than one half
+ of the entire aggregate, the Document’s Cover Texts may be placed
+ on covers that bracket the Document within the aggregate, or the
+ electronic equivalent of covers if the Document is in electronic
+ form. Otherwise they must appear on printed covers that bracket
+ the whole aggregate.
+
+ 8. TRANSLATION
+
+ Translation is considered a kind of modification, so you may
+ distribute translations of the Document under the terms of section
+ 4. Replacing Invariant Sections with translations requires special
+ permission from their copyright holders, but you may include
+ translations of some or all Invariant Sections in addition to the
+ original versions of these Invariant Sections. You may include a
+ translation of this License, and all the license notices in the
+ Document, and any Warranty Disclaimers, provided that you also
+ include the original English version of this License and the
+ original versions of those notices and disclaimers. In case of a
+ disagreement between the translation and the original version of
+ this License or a notice or disclaimer, the original version will
+ prevail.
+
+ If a section in the Document is Entitled “Acknowledgements”,
+ “Dedications”, or “History”, the requirement (section 4) to
+ Preserve its Title (section 1) will typically require changing the
+ actual title.
+
+ 9. TERMINATION
+
+ You may not copy, modify, sublicense, or distribute the Document
+ except as expressly provided under this License. Any attempt
+ otherwise to copy, modify, sublicense, or distribute it is void,
+ and will automatically terminate your rights under this License.
+
+ However, if you cease all violation of this License, then your
+ license from a particular copyright holder is reinstated (a)
+ provisionally, unless and until the copyright holder explicitly and
+ finally terminates your license, and (b) permanently, if the
+ copyright holder fails to notify you of the violation by some
+ reasonable means prior to 60 days after the cessation.
+
+ Moreover, your license from a particular copyright holder is
+ reinstated permanently if the copyright holder notifies you of the
+ violation by some reasonable means, this is the first time you have
+ received notice of violation of this License (for any work) from
+ that copyright holder, and you cure the violation prior to 30 days
+ after your receipt of the notice.
+
+ Termination of your rights under this section does not terminate
+ the licenses of parties who have received copies or rights from you
+ under this License. If your rights have been terminated and not
+ permanently reinstated, receipt of a copy of some or all of the
+ same material does not give you any rights to use it.
+
+ 10. FUTURE REVISIONS OF THIS LICENSE
+
+ The Free Software Foundation may publish new, revised versions of
+ the GNU Free Documentation License from time to time. Such new
+ versions will be similar in spirit to the present version, but may
+ differ in detail to address new problems or concerns. See
+ <https://www.gnu.org/licenses/>.
+
+ Each version of the License is given a distinguishing version
+ number. If the Document specifies that a particular numbered
+ version of this License “or any later version” applies to it, you
+ have the option of following the terms and conditions either of
+ that specified version or of any later version that has been
+ published (not as a draft) by the Free Software Foundation. If the
+ Document does not specify a version number of this License, you may
+ choose any version ever published (not as a draft) by the Free
+ Software Foundation. If the Document specifies that a proxy can
+ decide which future versions of this License can be used, that
+ proxy’s public statement of acceptance of a version permanently
+ authorizes you to choose that version for the Document.
+
+ 11. RELICENSING
+
+ “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any
+ World Wide Web server that publishes copyrightable works and also
+ provides prominent facilities for anybody to edit those works. A
+ public wiki that anybody can edit is an example of such a server.
+ A “Massive Multiauthor Collaboration” (or “MMC”) contained in the
+ site means any set of copyrightable works thus published on the MMC
+ site.
+
+ “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0
+ license published by Creative Commons Corporation, a not-for-profit
+ corporation with a principal place of business in San Francisco,
+ California, as well as future copyleft versions of that license
+ published by that same organization.
+
+ “Incorporate” means to publish or republish a Document, in whole or
+ in part, as part of another Document.
+
+ An MMC is “eligible for relicensing” if it is licensed under this
+ License, and if all works that were first published under this
+ License somewhere other than this MMC, and subsequently
+ incorporated in whole or in part into the MMC, (1) had no cover
+ texts or invariant sections, and (2) were thus incorporated prior
+ to November 1, 2008.
+
+ The operator of an MMC Site may republish an MMC contained in the
+ site under CC-BY-SA on the same site at any time before August 1,
+ 2009, provided the MMC is eligible for relicensing.
+
+ADDENDUM: How to use this License for your documents
+====================================================
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and license
+notices just after the title page:
+
+ Copyright (C) YEAR YOUR NAME.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.3
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ Texts. A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
+
+ If you have Invariant Sections, Front-Cover Texts and Back-Cover
+Texts, replace the “with...Texts.” line with this:
+
+ with the Invariant Sections being LIST THEIR TITLES, with
+ the Front-Cover Texts being LIST, and with the Back-Cover Texts
+ being LIST.
+
+ If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+ If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of free
+software license, such as the GNU General Public License, to permit
+their use in free software.
+
+
+
+Tag Table:
+Node: Top846
+Node: Example Use Cases & Main Features3652
+Node: Installation5867
+Node: Getting Started7010
+Node: Usage10019
+Node: Org-transclusion mode activate and deactivate10489
+Node: Org links supported12542
+Node: Control levels of headlines per transclusion14288
+Node: Filter Org elements per transclusion16092
+Node: Notes on excluding the headline element19768
+Node: Live-sync edit20740
+Node: Transclude source file into src-block23125
+Node: Transclude range of lines for text and source files24222
+Node: lines property to specify a range of lines24777
+Node: end property to specify a search term to dynamically look for the end of
a range26722
+Node: Extensions28299
+Node: Customizing30166
+Node: Customizable filter to exclude certain Org elements31993
+Node: Include the section before the first headline (Org file only)33027
+Node: Faces & fringe bitmap33702
+Node: Face for the #+transclude keyword34043
+Node: Faces for the fringes next to transcluded region and source region34537
+Node: Keybindings36119
+Node: Known Limitations36330
+Node: Credits38964
+Node: Original idea by John Kitchin39148
+Node: Text-Clone41709
+Node: Contributing42286
+Node: Notes on pull requests and Free Software Foundation (FSF) copy right
assignment42811
+Node: Index - Features43497
+Node: Index - Commands46128
+Node: Index - User Options47947
+Node: GNU Free Documentation License50289
+
+End Tag Table
+
+
+Local Variables:
+coding: utf-8
+End:
diff --git a/org-transclusion.org b/org-transclusion.org
index 5e916e0..ccc6023 100644
--- a/org-transclusion.org
+++ b/org-transclusion.org
@@ -1,11 +1,14 @@
#+title: Org-transclusion User Manual
#+author: Noboru Ota <me@nobiot.com>
-#+modified: 2021-12-23T164111
+#+modified: 2021-12-23T181620
#+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
+#+texinfo: @noindent
+
+#+options: toc:nil
#+macro: version 1.0.x
#+macro: updated last updated 23 December 2021
@@ -15,15 +18,14 @@
#+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";>
-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.
+This manual is for Org-transclusion version {{{version}}}.
-This manual is for Org-transclusion version {{{version}}}, {{{updated}}}
+{{{updated}}}.
+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.
#+texinfo: @insertcopying
-#+toc: headlines 8
-
* COPYING
:PROPERTIES:
:COPYING: t
@@ -44,21 +46,43 @@ modify this GNU manual.”
#+end_quote
* Example Use Cases & Main Features
-:PROPERTIES:
-:DESCRIPTION: How others use Org-transclusion
-:END:
+Example Use Cases:
+
+- Book writing ::
+
+ You have a collection of notes. You can quickly transclude paragraphs and
sections from them into a draft. As they are links, it's easy to re-organize
them into different sequences to see which way works the best.
+
+- 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.
-- Book writing
+- Technical writing ::
-- Academic 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.
-- Technical writing
+- Project status reports ::
-- 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.
Main Features:
+- Insert a copy of text content via a file link or ID link into an Org file
+
+- Work with any text file such as program source cod, plain text, Markdown, or
other Org files
+
+- Keep the file system clear of the copies of text content -- Org-transclusion
tries hard to save only the links to the file system
+
+- For Org files, use different headline levels from the source Org file
+
+- For Org files, use filters to include only relevant elements (e.g. filter
out properties in the transclusions)
+
+- 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
+
+- For program source files, transclude parts or whole code directly into Org's
source block to leverage the rich Org features
+
+- Extend Org-transclusion with its extension framework
+
* Installation
This package is available on
[[https://elpa.gnu.org/packages/org-transclusion.html][GNU ELPA]]. You can do
=M-x package-install RET
@@ -106,8 +130,7 @@ If you use Doom, you can do something like this below to
install the package. T
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 reference, use one of the following commands:
-
+To transclude content via a link, use one of the following commands:
- =org-transclusion-add=
@@ -624,7 +647,7 @@ Note this section is still incomplete, not exhaustive for
"known" limitations.
- =org-indent-mode= may not work well with Org-transclusion ::
A new extension has been added to support =org-indent-mode=
- Refer to [[#extensions---support-org-indent-mode][this section]].
+ Refer to [[#extensions][this section]].
- Doom's customization may interfere with Org-transclusion ::
Refer to issue
[[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:
@@ -677,11 +700,10 @@ It seems like this could work well for headlines, and
named tables, src blocks,
** 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[fn:6: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[fn:7:https://orgmode.org/contribute.html#copyright]).
+Org-transclusion is part of GNU ELPA and thus copyrighted by the
[[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"
([[https://orgmode.org/contribute.html#copyright][Org Mode website]]).
Thank you.
-
* Index - Features
:PROPERTIES:
:APPENDIX: t
diff --git a/org-transclusion.texi b/org-transclusion.texi
index 3d9142d..eba8c03 100644
--- a/org-transclusion.texi
+++ b/org-transclusion.texi
@@ -1,7 +1,7 @@
\input texinfo @c -*- texinfo -*-
@c %**start of header
@setfilename org-transclusion.info
-@settitle Org-transclusion
+@settitle Org-transclusion User Manual
@documentencoding UTF-8
@documentlanguage en
@c %**end of header
@@ -30,33 +30,40 @@ modify this GNU manual.”
@finalout
@titlepage
-@title Org-transclusion
+@title Org-transclusion User Manual
@author Noboru Ota <me@@nobiot.com>
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
-@contents
-
@ifnottex
@node Top
-@top Org-transclusion
+@top Org-transclusion User Manual
-@insertcopying
+@noindent
+
+This manual is for Org-transclusion version 1.0.x.
+last updated 23 December 2021.
+
+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.
+
+@insertcopying
@end ifnottex
@menu
-* Introduction::
+* Example Use Cases & Main Features::
* Installation::
* Getting Started::
* Usage::
* Customizing::
* Known Limitations::
* Credits::
-* Development::
-* License::
+* Contributing::
+* Index - Features:: Key concepts & features
+* Index - Commands:: Interactive functions
+* Index - User Options:: Customizable variables & faces
* GNU Free Documentation License::
@detailmenu
@@ -66,16 +73,15 @@ 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::
+* Control levels of headlines per transclusion::
+* Filter 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}::
+* Extensions::
-Filtering Org elements per transclusion
+Filter 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
@@ -100,17 +106,59 @@ Credits
* Original idea by John Kitchin::
* Text-Clone::
-Development
+Contributing
* Notes on pull requests and Free Software Foundation (FSF) copy right
assignment::
@end detailmenu
@end menu
-@node Introduction
-@chapter Introduction
+@node Example Use Cases & Main Features
+@chapter Example Use Cases & Main Features
+
+Example Use Cases:
+
+@table @asis
+@item Book writing
+You have a collection of notes. You can quickly transclude paragraphs and
sections from them into a draft. As they 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 cod, plain text, Markdown, or
other Org files
+
+@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
-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}.
+@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
+
+@item
+Extend Org-transclusion with its extension framework
+@end itemize
@node Installation
@chapter Installation
@@ -148,17 +196,27 @@ If you use Doom, you can do something like this below to
install the package. T
@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}.
+@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 reference, use one of the following commands:
+To transclude content via a link, 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}
+
+@item
+@samp{org-transclusion-make-from-link}
@end itemize
For example, if you have an ID link in your Org file like this:
@@ -167,21 +225,21 @@ For example, if you have an ID link in your Org file like
this:
[[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:
+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 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.
+Put your cursor somewhere on this keyword line and type @samp{M-x
org-transclusion-add RET}, and you will see the text content that the ID points
replace the whole line. If you have multiple links with a transclude keyword,
you can type @samp{M-x org-transclusion-add-all RET} to do all transclusions in
the current buffer.
-@image{resources/2021-05-09T190918,,,,png}
+Alternatively, you can also put cursor somewhere on the link and call
@samp{M-x org-transclusion-make-from-link}. That will insert another line with
@samp{#+transclusion:} keyword appended in front of a copy of the original link
in the next empty line.
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.
+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 @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.
+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
@@ -201,9 +259,7 @@ 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.
+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
@@ -211,17 +267,25 @@ As your next step, I recommend the section on
@ref{Filtering Org elements per tr
@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::
+* Control levels of headlines per transclusion::
+* Filter 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}::
+* 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 Transclusion 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 @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.
@@ -243,6 +307,9 @@ You can override the @samp{:disable-auto} property by
manually calling @samp{org
@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
@@ -262,7 +329,7 @@ ID link @samp{id:uuid}
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.
+Note search-options @samp{::/regex/} and @samp{::number} do not work as
intended.
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.
@@ -276,12 +343,17 @@ tincidunt quam. <<paragraph-id>>
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}.
+For the @samp{:only-contents} property, refer to sub-section @ref{Filter Org
elements per transclusion, , Filtering Org elements per transclusion}.
-@node Controlling levels of headlines in transclusions
-@section Controlling levels of headlines in transclusions
+@node Control levels of headlines per transclusion
+@section Control levels of headlines per transclusion
-You can specify a different level of transcluded headlines than that of the
source Org file.
+@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.
@@ -293,8 +365,26 @@ The top level of the transcluded headline will set to the
value of @samp{:level}
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
+Other ways to control include the following.
+
+@table @asis
+@item @samp{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 @samp{M-x} with @samp{C-2}
to pass "2"), this function automatically puts the @samp{:level} property to
the resultant transclusion keyword.
+
+@item @samp{org-transclusion-promote-subtree}
+Promote transcluded subtree at point. Mapped to "P" (capital "p") by default
in @samp{org-transclusion-map}
+
+@item @samp{org-transclusion-demote-subtree}
+Demote transcluded subtree at point. Mapped to "D" (capital "D") by default in
@samp{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-content
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.
@@ -336,32 +426,16 @@ Add @samp{:exclude-elements} with a list of elements
(each one as defined by @sa
#+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.
+
@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 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.
@@ -377,7 +451,13 @@ If you are transcluding only one subtree, this should be
intuitive. If you trans
@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.
+@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
@samp{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.
@@ -387,7 +467,7 @@ Once done with editing, press @samp{C-c C-c} to exit
live-sync edit. The key is
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.
+@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@}")
@@ -408,6 +488,12 @@ C-c C-c org-transclusion-live-sync-exit
@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
@@ -436,6 +522,12 @@ The source block will have the additional properties:
@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,
+
@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::
@@ -444,6 +536,8 @@ The source block will have the additional properties:
@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
@@ -475,7 +569,9 @@ 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).
+@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 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}).
@@ -486,19 +582,16 @@ Example 3:
#+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}
+@node Extensions
+@section Extensions
-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.
+@cindex Extensions
+@vindex org-transclusion-extensions
+@cindex Extension - org-transclusion-indent-mode
+@cindex Extension - org-transclusion-src-lines
+@cindex Extension - org-transclusion-font-lock
-@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}
+Org-transclusion provides a simple extension framework, where you can use
@samp{customize} to selectively add new features.
If you use @samp{customize}, the features are loaded automatically. Note that
it does not "unload" the feature until you relaunch Emacs.
@@ -506,21 +599,40 @@ If you do not use @samp{customize} (e.g. Doom), you may
need to explicitly requi
@lisp
;; Ensure that load-path to org-transclusion is already added
+;; If you installed it with the built-in package.el, this should be already
done.
;; (add-to-list 'load-path "path/to/org-transclusion/")
(add-to-list 'org-transclusion-extensions 'org-transclusion-indent-mode)
(require 'org-transclusion-indent-mode)
@end lisp
+Currently, the following extensions are available.
+
+@table @asis
+@item (off by default) @samp{org-transclusion-indent-mode}
+Support org-indent-mode.
+
+@item (on by default) @samp{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) @samp{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 @samp{org-meta-line}
face and the link part cannot be toggled as a normal link. This extension adds
@samp{org-transclusion-keyword} face to the keyword part and lets the link part
to be treated as a normal link for @samp{org-toggle-link-display}.
+@end table
+
@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
+
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.
+If you don't, you likely need to explicitly use @samp{require} to load them.
See @ref{Extensions, , seb-section}
@item @samp{org-transclusion-add-all-on-activate}
Defines whether or not all the
@@ -529,18 +641,18 @@ 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
+See @ref{Customizable filter to exclude certain Org elements, , sub-section}
@item @samp{org-transclusion-include-first-section}
-See @ref{Include the section before the first headline (Org file only), ,
sub-section} below
+See @ref{Include the section before the first headline (Org file only), ,
sub-section}
@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.
+for the accepted values. @samp{M-x customize} can also guide you on what types
of
+values are accepted.
@item @samp{org-transclusion-mode-lighter}
Define the lighter for Org-transclusion
@@ -557,22 +669,35 @@ minor mode. The default is " OT".
@node Customizable filter to exclude certain Org elements
@section Customizable filter to exclude certain Org elements
+@vindex org-transclusion-exclude-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}.
+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
@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
+@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::
@@ -581,7 +706,12 @@ You can include the first section (section before the
first headline) of an Org
@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 @samp{org-transclusion-keyword}
You can set your own face to the @samp{#+transclude} keyword with using the
@samp{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
@@ -590,15 +720,11 @@ If the fringes that indicate transcluding and source
regions are not visible in
@itemize
@item
-org-transclusion-source-fringe
+@samp{org-transclusion-source-fringe}
@item
-org-transclusion-fringe
+@samp{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
@@ -613,27 +739,28 @@ For colors, where "green" is, you can also use something
like "#62c86a" (Emacs
Other faces:
@itemize
@item
-org-transclusion-source
+@samp{org-transclusion-source}
@item
-org-transclusion-source-edit
+@samp{org-transclusion-source-edit}
@item
-org-transclusion
+@samp{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
+@samp{org-transclusion-edit}
+@item @samp{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
+@end itemize
@node Keybindings
@section Keybindings
+@vindex org-transclusion-map
+@vindex org-transclusion-live-sync-map
+
@itemize
@item
@samp{org-transclusion-map}
+@end itemize
+@itemize
@item
@samp{org-transclusion-live-sync-map}
@end itemize
@@ -652,7 +779,7 @@ For transclusions of Org elements or buffers, live-sync
works only on the follow
@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}.
+@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 @samp{org-transclusion-live-sync-enclosing-element}.
@@ -660,20 +787,20 @@ Work is in progress to lift this limitation but I'm still
experimenting differen
@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}.
+Refer to @ref{Extensions, , 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:
+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:
@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.
+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 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}}
+Refer to issue @uref{https://github.com/nobiot/org-transclusion/issues/86,
#86}. You will get "Text read-only" error when export tries to expand the noweb
references into the source code.
†@uref{https://orgmode.org/manual/Noweb-Reference-Syntax.html, noweb reference}
@end itemize
@node Credits
@@ -714,8 +841,8 @@ It seems like this could work well for headlines, and named
tables, src blocks,
@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
+@node Contributing
+@chapter Contributing
@itemize
@item
@@ -732,19 +859,27 @@ Create issues, discussion, and/or pull requests. All
welcome.
@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}}).
+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 License
-@chapter License
+@node Index - Features
+@appendix Index - Features
+
+@printindex cp
+
+@node Index - Commands
+@appendix Index - Commands
+
+@printindex fn
-Org-transclusion is licensed under a GPLv3 license. For a full copy of the
license, refer to @uref{./LICENSE, LICENSE}.
+@node Index - User Options
+@appendix Index - User Options
-This documentation is licensed under the GNU Free Documentation License,
version 1.3.
+@printindex vr
@node GNU Free Documentation License
-@chapter GNU Free Documentation License
+@appendix GNU Free Documentation License
@include docs/fdl.texi
- [elpa] externals/org-transclusion updated (664b973 -> 0dccf2b), ELPA Syncer, 2021/12/23
- [elpa] externals/org-transclusion 9373c3e 3/5: docs: add .nojekyll file for GitHub Pages, ELPA Syncer, 2021/12/23
- [elpa] externals/org-transclusion 0dccf2b 5/5: docs: update some text, ELPA Syncer, 2021/12/23
- [elpa] externals/org-transclusion 324842d 1/5: docs:initial version of dedicated user manual, ELPA Syncer, 2021/12/23
- [elpa] externals/org-transclusion 8f5f714 2/5: docs: add User Manual .texi, .info, and .html,
ELPA Syncer <=
- [elpa] externals/org-transclusion 97380c0 4/5: docs: add missing transclusions, ELPA Syncer, 2021/12/23