[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/org-transclusion eb1a5d2897 3/5: docs: Remove DOS line
|
From: |
ELPA Syncer |
|
Subject: |
[elpa] externals/org-transclusion eb1a5d2897 3/5: docs: Remove DOS line ending |
|
Date: |
Wed, 29 Dec 2021 06:02:05 -0500 (EST) |
branch: externals/org-transclusion
commit eb1a5d28979d299f88232adc7ecff0b7c4ddb364
Author: Noboru Ota <me@nobiot.com>
Commit: Noboru Ota <me@nobiot.com>
docs: Remove DOS line ending
---
README.org | 9 +-
docs/index.html | 1247 ++++++++++++++++++-----------------
docs/org-transclusion-manual.org | 1354 +++++++++++++++++++-------------------
3 files changed, 1311 insertions(+), 1299 deletions(-)
diff --git a/README.org b/README.org
index 605d34fbc1..ae4704735a 100644
--- a/README.org
+++ b/README.org
@@ -19,13 +19,16 @@ For installation and minimum configuration, refer to
[[#installation][Installati
Below are images and videos demonstrating some of the key features of
Org-transclusion.
-[[./resources/2021-09-10-transclusion.gif]]
+#+attr_html: :max-width 80%
+https://github.com/nobiot/org-transclusion/blob/main/resources/2021-09-10-transclusion.gif?raw=true
*Figure 1*. Animation to show creation of a transclusion from an ID link
-[[./resources/2021-05-01-org-transclusion-0.1.0-live-sync.gif]]
+#+attr_html: :max-width 80%
+https://github.com/nobiot/org-transclusion/blob/main/resources/2021-05-01-org-transclusion-0.1.0-live-sync.gif?raw=true
*Figure 2*. Animation to show live sync from transclusion to source
-[[./resources/demo9-title.png]]
+#+attr_html: :max-width 80%
+https://github.com/nobiot/org-transclusion/blob/main/resources/demo9-title.png?raw=true
*Figure 3*. [[https://youtu.be/ueaPiA622wA][Video demo on v0.2.1 on YouTube]]
demonstrating new features to transclude a source file into a src-block and
function to specify a range of text/source line
- Older videos
diff --git a/docs/index.html b/docs/index.html
index af1d47dbe9..b8848a6ec3 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -1,17 +1,17 @@
<!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.”
-
-->
+<!-- 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">
@@ -49,225 +49,232 @@ ul.no-bullet {list-style: none}
<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 1.0.x.
-</p>
-<p>Last updated: 26 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.<span id="whatis"></span></p>
-<p>Copyright (C) 2021 Free Software Foundation, Inc.
-</p>
+
+
+<p>This manual is for Org-transclusion 1.0.x.
+</p>
+<p>Last updated: 29 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.<span id="whatis"></span></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>
+<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">
+<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">
+<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">
+<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">Features in detail
+<tr><td align="left" valign="top">• <a href="#Usage"
accesskey="4">Usage</a></td><td> </td><td align="left"
valign="top">Features in detail
</td></tr>
-<tr><td align="left" valign="top">• <a href="#Customizing"
accesskey="5">Customizing</a></td><td> </td><td align="left"
valign="top">
+<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">
+<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">
+<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">
+<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
+<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
+<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
+<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">
+<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">
+<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">
+<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">
+<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">
+<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">
+<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">
+<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">
+<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">
+<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">
+<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">
+<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">
+<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">
+<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">
+<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">
+<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">
+<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">
+<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">
+<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">
+<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">
+<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">
+<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>Here are a summary of some real use cases that users have shared with the
author, including his own.
-</p>
+
+<p>Here are a summary of some real use cases that users have shared with the
author, including his own.
+</p>
<dl compact="compact">
<dt>Book writing</dt>
-<dd><p>You have a collection of notes. You can quickly transclude paragraphs
and sections from your notes and put together a draft. As transclusions are
links, it’s easy to re-organize them into different sequences to see
which way works the best.
-</p>
+<dd><p>You have a collection of notes. You can quickly transclude paragraphs
and sections from your notes and put together a draft. As transclusions are
links, it’s easy to re-organize them into different sequences to see
which way works the best.
+</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><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><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.
+<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>
+
+<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 code, 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> 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 code, 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 including noweb
style syntax
+
+</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:
-</p>
+
+<p>This package is available on:
+</p>
<ul>
-<li> <a href="https://elpa.gnu.org/packages/org-transclusion.html";>GNU
ELPA</a> (releases only; equivalent to MELPA-Stable)
-</li><li> <a href="https://elpa.gnu.org/devel/org-transclusion.html";>GNU-devel
ELPA</a> (unreleased development branch; equivalent to MELPA)
+<li> <a href="https://elpa.gnu.org/packages/org-transclusion.html";>GNU
ELPA</a> (releases only; equivalent to MELPA-Stable)
+</li><li> <a href="https://elpa.gnu.org/devel/org-transclusion.html";>GNU-devel
ELPA</a> (unreleased development branch; equivalent to MELPA)
</li></ul>
-
-<p>GNU ELPA should be already set up in your Emacs by default. If you wish to
add GNU-devel ELPA, simply add its URL to
‘<samp>package-archives</samp>’ like this:
-</p>
+
+<p>GNU ELPA should be already set up in your Emacs by default. If you wish to
add GNU-devel ELPA, simply add its URL to
‘<samp>package-archives</samp>’ like this:
+</p>
<div class="lisp">
-<pre class="lisp">(add-to-list 'package-archives '("gnu-devel" .
"https://elpa.gnu.org/devel/") t)
+<pre class="lisp">(add-to-list 'package-archives '("gnu-devel" .
"https://elpa.gnu.org/devel/") t)
</pre></div>
-
-<p>Refresh the archive with ‘<samp>M-x package-refresh-contents
RET</samp>’ and you can do ‘<samp>M-x package-install RET
org-transclusion</samp>’ to install it. Alternatively, you can use
‘<samp>package-list-packages</samp>’.
-</p>
-<p>After installation, you can start using Org-transclusion with no additional
configuration. Below are some example keybindings that can be put into your
Emacs configuration.
-</p>
+
+<p>Refresh the archive with ‘<samp>M-x package-refresh-contents
RET</samp>’ and you can do ‘<samp>M-x package-install RET
org-transclusion</samp>’ to install it. Alternatively, you can use
‘<samp>package-list-packages</samp>’.
+</p>
+<p>After installation, you can start using Org-transclusion with no additional
configuration. Below are some example keybindings that can be put into your
Emacs configuration.
+</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 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>For Doom users, you would need to do something like this below to install
the package and configure the keybindings.
-</p>
+
+<p>For Doom users, you would need to do something like this below to install
the package and configure the keybindings.
+</p>
<div class="lisp">
-<pre class="lisp">;; ~/.doom.d/package.el
-(package! org-transclusion)
+<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 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>
@@ -275,581 +282,583 @@ Next: <a href="#Usage" accesskey="n"
rel="next">Usage</a>, Previous: <a href="#I
<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>
+
+<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> ‘<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>
+
+<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 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>
+
+<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 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 to 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 add all transclusions in the current buffer.
-</p>
-<p>Alternatively, you can also put cursor somewhere on the link and type
‘<samp>M-x org-transclusion-make-from-link RET</samp>’. That will
insert another line with ‘<samp>#+transclusion:</samp>’ keyword
added 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>
+
+<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 to 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 add all transclusions in the current buffer.
+</p>
+<p>Alternatively, you can also put cursor somewhere on the link and type
‘<samp>M-x org-transclusion-make-from-link RET</samp>’. That will
insert another line with ‘<samp>#+transclusion:</samp>’ keyword
added in front of a copy of the original link in the next empty line.
+</p>
+<p>The transcluded paragraphs will be visually marked with “| ” in
the fringe (on graphical display) or in the beginning of line (on a text-only
terminal) by default. The source (original) of the transcluded paragraphs will
be also visually marked with an overlay. The appearance of these visual
elements can be customized (refer to section <a
href="#Faces-_0026-fringe-bitmap">Faces & fringe bitmap</a>).
+</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).
+</p>
+<p>You can call a number of useful commands with a single letter (by default).
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>’ [...]
+</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 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>
+
+<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">
+<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">
+<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">
+<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">
+<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">
+<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">
+<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">
+<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">
+<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-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>
+
+<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 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>
+
+<p>You can override the ‘<samp>:disable-auto</samp>’ property by
manually calling ‘<samp>org-transclusion-add</samp>’ at point.
There are various properties like ‘<samp>:disable-auto</samp>’ to
control each transclusion (refer to <a href="#Index-_002d-Features">Index -
Features</a> for a list).
+</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>
+
+<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> 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>
-
+
<blockquote>
-<p><b>Note:</b> Search-options ‘<samp>::/regex/</samp>’ and
‘<samp>::number</samp>’ do not work as intended.
-</p>
+<p><b>Note:</b> Search-options ‘<samp>::/regex/</samp>’ and
‘<samp>::number</samp>’ do not work as intended.
+</p>
</blockquote>
-
-
-<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>
+
+
+<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 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>
+
+<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>
+
+<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 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>
+
+<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><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><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>’
+<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>
+
+<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><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>.
+<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>
+
+<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:
+<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 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:
+<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 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>
+
+<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">
+<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>
+
+<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 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>
+
+<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 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 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>
+
+<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 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>
+
+<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 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>
+
+<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 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>The source block will have the additional properties:
</p><div class="example">
-<pre class="example">#+begin_src python :session :results value
+<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>
+
+<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, you can use following
properties to specify a range of lines to transclude.
+</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">
+<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">
+<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>
+
+<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 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>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 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>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 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>
+
+<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>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 [...]
+</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 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>
+
+<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 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>
+
+<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><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><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 [...]
+<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>
+
+<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><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">sub-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><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><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><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><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".
+<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">
+<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">
+<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">
+<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">
+<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>
+
+<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>
+
+<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>
@@ -858,226 +867,226 @@ Next: <a href="#Keybindings" accesskey="n"
rel="next">Keybindings</a>, Previous:
<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">
+<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">
+<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>
+
+<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.
+<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>
+
+<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> ‘<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>
+
+<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 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>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> ‘<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 on a graphical display (not on a text-only 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> ‘<samp>org-transclusion-map</samp>’
</li></ul>
<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 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>
-
+
<ul>
-<li> ‘<samp>org-transclusion-live-sync-map</samp>’
+<li> ‘<samp>org-transclusion-live-sync-map</samp>’
</li></ul>
<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 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="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>
+
+<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> 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">
+<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">
+<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>
+
+<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>
+<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>
+
+<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> 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>
-
-<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>
+
+<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>
@@ -1115,6 +1124,7 @@ Next: <a href="#Index-_002d-Commands" accesskey="n"
rel="next">Index - Commands<
<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-Properties">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></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>
@@ -1127,7 +1137,6 @@ Next: <a href="#Index-_002d-Commands" accesskey="n"
rel="next">Index - Commands<
<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>
@@ -1145,14 +1154,14 @@ Next: <a href="#Index-_002d-Commands" accesskey="n"
rel="next">Index - Commands<
<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>
@@ -1180,14 +1189,14 @@ Next: <a href="#Index-_002d-User-Options" accesskey="n"
rel="next">Index - User
<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>
@@ -1222,14 +1231,14 @@ Next: <a href="#GNU-Free-Documentation-License"
accesskey="n" rel="next">GNU Fre
<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>
@@ -1697,7 +1706,7 @@ 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>
diff --git a/docs/org-transclusion-manual.org b/docs/org-transclusion-manual.org
index 10e8c3c725..82b50643ce 100644
--- a/docs/org-transclusion-manual.org
+++ b/docs/org-transclusion-manual.org
@@ -1,677 +1,677 @@
-#+title: Org-transclusion User Manual
-#+author: Noboru Ota <me@nobiot.com>
-#+macro: version 1.0.x
-#+macro: modified 29 December 2021
-
-#+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: @paragraphindent asis
-
-#+options: toc:nil
-
-#+html: <a href="https://www.gnu.org/software/emacs/";><img alt="GNU Emacs"
src="https://img.shields.io/static/v1?logo=gnuemacs&logoColor=fafafa&label=Made%20for&message=GNU%20Emacs&color=7F5AB6&style=flat"/></a>
-#+html: <a href="http://elpa.gnu.org/packages/org-transclusion.html";><img
alt="GNU ELPA" src="https://elpa.gnu.org/packages/org-transclusion.svg"/></a>
-#+html: <a href="http://elpa.gnu.org/devel/org-transclusion.html";><img
alt="GNU-devel ELPA" src="https://elpa.gnu.org/devel/org-transclusion.svg"/></a>
-#+html: <img alt="GPLv3"
src="https://img.shields.io/badge/License-GPLv3-blue.svg";>
-
-This manual is for Org-transclusion {{{version}}}.
-
-Last updated: {{{modified}}}.
-
-#+transclude: [[../README.org::whatis]]
-
-#+texinfo: @insertcopying
-
-* COPYING
-:PROPERTIES:
-:COPYING: t
-:END:
-
-Copyright (C) 2021 Free Software Foundation, Inc.
-
-#+begin_quote
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.3 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover Texts being “A GNU Manual,” and
-with the Back-Cover Texts as in (a) below. A copy of the license is
-included in the section entitled “GNU Free Documentation License.”
-
-(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
-modify this GNU manual.”
-#+end_quote
-
-* Example Use Cases & Main Features
-
-#+transclude: [[../README.org::#use-cases]] :only-contents
-
-* Installation
-
-#+transclude: [[../README.org::*Installation]] :only-contents
-
-* Getting Started
-:PROPERTIES:
-:DESCRIPT: To get running in 5 minutes
-:CUSTOM_ID: getting-started
-:END:
-
-#+findex: org-transclusion-add
-#+findex: org-transclusion-add-all
-#+findex: org-transclusion-make-from-link
-#+findex: org-transclusion-open-source
-#+findex: org-transclusion-move-to-source
-#+findex: org-transclusion-refresh
-#+vindex: org-transclusion-map
-
-The basic idea of Org-transclusion is simple: insert a copy of text content
via a file link or ID link within an Org file. This is an Org Mode version of
transclusion.
-
-To transclude content via a link, use one of the following commands:
-
-- =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:
-
-#+begin_example
-[[id:20210501T171427.051019][Bertrand Russell]]
-#+end_example
-
-Simply type to add =#+transclude:= in front of the link like the example below.
-
-#+begin_example
-#+transclude: [[id:20210501T171427.051019][Bertrand Russell]]
-#+end_example
-
-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
to replace the whole line. If you have multiple links with a transclude
keyword, you can type =M-x org-transclusion-add-all RET= to add all
transclusions in the current buffer.
-
-Alternatively, you can also put cursor somewhere on the link and type =M-x
org-transclusion-make-from-link RET=. That will insert another line with
=#+transclusion:= keyword added in front of a copy of the original link in the
next empty line.
-
-The transcluded paragraphs will be visually marked with "| " in the fringe (on
graphical display) or in the beginning of line (on a text-only terminal) by
default. The source (original) of the transcluded paragraphs will be also
visually marked with an overlay. The appearance of these visual elements can be
customized (refer to section [[#faces][Faces & fringe bitmap]]).
-
-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.
-
-#+name: org-transclusion-map
-#+caption: Default org-transclusion-map
-#+begin_example
-key binding
---- -------
-
-C-c Prefix Command
-TAB org-cycle
-D org-transclusion-demote-subtree
-O org-transclusion-move-to-source
-P org-transclusion-promote-subtree
-d org-transclusion-remove
-e org-transclusion-live-sync-start
-g org-transclusion-refresh
-o org-transclusion-open-source
-
-C-c C-c org-ctrl-c-ctrl-c
-
-#+end_example
-
-This should get you started with Org-transclusion. There are more options and
customizing options available for you to fine-tune the text content you
transclude. Explore the rest of the user manual and play with Org-transclusion
to get familiar with it.
-
-* Usage
-:PROPERTIES:
-:DESCRIPTION: Features in detail
-:CUSTOM_ID: usage
-:END:
-** Org-transclusion mode, activate, and deactivate
-
-#+cindex: Activate / Deactivate
-#+findex: org-transclusion-mode
-#+findex: org-transclusion-activate
-#+findex: org-transclusion-deactivate
-#+cindex: Properties
-#+cindex: Property - :disable-auto
-#+vindex: org-transclusion-add-all-on-activate
-
-Org-transclusion is a local minor mode; however, you do not need to explicitly
call =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 [[#getting-started][Getting Started section]] 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.
-
-#+begin_example
-#+transclude: [[file:path/to/file.org]] :disable-auto
-#+end_example
-
-You can override the =:disable-auto= property by manually calling
=org-transclusion-add= at point. There are various properties like
=:disable-auto= to control each transclusion (refer to [[#cindex][Index -
Features]] for a list).
-
-** Org links supported
-:PROPERTIES:
-:CUSTOM_ID: org-links-supported
-:END:
-
-#+cindex: Org Links Supported
-#+cindex: Property - :only-contents
-
-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
-
-#+ATTR_TEXINFO: :tag Note
-#+begin_quote
-Search-options =::/regex/= and =::number= do not work as intended.
-#+end_quote
-
-
-For transcluding a specific paragraph, there are two main ways: Org Mode's
[[https://orgmode.org/manual/Internal-Links.html#Internal-Links][dedicated-target]]
and =:only-contents= property.
-
-For dedicated targets, the target paragraph must be identifiable by a
dedicated target with a =<<paragraph-id>>=:
-
-#+begin_example
-Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-Suspendisse ac velit fermentum, sodales nunc in,
-tincidunt quam. <<paragraph-id>>
-#+end_example
-
-It is generally assumed that the =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
[[#filtering-org-elements-per-transclusion][Filtering Org elements per
transclusion]].
-
-** Control levels of headlines per transclusion
-
-#+cindex: Property - :level
-#+findex: org-transclusion-demote-subtree
-#+findex: org-transclusion-promote-subtree
-#+findex: org-transclusion-make-from-link
-
-When you transclude Org contents, you can specify a different headline level
than those of the source Org file.
-
-Use the =:level= property with a value of single digit number from 1 to 9 like
this example below.
-
-#+begin_example
-#+transclude: [[file:path/to/file.org::*Headline]] :level 2
-#+end_example
-
-The top level of the transcluded headline will set to the value of =: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=
-
-** Filter Org elements per transclusion
-:PROPERTIES:
-:CUSTOM_ID: filtering-org-elements-per-transclusion
-:END:
-
-#+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.
-
-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
[[#customizable-filter-to-exclude-certain-org-elements][sub-section on this
user option]].
-
-- =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 fro [...]
-
- Refer also to the
[[#include-the-section-before-the-first-headline-org-file-only][sub-section on
this user option]].
-
-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:
-
-#+begin_example
-#+transclude: [[file:path/to/file.org]] :only-contents
-#+end_example
-
-- =: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:
-
-#+begin_example
-#+transclude: [[file:path/to/file.org]] :exclude-elements "drawer keyword"
-#+end_example
-
-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.
-
-*** 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.
-
-#+begin_example
- ** Headline 1
- Content of Headline 1
- ** Headline 2
- Content of Headline 2
- * Headline 3
- Content of Headline
-#+end_example
-
-** Live-sync edit
-:PROPERTIES:
-:CUSTOM_ID: live-sync-edit
-:END:
-
-#+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
-
-*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 r [...]
-
-*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.
-
-#+begin_src elisp :exports no
- (substitute-command-keys "\\{org-transclusion-live-sync-map}")
-#+end_src
-
-#+name: org-transclusion-live-sync-map
-#+caption: Default org-transclusion-live-sync-map
-#+begin_example
- key binding
- --- -------
-
- C-c Prefix Command
- C-y org-transclusion-live-sync-paste
-
- C-c C-c org-transclusion-live-sync-exit
-
- *Also inherits ‘org-mode-map’
-#+end_example
-
-** Transclude source file into src-block
-:PROPERTIES:
-:CUSTOM_ID: transclude-source-file-into-src-block
-:END:
-
-#+cindex: Transclude into Org's src-block
-#+cindex: Property - :src
-#+cindex: Property - :rest
-
-This feature is provided as an [[#extensions][extension]] (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:
-
-#+begin_example
-#+transclude: [[file:../../test/python-1.py]] :src python
-#+end_example
-
-The content you specify in the link gets wrapped into a src-block with the
language like this:
-
-#+begin_example
-,#+begin_src python
-[... content of python-1.py]
-,#+end_src
-#+end_example
-
-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.
-
-#+begin_example
-#+transclude: [[file:../../test/python-3.py]] :src python :rest ":session
:results value"
-#+end_example
-
-The source block will have the additional properties:
-#+begin_example
-,#+begin_src python :session :results value
-#+end_example
-
-** Transclude range of lines for text and source files
-:PROPERTIES:
-:CUSTOM_ID: transclude-range-of-lines-for-text-and-source-files
-:END:
-
-#+cindex: Transclude range of lines
-
-This feature is provided as an [[#extensions][extension]] (default on).
-
-When you transclude text files other than Org files, you can use following
properties to specify a range of lines to transclude.
-
-*** =: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 =:lines= property like this.
-
-#+begin_example
-#+transclude: [[file:../../test/test.txt]] :lines 3-5
-#+end_example
-
-The rage is specified by the number "3-5"; in this case, lines from 3 to 5,
both lines inclusive.
-
-To transclude a single line, have the the same number in both places (e.g.
10-10, meaning line 10 only).
-
-One of the numbers can be omitted. When the first number is omitted (e.g.
-10), it means from the beginning of the file to line 10. Likewise, when the
second number is omitted (e.g. 10-), it means from line 10 to the end of file.
-
-You can combine the =: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
[[https://orgmode.org/manual/Search-Options.html][search options]] specified by
the "::" (two colons) notation. When a search finds a line that includes the
string, the Org-transclude counts it as the starting line 1 for the =: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).
-#+begin_example
-#+transclude: [[file:../../test/python-1.py::id-1234]] :lines 1-4 :src python
-#+end_example
-
-Example 2: This transcludes only the single line that contains the line found
by the search option for text string "Transcendental Ontology"
-#+begin_example
-#+transclude: [[file:../../test/test.txt::Transcendental Ontology]] :lines 1-1
-#+end_example
-
-Note search-options =::/regex/= and =::number= do not work as intended.
-
-*** =:end= property to specify a search term to dynamically look for the end
of a range
-
-#+cindex: Property - :end
-
-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:
-#+begin_example
-#+transclude: [[file:../../test/python-1.py::id-1234]] :lines 2- :src python
:end "id-1234 end here"
-#+end_example
-
-** Extensions
-:PROPERTIES:
-:CUSTOM_ID: extensions
-:END:
-
-#+cindex: Extensions
-#+vindex: org-transclusion-extensions
-#+cindex: Extension - org-transclusion-indent-mode
-#+cindex: Extension - org-transclusion-src-lines
-#+cindex: Extension - org-transclusion-font-lock
-
-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.
-
- #+BEGIN_SRC emacs-lisp
- ;; Ensure that load-path to org-transclusion is already added
- ;; If you installed it with the built-in package.el, this should be already
done.
- ;; (add-to-list 'load-path "path/to/org-transclusion/")
- (add-to-list 'org-transclusion-extensions 'org-transclusion-indent-mode)
- (require 'org-transclusion-indent-mode)
- #+END_SRC
-
-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=.
-
-* 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 =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
[[#extensions][sub-section]]
-
-- =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
[[#customizable-filter-to-exclude-certain-org-elements][sub-section]]
-
-- =org-transclusion-include-first-section= :: See
[[#include-the-section-before-the-first-headline-org-file-only][sub-section]]
-
-- =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".
-
-** Customizable filter to exclude certain Org elements
-:PROPERTIES:
-:CUSTOM_ID: customizable-filter-to-exclude-certain-org-elements
-:END:
-
-#+vindex: org-transclusion-exclude-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 [[#filtering-org-elements-per-transclusion][filtering Org
elements per transclusion]].
-
-** Include the section before the first headline (Org file only)
-:PROPERTIES:
-:CUSTOM_ID: include-the-section-before-the-first-headline-org-file-only
-:END:
-
-#+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
=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.
-
-** Faces & fringe bitmap
-:PROPERTIES:
-:CUSTOM_ID: faces
-:END:
-
-#+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
-
-*** Face for the =#+transclude= keyword
-
-This feature is provided as an [[#extensions][extension]] (default on).
-
-- =org-transclusion-keyword= ::
-
- You can set your own face to the =#+transclude= keyword with using the
=org-transclusion-keyword= face.
-
-*** 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.
-
-#+BEGIN_SRC elisp
-(set-face-attribute
- 'org-transclusion-fringe nil
- :foreground "green"
- :background "green")
-#+END_SRC
-
-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 on a graphical display (not on a text-only terminal).
-
-** Keybindings
-#+vindex: org-transclusion-map
-#+vindex: org-transclusion-live-sync-map
-
-- =org-transclusion-map=
-#+transclude: [[./org-transclusion-manual.org::org-transclusion-map]]
-
-- =org-transclusion-live-sync-map=
-#+transclude:
[[./org-transclusion-manual.org::org-transclusion-live-sync-map]]
-
-* 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 [[#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:
-
- =(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
[[https://github.com/nobiot/org-transclusion/issues/20][#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
[[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.
†[[https://orgmode.org/manual/Noweb-Reference-Syntax.html][noweb reference]]
-
-* Credits
-** Original idea by John Kitchin
-:PROPERTIES:
-:CUSTOM_ID: original-idea-by-john-kitchin
-:END:
-
-https://github.com/alphapapa/transclusion-in-emacs#org-mode
-
-#+begin_quote
-{O} transcluding some org-elements in multiple places
-[2016-12-09 Fri] John Kitchin asks:
-
-I have an idea for how I could transclude “copies” or links to org-elements in
multiple places and keep them up to date. A prototypical example of this is I
have a set of org-contacts in one place, and I want to create a new list of
people for a committee in a new place made of “copies” of the contact
headlines. But I do not really want to duplicate the headlines, and if I modify
one, I want it reflected in the other places. I do not want just links to those
contacts, because then I can [...]
-
-This idea was inspired by https://github.com/gregdetre/emacs-freex.
-
-The idea starts with creating (wait for it…) a new link ;) In a document where
I want to transclude a headline, I would enter something like:
-
-transclude:some-file.org::*headline title
-
-Then, I would rely on the font-lock system to replace that link with the
headline and its contents (via the :activate-func link property), and to put an
overlay on it with a bunch of useful properties, including modification hooks
that would update the source if I change the the element in this document, and
some visual indication that it is transcluded (e.g. light gray
background/tooltip).
-
-I would create a kill-buffer hook function that would replace that transcluded
content with the original link. A focus-in hook function would make sure the
transcluded content is updated when you enter the frame. So when the file is
not open, there is just a transclude link indicating what should be put there,
and when it is open, the overlay modification hooks and focus hook should
ensure everything stays synchronized (as long as external processes are not
modifying the contents).
-
-It seems like this could work well for headlines, and named tables, src
blocks, and probably any other element that can be addressed by a name/ID.
-#+end_quote
-
-** 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.
-
-* Contributing
-
-#+transclude: [[../README.org::*Contributing]] :only-contents
-
-* Index - Features
-:PROPERTIES:
-:CUSTOM_ID: cindex
-:APPENDIX: t
-:INDEX: cp
-:DESCRIPTION: Key concepts & features
-:END:
-
-* Index - Commands
-:PROPERTIES:
-:APPENDIX: t
-:INDEX: fn
-:DESCRIPTION: Interactive functions
-:END:
-
-* Index - User Options
-:PROPERTIES:
-:APPENDIX: t
-:INDEX: vr
-:DESCRIPTION: Customizable variables & faces
-:END:
-
-* GNU Free Documentation License
-:PROPERTIES:
-:appendix: t
-:END:
-
-#+texinfo: @include fdl.texi
-
-# LocalWords: href img src devel GPLv texinfo insertcopying toc RET findex
-# LocalWords: vindex cindex dir
-
-# Local Variables:
-# time-stamp-start: "modified +\\\\?"
-# End:
+#+title: Org-transclusion User Manual
+#+author: Noboru Ota <me@nobiot.com>
+#+macro: version 1.0.x
+#+macro: modified 29 December 2021
+
+#+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: @paragraphindent asis
+
+#+options: toc:nil ':t
+
+#+html: <a href="https://www.gnu.org/software/emacs/";><img alt="GNU Emacs"
src="https://img.shields.io/static/v1?logo=gnuemacs&logoColor=fafafa&label=Made%20for&message=GNU%20Emacs&color=7F5AB6&style=flat"/></a>
+#+html: <a href="http://elpa.gnu.org/packages/org-transclusion.html";><img
alt="GNU ELPA" src="https://elpa.gnu.org/packages/org-transclusion.svg"/></a>
+#+html: <a href="http://elpa.gnu.org/devel/org-transclusion.html";><img
alt="GNU-devel ELPA" src="https://elpa.gnu.org/devel/org-transclusion.svg"/></a>
+#+html: <img alt="GPLv3"
src="https://img.shields.io/badge/License-GPLv3-blue.svg";>
+
+This manual is for Org-transclusion {{{version}}}.
+
+Last updated: {{{modified}}}.
+
+#+transclude: [[../README.org::whatis]]
+
+#+texinfo: @insertcopying
+
+* COPYING
+:PROPERTIES:
+:COPYING: t
+:END:
+
+Copyright (C) 2021 Free Software Foundation, Inc.
+
+#+begin_quote
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover Texts being “A GNU Manual,” and
+with the Back-Cover Texts as in (a) below. A copy of the license is
+included in the section entitled “GNU Free Documentation License.”
+
+(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
+modify this GNU manual.”
+#+end_quote
+
+* Example Use Cases & Main Features
+
+#+transclude: [[../README.org::#use-cases]] :only-contents
+
+* Installation
+
+#+transclude: [[../README.org::*Installation]] :only-contents
+
+* Getting Started
+:PROPERTIES:
+:DESCRIPT: To get running in 5 minutes
+:CUSTOM_ID: getting-started
+:END:
+
+#+findex: org-transclusion-add
+#+findex: org-transclusion-add-all
+#+findex: org-transclusion-make-from-link
+#+findex: org-transclusion-open-source
+#+findex: org-transclusion-move-to-source
+#+findex: org-transclusion-refresh
+#+vindex: org-transclusion-map
+
+The basic idea of Org-transclusion is simple: insert a copy of text content
via a file link or ID link within an Org file. This is an Org Mode version of
transclusion.
+
+To transclude content via a link, use one of the following commands:
+
+- =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:
+
+#+begin_example
+[[id:20210501T171427.051019][Bertrand Russell]]
+#+end_example
+
+Simply type to add =#+transclude:= in front of the link like the example below.
+
+#+begin_example
+#+transclude: [[id:20210501T171427.051019][Bertrand Russell]]
+#+end_example
+
+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
to replace the whole line. If you have multiple links with a transclude
keyword, you can type =M-x org-transclusion-add-all RET= to add all
transclusions in the current buffer.
+
+Alternatively, you can also put cursor somewhere on the link and type =M-x
org-transclusion-make-from-link RET=. That will insert another line with
=#+transclusion:= keyword added in front of a copy of the original link in the
next empty line.
+
+The transcluded paragraphs will be visually marked with "| " in the fringe (on
graphical display) or in the beginning of line (on a text-only terminal) by
default. The source (original) of the transcluded paragraphs will be also
visually marked with an overlay. The appearance of these visual elements can be
customized (refer to section [[#faces][Faces & fringe bitmap]]).
+
+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.
+
+#+name: org-transclusion-map
+#+caption: Default org-transclusion-map
+#+begin_example
+key binding
+--- -------
+
+C-c Prefix Command
+TAB org-cycle
+D org-transclusion-demote-subtree
+O org-transclusion-move-to-source
+P org-transclusion-promote-subtree
+d org-transclusion-remove
+e org-transclusion-live-sync-start
+g org-transclusion-refresh
+o org-transclusion-open-source
+
+C-c C-c org-ctrl-c-ctrl-c
+
+#+end_example
+
+This should get you started with Org-transclusion. There are more options and
customizing options available for you to fine-tune the text content you
transclude. Explore the rest of the user manual and play with Org-transclusion
to get familiar with it.
+
+* Usage
+:PROPERTIES:
+:DESCRIPTION: Features in detail
+:CUSTOM_ID: usage
+:END:
+** Org-transclusion mode, activate, and deactivate
+
+#+cindex: Activate / Deactivate
+#+findex: org-transclusion-mode
+#+findex: org-transclusion-activate
+#+findex: org-transclusion-deactivate
+#+cindex: Properties
+#+cindex: Property - :disable-auto
+#+vindex: org-transclusion-add-all-on-activate
+
+Org-transclusion is a local minor mode; however, you do not need to explicitly
call =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 [[#getting-started][Getting Started section]] 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.
+
+#+begin_example
+#+transclude: [[file:path/to/file.org]] :disable-auto
+#+end_example
+
+You can override the =:disable-auto= property by manually calling
=org-transclusion-add= at point. There are various properties like
=:disable-auto= to control each transclusion (refer to [[#cindex][Index -
Features]] for a list).
+
+** Org links supported
+:PROPERTIES:
+:CUSTOM_ID: org-links-supported
+:END:
+
+#+cindex: Org Links Supported
+#+cindex: Property - :only-contents
+
+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
+
+#+ATTR_TEXINFO: :tag Note
+#+begin_quote
+Search-options =::/regex/= and =::number= do not work as intended.
+#+end_quote
+
+
+For transcluding a specific paragraph, there are two main ways: Org Mode's
[[https://orgmode.org/manual/Internal-Links.html#Internal-Links][dedicated-target]]
and =:only-contents= property.
+
+For dedicated targets, the target paragraph must be identifiable by a
dedicated target with a =<<paragraph-id>>=:
+
+#+begin_example
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+Suspendisse ac velit fermentum, sodales nunc in,
+tincidunt quam. <<paragraph-id>>
+#+end_example
+
+It is generally assumed that the =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
[[#filtering-org-elements-per-transclusion][Filtering Org elements per
transclusion]].
+
+** Control levels of headlines per transclusion
+
+#+cindex: Property - :level
+#+findex: org-transclusion-demote-subtree
+#+findex: org-transclusion-promote-subtree
+#+findex: org-transclusion-make-from-link
+
+When you transclude Org contents, you can specify a different headline level
than those of the source Org file.
+
+Use the =:level= property with a value of single digit number from 1 to 9 like
this example below.
+
+#+begin_example
+#+transclude: [[file:path/to/file.org::*Headline]] :level 2
+#+end_example
+
+The top level of the transcluded headline will set to the value of =: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=
+
+** Filter Org elements per transclusion
+:PROPERTIES:
+:CUSTOM_ID: filtering-org-elements-per-transclusion
+:END:
+
+#+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.
+
+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
[[#customizable-filter-to-exclude-certain-org-elements][sub-section on this
user option]].
+
+- =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 fro [...]
+
+ Refer also to the
[[#include-the-section-before-the-first-headline-org-file-only][sub-section on
this user option]].
+
+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:
+
+#+begin_example
+#+transclude: [[file:path/to/file.org]] :only-contents
+#+end_example
+
+- =: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:
+
+#+begin_example
+#+transclude: [[file:path/to/file.org]] :exclude-elements "drawer keyword"
+#+end_example
+
+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.
+
+*** 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.
+
+#+begin_example
+ ** Headline 1
+ Content of Headline 1
+ ** Headline 2
+ Content of Headline 2
+ * Headline 3
+ Content of Headline
+#+end_example
+
+** Live-sync edit
+:PROPERTIES:
+:CUSTOM_ID: live-sync-edit
+:END:
+
+#+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
+
+*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 r [...]
+
+*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.
+
+#+begin_src elisp :exports no
+ (substitute-command-keys "\\{org-transclusion-live-sync-map}")
+#+end_src
+
+#+name: org-transclusion-live-sync-map
+#+caption: Default org-transclusion-live-sync-map
+#+begin_example
+ key binding
+ --- -------
+
+ C-c Prefix Command
+ C-y org-transclusion-live-sync-paste
+
+ C-c C-c org-transclusion-live-sync-exit
+
+ *Also inherits ‘org-mode-map’
+#+end_example
+
+** Transclude source file into src-block
+:PROPERTIES:
+:CUSTOM_ID: transclude-source-file-into-src-block
+:END:
+
+#+cindex: Transclude into Org's src-block
+#+cindex: Property - :src
+#+cindex: Property - :rest
+
+This feature is provided as an [[#extensions][extension]] (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:
+
+#+begin_example
+#+transclude: [[file:../../test/python-1.py]] :src python
+#+end_example
+
+The content you specify in the link gets wrapped into a src-block with the
language like this:
+
+#+begin_example
+,#+begin_src python
+[... content of python-1.py]
+,#+end_src
+#+end_example
+
+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.
+
+#+begin_example
+#+transclude: [[file:../../test/python-3.py]] :src python :rest ":session
:results value"
+#+end_example
+
+The source block will have the additional properties:
+#+begin_example
+,#+begin_src python :session :results value
+#+end_example
+
+** Transclude range of lines for text and source files
+:PROPERTIES:
+:CUSTOM_ID: transclude-range-of-lines-for-text-and-source-files
+:END:
+
+#+cindex: Transclude range of lines
+
+This feature is provided as an [[#extensions][extension]] (default on).
+
+When you transclude text files other than Org files, you can use following
properties to specify a range of lines to transclude.
+
+*** =: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 =:lines= property like this.
+
+#+begin_example
+#+transclude: [[file:../../test/test.txt]] :lines 3-5
+#+end_example
+
+The rage is specified by the number "3-5"; in this case, lines from 3 to 5,
both lines inclusive.
+
+To transclude a single line, have the the same number in both places (e.g.
10-10, meaning line 10 only).
+
+One of the numbers can be omitted. When the first number is omitted (e.g.
-10), it means from the beginning of the file to line 10. Likewise, when the
second number is omitted (e.g. 10-), it means from line 10 to the end of file.
+
+You can combine the =: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
[[https://orgmode.org/manual/Search-Options.html][search options]] specified by
the "::" (two colons) notation. When a search finds a line that includes the
string, the Org-transclude counts it as the starting line 1 for the =: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).
+#+begin_example
+#+transclude: [[file:../../test/python-1.py::id-1234]] :lines 1-4 :src python
+#+end_example
+
+Example 2: This transcludes only the single line that contains the line found
by the search option for text string "Transcendental Ontology"
+#+begin_example
+#+transclude: [[file:../../test/test.txt::Transcendental Ontology]] :lines 1-1
+#+end_example
+
+Note search-options =::/regex/= and =::number= do not work as intended.
+
+*** =:end= property to specify a search term to dynamically look for the end
of a range
+
+#+cindex: Property - :end
+
+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:
+#+begin_example
+#+transclude: [[file:../../test/python-1.py::id-1234]] :lines 2- :src python
:end "id-1234 end here"
+#+end_example
+
+** Extensions
+:PROPERTIES:
+:CUSTOM_ID: extensions
+:END:
+
+#+cindex: Extensions
+#+vindex: org-transclusion-extensions
+#+cindex: Extension - org-transclusion-indent-mode
+#+cindex: Extension - org-transclusion-src-lines
+#+cindex: Extension - org-transclusion-font-lock
+
+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.
+
+ #+BEGIN_SRC emacs-lisp
+ ;; Ensure that load-path to org-transclusion is already added
+ ;; If you installed it with the built-in package.el, this should be already
done.
+ ;; (add-to-list 'load-path "path/to/org-transclusion/")
+ (add-to-list 'org-transclusion-extensions 'org-transclusion-indent-mode)
+ (require 'org-transclusion-indent-mode)
+ #+END_SRC
+
+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=.
+
+* 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 =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
[[#extensions][sub-section]]
+
+- =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
[[#customizable-filter-to-exclude-certain-org-elements][sub-section]]
+
+- =org-transclusion-include-first-section= :: See
[[#include-the-section-before-the-first-headline-org-file-only][sub-section]]
+
+- =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".
+
+** Customizable filter to exclude certain Org elements
+:PROPERTIES:
+:CUSTOM_ID: customizable-filter-to-exclude-certain-org-elements
+:END:
+
+#+vindex: org-transclusion-exclude-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 [[#filtering-org-elements-per-transclusion][filtering Org
elements per transclusion]].
+
+** Include the section before the first headline (Org file only)
+:PROPERTIES:
+:CUSTOM_ID: include-the-section-before-the-first-headline-org-file-only
+:END:
+
+#+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
=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.
+
+** Faces & fringe bitmap
+:PROPERTIES:
+:CUSTOM_ID: faces
+:END:
+
+#+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
+
+*** Face for the =#+transclude= keyword
+
+This feature is provided as an [[#extensions][extension]] (default on).
+
+- =org-transclusion-keyword= ::
+
+ You can set your own face to the =#+transclude= keyword with using the
=org-transclusion-keyword= face.
+
+*** 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.
+
+#+BEGIN_SRC elisp
+(set-face-attribute
+ 'org-transclusion-fringe nil
+ :foreground "green"
+ :background "green")
+#+END_SRC
+
+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 on a graphical display (not on a text-only terminal).
+
+** Keybindings
+#+vindex: org-transclusion-map
+#+vindex: org-transclusion-live-sync-map
+
+- =org-transclusion-map=
+#+transclude: [[./org-transclusion-manual.org::org-transclusion-map]]
+
+- =org-transclusion-live-sync-map=
+#+transclude:
[[./org-transclusion-manual.org::org-transclusion-live-sync-map]]
+
+* 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 [[#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:
+
+ =(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
[[https://github.com/nobiot/org-transclusion/issues/20][#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
[[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.
†[[https://orgmode.org/manual/Noweb-Reference-Syntax.html][noweb reference]]
+
+* Credits
+** Original idea by John Kitchin
+:PROPERTIES:
+:CUSTOM_ID: original-idea-by-john-kitchin
+:END:
+
+https://github.com/alphapapa/transclusion-in-emacs#org-mode
+
+#+begin_quote
+{O} transcluding some org-elements in multiple places
+[2016-12-09 Fri] John Kitchin asks:
+
+I have an idea for how I could transclude “copies” or links to org-elements in
multiple places and keep them up to date. A prototypical example of this is I
have a set of org-contacts in one place, and I want to create a new list of
people for a committee in a new place made of “copies” of the contact
headlines. But I do not really want to duplicate the headlines, and if I modify
one, I want it reflected in the other places. I do not want just links to those
contacts, because then I can [...]
+
+This idea was inspired by https://github.com/gregdetre/emacs-freex.
+
+The idea starts with creating (wait for it…) a new link ;) In a document where
I want to transclude a headline, I would enter something like:
+
+transclude:some-file.org::*headline title
+
+Then, I would rely on the font-lock system to replace that link with the
headline and its contents (via the :activate-func link property), and to put an
overlay on it with a bunch of useful properties, including modification hooks
that would update the source if I change the the element in this document, and
some visual indication that it is transcluded (e.g. light gray
background/tooltip).
+
+I would create a kill-buffer hook function that would replace that transcluded
content with the original link. A focus-in hook function would make sure the
transcluded content is updated when you enter the frame. So when the file is
not open, there is just a transclude link indicating what should be put there,
and when it is open, the overlay modification hooks and focus hook should
ensure everything stays synchronized (as long as external processes are not
modifying the contents).
+
+It seems like this could work well for headlines, and named tables, src
blocks, and probably any other element that can be addressed by a name/ID.
+#+end_quote
+
+** 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.
+
+* Contributing
+
+#+transclude: [[../README.org::*Contributing]] :only-contents
+
+* Index - Features
+:PROPERTIES:
+:CUSTOM_ID: cindex
+:APPENDIX: t
+:INDEX: cp
+:DESCRIPTION: Key concepts & features
+:END:
+
+* Index - Commands
+:PROPERTIES:
+:APPENDIX: t
+:INDEX: fn
+:DESCRIPTION: Interactive functions
+:END:
+
+* Index - User Options
+:PROPERTIES:
+:APPENDIX: t
+:INDEX: vr
+:DESCRIPTION: Customizable variables & faces
+:END:
+
+* GNU Free Documentation License
+:PROPERTIES:
+:appendix: t
+:END:
+
+#+texinfo: @include fdl.texi
+
+# LocalWords: href img src devel GPLv texinfo insertcopying toc RET findex
+# LocalWords: vindex cindex dir
+
+# Local Variables:
+# time-stamp-start: "modified +\\\\?"
+# End: