branch: externals/org-transclusion
commit 818e2200c0679187c04fded674ee1576bd1848e6
Author: Noboru Ota <m...@nobiot.com>
Commit: Noboru Ota <m...@nobiot.com>
docs: changes for ELPA doc generation
---
.dir-locals.el | 3 +-
Makefile | 25 +-
NEWS | 4 +
docs/Makefile | 2 +-
docs/index.html | 4 +-
...ransclusion.org => org-transclusion-manual.org} | 18 +-
org-transclusion.info | 1695 --------------------
7 files changed, 28 insertions(+), 1723 deletions(-)
diff --git a/.dir-locals.el b/.dir-locals.el
index 349f1363c1..75fe4f4a01 100644
--- a/.dir-locals.el
+++ b/.dir-locals.el
@@ -7,6 +7,5 @@
;; Need this locale to be "C" or "en_US.UTF-8" or something to standardize
the
;; time stamp with English
(system-time-locale . "C"))
- (emacs-lisp-mode
(fill-column . 80)
- (indent-tabs-mode . nil)))
+ (indent-tabs-mode . nil))
diff --git a/Makefile b/Makefile
index 83c703ce84..e6ea833526 100644
--- a/Makefile
+++ b/Makefile
@@ -1,19 +1,12 @@
-
-clean:
- find . -name "*.elc" -delete
-
+docs/org-transclusion.org: docs/org-transclusion-manual.org
+ emacs --batch -L "$$(pwd)" -l org-transclusion $< \
+ --eval '(progn (org-transclusion-add-all) (write-region nil nil
"org-transclusion.org"))'
test-compile:
- emacs --quick --batch --eval "(progn (add-to-list 'load-path
default-directory) \
- (byte-compile-file
\"org-transclusion.el\"))"
- emacs --quick --batch --eval "(progn (add-to-list 'load-path
default-directory) \
- (byte-compile-file
\"text-clone.el\"))"
- emacs --quick --batch --eval "(progn (add-to-list 'load-path
default-directory) \
- (byte-compile-file
\"org-transclusion-indent-mode.el\"))"
- emacs --quick --batch --eval "(progn (add-to-list 'load-path
default-directory) \
- (byte-compile-file
\"org-transclusion-src-lines.el\"))"
- emacs --quick --batch --eval "(progn (add-to-list 'load-path
default-directory) \
- (byte-compile-file
\"org-transclusion-font-lock.el\"))"
- # Check declare-function
- emacs --quick --batch --eval "(check-declare-directory
default-directory)"
+ emacs --batch --eval "(add-to-list 'load-path default-directory)" \
+ -f batch-byte-compile ./*.el
+ # Check declare-function
+ emacs --batch --eval "(check-declare-directory default-directory)"
+clean:
+ find . -name "*.elc" -delete
diff --git a/NEWS b/NEWS
index 8a254c3f1b..e5865c9865 100644
--- a/NEWS
+++ b/NEWS
@@ -1,6 +1,10 @@
* Current
- fix:add-all not to stop with error in one trasclusion
+- fix:Remove extra space/line added to Org elements transcluded
+- add:inhibit-read-only: fix:Org export errors with read-only
+ With this, noweb expansion seems to work now
+- README, Info doc user manual, online user manual
* Version 1.0.1
diff --git a/docs/Makefile b/docs/Makefile
index 7acd7e8dce..f91c03deb5 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -13,7 +13,7 @@ run: html install clear
manual:
@printf "\n\n### Generating manual .texi and .info files \n\n"
- $(EMACS) --batch -L ../ --file org-transclusion.org \
+ $(EMACS) --batch -L ../ --file org-transclusion-manual.org \
--eval="(progn (require
'org-transclusion)(org-transclusion-add-all)(org-texinfo-export-to-info))"
html:
diff --git a/docs/index.html b/docs/index.html
index bca88161ae..e411895f5f 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -60,9 +60,9 @@ Next: <a href="#Example-Use-Cases-_0026-Main-Features"
accesskey="n" rel="next">
<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>This manual is for Org-transclusion {{{version:}}}.
</p>
-<p>Last updated 24 December 2021.
+<p>Last updated: {{{modified:}}}.
</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.
diff --git a/docs/org-transclusion.org b/docs/org-transclusion-manual.org
similarity index 97%
rename from docs/org-transclusion.org
rename to docs/org-transclusion-manual.org
index e35347918f..4500434d4f 100644
--- a/docs/org-transclusion.org
+++ b/docs/org-transclusion-manual.org
@@ -1,5 +1,8 @@
#+title: Org-transclusion User Manual
#+author: Noboru Ota <m...@nobiot.com>
+#+macro: version 1.0.x
+#+macro: modified 26 December 2021
+
#+language: en
#+export_file_name: org-transclusion.texi
#+texinfo_dir_category: Emacs
@@ -9,17 +12,14 @@
#+options: toc:nil
-#+macro: version 1.0.x.
-#+macro: updated Last updated 24 December 2021.
-
#+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}}}
+This manual is for Org-transclusion {{{version}}}.
-{{{updated}}}
+Last updated: {{{modified}}}.
#+transclude: [[../README.org::whatis]]
@@ -562,10 +562,10 @@ Other faces:
#+vindex: org-transclusion-live-sync-map
- =org-transclusion-map=
-#+transclude: [[./org-transclusion.org::org-transclusion-map]]
+#+transclude: [[./org-transclusion-manual.org::org-transclusion-map]]
- =org-transclusion-live-sync-map=
-#+transclude: [[./org-transclusion.org::org-transclusion-live-sync-map]]
+#+transclude:
[[./org-transclusion-manual.org::org-transclusion-live-sync-map]]
* Known Limitations
@@ -665,3 +665,7 @@ It seems like this could work well for headlines, and named
tables, src blocks,
# LocalWords: href img src devel GPLv texinfo insertcopying toc RET findex
# LocalWords: vindex cindex dir
+
+# Local Variables:
+# time-stamp-start: "modified +\\\\?"
+# End:
diff --git a/org-transclusion.info b/org-transclusion.info
deleted file mode 100644
index e7dc767699..0000000000
--- a/org-transclusion.info
+++ /dev/null
@@ -1,1695 +0,0 @@
-This is org-transclusion.info, produced by makeinfo version 6.7 from
-org-transclusion.texi.
-
-Copyright (C) 2021 Free Software Foundation, Inc.
-
- Permission is granted to copy, distribute and/or modify this
- document under the terms of the GNU Free Documentation License,
- Version 1.3 or any later version published by the Free Software
- Foundation; with no Invariant Sections, with the Front-Cover Texts
- being “A GNU Manual,” and with the Back-Cover Texts as in (a)
- below. A copy of the license is included in the section entitled
- “GNU Free Documentation License.”
-
- (a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
- modify this GNU manual.”
-
-INFO-DIR-SECTION Emacs
-START-INFO-DIR-ENTRY
-* Org-transclusion: (org-transclusion). Transclusion in Org mode.
-END-INFO-DIR-ENTRY
-
-
-File: org-transclusion.info, Node: Top, Next: Example Use Cases & Main
Features, Up: (dir)
-
-Org-transclusion User Manual
-****************************
-
-This manual is for Org-transclusion 1.0.x.
-
-Last updated 24 December 2021.
-
-Org-transclusion lets you insert a copy of text content via a file link
-or ID link within an Org file. It lets you have the same content
-present in different buffers at the same time without copy-and-pasting
-it. Edit the source of the content, and you can refresh the transcluded
-copies to the up-to-date state. Org-transclusion keeps your files clear
-of the transcluded copies, leaving only the links to the original
-content.
-
-Copyright (C) 2021 Free Software Foundation, Inc.
-
- Permission is granted to copy, distribute and/or modify this
- document under the terms of the GNU Free Documentation License,
- Version 1.3 or any later version published by the Free Software
- Foundation; with no Invariant Sections, with the Front-Cover Texts
- being “A GNU Manual,” and with the Back-Cover Texts as in (a)
- below. A copy of the license is included in the section entitled
- “GNU Free Documentation License.”
-
- (a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
- modify this GNU manual.”
-
-* Menu:
-
-* Example Use Cases & Main Features::
-* Installation::
-* Getting Started::
-* Usage:: Features in detail
-* Customizing::
-* Known Limitations::
-* Credits::
-* Contributing::
-* Index - Features:: Key concepts & features
-* Index - Commands:: Interactive functions
-* Index - User Options:: Customizable variables & faces
-* GNU Free Documentation License::
-
-— The Detailed Node Listing —
-
-Usage
-
-* Org-transclusion mode, activate, and deactivate: Org-transclusion mode
activate and deactivate.
-* Org links supported::
-* Control levels of headlines per transclusion::
-* Filter Org elements per transclusion::
-* Live-sync edit::
-* Transclude source file into src-block::
-* Transclude range of lines for text and source files::
-* Extensions::
-
-Filter Org elements per transclusion
-
-* Notes on excluding the headline element::
-
-Transclude range of lines for text and source files
-
-* lines property to specify a range of lines::
-* end property to specify a search term to dynamically look for the end of a
range::
-
-Customizing
-
-* Customizable filter to exclude certain Org elements::
-* Include the section before the first headline (Org file only)::
-* Faces & fringe bitmap::
-* Keybindings::
-
-Faces & fringe bitmap
-
-* Face for the #+transclude keyword::
-* Faces for the fringes next to transcluded region and source region::
-
-Credits
-
-* Original idea by John Kitchin::
-* Text-Clone::
-
-
-
-File: org-transclusion.info, Node: Example Use Cases & Main Features, Next:
Installation, Prev: Top, Up: Top
-
-1 Example Use Cases & Main Features
-***********************************
-
-Here are a summary of some real use cases that users have shared with
-the author, including his own.
-
-Book writing
- You have a collection of notes. You can quickly transclude
- paragraphs and sections from your notes and put together a draft.
- As transclusions are links, it’s easy to re-organize them into
- different sequences to see which way works the best.
-
-Academic writing
- You have a collection of quotes and notes from your research and
- literature review. Transclude relevant elements of quotes and
- notes into different papers. You can keep your collection as the
- central repository of your research.
-
-Technical writing
- You write technical documents for software. Transclude relevant
- lines of code into the document. As the code is only transcluded,
- you can keep the document up-to-date as the code evolves.
-
-Project status reports
- You work on multiple projects at the same time and need to report
- to different project managers. Transclude relevant parts of your
- work notes and logs into respective project reports. You can keep
- a single collection of your work notes and logs.
-
-Main Features:
-
- • Insert a copy of text content via a file link or ID link into an
- Org file
-
- • Work with any text file such as program source code, plain text,
- Markdown, or other Org files
-
- • Keep the file system clear of the copies of text content –
- Org-transclusion tries hard to save only the links to the file
- system
-
- • For Org files, use different headline levels from the source Org
- file
-
- • For Org files, use filters to include only relevant elements (e.g.
- filter out properties in the transclusions)
-
- • For program source and plain text files, transclude a certain lines
- or dynamically specify the from/to lines to keep the transclusion
- always up-to-date with the evolving source files
-
- • For program source files, transclude parts or whole code directly
- into Org’s source block to leverage the rich Org features
-
- • Extend Org-transclusion with its extension framework
-
-
-File: org-transclusion.info, Node: Installation, Next: Getting Started,
Prev: Example Use Cases & Main Features, Up: Top
-
-2 Installation
-**************
-
-This package is available on GNU ELPA
-(https://elpa.gnu.org/packages/org-transclusion.html). You can do ‘M-x
-package-install RET org-transclusion’ to install it. After
-installation, you can start using Org-transclusion.
-
-Below are some example keybindings that can be put into your Emacs
-configuration.
-
- (define-key global-map (kbd "<f12>") #'org-transclusion-add)
- (define-key global-map (kbd "C-n t") #'org-transclusion-mode)
-
-For Doom users, you would need to do something like this below to
-install the package and configure the keybindings.
-
- ;; ~/.doom.d/package.el
- (package! org-transclusion)
-
- ;; ~/.doom.d/config.el
- (use-package! org-transclusion
- :after org
- :init
- (map!
- :map global-map "<f12>" #'org-transclusion-add
- :leader
- :prefix "n"
- :desc "Org Transclusion Mode" "t" #'org-transclusion-mode))
-
-
-File: org-transclusion.info, Node: Getting Started, Next: Usage, Prev:
Installation, Up: Top
-
-3 Getting Started
-*****************
-
-The basic idea of Org-transclusion is simple: insert a copy of text
-content via a file link or ID link within an Org file. This is an Org
-Mode version of transclusion.
-
-To transclude content via a link, use one of the following commands:
-
- • ‘org-transclusion-add’
-
- • ‘org-transclusion-add-all’
-
- • ‘org-transclusion-make-from-link’
-
-For example, if you have an ID link in your Org file like this:
-
- [[id:20210501T171427.051019][Bertrand Russell]]
-
-Simply type to add ‘#+transclude:’ in front of the link like the example
-below.
-
- #+transclude: [[id:20210501T171427.051019][Bertrand Russell]]
-
-Put your cursor somewhere on this keyword line and type ‘M-x
-org-transclusion-add RET’, and you will see the text content that the ID
-points 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 text is *read-only* but you can copy it and export it as
-normal text. Org-transclusion remembers where it has transcluded the
-text from (its source buffer). You can call a number of useful commands
-with a single letter (by default).
-
-For example, you can press ‘o’ to open the source buffer of the
-transclusion at point, or ‘O’ (capital "o") to open and move to it.
-Press ‘g’ to refresh the transclusion. Press ‘e’ to start live-sync
-edit. For more detail, inspect the documentation of each command.
-Press ‘d’ to remove the transcluded content, putting the original
-‘#+transclude: [[id:id-of-the-content]]’.
-
-This single-letter-context-menu is defined in ‘org-transclusion-map’.
-The default keybindings are shown below. Adapt them to your liking,
-especially if you use Vim keybindings with Evil Mode, etc.
-
- key binding
- --- -------
-
- C-c Prefix Command
- TAB org-cycle
- D org-transclusion-demote-subtree
- O org-transclusion-move-to-source
- P org-transclusion-promote-subtree
- d org-transclusion-remove
- e org-transclusion-live-sync-start
- g org-transclusion-refresh
- o org-transclusion-open-source
-
- C-c C-c org-ctrl-c-ctrl-c
-
-
-This should get you started with Org-transclusion. There are more
-options and customizing options available for you to fine-tune the text
-content you transclude. Explore the rest of the user manual and play
-with Org-transclusion to get familiar with it.
-
-
-File: org-transclusion.info, Node: Usage, Next: Customizing, Prev: Getting
Started, Up: Top
-
-4 Usage
-*******
-
-* Menu:
-
-* Org-transclusion mode, activate, and deactivate: Org-transclusion mode
activate and deactivate.
-* Org links supported::
-* Control levels of headlines per transclusion::
-* Filter Org elements per transclusion::
-* Live-sync edit::
-* Transclude source file into src-block::
-* Transclude range of lines for text and source files::
-* Extensions::
-
-
-File: org-transclusion.info, Node: Org-transclusion mode activate and
deactivate, Next: Org links supported, Up: Usage
-
-4.1 Org-transclusion mode, activate, and deactivate
-===================================================
-
-Org-transclusion is a local minor mode; however, you do not need to
-explicitly call ‘org-transclusion-mode’. The minor mode is intended to
-be just a convenient wrapper to let you easily toggle between ‘activate’
-and ‘deactivate’.
-
-As you saw in the *note Getting Started section: Getting Started. above,
-calling ‘org-transclusion-add’ or ‘org-transclusion-add-all’ is enough
-to add transclusions in your current buffer.
-
-The minor mode is automatically turned on locally for your current
-buffer through one of these commands. All it does is to call
-‘org-transclusion-activate’ to activate hooks and some other variables.
-Their main purpose is to keep files in the filesystem clear of the
-transcluded content.
-
-Turn off the minor mode or use ‘org-transclusion-deactivate’; you will
-remove all the transclusions in the current buffer and clear the hooks
-and other setup variables.
-
-If you prefer, you can use ‘org-transclusion-mode’ as your entry command
-for transclusion. When customizable variable
-‘org-transclusion-add-all-on-activate’ is non-nil (it is ‘t’ by
-default), turning on the minor mode calls the ‘org-transclusion-add-all’
-command to attempt to add all transclusions automatically in the current
-buffer.
-
-You can control whether or not transclusions are to be added
-automatically per transclude keyword. By default,
-‘org-transclusion-add-all’ (it is also used by ‘org-transclusion-mode’)
-will work on every transclude keyword in the buffer. Add
-‘:disable-auto’ property to a keyword as shown in the example below;
-‘add-all’ skips transclude keywords with it.
-
- #+transclude: [[file:path/to/file.org]] :disable-auto
-
-You can override the ‘:disable-auto’ property by manually calling
-‘org-transclusion-add’ at point.
-
-
-File: org-transclusion.info, Node: Org links supported, Next: Control levels
of headlines per transclusion, Prev: Org-transclusion mode activate and
deactivate, Up: Usage
-
-4.2 Org links supported
-=======================
-
-Transclusion has been tested to work for the following types of links:
-
- • File link for an entire org file/buffer; e.g.
- ‘[[file:~/org/file.org][My Org Notes]]’
- • File link with ‘::*heading’
- • File link with ‘::#custom-id’
- • File link with ‘::name’ for blocks (e.g. blocked quotations),
- tables, and links
- • File link with ‘::dedicated-target’; this is intended for linking
- to a paragraph. See below.
- • ID link ‘id:uuid’
- • File link for non-org files (tested with ‘.txt’ and ‘.md’); for
- these, the whole buffer gets transcluded
-
- Note: Search-options ‘::/regex/’ and ‘::number’ do not work as
- intended.
-
-For transcluding a specific paragraph, there are two main ways: Org
-Mode’s dedicated-target
-(https://orgmode.org/manual/Internal-Links.html#Internal-Links) and
-‘:only-contents’ property.
-
-For dedicated targets, the target paragraph must be identifiable by a
-dedicated target with a ‘<<paragraph-id>>’:
-
- Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- Suspendisse ac velit fermentum, sodales nunc in,
- tincidunt quam. <<paragraph-id>>
-
-It is generally assumed that the ‘paragraph-id’ is placed after its
-content, but it is not an absolute requirement; it can be in the
-beginning (before the content) or in the middle of it.
-
-For the ‘:only-contents’ property, refer to sub-section *note Filtering
-Org elements per transclusion: Filter Org elements per transclusion.
-
-
-File: org-transclusion.info, Node: Control levels of headlines per
transclusion, Next: Filter Org elements per transclusion, Prev: Org links
supported, Up: Usage
-
-4.3 Control levels of headlines per transclusion
-================================================
-
-When you transclude Org contents, you can specify a different headline
-level than those of the source Org file.
-
-Use the ‘:level’ property with a value of single digit number from 1 to
-9 like this example below.
-
- #+transclude: [[file:path/to/file.org::*Headline]] :level 2
-
-The top level of the transcluded headline will set to the value of
-‘:level’ property – in this example, level 2 regardless of that in the
-source. When the headline contains sub-headlines, they will be all
-automatically promoted or demoted to align according to how many levels
-the top of the subtree will move.
-
-When you transclude an entire Org file, it may contain multiple
-subtrees. In such cases, the top-most level among the subtrees will be
-set according to the ‘:level’ property; the rest of headlines in the
-buffer will align accordingly.
-
-Other ways to control include the following.
-
-‘org-transclusion-make-from-link’
- Make a transclusion keyword from a link at point. If you pass a
- positive number 1-9 with ‘digit-argument’ (e.g. prefix ‘M-x’ with
- ‘C-2’ to pass "2"), this function automatically puts the ‘:level’
- property to the resultant transclusion keyword.
-
-‘org-transclusion-promote-subtree’
- Promote transcluded subtree at point. Mapped to "P" (capital "p")
- by default in ‘org-transclusion-map’
-
-‘org-transclusion-demote-subtree’
- Demote transcluded subtree at point. Mapped to "D" (capital "D")
- by default in ‘org-transclusion-map’
-
-
-File: org-transclusion.info, Node: Filter Org elements per transclusion,
Next: Live-sync edit, Prev: Control levels of headlines per transclusion, Up:
Usage
-
-4.4 Filter Org elements per transclusion
-========================================
-
-You can control what elements to include in many different ways with
-using various filters. The filters work in two layers: customizable
-variable and properties per transclude keyword.
-
-The following two customizable variables are applicable to all
-transclusions globally. You can think of them as the global default.
-
-‘org-transclusion-exclude-elements’
- This customizable variable globally defines the exclusion filter
- for elements. It is a list of symbols; the acceptable values can
- be seen by inspecting ‘org-element-all-elements’. The default is
- to exclude ‘property-drawer’.
-
- Refer also to the *note sub-section on this user option:
- Customizable filter to exclude certain Org elements.
-
-‘org-transclusion-include-first-section’
- This customizing variable globally defines whether or not to
- include the first section of the source Org file. The first
- section is the part before the first headline – that’s the section
- that typically contains ‘#+title’, ‘#+author’, and so on. Many
- people also write notes in it without adding any headlines. Note
- that this user option’s default is now ‘t’ (changed from ‘nil’ as
- users seem to spend time to "correct" this issue). Turn it to ‘t’
- if you wish to transclude the content from the first section of
- your Org files. If you wish to exclude the "meta data" defined by
- ‘#+title’ and others, exclude ‘keyword’ as described in this
- section – these meta data are defined with using the ‘keyword’
- element of Org Mode.
-
- Refer also to the *note sub-section on this user option: Include
- the section before the first headline (Org file only).
-
-In addition to the global user options above, you can fine-tune the
-default exclusion filter per transclusion. Add following properties to
-transclusions you wish to apply additional filters.
-
-‘:only-contents’
- This property lets you exclude titles of headlines when you
- transclude a subtree (headline); you transclude only the contents.
- When the subtree contains sub-headlines, all the contents will be
- transcluded.
-
- Add ‘:only-contents’ without any value like this example:
-
- #+transclude: [[file:path/to/file.org]] :only-contents
-
-‘:exclude-elements’
- This property lets you *add* elements to exclude per transclusion
- on top of the variable ‘org-transclusion-exclude-elements’ defines.
- You cannot *remove* the ones defined by it; thus, it is intended
- that you use the customizable variable as your global default and
- fine-tune it by the property per transclusion.
-
- Add ‘:exclude-elements’ with a list of elements (each one as
- defined by ‘org-element-all-elements’) separated by a space inside
- double quotation marks like this example:
-
- #+transclude: [[file:path/to/file.org]] :exclude-elements "drawer keyword"
-
-You can combine ‘:only-contents’ and ‘:exclude-elements’ to control how
-you transclude a subtree. With these properties, you can really have
-great control over what to include and exclude. It might be a little
-overwhelming at a time but the changes via properties are easy to change
-– simply press ‘d’ to remove the transclusion, change the properties,
-and transclude again to see a new result.
-
-* Menu:
-
-* Notes on excluding the headline element::
-
-
-File: org-transclusion.info, Node: Notes on excluding the headline element,
Up: Filter Org elements per transclusion
-
-4.4.1 Notes on excluding the headline element
----------------------------------------------
-
-If you add ‘headline’ as a list of elements to exclude, you exclude
-sub-headlines within your subtrees and you will still transclude the
-content of the top-most headline of the subtrees.
-
-If you are transcluding only one subtree, this should be intuitive. If
-you transclude a whole buffer, you might be transcluding multiple
-subtrees. In some cases, this can be a little anti-intuitive. In the
-following examples, you will be transcluding three subtrees – even
-though the first headline levels are lower than the third one, the first
-two are still the top-most level of their own respective subtrees.
-
- ** Headline 1
- Content of Headline 1
- ** Headline 2
- Content of Headline 2
- * Headline 3
- Content of Headline
-
-
-File: org-transclusion.info, Node: Live-sync edit, Next: Transclude source
file into src-block, Prev: Filter Org elements per transclusion, Up: Usage
-
-4.5 Live-sync edit
-==================
-
-*Experimental.* You can start live-sync edit by pressing ‘e’ (by
-default) on a text element you want to edit. This will call
-‘org-transclusion-live-sync-start’ and put a colored overlay on top of
-the region being live-synced and brings up another buffer that visits
-the source file of the transclusion. The source buffer will also have a
-corresponding overlay to the region being edited and live-synced.
-
-If you have other windows open, they will be temporarily hidden –
-Org-transclusion will remembers your current window layout and attempts
-to recover it when you exit live-sync edit.
-
-In the live-sync edit region, you can freely type to edit the
-transclusion or source regions; they will sync simultaneously.
-
-Once done with editing, press ‘C-c C-c’ to exit live-sync edit. The key
-is bound to ‘org-transclusion-live-sync-exit’. It will turn off the
-live sync edit but keep the transclusion on.
-
-In the live-sync edit region, the normal ‘yank’ command (‘C-y’) is
-replaced with a special command ‘org-transclusion-live-sync-paste’.
-This command lets the pasted text inherit the text-properties of the
-transcluded region correctly; the normal yank does not have this feature
-and thus causes some inconvenience in live-sync edit. If you use vim
-keybindings (e.g. ‘evil-mode’), it is advised that you review the
-default keybindings. You can customize the local keybindings for the
-live-sync region by ‘org-transclusion-live-sync-map’.
-
-*Note*: During live-sync edit, file’s content gets saved to the file
-system as is – i.e. the transcluded text will be saved instead of the
-‘#+transclude:’ keyword. If you kill buffer or quit Emacs, other hooks
-will still remove the transclusion to keep the file clear of the
-transcluded copy, leaving only the keyword in the file system.
-
- (substitute-command-keys "\\{org-transclusion-live-sync-map}")
-
- key binding
- --- -------
-
- C-c Prefix Command
- C-y org-transclusion-live-sync-paste
-
- C-c C-c org-transclusion-live-sync-exit
-
- *Also inherits ‘org-mode-map’
-
-
-File: org-transclusion.info, Node: Transclude source file into src-block,
Next: Transclude range of lines for text and source files, Prev: Live-sync
edit, Up: Usage
-
-4.6 Transclude source file into src-block
-=========================================
-
-This feature is provided as an *note extension: Extensions. (default
-on).
-
-You can transclude a source file into an Org’s src block. Use the
-‘:src’ property and specify the language you would like to use like
-this:
-
- #+transclude: [[file:../../test/python-1.py]] :src python
-
-The content you specify in the link gets wrapped into a src-block with
-the language like this:
-
- #+begin_src python
- [... content of python-1.py]
- #+end_src
-
-Use ‘:rest’ property to define additional properties you would like to
-add for the src-block. The double quotation marks are mandatory for the
-‘:rest’ property.
-
- #+transclude: [[file:../../test/python-3.py]] :src python :rest
":session :results value"
-
-The source block will have the additional properties:
- #+begin_src python :session :results value
-
-
-File: org-transclusion.info, Node: Transclude range of lines for text and
source files, Next: Extensions, Prev: Transclude source file into src-block,
Up: Usage
-
-4.7 Transclude range of lines for text and source files
-=======================================================
-
-This feature is provided as an *note extension: Extensions. (default
-on).
-
-When you transclude text files other than Org files,
-
-* Menu:
-
-* lines property to specify a range of lines::
-* end property to specify a search term to dynamically look for the end of a
range::
-
-
-File: org-transclusion.info, Node: lines property to specify a range of
lines, Next: end property to specify a search term to dynamically look for the
end of a range, Up: Transclude range of lines for text and source files
-
-4.7.1 ‘:lines’ property to specify a range of lines
----------------------------------------------------
-
-You can specify a range of lines to transclude from a source and text
-file. Use the ‘:lines’ property like this.
-
- #+transclude: [[file:../../test/test.txt]] :lines 3-5
-
-The rage is specified by the number "3-5"; in this case, lines from 3 to
-5, both lines inclusive.
-
-To transclude a single line, have the the same number in both places
-(e.g. 10-10, meaning line 10 only).
-
-One of the numbers can be omitted. When the first number is omitted
-(e.g. -10), it means from the beginning of the file to line 10.
-Likewise, when the second number is omitted (e.g. 10-), it means from
-line 10 to the end of file.
-
-You can combine the ‘:lines’ property with the ‘:src’ property to
-transclude only a certain range of source files (Example 1 below).
-
-For Org’s file links, you can use search options
-(https://orgmode.org/manual/Search-Options.html) specified by the "::"
-(two colons) notation. When a search finds a line that includes the
-string, the Org-transclude counts it as the starting line 1 for the
-‘:lines’ property.
-
-Example 1: This transcludes the four lines of the source file from the
-line that contains string "id-1234" (including that line counted as line
-1).
- #+transclude: [[file:../../test/python-1.py::id-1234]] :lines 1-4 :src
python
-
-Example 2: This transcludes only the single line that contains the line
-found by the search option for text string "Transcendental Ontology"
- #+transclude: [[file:../../test/test.txt::Transcendental Ontology]]
:lines 1-1
-
-Note search-options ‘::/regex/’ and ‘::number’ do not work as intended.
-
-
-File: org-transclusion.info, Node: end property to specify a search term to
dynamically look for the end of a range, Prev: lines property to specify a
range of lines, Up: Transclude range of lines for text and source files
-
-4.7.2 ‘:end’ property to specify a search term to dynamically look for the end
of a range
------------------------------------------------------------------------------------------
-
-You can add ‘:end’ property and specify the search term as its value.
-Surround the search term with double quotation marks (mandatory).
-
-See Example 3 below. This transclusion will look for ‘id-1234’ as the
-beginning line of the range as specified by the search option
-‘::id-1234’ in the link. With the ‘:end’ property, the search term
-‘id-1234 end here’ defines the end of the range. The search looks for
-‘id-123 end here’ in the body text, and use the line one before the one
-where the text is find (thus, the transcluded range will not contain
-‘id-1234 end here’).
-
-You can also combined ‘:lines’ property with ‘:end’ property. It will
-only displace the beginning, and the end part of the range (the second
-number after the hyphen "-") is ignored. In the same example, the
-beginning of the range is the one line after the line where "id-1234" is
-found; it’s the "second line, or line 2". Instead of transcluding until
-the end of the buffer, the end is defined by the ‘:end’ property.
-
-Example 3:
- #+transclude: [[file:../../test/python-1.py::id-1234]] :lines 2- :src
python :end "id-1234 end here"
-
-
-File: org-transclusion.info, Node: Extensions, Prev: Transclude range of
lines for text and source files, Up: Usage
-
-4.8 Extensions
-==============
-
-Org-transclusion provides a simple extension framework, where you can
-use ‘customize’ to selectively add new features.
-
-If you use ‘customize’, the features are loaded automatically. Note
-that it does not "unload" the feature until you relaunch Emacs.
-
-If you do not use ‘customize’ (e.g. Doom), you may need to explicitly
-require an extension. For example, to activate
-‘org-transclusion-indent-mode’, you might need to add something like
-this in your configuration file.
-
- ;; Ensure that load-path to org-transclusion is already added
- ;; If you installed it with the built-in package.el, this should be
already done.
- ;; (add-to-list 'load-path "path/to/org-transclusion/")
- (add-to-list 'org-transclusion-extensions 'org-transclusion-indent-mode)
- (require 'org-transclusion-indent-mode)
-
-Currently, the following extensions are available.
-
-(off by default) ‘org-transclusion-indent-mode’
- Support org-indent-mode.
-
-(on by default) ‘org-transclusion-src-lines’
- Add features for ‘:src’ and ‘:lines’ properties to ‘#+transclude’.
- It is meant for non-Org files such as program source and text files
-
-(on by default) ‘org-transclusion-font-lock’
- Add font-lock for ‘#+transclude’. Org mode’s standard syntax
- treats the combination of a ‘#+transclude:’ keyword and a link used
- by Org-transclusion as a keyword. This means it applies the
- ‘org-meta-line’ face and the link part cannot be toggled as a
- normal link. This extension adds ‘org-transclusion-keyword’ face
- to the keyword part and lets the link part to be treated as a
- normal link for ‘org-toggle-link-display’.
-
-
-File: org-transclusion.info, Node: Customizing, Next: Known Limitations,
Prev: Usage, Up: Top
-
-5 Customizing
-*************
-
-You can customize settings in the ‘org-transclusion’ group.
-
-‘org-transclusion-extensions’
- Defines extensions to be loaded with org-transclusion.el. If you
- use ‘customize’, the extensions are loaded by it. If you don’t,
- you likely need to explicitly use ‘require’ to load them. See
- *note seb-section: Extensions.
-
-‘org-transclusion-add-all-on-activate’
- Defines whether or not all the active transclusions (with ‘t’) get
- automatically transcluded on minor mode activation
- (‘org-transclusion-mode’). This does not affect the manual
- activation when you directly call ‘org-transclusion-activate’
-
-‘org-transclusion-exclude-elements’
- See *note sub-section: Customizable filter to exclude certain Org
- elements.
-
-‘org-transclusion-include-first-section’
- See *note sub-section: Include the section before the first
- headline (Org file only).
-
-‘org-transclusion-open-source-display-action-list’
- You can customize the way the ‘org-transclusion-open-source’
- function displays the source buffer for the transclusion. You
- specify the "action" in the way defined by the built-in
- ‘display-buffer’ function. Refer to its in-system documentation
- (with ‘C-h f’) for the accepted values. ‘M-x customize’ can also
- guide you on what types of values are accepted.
-
-‘org-transclusion-mode-lighter’
- Define the lighter for Org-transclusion minor mode. The default is
- " OT".
-
-* Menu:
-
-* Customizable filter to exclude certain Org elements::
-* Include the section before the first headline (Org file only)::
-* Faces & fringe bitmap::
-* Keybindings::
-
-
-File: org-transclusion.info, Node: Customizable filter to exclude certain Org
elements, Next: Include the section before the first headline (Org file only),
Up: Customizing
-
-5.1 Customizable filter to exclude certain Org elements
-=======================================================
-
-Set customizable variable ‘org-transclusion-exclude-elements’ to define
-which elements to be *excluded* in the transclusion.
-
-The filter works for all supported types of links within an Org file
-when transcluding an entire Org file, and parts of it (headlines, custom
-ID, etc.). There is no filter for non-Org files.
-
-It is a list of symbols, and the default is ‘(property-drawer)’. The
-accepted values are the ones defined by ‘org-element-all-elements’
-(Org’s standard set of elements; refer to its documentation for an
-exhaustive list).
-
-You can also fine-tune the exclusion filter per transclusion. Refer to
-the sub-section on *note filtering Org elements per transclusion: Filter
-Org elements per transclusion.
-
-
-File: org-transclusion.info, Node: Include the section before the first
headline (Org file only), Next: Faces & fringe bitmap, Prev: Customizable
filter to exclude certain Org elements, Up: Customizing
-
-5.2 Include the section before the first headline (Org file only)
-=================================================================
-
-You can include the first section (section before the first headline) of
-an Org file. It is toggled via customizable variable
-‘org-transclusion-include-first-section’. Its default value is ‘t’.
-Set it to ‘t’ (or non-nil) to transclude the first section. It also
-works when the first section is followed by headlines.
-
-
-File: org-transclusion.info, Node: Faces & fringe bitmap, Next: Keybindings,
Prev: Include the section before the first headline (Org file only), Up:
Customizing
-
-5.3 Faces & fringe bitmap
-=========================
-
-* Menu:
-
-* Face for the #+transclude keyword::
-* Faces for the fringes next to transcluded region and source region::
-
-
-File: org-transclusion.info, Node: Face for the #+transclude keyword, Next:
Faces for the fringes next to transcluded region and source region, Up: Faces
& fringe bitmap
-
-5.3.1 Face for the ‘#+transclude’ keyword
------------------------------------------
-
-This feature is provided as an *note extension: Extensions. (default
-on).
-
-‘org-transclusion-keyword’
- You can set your own face to the ‘#+transclude’ keyword with using
- the ‘org-transclusion-keyword’ face.
-
-
-File: org-transclusion.info, Node: Faces for the fringes next to transcluded
region and source region, Prev: Face for the #+transclude keyword, Up: Faces
& fringe bitmap
-
-5.3.2 Faces for the fringes next to transcluded region and source region
-------------------------------------------------------------------------
-
-If the fringes that indicate transcluding and source regions are not
-visible in your system (e.g. Doom), try adding background and/or
-foreground colors to these custom faces.
-
- • ‘org-transclusion-source-fringe’
- • ‘org-transclusion-fringe’
-
-To customize a face, it’s probably the easiest to use ‘M-x
-customize-face’. If you want to use Elisp for some reason (e.g. on
-Doom), something like this below should set faces. Experiment with the
-colors of your choice. By default, the faces above have no values.
-
- (set-face-attribute
- 'org-transclusion-fringe nil
- :foreground "green"
- :background "green")
-
-For colors, where "green" is, you can also use something like "#62c86a"
-(Emacs calls it "RGB triple"; you can refer to in-system manual Emacs >
-Colors). You might also like to refer to a list of currently defined
-faces in your Emacs by ‘list-faces-display’.
-
-Other faces:
- • ‘org-transclusion-source’
- • ‘org-transclusion-source-edit’
- • ‘org-transclusion’
- • ‘org-transclusion-edit’
- • ‘org-transclusion-fringe-bitmap’ It is used for the fringe that
- indicates the transcluded region. It works only in a graphical
- environment (not in terminal).
-
-
-File: org-transclusion.info, Node: Keybindings, Prev: Faces & fringe bitmap,
Up: Customizing
-
-5.4 Keybindings
-===============
-
- • ‘org-transclusion-map’
- 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
-
- • ‘org-transclusion-live-sync-map’
- key binding
- --- -------
-
- C-c Prefix Command
- C-y org-transclusion-live-sync-paste
-
- C-c C-c org-transclusion-live-sync-exit
-
- *Also inherits ‘org-mode-map’
-
-
-File: org-transclusion.info, Node: Known Limitations, Next: Credits, Prev:
Customizing, Up: Top
-
-6 Known Limitations
-*******************
-
-Note this section is still incomplete, not exhaustive for "known"
-limitations.
-
- • Org link’s search-options ‘::/regex/’ and ‘::number’ do not work as
- intended.
-
- • ‘org-transclusion-live-sync-start’ does not support all Org
- elements For transclusions of Org elements or buffers, live-sync
- works only on the following elements: ‘center-block’, ‘drawer’,
- ‘dynamic-block’, ‘latex-environment’, ‘paragraph’, ‘plain-list’,
- ‘quote-block’, ‘special-block’, ‘table’, and ‘verse-block’.
-
- It is known that live-sync does not work for the other elements;
- namely: ‘comment-block’, ‘export-block’, ‘example-block’,
- ‘fixed-width’, ‘keyword’, ‘src-block’, and ‘property-drawer’.
-
- More technical reason for this limitation is documented in the
- docstring of function
- ‘org-transclusion-live-sync-enclosing-element’.
-
- Work is in progress to lift this limitation but I’m still
- experimenting different ideas.
-
- • ‘org-indent-mode’ may not work well with Org-transclusion A new
- extension has been added to support ‘org-indent-mode’ Refer to
- *note this section: Extensions.
-
- • Doom’s customization may interfere with Org-transclusion Refer to
- issue #52 (https://github.com/nobiot/org-transclusion/issues/52).
- The symptom is that in Doom you get an error message that includes
- this: "progn: ‘recenter’ing a window that does not display
- current-buffer." Adding this in your configuration has been
- reported to fix the issue:
-
- ‘(advice-remove 'org-link-search
- '+org--recenter-after-follow-link-a)’
-
- It is probably rather drastic a measure. I will appreciate it if
- you find a less drastic way that works. Thank you.
-
- • Org refile does not work "properly" on the transcluded headlines
- Refer to issue #20
- (https://github.com/nobiot/org-transclusion/issues/20). I don’t
- intend to support this – refile the source, not the transcluded
- copy.
-
- • Org-transclusion does not support expansion of noweb references
- when a transcluded source block code has them Refer to issue #86
- (https://github.com/nobiot/org-transclusion/issues/86). You will
- get "Text read-only" error when export tries to expand the noweb
- references into the source code. †noweb reference
- (https://orgmode.org/manual/Noweb-Reference-Syntax.html)
-
-
-File: org-transclusion.info, Node: Credits, Next: Contributing, Prev: Known
Limitations, Up: Top
-
-7 Credits
-*********
-
-* Menu:
-
-* Original idea by John Kitchin::
-* Text-Clone::
-
-
-File: org-transclusion.info, Node: Original idea by John Kitchin, Next:
Text-Clone, Up: Credits
-
-7.1 Original idea by John Kitchin
-=================================
-
-<https://github.com/alphapapa/transclusion-in-emacs#org-mode>
-
- {O} transcluding some org-elements in multiple places _[2016-12-09
- ven.] _ John Kitchin asks:
-
- I have an idea for how I could transclude “copies” or links to
- org-elements in multiple places and keep them up to date. A
- prototypical example of this is I have a set of org-contacts in one
- place, and I want to create a new list of people for a committee in
- a new place made of “copies” of the contact headlines. But I do
- not really want to duplicate the headlines, and if I modify one, I
- want it reflected in the other places. I do not want just links to
- those contacts, because then I can not do things with
- org-map-entries, and other org-machinery which needs the actual
- headlines/properties present. Another example might be I want a
- table in two places, but the contents of them should stay
- synchronized, ditto for a code block.
-
- This idea was inspired by
- <https://github.com/gregdetre/emacs-freex>.
-
- The idea starts with creating (wait for it…) a new link ;) In a
- document where I want to transclude a headline, I would enter
- something like:
-
- transclude:some-file.org::*headline title
-
- Then, I would rely on the font-lock system to replace that link
- with the headline and its contents (via the :activate-func link
- property), and to put an overlay on it with a bunch of useful
- properties, including modification hooks that would update the
- source if I change the the element in this document, and some
- visual indication that it is transcluded (e.g. light gray
- background/tooltip).
-
- I would create a kill-buffer hook function that would replace that
- transcluded content with the original link. A focus-in hook
- function would make sure the transcluded content is updated when
- you enter the frame. So when the file is not open, there is just a
- transclude link indicating what should be put there, and when it is
- open, the overlay modification hooks and focus hook should ensure
- everything stays synchronized (as long as external processes are
- not modifying the contents).
-
- It seems like this could work well for headlines, and named tables,
- src blocks, and probably any other element that can be addressed by
- a name/ID.
-
-
-File: org-transclusion.info, Node: Text-Clone, Prev: Original idea by John
Kitchin, Up: Credits
-
-7.2 Text-Clone
-==============
-
-‘text-clone.el’ is an extension of text-clone functions written as part
-of GNU Emacs in ‘subr.el’. The first adaption to extend text-clone
-functions to work across buffers was published in StackExchange by the
-user named Tobias in March 2020. It can be found at
-<https://emacs.stackexchange.com/questions/56201/is-there-an-emacs-package-which-can-mirror-a-region/56202#56202>.
-The text-clone library takes this line of work further.
-
-
-File: org-transclusion.info, Node: Contributing, Next: Index - Features,
Prev: Credits, Up: Top
-
-8 Contributing
-**************
-
- • Get involved in a discussion in Org-roam forum
-
(https://org-roam.discourse.group/t/prototype-transclusion-block-reference-with-emacs-org-mode/830)
- (the package is originally aimed for its users, me included)
-
- • Create issues, discussion, and/or pull requests. All welcome.
-
-Org-transclusion is part of GNU ELPA and thus copyrighted by the Free
-Software Foundation (http://fsf.org) (FSF). This means that anyone who
-is making a substantive code contribution will need to "assign the
-copyright for your contributions to the FSF so that they can be included
-in GNU Emacs" (Org Mode website
-(https://orgmode.org/contribute.html#copyright)).
-
-Thank you.
-
-
-File: org-transclusion.info, Node: Index - Features, Next: Index - Commands,
Prev: Contributing, Up: Top
-
-Appendix A Index - Features
-***************************
-
-usion.
- (line 6)
-* Property - :only-contents: Org links supported. (line 6)
-* Property - :rest: Transclude source file into src-block.
- (line 6)
-* Property - :src: Transclude source file into src-block.
- (line 6)
-* Transclude into Org’s src-block: Transclude source file into src-block.
- (line 6)
-* Transclude range of lines: Transclude range of lines for text
and source files.
- (line 6)
-* Transclusion Properties: Org-transclusion mode activate and
deactivate.
- (line 6)
-
-
-File: org-transclusion.info, Node: Index - Commands, Next: Index - User
Options, Prev: Index - Features, Up: Top
-
-Appendix B Index - Commands
-***************************
-
- (Thus, if the Document
- is in part a textbook of mathematics, a Secondary Section may not
- explain any mathematics.) The relationship could be a matter of
- historical connection with the subject or with related matters, or
- of legal, commercial, philosophical, ethical or political position
- regarding them.
-
- The “Invariant Sections” are certain Secondary Sections whose
- titles are designated, as being those of Invariant Sections, in the
- notice that says that the Document is released under this License.
- If a section does not fit the above definition of Secondary then it
- is not allowed to be designated as Invariant. The Document may
- contain zero Invariant Sections. If the Document does not identify
- any Invariant Sections then there are none.
-
- The “Cover Texts” are certain short passages of text that are
- listed, as Front-Cover Texts or Back-Cover Texts, in the notice
- that says that the Document is released under this License. A
- Front-Cover Text may be at most 5 words, and a Back-Cover Text may
- be at most 25 words.
-
- A “Transparent” copy of the Document means a machine-readable copy,
- represented in a format whose specification is available to the
- general public, that is suitable for revising the document
- straightforwardly with generic text editors or (for images composed
- of pixels) generic paint programs or (for drawings) some widely
- available drawing editor, and that is suitable for input to text
- formatters or for automatic translation to a variety of formats
- suitable for input to text formatters. A copy made in an otherwise
- Transparent file format whose markup, or absence of markup, has
- been arranged to thwart or discourage subsequent modification by
- readers is not Transparent. An image format is not Transparent if
- used for any substantial amount of text. A copy that is not
- “Transparent” is called “Opaque”.
-
- Examples of suitable formats for Transparent copies include plain
- ASCII without markup, Texinfo input format, LaTeX input format,
- SGML or XML using a publicly available DTD, and standard-conforming
- simple HTML, PostScript or PDF designed for human modification.
- Examples of transparent image formats include PNG, XCF and JPG.
- Opaque formats include proprietary formats that can be read and
- edited only by proprietary word processors, SGML or XML for which
- the DTD and/or processing tools are not generally available, and
- the machine-generated HTML, PostScript or PDF produced by some word
- processors for output purposes only.
-
- The “Title Page” means, for a printed book, the title page itself,
- plus such following pages as are needed to hold, legibly, the
- material this License requires to appear in the title page. For
- works in formats which do not have any title page as such, “Title
- Page” means the text near the most prominent appearance of the
- work’s title, preceding the beginning of the body of the text.
-
- The “publisher” means any person or entity that distributes copies
- of the Document to the public.
-
- A section “Entitled XYZ” means a named subunit of the Document
- whose title either is precisely XYZ or contains XYZ in parentheses
- following text that translates XYZ in another language. (Here XYZ
- stands for a specific section name mentioned below, such as
- “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.)
- To “Preserve the Title” of such a section when you modify the
- Document means that it remains a section “Entitled XYZ” according
- to this definition.
-
- The Document may include Warranty Disclaimers next to the notice
- which states that this License applies to the Document. These
- Warranty Disclaimers are considered to be included by reference in
- this License, but only as regards disclaiming warranties: any other
- implication that these Warranty Disclaimers may have is void and
- has no effect on the meaning of this License.
-
- 2. VERBATIM COPYING
-
- You may copy and distribute the Document in any medium, either
- commercially or noncommercially, provided that this License, the
- copyright notices, and the license notice saying this License
- applies to the Document are reproduced in all copies, and that you
- add no other conditions whatsoever to those of this License. You
- may not use technical measures to obstruct or control the reading
- or further copying of the copies you make or distribute. However,
- you may accept compensation in exchange for copies. If you
- distribute a large enough number of copies you must also follow the
- conditions in section 3.
-
- You may also lend copies, under the same conditions stated above,
- and you may publicly display copies.
-
- 3. COPYING IN QUANTITY
-
- If you publish printed copies (or copies in media that commonly
- have printed covers) of the Document, numbering more than 100, and
- the Document’s license notice requires Cover Texts, you must
- enclose the copies in covers that carry, clearly and legibly, all
- these Cover Texts: Front-Cover Texts on the front cover, and
- Back-Cover Texts on the back cover. Both covers must also clearly
- and legibly identify you as the publisher of these copies. The
- front cover must present the full title with all words of the title
- equally prominent and visible. You may add other material on the
- covers in addition. Copying with changes limited to the covers, as
- long as they preserve the title of the Document and satisfy these
- conditions, can be treated as verbatim copying in other respects.
-
- If the required texts for either cover are too voluminous to fit
- legibly, you should put the first ones listed (as many as fit
- reasonably) on the actual cover, and continue the rest onto
- adjacent pages.
-
- If you publish or distribute Opaque copies of the Document
- numbering more than 100, you must either include a machine-readable
- Transparent copy along with each Opaque copy, or state in or with
- each Opaque copy a computer-network location from which the general
- network-using public has access to download using public-standard
- network protocols a complete Transparent copy of the Document, free
- of added material. If you use the latter option, you must take
- reasonably prudent steps, when you begin distribution of Opaque
- copies in quantity, to ensure that this Transparent copy will
- remain thus accessible at the stated location until at least one
- year after the last time you distribute an Opaque copy (directly or
- through your agents or retailers) of that edition to the public.
-
- It is requested, but not required, that you contact the authors of
- the Document well before redistributing any large number of copies,
- to give them a chance to provide you with an updated version of the
- Document.
-
- 4. MODIFICATIONS
-
- You may copy and distribute a Modified Version of the Document
- under the conditions of sections 2 and 3 above, provided that you
- release the Modified Version under precisely this License, with the
- Modified Version filling the role of the Document, thus licensing
- distribution and modification of the Modified Version to whoever
- possesses a copy of it. In addition, you must do these things in
- the Modified Version:
-
- A. Use in the Title Page (and on the covers, if any) a title
- distinct from that of the Document, and from those of previous
- versions (which should, if there were any, be listed in the
- History section of the Document). You may use the same title
- as a previous version if the original publisher of that
- version gives permission.
-
- B. List on the Title Page, as authors, one or more persons or
- entities responsible for authorship of the modifications in
- the Modified Version, together with at least five of the
- principal authors of the Document (all of its principal
- authors, if it has fewer than five), unless they release you
- from this requirement.
-
- C. State on the Title page the name of the publisher of the
- Modified Version, as the publisher.
-
- D. Preserve all the copyright notices of the Document.
-
- E. Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.
-
- F. Include, immediately after the copyright notices, a license
- notice giving the public permission to use the Modified
- Version under the terms of this License, in the form shown in
- the Addendum below.
-
- G. Preserve in that license notice the full lists of Invariant
- Sections and required Cover Texts given in the Document’s
- license notice.
-
- H. Include an unaltered copy of this License.
-
- I. Preserve the section Entitled “History”, Preserve its Title,
- and add to it an item stating at least the title, year, new
- authors, and publisher of the Modified Version as given on the
- Title Page. If there is no section Entitled “History” in the
- Document, create one stating the title, year, authors, and
- publisher of the Document as given on its Title Page, then add
- an item describing the Modified Version as stated in the
- previous sentence.
-
- J. Preserve the network location, if any, given in the Document
- for public access to a Transparent copy of the Document, and
- likewise the network locations given in the Document for
- previous versions it was based on. These may be placed in the
- “History” section. You may omit a network location for a work
- that was published at least four years before the Document
- itself, or if the original publisher of the version it refers
- to gives permission.
-
- K. For any section Entitled “Acknowledgements” or “Dedications”,
- Preserve the Title of the section, and preserve in the section
- all the substance and tone of each of the contributor
- acknowledgements and/or dedications given therein.
-
- L. Preserve all the Invariant Sections of the Document, unaltered
- in their text and in their titles. Section numbers or the
- equivalent are not considered part of the section titles.
-
- M. Delete any section Entitled “Endorsements”. Such a section
- may not be included in the Modified Version.
-
- N. Do not retitle any existing section to be Entitled
- “Endorsements” or to conflict in title with any Invariant
- Section.
-
- O. Preserve any Warranty Disclaimers.
-
- If the Modified Version includes new front-matter sections or
- appendices that qualify as Secondary Sections and contain no
- material copied from the Document, you may at your option designate
- some or all of these sections as invariant. To do this, add their
- titles to the list of Invariant Sections in the Modified Version’s
- license notice. These titles must be distinct from any other
- section titles.
-
- You may add a section Entitled “Endorsements”, provided it contains
- nothing but endorsements of your Modified Version by various
- parties—for example, statements of peer review or that the text has
- been approved by an organization as the authoritative definition of
- a standard.
-
- You may add a passage of up to five words as a Front-Cover Text,
- and a passage of up to 25 words as a Back-Cover Text, to the end of
- the list of Cover Texts in the Modified Version. Only one passage
- of Front-Cover Text and one of Back-Cover Text may be added by (or
- through arrangements made by) any one entity. If the Document
- already includes a cover text for the same cover, previously added
- by you or by arrangement made by the same entity you are acting on
- behalf of, you may not add another; but you may replace the old
- one, on explicit permission from the previous publisher that added
- the old one.
-
- The author(s) and publisher(s) of the Document do not by this
- License give permission to use their names for publicity for or to
- assert or imply endorsement of any Modified Version.
-
- 5. COMBINING DOCUMENTS
-
- You may combine the Document with other documents released under
- this License, under the terms defined in section 4 above for
- modified versions, provided that you include in the combination all
- of the Invariant Sections of all of the original documents,
- unmodified, and list them all as Invariant Sections of your
- combined work in its license notice, and that you preserve all
- their Warranty Disclaimers.
-
- The combined work need only contain one copy of this License, and
- multiple identical Invariant Sections may be replaced with a single
- copy. If there are multiple Invariant Sections with the same name
- but different contents, make the title of each such section unique
- by adding at the end of it, in parentheses, the name of the
- original author or publisher of that section if known, or else a
- unique number. Make the same adjustment to the section titles in
- the list of Invariant Sections in the license notice of the
- combined work.
-
- In the combination, you must combine any sections Entitled
- “History” in the various original documents, forming one section
- Entitled “History”; likewise combine any sections Entitled
- “Acknowledgements”, and any sections Entitled “Dedications”. You
- must delete all sections Entitled “Endorsements.”
-
- 6. COLLECTIONS OF DOCUMENTS
-
- You may make a collection consisting of the Document and other
- documents released under this License, and replace the individual
- copies of this License in the various documents with a single copy
- that is included in the collection, provided that you follow the
- rules of this License for verbatim copying of each of the documents
- in all other respects.
-
- You may extract a single document from such a collection, and
- distribute it individually under this License, provided you insert
- a copy of this License into the extracted document, and follow this
- License in all other respects regarding verbatim copying of that
- document.
-
- 7. AGGREGATION WITH INDEPENDENT WORKS
-
- A compilation of the Document or its derivatives with other
- separate and independent documents or works, in or on a volume of a
- storage or distribution medium, is called an “aggregate” if the
- copyright resulting from the compilation is not used to limit the
- legal rights of the compilation’s users beyond what the individual
- works permit. When the Document is included in an aggregate, this
- License does not apply to the other works in the aggregate which
- are not themselves derivative works of the Document.
-
- If the Cover Text requirement of section 3 is applicable to these
- copies of the Document, then if the Document is less than one half
- of the entire aggregate, the Document’s Cover Texts may be placed
- on covers that bracket the Document within the aggregate, or the
- electronic equivalent of covers if the Document is in electronic
- form. Otherwise they must appear on printed covers that bracket
- the whole aggregate.
-
- 8. TRANSLATION
-
- Translation is considered a kind of modification, so you may
- distribute translations of the Document under the terms of section
- 4. Replacing Invariant Sections with translations requires special
- permission from their copyright holders, but you may include
- translations of some or all Invariant Sections in addition to the
- original versions of these Invariant Sections. You may include a
- translation of this License, and all the license notices in the
- Document, and any Warranty Disclaimers, provided that you also
- include the original English version of this License and the
- original versions of those notices and disclaimers. In case of a
- disagreement between the translation and the original version of
- this License or a notice or disclaimer, the original version will
- prevail.
-
- If a section in the Document is Entitled “Acknowledgements”,
- “Dedications”, or “History”, the requirement (section 4) to
- Preserve its Title (section 1) will typically require changing the
- actual title.
-
- 9. TERMINATION
-
- You may not copy, modify, sublicense, or distribute the Document
- except as expressly provided under this License. Any attempt
- otherwise to copy, modify, sublicense, or distribute it is void,
- and will automatically terminate your rights under this License.
-
- However, if you cease all violation of this License, then your
- license from a particular copyright holder is reinstated (a)
- provisionally, unless and until the copyright holder explicitly and
- finally terminates your license, and (b) permanently, if the
- copyright holder fails to notify you of the violation by some
- reasonable means prior to 60 days after the cessation.
-
- Moreover, your license from a particular copyright holder is
- reinstated permanently if the copyright holder notifies you of the
- violation by some reasonable means, this is the first time you have
- received notice of violation of this License (for any work) from
- that copyright holder, and you cure the violation prior to 30 days
- after your receipt of the notice.
-
- Termination of your rights under this section does not terminate
- the licenses of parties who have received copies or rights from you
- under this License. If your rights have been terminated and not
- permanently reinstated, receipt of a copy of some or all of the
- same material does not give you any rights to use it.
-
- 10. FUTURE REVISIONS OF THIS LICENSE
-
- The Free Software Foundation may publish new, revised versions of
- the GNU Free Documentation License from time to time. Such new
- versions will be similar in spirit to the present version, but may
- differ in detail to address new problems or concerns. See
- <https://www.gnu.org/licenses/>.
-
- Each version of the License is given a distinguishing version
- number. If the Document specifies that a particular numbered
- version of this License “or any later version” applies to it, you
- have the option of following the terms and conditions either of
- that specified version or of any later version that has been
- published (not as a draft) by the Free Software Foundation. If the
- Document does not specify a version number of this License, you may
- choose any version ever published (not as a draft) by the Free
- Software Foundation. If the Document specifies that a proxy can
- decide which future versions of this License can be used, that
- proxy’s public statement of acceptance of a version permanently
- authorizes you to choose that version for the Document.
-
- 11. RELICENSING
-
- “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any
- World Wide Web server that publishes copyrightable works and also
- provides prominent facilities for anybody to edit those works. A
- public wiki that anybody can edit is an example of such a server.
- A “Massive Multiauthor Collaboration” (or “MMC”) contained in the
- site means any set of copyrightable works thus published on the MMC
- site.
-
- “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0
- license published by Creative Commons Corporation, a not-for-profit
- corporation with a principal place of business in San Francisco,
- California, as well as future copyleft versions of that license
- published by that same organization.
-
- “Incorporate” means to publish or republish a Document, in whole or
- in part, as part of another Document.
-
- An MMC is “eligible for relicensing” if it is licensed under this
- License, and if all works that were first published under this
- License somewhere other than this MMC, and subsequently
- incorporated in whole or in part into the MMC, (1) had no cover
- texts or invariant sections, and (2) were thus incorporated prior
- to November 1, 2008.
-
- The operator of an MMC Site may republish an MMC contained in the
- site under CC-BY-SA on the same site at any time before August 1,
- 2009, provided the MMC is eligible for relicensing.
-
-ADDENDUM: How to use this License for your documents
-====================================================
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and license
-notices just after the title page:
-
- Copyright (C) YEAR YOUR NAME.
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.3
- or any later version published by the Free Software Foundation;
- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
- Texts. A copy of the license is included in the section entitled ``GNU
- Free Documentation License''.
-
-If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
-replace the “with...Texts.” line with this:
-
- with the Invariant Sections being LIST THEIR TITLES, with
- the Front-Cover Texts being LIST, and with the Back-Cover Texts
- being LIST.
-
-If you have Invariant Sections without Cover Texts, or some other
-combination of the three, merge those two alternatives to suit the
-situation.
-
-If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of free
-software license, such as the GNU General Public License, to permit
-their use in free software.
-
-
-
-Tag Table:
-Node: Top846
-Ref: whatis1507
-Node: Example Use Cases & Main Features3574
-Node: Installation5895
-Node: Getting Started7031
-Node: Usage10018
-Node: Org-transclusion mode activate and deactivate10488
-Node: Org links supported12523
-Node: Control levels of headlines per transclusion14265
-Node: Filter Org elements per transclusion16057
-Node: Notes on excluding the headline element19724
-Node: Live-sync edit20694
-Node: Transclude source file into src-block23064
-Node: Transclude range of lines for text and source files24149
-Node: lines property to specify a range of lines24701
-Node: end property to specify a search term to dynamically look for the end of
a range26622
-Node: Extensions28190
-Node: Customizing30048
-Node: Customizable filter to exclude certain Org elements31875
-Node: Include the section before the first headline (Org file only)32900
-Node: Faces & fringe bitmap33575
-Node: Face for the #+transclude keyword33916
-Node: Faces for the fringes next to transcluded region and source region34410
-Node: Keybindings35983
-Node: Known Limitations36989
-Node: Credits39623
-Node: Original idea by John Kitchin39807
-Node: Text-Clone42368
-Node: Contributing42945
-Node: Index - Features43752
-Node: Index - Commands46383
-Node: Index - User Options48202
-Node: GNU Free Documentation License50544
-
-End Tag Table
-
-
-Local Variables:
-coding: utf-8
-End:
![https://elpa.gnu.org/packages/org-transclusion.svg"/](https://elpa.gnu.org/packages/org-transclusion.svg"/){kind=link}
![https://elpa.gnu.org/devel/org-transclusion.svg"/](https://elpa.gnu.org/devel/org-transclusion.svg"/){kind=link}
![https://img.shields.io/badge/License-GPLv3-blue.svg"](https://img.shields.io/badge/License-GPLv3-blue.svg"){kind=link}