This manual is for Org-transclusion version 1.3.x.
Last updated: 05 April 2024.
Org-transclusion lets you insert a copy of text content via a file link or ID link within an Org file. It lets you have the same content present in different buffers at the same time without copy-and-pasting it. Edit the source of the content, and you can refresh the transcluded copies to the up-to-date state. Org-transclusion keeps your files clear of the transcluded copies, leaving only the links to the original content.
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.”
Next: Installation, Previous: Org-transclusion User Manual, Up: Org-transclusion User Manual [Index]
Here are some real use cases that users have shared with the author, including his own.
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.
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.
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.
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:
http:// (with org-transclusion-http) and hyper:// (with hyperdrive-org-transclusion). Splitting org-transclusion-add into two parts enables functions in org-transclusion-add-functions to be asynchronous.
Next: Getting Started, Previous: Example Use Cases & Main Features, Up: Org-transclusion User Manual [Index]
This package is available on:
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 package-archives like this:
(add-to-list 'package-archives
'("gnu-devel" . "https://elpa.gnu.org/devel/") :append)
Refresh the archive with M-x package-refresh-contents RET and you can do M-x package-install RET org-transclusion to install it. Alternatively, you can use package-list-packages.
After installation, you can start using Org-transclusion with no additional configuration. Below are some example keybindings that can be put into your Emacs configuration.
(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))
Next: Usage, Previous: Installation, Up: Org-transclusion User Manual [Index]
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 paragraphs will be visually marked with a vertical line “| ” in the fringe (on graphical display) or in the beginning of line (on a text-only terminal) by default. The source (original) of the transcluded paragraphs will be also visually marked with an overlay. The appearance of these visual elements can be customized (refer to section 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.
key binding
--- -------
C-c Prefix Command
TAB org-cycle
D org-transclusion-demote-subtree
O org-transclusion-move-to-source
P org-transclusion-promote-subtree
d org-transclusion-remove
C-d org-transclusion-detach
e org-transclusion-live-sync-start
g org-transclusion-refresh
o org-transclusion-open-source
† Also inherits ‘org-mode-map’ as of development version 1.1.1.0.20220106.203639
and planned to be part of 1.2.0
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.
Next: Customizing, Previous: Getting Started, Up: Org-transclusion User Manual [Index]
hyper://, http://, etc.Next: Org links supported, Up: Usage [Index]
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 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.
#+transclude: [[file:path/to/file.org]] :disable-auto
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 Index - Features for a list).
Next: Transclude over a network with hyper://, http://, etc., Previous: Org-transclusion mode, activate, and deactivate, Up: Usage [Index]
Transclusion has been tested to work for the following types of links:
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 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 Filtering Org elements per transclusion.
Next: Control levels of headlines per transclusion, Previous: Org links supported, Up: Usage [Index]
hyper://, http://, etc.Version 1.4 includes changes which make it possible for asynchronously
transclude content, e.g., over a network. To transclude content via
‘http://’, first install the org-transclusion-http extension (see
extensions), then run M-x org-transclusion-add on the following link
to transclude the HTML element with the “#emacs” id:
#+transclude: [[https://ushin.org/software.html#emacs]]
To transclude content via ‘hyper://’, first install the
hyperdrive-org-transclusion extension (see extensions), then run M-x
org-transclusion-add on the following link to transclude the Org
heading with the property CUSTOM_ID: emacs inside the /software.org
file inside the USHIN hyperdrive:
#+transclude: [[hyper://aaj45d88g4eenu76rpmwzjiabsof1w8u6fufq6oogyhjk1ubygxy/software.org#%3A%3A%23emacs]]
Next: Filter Org elements per transclusion, Previous: Transclude over a network with hyper://, http://, etc., Up: Usage [Index]
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 be 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-linkMake 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-subtreePromote transcluded subtree at point. Mapped to “P” (capital “p”) by default in org-transclusion-map
org-transclusion-demote-subtreeDemote transcluded subtree at point. Mapped to “D” (capital “d”) by default in org-transclusion-map
Next: Detach transclusion and copy source buffer, Previous: Control levels of headlines per transclusion, Up: Usage [Index]
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.
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 sub-section on this user option.
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 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.
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
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.
This property lets you expand the file names in links to absolute file names.
You can use the property in the following way.
#+transclude: [[file:path/to/file.org]] :expand-links
As an exanmple if you have the content of this source file like this:
This is a sample file link to [[file:test2.org]].
For this source file, you will get the following transclusion with the link expanded 1
This is a sample file link to [[file:/home/user/org/test2.org]].
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
Next: Live-sync edit, Previous: Filter Org elements per transclusion, Up: Usage [Index]
Detach is added to the current development version and is planned to be part of release version 1.4.0, and thus available only in GNU-devel ELPA. If you are using GNU ELPA, it will be available with the release of 1.4.0.
org-transclusion-detach can be used on the transclusion
at point. It turns it into a normal, edtitable text content.
You can undo this operation.
In addition, you can press C-d directly on the transclusion at point
to detach it. This is because the command is bound to C-d by
default in ’org-transclusion-map’.
org-transclusion-refresh now accepts universal argument such as
C-u M-x org-transclusion-refresh and detaches the transclusion at
point.
You can undo this operation.
org-transclusion-add now accepts universal argument such as ’C-u M-x
org-transclusion-add’ and copies the source content rather than
transclude it.
You can undo this operation.
Next: Transclude source file into src-block, Previous: Detach transclusion and copy source buffer, Up: Usage [Index]
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’
Next: Transclude range of lines for text and source files, Previous: Live-sync edit, Up: Usage [Index]
This feature is provided as an 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:
#+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
With since 2023-03-28 update, you can also use live-sync the source code transcluded into src-block. It is planned to be added to the next stable release.
Next: Extensions, Previous: Transclude source file into src-block, Up: Usage [Index]
This feature is provided as an 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.
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 [Index]
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 ‘:lines’ with ‘:src’ to transclude only a certain range of source files (Example 1 below).
For Org’s file links, you can use 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).
#+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.
Next: ‘:thing-at-point’ or ‘:thingatpt’ property to specify a “thing” to transclude from the source., Previous: ‘:lines’ property to specify a range of lines, Up: Transclude range of lines for text and source files [Index]
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 string ‘id-1234 end here’ defines the end of the range. The search looks for ‘id-123 end here’ in the body text. When found, the line one before the search string is used as the ending line (thus, the transcluded range will not contain string ‘id-1234 end here’).
You can also combine ‘:lines’ with ‘:end’. It will only displace the beginning, and the end part of the range (the second number after the hyphen “-”) is ignored. In the same example, the beginning of the range is the next line after “id-1234” (line 2). Instead of transcluding all the text until the end of the buffer, the end is defined by the ‘:end’ property (one line before the string ‘id-1234 end here’ is found).
Example 3:
#+transclude: [[file:../../test/python-1.py::id-1234]] :lines 2- :src python :end "id-1234 end here"
Next: Transclude HTML content with Pandoc, Previous: ‘: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 [Index]
You can add ‘:thing-at-point’ or ‘:thingatpt’ (they are synonyms with each other and both work) property to transclude a certain “thing” at point to be transcluded. The following text elements have been tested to work:
Note: As it stands now, you cannot use ‘:thing-at-point’ or ‘:thingatpt’ to specify the precise beginning of the thing within a line – it is always the beginning of the line.
Note: The definition of sentence is controlled by various variables in Emacs. It is suggested to consult the documentation of function
sentence-end. For those who do not use double-space after a period (in the language this is relevant), it is probably more intuitive to turn off customizingsentence-end-double-space. The default behavior is this: “Non-nil means a single space does not end a sentence.”
See Example 4. When you have a text file for prose, you can use paragraph or sentence as a “thing” to transclude. In this example, the beginning of the source of transclude is specified by the search option with “::Once upon a time”. The two colons “::” immediately following the file name denote the search option, which is a built-in Org syntax. Then the paragraph or sentence beginning “Once upon a time” is transcluded. When the source file contains multiple occurrences of “Once upon a time”, the first one is taken.
Example 4:
#+transclude: [[./things-at-point-dir/story.txt::Once upon a time][story]] :thing-at-point paragraph #+transclude: [[./things-at-point-dir/story.txt::Once upon a time][story]] :thingatpt sentence
You can combine ‘:thing-at=point’ (or ‘:thingatpt’) with ‘:src’ property so that the transcluded text is wrapped in Org’s source block. Example 5 shows a way to do so. id:1234567890 is assumed to be present as comment in the source file.
Example 5:
#+transclude: [[./things-at-point-dir/baz.el::id:1234567890][barz-baz-fuzz]] :src elisp #+transclude: [[./things-at-point-dir/baz.el::foo][barz-baz-fuzz]] :src elisp :thing-at-point sexp #+transclude: [[./things-at-point-dir/baz.el::id:1234567890][barz-baz-fuzz]] :src elisp :thingatpt defun
Previous: ‘:thing-at-point’ or ‘:thingatpt’ property to specify a “thing” to transclude from the source., Up: Transclude range of lines for text and source files [Index]
If you have Pandoc installed, you can transclude local HTML files as Org documents.
This feature is provided as an extension (default off).
#+transclude: [[file:../test/source-html-no-ext]]
Since it’s not currently possible to add anchor links to local ‘file:’ Org links, HTML transclusions always render the entire document as Org. However, packages which transclude HTML documents over a network protocol that supports link fragments, such as hyperdrive-org-transclusion and org-transclusion-http, are able to render specific HTML elements by tag (see subsection).
Previous: Transclude range of lines for text and source files, Up: Usage [Index]
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/") (with-eval-after-load 'org-transclusion (add-to-list 'org-transclusion-extensions 'org-transclusion-indent-mode) (require 'org-transclusion-indent-mode))
Currently, the following extensions are available.
org-transclusion-indent-modeSupport org-indent-mode. Known limitation: when transcluded, the source will temporarily lose the indentation. When the transclusion is removed, the source will regain the indentation.
org-transclusion-src-linesAdd features for ‘:src’ and ‘:lines’ properties to ‘#+transclude’. It is meant for non-Org files such as program source and text files
org-transclusion-font-lockAdd 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.
org-transclusion-htmlTransclude local HTML files by converting them to Org with Pandoc.
org-transclusion-httpAsynchronously transclude remote HTML files (and other file types) over HTTP. To use this feature, first install org-transclusion-http and then add the following snippet to your configuration:
(with-eval-after-load 'org-transclusion (add-to-list 'org-transclusion-extensions 'org-transclusion-http) (require 'org-transclusion-http))
hyperdrive-org-transclusionAsynchronously transclude remote hyperdrive files over HTTP. To use this feature, first install hyperdrive-org-transclusion and then add the following snippet to your configuration:
(with-eval-after-load 'org-transclusion (add-to-list 'org-transclusion-extensions 'hyperdrive-org-transclusion) (require 'hyperdrive-org-transclusion))
Next: Known Limitations, Previous: Usage, Up: Org-transclusion User Manual [Index]
You can customize settings in the customization group ‘org-transclusion’.
org-transclusion-extensionsDefines 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 sub-section
org-transclusion-add-all-on-activateDefines 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-elementsSee sub-section
org-transclusion-include-first-sectionSee sub-section
org-transclusion-open-source-display-action-listYou 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-lighterDefine the lighter for Org-transclusion minor mode. The default is “ OT”.
org-transclusion-after-add-functionsFunctions to be called after a transclusion content has been added. The hook runs after the content and the read-only text property have been added so it is not supposed to manipulate the content but to add further text properties. For example, it is used by the ‘org-transclusion-indent-mode’ extension to support ‘org-indent-mode’. The functions are called with arguments beg and end, pointing to the beginning and end of the transcluded content.
The hook can be also used to activate org-latex-preview for transclusions:
(add-hook 'org-transclusion-after-add-functions
#'(lambda (_beg _end) (org-latex-preview '(16))))
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.
Next: Faces & fringe bitmap, Previous: Customizable filter to exclude certain Org elements, Up: Customizing [Index]
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.
Next: Keybindings, Previous: Include the section before the first headline (Org file only), Up: Customizing [Index]
Next: Faces for the fringes next to transcluded region and source region, Up: Faces & fringe bitmap [Index]
This feature is provided as an extension (default on).
org-transclusion-keywordYou can set your own face to the ‘#+transclude’ keyword with using the org-transclusion-keyword face.
Previous: Face for the ‘#+transclude’ keyword, Up: Faces & fringe bitmap [Index]
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:
The default for faces org-transclusion and org-transclusion-source is no color or any other specification (transparent). An intended use of these faces is when you use packages such as org-indent-mode or org-modern, which might override the fringe org-transclusion places. To make the translusion and its source visible, you might like to put some background color to source and transclusion.
org-transclusion-sourceThe default is no color specification (transparent).
org-transclusion-source-edit
org-transclusionThe default is no color specification (transparent).
org-transclusion-edit
org-transclusion-fringe-bitmapIt is used for the fringe that indicates the transcluded region. It works only in on a graphical display (not on a text-only terminal).
Previous: Faces & fringe bitmap, Up: Customizing [Index]
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
C-d org-transclusion-detach
e org-transclusion-live-sync-start
g org-transclusion-refresh
o org-transclusion-open-source
† Also inherits ‘org-mode-map’ as of development version 1.1.1.0.20220106.203639
and planned to be part of 1.2.0
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’
Next: Credits, Previous: Customizing, Up: Org-transclusion User Manual [Index]
Note this section is still incomplete, not exhaustive for “known” limitations.
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 this section.
(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.
Next: Contributing, Previous: Known Limitations, Up: Org-transclusion User Manual [Index]
Next: Text-Clone, Up: Credits [Index]
https://github.com/alphapapa/transclusion-in-emacs#org-mode
{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 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.
Previous: Original idea by John Kitchin, Up: Credits [Index]
‘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.
Next: Index - Features, Previous: Credits, Up: Org-transclusion User Manual [Index]
Org-transclusion is part of GNU ELPA and thus copyrighted by the Free Software Foundation (FSF). This means that anyone who is making a substantive code contribution will need to “assign the copyright for your contributions to the FSF so that they can be included in GNU Emacs” (Org Mode website).
Thank you.
Next: Index - Commands, Previous: Contributing, Up: Org-transclusion User Manual [Index]
| Jump to: | A D E F H L O P T |
|---|
| Jump to: | A D E F H L O P T |
|---|
Next: Index - User Options, Previous: Index - Features, Up: Org-transclusion User Manual [Index]
| Jump to: | O |
|---|
| Jump to: | O |
|---|
Next: GNU Free Documentation License, Previous: Index - Commands, Up: Org-transclusion User Manual [Index]
| Jump to: | O |
|---|
| Jump to: | O |
|---|
Previous: Index - User Options, Up: Org-transclusion User Manual [Index]
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. https://fsf.org/ Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.
The “publisher” means any person or entity that distributes copies of the Document to the public.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
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.
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.
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:
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.
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.”
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.
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.
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.
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.
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.
“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.
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.
“Expanding” in Emacs means converting a relative file name to an absolute one. Info node ‘(elisp) File-Name-Expansion’