[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/org-transclusion ec2bbb0 1/3: docs: Makefile to automat
|
From: |
ELPA Syncer |
|
Subject: |
[elpa] externals/org-transclusion ec2bbb0 1/3: docs: Makefile to automate generation of manual docs |
|
Date: |
Fri, 24 Dec 2021 05:57:33 -0500 (EST) |
branch: externals/org-transclusion
commit ec2bbb02f28c0d915c983456756c942212ca2625
Author: Noboru Ota <me@nobiot.com>
Commit: Noboru Ota <me@nobiot.com>
docs: Makefile to automate generation of manual docs
---
dir | 19 +
docs/Makefile | 28 +
docs/index.html | 43 +-
docs/manual-gen.el | 10 +
org-transclusion.org => docs/org-transclusion.org | 86 +-
org-transclusion.info | 106 +--
org-transclusion.texi | 916 ----------------------
7 files changed, 151 insertions(+), 1057 deletions(-)
diff --git a/dir b/dir
new file mode 100644
index 0000000..a3a6852
--- /dev/null
+++ b/dir
@@ -0,0 +1,19 @@
+This is the file .../info/dir, which contains the
+topmost node of the Info hierarchy, called (dir)Top.
+The first time you invoke Info you start off looking at this node.
+
+File: dir, Node: Top This is the top of the INFO tree
+
+ This (the Directory node) gives a menu of major topics.
+ Typing "q" exits, "H" lists all Info commands, "d" returns here,
+ "h" gives a primer for first-timers,
+ "mEmacs<Return>" visits the Emacs manual, etc.
+
+ In Emacs, you can click mouse button 2 on a menu item or cross reference
+ to select it.
+
+* Menu:
+
+Emacs
+* Org-transclusion: (org-transclusion).
+ Transclusion in Org mode.
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..6e0a368
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,28 @@
+.POSIX:
+EMACS = emacs
+MAKEINFO = makeinfo
+INSTALLINFO = install-info
+MV = mv
+RM = rm
+MANUAL_HTML_ARGS =--html --no-split --footnote-style=separate
--css-ref=resources/manual.css
+
+## Build #############################################################
+
+all: manual html install clear
+
+manual:
+ @printf "\n\n### Generating manual .texi and .info files \n\n"
+ $(EMACS) -Q --batch -L ../ --file org-transclusion.org -l manual-gen.el
+
+html:
+ @printf "\n\n### Generating manual .html files \n\n"
+ $(MAKEINFO) $(MANUAL_HTML_ARGS) org-transclusion.texi -o index.html
+
+install:
+ @printf "\n\n### Installing manual files \n\n"
+ $(INSTALLINFO) org-transclusion.info ../dir
+ $(MV) org-transclusion.info ../
+
+clear:
+ @printf "\n\n### Clear .texi file \n\n"
+ $(RM) org-transclusion.texi*
diff --git a/docs/index.html b/docs/index.html
index 87fdd4e..69e4a06 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -88,7 +88,7 @@ modify this GNU manual.”
</td></tr>
<tr><td align="left" valign="top">• <a href="#Getting-Started"
accesskey="3">Getting Started</a></td><td> </td><td align="left"
valign="top">
</td></tr>
-<tr><td align="left" valign="top">• <a href="#Usage"
accesskey="4">Usage</a></td><td> </td><td align="left" valign="top">
+<tr><td align="left" valign="top">• <a href="#Usage"
accesskey="4">Usage</a></td><td> </td><td align="left"
valign="top">Features in detail
</td></tr>
<tr><td align="left" valign="top">• <a href="#Customizing"
accesskey="5">Customizing</a></td><td> </td><td align="left"
valign="top">
</td></tr>
@@ -296,15 +296,15 @@ Next: <a href="#Usage" accesskey="n"
rel="next">Usage</a>, Previous: <a href="#I
<pre class="example">#+transclude: [[id:20210501T171427.051019][Bertrand
Russell]]
</pre></div>
-<p>Put your cursor somewhere on this keyword line and type ‘<samp>M-x
org-transclusion-add RET</samp>’, and you will see the text content that
the ID points replace the whole line. If you have multiple links with a
transclude keyword, you can type ‘<samp>M-x org-transclusion-add-all
RET</samp>’ to do all transclusions in the current buffer.
+<p>Put your cursor somewhere on this keyword line and type ‘<samp>M-x
org-transclusion-add RET</samp>’, and you will see the text content that
the ID points to replace the whole line. If you have multiple links with a
transclude keyword, you can type ‘<samp>M-x org-transclusion-add-all
RET</samp>’ to add all transclusions in the current buffer.
</p>
-<p>Alternatively, you can also put cursor somewhere on the link and call
‘<samp>M-x org-transclusion-make-from-link</samp>’. That will
insert another line with ‘<samp>#+transclusion:</samp>’ keyword
appended in front of a copy of the original link in the next empty line.
+<p>Alternatively, you can also put cursor somewhere on the link and type
‘<samp>M-x org-transclusion-make-from-link RET</samp>’. That will
insert another line with ‘<samp>#+transclusion:</samp>’ keyword
added in front of a copy of the original link in the next empty line.
</p>
<p>The transcluded text is <strong>read-only</strong> but you can copy it and
export it as normal text. Org-transclusion remembers where it has transcluded
the text from (its source buffer). You can call a number of useful commands
with a single letter (by default).
</p>
<p>For example, you can press ‘<samp>o</samp>’ to open the source
buffer of the transclusion at point, or ‘<samp>O</samp>’ (capital
"o") to open and move to it. Press ‘<samp>g</samp>’ to
refresh the transclusion. Press ‘<samp>e</samp>’ to start live-sync
edit. For more detail, inspect the documentation of each command. Press
‘<samp>d</samp>’ to remove the transcluded content, putting the
original ‘<samp>#+transcl [...]
</p>
-<p>This single-letter-context-menu is defined in
‘<samp>org-transclusion-map</samp>’. The default keybindings are
shown below. Adapt them to your liking, especially if you use vim keybindings
with Evil Mode, etc.
+<p>This single-letter-context-menu is defined in
‘<samp>org-transclusion-map</samp>’. The default keybindings are
shown below. Adapt them to your liking, especially if you use Vim keybindings
with Evil Mode, etc.
</p>
<div class="example">
<pre class="example">key binding
@@ -407,8 +407,12 @@ Next: <a
href="#Control-levels-of-headlines-per-transclusion" accesskey="n" rel=
</li><li> File link for non-org files (tested with
‘<samp>.txt</samp>’ and ‘<samp>.md</samp>’); for these,
the whole buffer gets transcluded
</li></ul>
-<p>Note search-options ‘<samp>::/regex/</samp>’ and
‘<samp>::number</samp>’ do not work as intended.
+<blockquote>
+<p><b>Note:</b> Search-options ‘<samp>::/regex/</samp>’ and
‘<samp>::number</samp>’ do not work as intended.
</p>
+</blockquote>
+
+
<p>For transcluding a specific paragraph, there are two main ways: Org
Mode’s <a
href="https://orgmode.org/manual/Internal-Links.html#Internal-Links";>dedicated-target</a>
and ‘<samp>:only-contents</samp>’ property.
</p>
<p>For dedicated targets, the target paragraph must be identifiable by a
dedicated target with a ‘<samp><<paragraph-id>></samp>’:
@@ -921,38 +925,9 @@ Previous: <a href="#Faces-_0026-fringe-bitmap"
accesskey="p" rel="prev">Faces &a
<ul>
<li> ‘<samp>org-transclusion-map</samp>’
</li></ul>
-<div class="example">
-<pre class="example">key binding
---- -------
-
-C-c Prefix Command
-TAB org-cycle
-D org-transclusion-demote-subtree
-O org-transclusion-move-to-source
-P org-transclusion-promote-subtree
-d org-transclusion-remove
-e org-transclusion-live-sync-start
-g org-transclusion-refresh
-o org-transclusion-open-source
-
-C-c C-c org-ctrl-c-ctrl-c
-</pre></div>
-
-
<ul>
<li> ‘<samp>org-transclusion-live-sync-map</samp>’
</li></ul>
-<div class="example">
-<pre class="example">key binding
---- -------
-
-C-c Prefix Command
-C-y org-transclusion-live-sync-paste
-
-C-c C-c org-transclusion-live-sync-exit
-
-*Also inherits ‘org-mode-map’
-</pre></div>
<hr>
<span id="Known-Limitations"></span><div class="header">
diff --git a/docs/manual-gen.el b/docs/manual-gen.el
new file mode 100644
index 0000000..47bdf29
--- /dev/null
+++ b/docs/manual-gen.el
@@ -0,0 +1,10 @@
+;; -*- lexical-binding: t; -*-
+
+(require 'org-transclusion)
+
+(ignore-error
+ (org-transclusion-add-all))
+
+(let ((inhibit-read-only t))
+ (org-texinfo-export-to-info))
+
diff --git a/org-transclusion.org b/docs/org-transclusion.org
similarity index 93%
rename from org-transclusion.org
rename to docs/org-transclusion.org
index 7d6eff9..2e2e3e2 100644
--- a/org-transclusion.org
+++ b/docs/org-transclusion.org
@@ -1,6 +1,6 @@
#+title: Org-transclusion User Manual
#+author: Noboru Ota <me@nobiot.com>
-#+modified: 2021-12-23T184320
+#+modified: 2021-12-24T101247
#+language: en
#+export_file_name: org-transclusion.texi
#+texinfo_dir_category: Emacs
@@ -18,9 +18,9 @@
#+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 {{{version}}}.
+This manual is for Org-transclusion version 1.0.x.
-{{{updated}}}.
+last updated 23 December 2021.
Org-transclusion lets you insert a copy of text content via a file link or ID
link within an Org file. It lets you have the same content present in different
buffers at the same time without copy-and-pasting it. Edit the source of the
content, and you can refresh the transcluded copies to the up-to-date state.
Org-transclusion keeps your files clear of the transcluded copies, leaving only
the links to the original content.
@@ -92,32 +92,33 @@ Org-transclusion (refer to the [[#getting-started][Getting
Started]] section).
Below are some example keybindings that can be put into your Emacs
configuration.
#+BEGIN_SRC elisp
- (define-key global-map (kbd "<f12>") #'org-transclusion-add)
- (define-key global-map (kbd "C-n t") #'org-transclusion-mode)
+(define-key global-map (kbd "<f12>") #'org-transclusion-add)
+(define-key global-map (kbd "C-n t") #'org-transclusion-mode)
#+END_SRC
For Doom users, you would need to do something like this below to install the
package and configure the keybindings.
-#+begin_src elisp
- ;; ~/.doom.d/package.el
- (package! org-transclusion)
+#+BEGIN_SRC elisp
+;; ~/.doom.d/package.el
+(package! org-transclusion)
-#+end_src
+#+END_SRC
-#+begin_src elisp
- ;; ~/.doom.d/config.el
- (use-package! org-transclusion
- :after org
- :init
- (map!
- :map global-map "<f12>" #'org-transclusion-add
- :leader
- :prefix "n"
- :desc "Org Transclusion Mode" "t" #'org-transclusion-mode))
-#+end_src
+#+BEGIN_SRC elisp
+;; ~/.doom.d/config.el
+(use-package! org-transclusion
+ :after org
+ :init
+ (map!
+ :map global-map "<f12>" #'org-transclusion-add
+ :leader
+ :prefix "n"
+ :desc "Org Transclusion Mode" "t" #'org-transclusion-mode))
+#+END_SRC
* Getting Started
:PROPERTIES:
+:DESCRIPT: To get running in 5 minutes
:CUSTOM_ID: getting-started
:END:
@@ -151,19 +152,15 @@ Simply type to add =#+transclude:= in front of the link
like the example below.
#+transclude: [[id:20210501T171427.051019][Bertrand Russell]]
#+end_example
-Put your cursor somewhere on this keyword line and type =M-x
org-transclusion-add RET=, and you will see the text content that the ID points
replace the whole line. If you have multiple links with a transclude keyword,
you can type =M-x org-transclusion-add-all RET= to do all transclusions in the
current buffer.
+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 call =M-x
org-transclusion-make-from-link=. That will insert another line with
=#+transclusion:= keyword appended in front of a copy of the original link in
the next empty line.
+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.
-
-#+begin_src elisp :exports none
-(substitute-command-keys "\\{org-transclusion-map}")
-#+end_src
+This single-letter-context-menu is defined in =org-transclusion-map=. The
default keybindings are shown below. Adapt them to your liking, especially if
you use Vim keybindings with Evil Mode, etc.
#+name: org-transclusion-map
#+caption: Default org-transclusion-map
@@ -189,6 +186,7 @@ This should get you started with Org-transclusion. There
are more options and cu
* Usage
:PROPERTIES:
+:DESCRIPTION: Features in detail
:CUSTOM_ID: usage
:END:
** Org-transclusion mode, activate, and deactivate
@@ -237,7 +235,11 @@ Transclusion has been tested to work for the following
types of links:
- 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.
+#+ATTR_TEXINFO: :tag Note
+#+begin_quote
+Search-options =::/regex/= and =::number= do not work as intended.
+#+end_quote
+
For transcluding a specific paragraph, there are two main ways: Org Mode's
[[https://orgmode.org/manual/Internal-Links.html#Internal-Links][dedicated-target]]
and =:only-contents= property.
@@ -498,13 +500,13 @@ If you use =customize=, the features are loaded
automatically. Note that it does
If you do not use =customize= (e.g. Doom), you may need to explicitly require
an extension. For example, to activate =org-transclusion-indent-mode=, you
might need to add something like this in your configuration file.
- #+begin_src emacs-lisp
- ;; Ensure that load-path to org-transclusion is already added
- ;; If you installed it with the built-in package.el, this should be already
done.
- ;; (add-to-list 'load-path "path/to/org-transclusion/")
- (add-to-list 'org-transclusion-extensions 'org-transclusion-indent-mode)
- (require 'org-transclusion-indent-mode)
- #+end_src
+ #+BEGIN_SRC emacs-lisp
+ ;; Ensure that load-path to org-transclusion is already added
+ ;; If you installed it with the built-in package.el, this should be already
done.
+ ;; (add-to-list 'load-path "path/to/org-transclusion/")
+ (add-to-list 'org-transclusion-extensions 'org-transclusion-indent-mode)
+ (require 'org-transclusion-indent-mode)
+ #+END_SRC
Currently, the following extensions are available.
@@ -602,12 +604,12 @@ If the fringes that indicate transcluding and source
regions are not visible in
To customize a face, it's probably the easiest to use =M-x customize-face=. If
you want to use Elisp for some reason (e.g. on Doom), something like this below
should set faces. Experiment with the colors of your choice. By default, the
faces above have no values.
-#+begin_src elisp
- (set-face-attribute
- 'org-transclusion-fringe nil
- :foreground "green"
- :background "green")
-#+end_src
+#+BEGIN_SRC elisp
+(set-face-attribute
+ 'org-transclusion-fringe nil
+ :foreground "green"
+ :background "green")
+#+END_SRC
For colors, where "green" is, you can also use something like "#62c86a"
(Emacs calls it "RGB triple"; you can refer to in-system manual Emacs >
Colors). You might also like to refer to a list of currently defined faces in
your Emacs by =list-faces-display=.
@@ -731,7 +733,7 @@ Thank you.
:appendix: t
:END:
-#+texinfo: @include docs/fdl.texi
+#+texinfo: @include fdl.texi
# LocalWords: href img src devel GPLv texinfo insertcopying toc RET findex
# LocalWords: vindex cindex dir
diff --git a/org-transclusion.info b/org-transclusion.info
index 4680c7e..9fcceef 100644
--- a/org-transclusion.info
+++ b/org-transclusion.info
@@ -56,7 +56,7 @@ content.
* Example Use Cases & Main Features::
* Installation::
* Getting Started::
-* Usage::
+* Usage:: Features in detail
* Customizing::
* Known Limitations::
* Credits::
@@ -233,13 +233,13 @@ example below.
Put your cursor somewhere on this keyword line and type ‘M-x
org-transclusion-add RET’, and you will see the text content that the ID
-points replace the whole line. If you have multiple links with a
+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
-do all transclusions in the current buffer.
+add all transclusions in the current buffer.
- Alternatively, you can also put cursor somewhere on the link and call
-‘M-x org-transclusion-make-from-link’. That will insert another line
-with ‘#+transclusion:’ keyword appended in front of a copy of the
+ 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
@@ -256,7 +256,7 @@ Press ‘d’ to remove the transcluded content, putting the
original
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.
+especially if you use Vim keybindings with Evil Mode, etc.
key binding
--- -------
@@ -360,8 +360,8 @@ Transclusion has been tested to work for the following
types of links:
• 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.
+ 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
@@ -885,31 +885,7 @@ File: org-transclusion.info, Node: Keybindings, Prev:
Faces & fringe bitmap,
===============
• ‘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
@@ -1675,38 +1651,38 @@ their use in free software.
Tag Table:
Node: Top846
-Node: Example Use Cases & Main Features3652
-Node: Installation5975
-Node: Getting Started7081
-Node: Usage10090
-Node: Org-transclusion mode activate and deactivate10560
-Node: Org links supported12613
-Node: Control levels of headlines per transclusion14359
-Node: Filter Org elements per transclusion16163
-Node: Notes on excluding the headline element19839
-Node: Live-sync edit20811
-Node: Transclude source file into src-block23196
-Node: Transclude range of lines for text and source files24293
-Node: lines property to specify a range of lines24848
-Node: end property to specify a search term to dynamically look for the end of
a range26793
-Node: Extensions28370
-Node: Customizing30237
-Node: Customizable filter to exclude certain Org elements32064
-Node: Include the section before the first headline (Org file only)33098
-Node: Faces & fringe bitmap33773
-Node: Face for the #+transclude keyword34114
-Node: Faces for the fringes next to transcluded region and source region34608
-Node: Keybindings36190
-Node: Known Limitations37196
-Node: Credits39830
-Node: Original idea by John Kitchin40014
-Node: Text-Clone42575
-Node: Contributing43152
-Node: Notes on pull requests and Free Software Foundation (FSF) copy right
assignment43677
-Node: Index - Features44363
-Node: Index - Commands46994
-Node: Index - User Options48813
-Node: GNU Free Documentation License51155
+Node: Example Use Cases & Main Features3694
+Node: Installation6017
+Node: Getting Started7123
+Node: Usage10137
+Node: Org-transclusion mode activate and deactivate10607
+Node: Org links supported12660
+Node: Control levels of headlines per transclusion14414
+Node: Filter Org elements per transclusion16218
+Node: Notes on excluding the headline element19894
+Node: Live-sync edit20866
+Node: Transclude source file into src-block23251
+Node: Transclude range of lines for text and source files24348
+Node: lines property to specify a range of lines24903
+Node: end property to specify a search term to dynamically look for the end of
a range26848
+Node: Extensions28425
+Node: Customizing30292
+Node: Customizable filter to exclude certain Org elements32119
+Node: Include the section before the first headline (Org file only)33153
+Node: Faces & fringe bitmap33828
+Node: Face for the #+transclude keyword34169
+Node: Faces for the fringes next to transcluded region and source region34663
+Node: Keybindings36245
+Node: Known Limitations36456
+Node: Credits39090
+Node: Original idea by John Kitchin39274
+Node: Text-Clone41835
+Node: Contributing42412
+Node: Notes on pull requests and Free Software Foundation (FSF) copy right
assignment42937
+Node: Index - Features43623
+Node: Index - Commands46254
+Node: Index - User Options48073
+Node: GNU Free Documentation License50415
End Tag Table
diff --git a/org-transclusion.texi b/org-transclusion.texi
deleted file mode 100644
index b8dfb4a..0000000
--- a/org-transclusion.texi
+++ /dev/null
@@ -1,916 +0,0 @@
-\input texinfo @c -*- texinfo -*-
-@c %**start of header
-@setfilename org-transclusion.info
-@settitle Org-transclusion User Manual
-@documentencoding UTF-8
-@documentlanguage en
-@c %**end of header
-
-@copying
-Copyright (C) 2021 Free Software Foundation, Inc.
-
-@quotation
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.3 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover Texts being “A GNU Manual,” and
-with the Back-Cover Texts as in (a) below. A copy of the license is
-included in the section entitled “GNU Free Documentation License.”
-
-(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
-modify this GNU manual.”
-
-@end quotation
-@end copying
-
-@dircategory Emacs
-@direntry
-* Org-transclusion: (org-transclusion). Transclusion in Org mode.
-@end direntry
-
-@finalout
-@titlepage
-@title Org-transclusion User Manual
-@author Noboru Ota <me@@nobiot.com>
-@page
-@vskip 0pt plus 1filll
-@insertcopying
-@end titlepage
-
-@ifnottex
-@node Top
-@top Org-transclusion User Manual
-
-@noindent
-
-This manual is for Org-transclusion version 1.0.x.
-
-last updated 23 December 2021.
-
-Org-transclusion lets you insert a copy of text content via a file link or ID
link within an Org file. It lets you have the same content present in different
buffers at the same time without copy-and-pasting it. Edit the source of the
content, and you can refresh the transcluded copies to the up-to-date state.
Org-transclusion keeps your files clear of the transcluded copies, leaving only
the links to the original content.
-
-@insertcopying
-@end ifnottex
-
-@menu
-* Example Use Cases & Main Features::
-* Installation::
-* Getting Started::
-* Usage::
-* Customizing::
-* Known Limitations::
-* Credits::
-* Contributing::
-* Index - Features:: Key concepts & features
-* Index - Commands:: Interactive functions
-* Index - User Options:: Customizable variables & faces
-* GNU Free Documentation License::
-
-@detailmenu
---- 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
-
-* @samp{lines} property to specify a range of lines::
-* @samp{end} property to specify a search term to dynamically look for the end
of a range::
-
-Customizing
-
-* Customizable filter to exclude certain Org elements::
-* Include the section before the first headline (Org file only)::
-* Faces & fringe bitmap::
-* Keybindings::
-
-Faces & fringe bitmap
-
-* Face for the @samp{#+transclude} keyword::
-* Faces for the fringes next to transcluded region and source region::
-
-Credits
-
-* Original idea by John Kitchin::
-* Text-Clone::
-
-Contributing
-
-* Notes on pull requests and Free Software Foundation (FSF) copy right
assignment::
-
-@end detailmenu
-@end menu
-
-@node Example Use Cases & Main Features
-@chapter Example Use Cases & Main Features
-
-Here are a summary of some real use cases that users have shared with the
author, including his own.
-
-@table @asis
-@item 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.
-
-@item Academic writing
-You have a collection of quotes and notes from your research and literature
review. Transclude relevant elements of quotes and notes into different papers.
You can keep your collection as the central repository of your research.
-
-@item Technical writing
-You write technical documents for software. Transclude relevant lines of code
into the document. As the code is only transcluded, you can keep the document
up-to-date as the code evolves.
-
-@item Project status reports
-You work on multiple projects at the same time and need to report to different
project managers. Transclude relevant parts of your work notes and logs into
respective project reports. You can keep a single collection of your work notes
and logs.
-@end table
-
-Main Features:
-
-@itemize
-@item
-Insert a copy of text content via a file link or ID link into an Org file
-
-@item
-Work with any text file such as program source cod, plain text, Markdown, or
other Org files
-
-@item
-Keep the file system clear of the copies of text content -- Org-transclusion
tries hard to save only the links to the file system
-
-@item
-For Org files, use different headline levels from the source Org file
-
-@item
-For Org files, use filters to include only relevant elements (e.g. filter out
properties in the transclusions)
-
-@item
-For program source and plain text files, transclude a certain lines or
dynamically specify the from/to lines to keep the transclusion always
up-to-date with the evolving source files
-
-@item
-For program source files, transclude parts or whole code directly into Org's
source block to leverage the rich Org features
-
-@item
-Extend Org-transclusion with its extension framework
-@end itemize
-
-@node Installation
-@chapter Installation
-
-This package is available on
@uref{https://elpa.gnu.org/packages/org-transclusion.html, GNU ELPA}. You can
do @samp{M-x package-install RET
-org-transclusion} to install it. After installation, you can start using
-Org-transclusion (refer to the @ref{Getting Started} section).
-
-Below are some example keybindings that can be put into your Emacs
configuration.
-
-@lisp
-(define-key global-map (kbd "<f12>") #'org-transclusion-add)
-(define-key global-map (kbd "C-n t") #'org-transclusion-mode)
-@end lisp
-
-For Doom users, you would need to do something like this below to install the
package and configure the keybindings.
-
-@lisp
-;; ~/.doom.d/package.el
-(package! org-transclusion)
-
-@end lisp
-
-@lisp
-;; ~/.doom.d/config.el
-(use-package! org-transclusion
- :after org
- :init
- (map!
- :map global-map "<f12>" #'org-transclusion-add
- :leader
- :prefix "n"
- :desc "Org Transclusion Mode" "t" #'org-transclusion-mode))
-@end lisp
-
-@node Getting Started
-@chapter Getting Started
-
-@findex org-transclusion-add
-@findex org-transclusion-add-all
-@findex org-transclusion-make-from-link
-@findex org-transclusion-open-source
-@findex org-transclusion-move-to-source
-@findex org-transclusion-refresh
-@vindex org-transclusion-map
-
-The basic idea of Org-transclusion is simple: insert a copy of text content
via a file link or ID link within an Org file. This is an Org Mode version of
transclusion.
-
-To transclude content via a link, use one of the following commands:
-
-@itemize
-@item
-@samp{org-transclusion-add}
-
-@item
-@samp{org-transclusion-add-all}
-
-@item
-@samp{org-transclusion-make-from-link}
-@end itemize
-
-For example, if you have an ID link in your Org file like this:
-
-@example
-[[id:20210501T171427.051019][Bertrand Russell]]
-@end example
-
-Simply type to add @samp{#+transclude:} in front of the link like the example
below.
-
-@example
-#+transclude: [[id:20210501T171427.051019][Bertrand Russell]]
-@end example
-
-Put your cursor somewhere on this keyword line and type @samp{M-x
org-transclusion-add RET}, and you will see the text content that the ID points
replace the whole line. If you have multiple links with a transclude keyword,
you can type @samp{M-x org-transclusion-add-all RET} to do all transclusions in
the current buffer.
-
-Alternatively, you can also put cursor somewhere on the link and call
@samp{M-x org-transclusion-make-from-link}. That will insert another line with
@samp{#+transclusion:} keyword appended in front of a copy of the original link
in the next empty line.
-
-The transcluded text is @strong{read-only} but you can copy it and export it
as normal text. Org-transclusion remembers where it has transcluded the text
from (its source buffer). You can call a number of useful commands with a
single letter (by default).
-
-For example, you can press @samp{o} to open the source buffer of the
transclusion at point, or @samp{O} (capital "o") to open and move to it. Press
@samp{g} to refresh the transclusion. Press @samp{e} to start live-sync edit.
For more detail, inspect the documentation of each command. Press @samp{d} to
remove the transcluded content, putting the original @samp{#+transclude:
[[id:id-of-the-content]]}.
-
-This single-letter-context-menu is defined in @samp{org-transclusion-map}. The
default keybindings are shown below. Adapt them to your liking, especially if
you use vim keybindings with Evil Mode, etc.
-
-@example
-key binding
---- -------
-
-C-c Prefix Command
-TAB org-cycle
-D org-transclusion-demote-subtree
-O org-transclusion-move-to-source
-P org-transclusion-promote-subtree
-d org-transclusion-remove
-e org-transclusion-live-sync-start
-g org-transclusion-refresh
-o org-transclusion-open-source
-
-C-c C-c org-ctrl-c-ctrl-c
-
-@end example
-
-This should get you started with Org-transclusion. There are more options and
customizing options available for you to fine-tune the text content you
transclude. Explore the rest of the user manual and play with Org-transclusion
to get familiar with it.
-
-@node Usage
-@chapter 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::
-@end menu
-
-@node Org-transclusion mode activate and deactivate
-@section Org-transclusion mode, activate, and deactivate
-
-@cindex Activate / Deactivate
-@findex org-transclusion-mode
-@findex org-transclusion-activate
-@findex org-transclusion-deactivate
-@cindex Transclusion Properties
-@cindex Property - :disable-auto
-@vindex org-transclusion-add-all-on-activate
-
-Org-transclusion is a local minor mode; however, you do not need to explicitly
call @samp{org-transclusion-mode}. The minor mode is intended to be just a
convenient wrapper to let you easily toggle between @samp{activate} and
@samp{deactivate}.
-
-As you saw in the @ref{Getting Started, , Getting Started section} above,
calling @samp{org-transclusion-add} or @samp{org-transclusion-add-all} is
enough to add transclusions in your current buffer.
-
-The minor mode is automatically turned on locally for your current buffer
through one of these commands. All it does is to call
@samp{org-transclusion-activate} to activate hooks and some other variables.
Their main purpose is to keep files in the filesystem clear of the transcluded
content.
-
-Turn off the minor mode or use @samp{org-transclusion-deactivate}; you will
remove all the transclusions in the current buffer and clear the hooks and
other setup variables.
-
-If you prefer, you can use @samp{org-transclusion-mode} as your entry command
for transclusion. When customizable variable
@samp{org-transclusion-add-all-on-activate} is non-nil (it is @samp{t} by
default), turning on the minor mode calls the @samp{org-transclusion-add-all}
command to attempt to add all transclusions automatically in the current buffer.
-
-You can control whether or not transclusions are to be added automatically per
transclude keyword. By default, @samp{org-transclusion-add-all} (it is also
used by @samp{org-transclusion-mode}) will work on every transclude keyword in
the buffer. Add @samp{:disable-auto} property to a keyword as shown in the
example below; @samp{add-all} skips transclude keywords with it.
-
-@example
-#+transclude: [[file:path/to/file.org]] :disable-auto
-@end example
-
-You can override the @samp{:disable-auto} property by manually calling
@samp{org-transclusion-add} at point.
-
-@node Org links supported
-@section Org links supported
-
-@cindex Org Links Supported
-@cindex Property - :only-contents
-
-Transclusion has been tested to work for the following types of links:
-
-@itemize
-@item
-File link for an entire org file/buffer; e.g. @samp{[[file:~/org/file.org][My
Org Notes]]}
-@item
-File link with @samp{::*heading}
-@item
-File link with @samp{::#custom-id}
-@item
-File link with @samp{::name} for blocks (e.g. blocked quotations), tables, and
links
-@item
-File link with @samp{::dedicated-target}; this is intended for linking to a
paragraph. See below.
-@item
-ID link @samp{id:uuid}
-@item
-File link for non-org files (tested with @samp{.txt} and @samp{.md}); for
these, the whole buffer gets transcluded
-@end itemize
-
-Note search-options @samp{::/regex/} and @samp{::number} do not work as
intended.
-
-For transcluding a specific paragraph, there are two main ways: Org Mode's
@uref{https://orgmode.org/manual/Internal-Links.html#Internal-Links,
dedicated-target} and @samp{:only-contents} property.
-
-For dedicated targets, the target paragraph must be identifiable by a
dedicated target with a @samp{<<paragraph-id>>}:
-
-@example
-Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-Suspendisse ac velit fermentum, sodales nunc in,
-tincidunt quam. <<paragraph-id>>
-@end example
-
-It is generally assumed that the @samp{paragraph-id} is placed after its
content, but it is not an absolute requirement; it can be in the beginning
(before the content) or in the middle of it.
-
-For the @samp{:only-contents} property, refer to sub-section @ref{Filter Org
elements per transclusion, , Filtering Org elements per transclusion}.
-
-@node Control levels of headlines per transclusion
-@section Control levels of headlines per transclusion
-
-@cindex Property - :level
-@findex org-transclusion-demote-subtree
-@findex org-transclusion-promote-subtree
-@findex org-transclusion-make-from-link
-
-When you transclude Org contents, you can specify a different headline level
than those of the source Org file.
-
-Use the @samp{:level} property with a value of single digit number from 1 to 9
like this example below.
-
-@example
-#+transclude: [[file:path/to/file.org::*Headline]] :level 2
-@end example
-
-The top level of the transcluded headline will set to the value of
@samp{:level} property -- in this example, level 2 regardless of that in the
source. When the headline contains sub-headlines, they will be all
automatically promoted or demoted to align according to how many levels the top
of the subtree will move.
-
-When you transclude an entire Org file, it may contain multiple subtrees. In
such cases, the top-most level among the subtrees will be set according to the
@samp{:level} property; the rest of headlines in the buffer will align
accordingly.
-
-Other ways to control include the following.
-
-@table @asis
-@item @samp{org-transclusion-make-from-link}
-Make a transclusion keyword from a link at point. If you pass a positive
number 1-9 with @samp{digit-argument} (e.g. prefix @samp{M-x} with @samp{C-2}
to pass "2"), this function automatically puts the @samp{:level} property to
the resultant transclusion keyword.
-
-@item @samp{org-transclusion-promote-subtree}
-Promote transcluded subtree at point. Mapped to "P" (capital "p") by default
in @samp{org-transclusion-map}
-
-@item @samp{org-transclusion-demote-subtree}
-Demote transcluded subtree at point. Mapped to "D" (capital "D") by default in
@samp{org-transclusion-map}
-@end table
-
-@node Filter Org elements per transclusion
-@section Filter Org elements per transclusion
-
-@cindex Filters
-@vindex org-transclusion-exclude-elements
-@vindex org-transclusion-include-first-section
-@cindex Property - :only-content
-
-You can control what elements to include in many different ways with using
various filters. The filters work in two layers: customizable variable and
properties per transclude keyword.
-
-The following two customizable variables are applicable to all transclusions
globally. You can think of them as the global default.
-
-@table @asis
-@item @samp{org-transclusion-exclude-elements}
-This customizable variable globally defines the exclusion filter for elements.
It is a list of symbols; the acceptable values can be seen by inspecting
@samp{org-element-all-elements}. The default is to exclude
@samp{property-drawer}.
-
-Refer also to the @ref{Customizable filter to exclude certain Org elements, ,
sub-section on this user option}.
-
-@item @samp{org-transclusion-include-first-section}
-This customizing variable globally defines whether or not to include the first
section of the source Org file. The first section is the part before the first
headline -- that's the section that typically contains @samp{#+title},
@samp{#+author}, and so on. Many people also write notes in it without adding
any headlines. Note that this user option's default is now @samp{t} (changed
from @samp{nil} as users seem to spend time to "correct" this issue). Turn it
to @samp{t} if you wish to tra [...]
-
-Refer also to the @ref{Include the section before the first headline (Org file
only), , sub-section on this user option}.
-@end table
-
-In addition to the global user options above, you can fine-tune the default
exclusion filter per transclusion. Add following properties to transclusions
you wish to apply additional filters.
-
-@table @asis
-@item @samp{:only-contents}
-This property lets you exclude titles of headlines when you transclude a
subtree (headline); you transclude only the contents. When the subtree contains
sub-headlines, all the contents will be transcluded.
-
-Add @samp{:only-contents} without any value like this example:
-@end table
-
-@example
-#+transclude: [[file:path/to/file.org]] :only-contents
-@end example
-
-@table @asis
-@item @samp{:exclude-elements}
-This property lets you @strong{add} elements to exclude per transclusion on
top of the variable @samp{org-transclusion-exclude-elements} defines. You
cannot @strong{remove} the ones defined by it; thus, it is intended that you
use the customizable variable as your global default and fine-tune it by the
property per transclusion.
-
-Add @samp{:exclude-elements} with a list of elements (each one as defined by
@samp{org-element-all-elements}) separated by a space inside double quotation
marks like this example:
-@end table
-
-@example
-#+transclude: [[file:path/to/file.org]] :exclude-elements "drawer keyword"
-@end example
-
-You can combine @samp{:only-contents} and @samp{:exclude-elements} to control
how you transclude a subtree. With these properties, you can really have great
control over what to include and exclude. It might be a little overwhelming at
a time but the changes via properties are easy to change -- simply press
@samp{d} to remove the transclusion, change the properties, and transclude
again to see a new result.
-
-@menu
-* Notes on excluding the headline element::
-@end menu
-
-@node Notes on excluding the headline element
-@subsection Notes on excluding the headline element
-
-If you add @samp{headline} as a list of elements to exclude, you exclude
sub-headlines within your subtrees 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.
-
-@example
-** Headline 1
- Content of Headline 1
-** Headline 2
- Content of Headline 2
-* Headline 3
- Content of Headline
-@end example
-
-@node Live-sync edit
-@section Live-sync edit
-
-@cindex Live-sync edit
-@findex org-transclusion-live-sync-start
-@findex org-transclusion-live-sync-exit
-@findex org-transclusion-live-sync-paste
-@vindex org-transclusion-live-sync-map
-
-@strong{Experimental.} You can start live-sync edit by pressing @samp{e} (by
default) on a text element you want to edit. This will call
@samp{org-transclusion-live-sync-start} and put a colored overlay on top of the
region being live-synced and brings up another buffer that visits the source
file of the transclusion. The source buffer will also have a corresponding
overlay to the region being edited and live-synced.
-
-If you have other windows open, they will be temporarily hidden --
Org-transclusion will remembers your current window layout and attempts to
recover it when you exit live-sync edit.
-
-In the live-sync edit region, you can freely type to edit the transclusion or
source regions; they will sync simultaneously.
-
-Once done with editing, press @samp{C-c C-c} to exit live-sync edit. The key
is bound to @samp{org-transclusion-live-sync-exit}. It will turn off the live
sync edit but keep the transclusion on.
-
-In the live-sync edit region, the normal @samp{yank} command (@samp{C-y}) is
replaced with a special command @samp{org-transclusion-live-sync-paste}. This
command lets the pasted text inherit the text-properties of the transcluded
region correctly; the normal yank does not have this feature and thus causes
some inconvenience in live-sync edit. If you use vim keybindings (e.g.
@samp{evil-mode}), it is advised that you review the default keybindings. You
can customize the local keybindings [...]
-
-@strong{Note}: During live-sync edit, file's content gets saved to the file
system as is -- i.e. the transcluded text will be saved instead of the
@samp{#+transclude:} keyword. If you kill buffer or quit Emacs, other hooks
will still remove the transclusion to keep the file clear of the transcluded
copy, leaving only the keyword in the file system.
-
-@lisp
-(substitute-command-keys "\\@{org-transclusion-live-sync-map@}")
-@end lisp
-
-@example
-key binding
---- -------
-
-C-c Prefix Command
-C-y org-transclusion-live-sync-paste
-
-C-c C-c org-transclusion-live-sync-exit
-
-*Also inherits ‘org-mode-map’
-@end example
-
-@node Transclude source file into src-block
-@section Transclude source file into src-block
-
-@cindex Transclude into Org's src-block
-@cindex Property - :src
-@cindex Property - :rest
-
-This feature is provided as an @ref{Extensions, , extension} (default on).
-
-You can transclude a source file into an Org's src block. Use the @samp{:src}
property and specify the language you would like to use like this:
-
-@example
-#+transclude: [[file:../../test/python-1.py]] :src python
-@end example
-
-The content you specify in the link gets wrapped into a src-block with the
language like this:
-
-@example
-#+begin_src python
-[... content of python-1.py]
-#+end_src
-@end example
-
-Use @samp{:rest} property to define additional properties you would like to
add for the src-block. The double quotation marks are mandatory for the
@samp{:rest} property.
-
-@example
-#+transclude: [[file:../../test/python-3.py]] :src python :rest ":session
:results value"
-@end example
-
-The source block will have the additional properties:
-@example
-#+begin_src python :session :results value
-@end example
-
-@node Transclude range of lines for text and source files
-@section Transclude range of lines for text and source files
-
-@cindex Transclude range of lines
-
-This feature is provided as an @ref{Extensions, , extension} (default on).
-
-When you transclude text files other than Org files,
-
-@menu
-* @samp{lines} property to specify a range of lines::
-* @samp{end} property to specify a search term to dynamically look for the end
of a range::
-@end menu
-
-@node @samp{lines} property to specify a range of lines
-@subsection @samp{:lines} property to specify a range of lines
-
-@cindex Property - :lines
-
-You can specify a range of lines to transclude from a source and text file.
Use the @samp{:lines} property like this.
-
-@example
-#+transclude: [[file:../../test/test.txt]] :lines 3-5
-@end example
-
-The rage is specified by the number "3-5"; in this case, lines from 3 to 5,
both lines inclusive.
-
-To transclude a single line, have the the same number in both places (e.g.
10-10, meaning line 10 only).
-
-One of the numbers can be omitted. When the first number is omitted (e.g.
-10), it means from the beginning of the file to line 10. Likewise, when the
second number is omitted (e.g. 10-), it means from line 10 to the end of file.
-
-You can combine the @samp{:lines} property with the @samp{:src} property to
transclude only a certain range of source files (Example 1 below).
-
-For Org's file links, you can use
@uref{https://orgmode.org/manual/Search-Options.html, search options} specified
by the "::" (two colons) notation. When a search finds a line that includes the
string, the Org-transclude counts it as the starting line 1 for the
@samp{:lines} property.
-
-Example 1: This transcludes the four lines of the source file from the line
that contains string "id-1234" (including that line counted as line 1).
-@example
-#+transclude: [[file:../../test/python-1.py::id-1234]] :lines 1-4 :src python
-@end example
-
-Example 2: This transcludes only the single line that contains the line found
by the search option for text string "Transcendental Ontology"
-@example
-#+transclude: [[file:../../test/test.txt::Transcendental Ontology]] :lines 1-1
-@end example
-
-Note search-options @samp{::/regex/} and @samp{::number} do not work as
intended.
-
-@node @samp{end} property to specify a search term to dynamically look for the
end of a range
-@subsection @samp{:end} property to specify a search term to dynamically look
for the end of a range
-
-@cindex Property - :end
-
-You can add @samp{:end} property and specify the search term as its value.
Surround the search term with double quotation marks (mandatory).
-
-See Example 3 below. This transclusion will look for @samp{id-1234} as the
beginning line of the range as specified by the search option @samp{::id-1234}
in the link. With the @samp{:end} property, the search term @samp{id-1234 end
here} defines the end of the range. The search looks for @samp{id-123 end here}
in the body text, and use the line one before the one where the text is find
(thus, the transcluded range will not contain @samp{id-1234 end here}).
-
-You can also combined @samp{:lines} property with @samp{:end} property. It
will only displace the beginning, and the end part of the range (the second
number after the hyphen "-") is ignored. In the same example, the beginning of
the range is the one line after the line where "id-1234" is found; it's the
"second line, or line 2". Instead of transcluding until the end of the buffer,
the end is defined by the @samp{:end} property.
-
-Example 3:
-@example
-#+transclude: [[file:../../test/python-1.py::id-1234]] :lines 2- :src python
:end "id-1234 end here"
-@end example
-
-@node Extensions
-@section Extensions
-
-@cindex Extensions
-@vindex org-transclusion-extensions
-@cindex Extension - org-transclusion-indent-mode
-@cindex Extension - org-transclusion-src-lines
-@cindex Extension - org-transclusion-font-lock
-
-Org-transclusion provides a simple extension framework, where you can use
@samp{customize} to selectively add new features.
-
-If you use @samp{customize}, the features are loaded automatically. Note that
it does not "unload" the feature until you relaunch Emacs.
-
-If you do not use @samp{customize} (e.g. Doom), you may need to explicitly
require an extension. For example, to activate
@samp{org-transclusion-indent-mode}, you might need to add something like this
in your configuration file.
-
-@lisp
-;; Ensure that load-path to org-transclusion is already added
-;; If you installed it with the built-in package.el, this should be already
done.
-;; (add-to-list 'load-path "path/to/org-transclusion/")
-(add-to-list 'org-transclusion-extensions 'org-transclusion-indent-mode)
-(require 'org-transclusion-indent-mode)
-@end lisp
-
-Currently, the following extensions are available.
-
-@table @asis
-@item (off by default) @samp{org-transclusion-indent-mode}
-Support org-indent-mode.
-
-@item (on by default) @samp{org-transclusion-src-lines}
-Add features for @samp{:src} and @samp{:lines} properties to
@samp{#+transclude}. It is meant for non-Org files such as program source and
text files
-
-@item (on by default) @samp{org-transclusion-font-lock}
-Add font-lock for @samp{#+transclude}. Org mode's standard syntax treats the
combination of a @samp{#+transclude:} keyword and a link used by
Org-transclusion as a keyword. This means it applies the @samp{org-meta-line}
face and the link part cannot be toggled as a normal link. This extension adds
@samp{org-transclusion-keyword} face to the keyword part and lets the link part
to be treated as a normal link for @samp{org-toggle-link-display}.
-@end table
-
-@node Customizing
-@chapter Customizing
-
-@vindex org-transclusion-extensions
-@vindex org-transclusion-add-all-on-activate
-@vindex org-transclusion-mode-lighter
-@vindex org-transclusion-open-source-display-action-list
-
-You can customize settings in the @samp{org-transclusion} group.
-
-@table @asis
-@item @samp{org-transclusion-extensions}
-Defines extensions to be loaded with
-org-transclusion.el. If you use @samp{customize}, the extensions are loaded by
it.
-If you don't, you likely need to explicitly use @samp{require} to load them.
See @ref{Extensions, , seb-section}
-
-@item @samp{org-transclusion-add-all-on-activate}
-Defines whether or not all the
-active transclusions (with @samp{t}) get automatically transcluded on minor
mode
-activation (@samp{org-transclusion-mode}). This does not affect the manual
-activation when you directly call @samp{org-transclusion-activate}
-
-@item @samp{org-transclusion-exclude-elements}
-See @ref{Customizable filter to exclude certain Org elements, , sub-section}
-
-@item @samp{org-transclusion-include-first-section}
-See @ref{Include the section before the first headline (Org file only), ,
sub-section}
-
-@item @samp{org-transclusion-open-source-display-action-list}
-You can customize the
-way the @samp{org-transclusion-open-source} function displays the source
buffer for
-the transclusion. You specify the "action" in the way defined by the built-in
-@samp{display-buffer} function. Refer to its in-system documentation (with
@samp{C-h f})
-for the accepted values. @samp{M-x customize} can also guide you on what types
of
-values are accepted.
-
-@item @samp{org-transclusion-mode-lighter}
-Define the lighter for Org-transclusion
-minor mode. The default is " OT".
-@end table
-
-@menu
-* Customizable filter to exclude certain Org elements::
-* Include the section before the first headline (Org file only)::
-* Faces & fringe bitmap::
-* Keybindings::
-@end menu
-
-@node Customizable filter to exclude certain Org elements
-@section Customizable filter to exclude certain Org elements
-
-@vindex org-transclusion-exclude-elements
-
-Set customizable variable @samp{org-transclusion-exclude-elements} to define
which elements to be @strong{excluded} in the transclusion.
-
-The filter works for all supported types of links within an Org file when
transcluding an entire Org file, and parts of it (headlines, custom ID, etc.).
There is no filter for non-Org files.
-
-It is a list of symbols, and the default is @samp{(property-drawer)}. The
accepted values are the ones defined by @samp{org-element-all-elements} (Org's
standard set of elements; refer to its documentation for an exhaustive list).
-
-You can also fine-tune the exclusion filter per transclusion. Refer to the
sub-section on @ref{Filter Org elements per transclusion, , filtering Org
elements per transclusion}.
-
-@node Include the section before the first headline (Org file only)
-@section Include the section before the first headline (Org file only)
-
-@vindex org-transclusion-include-first-section
-
-You can include the first section (section before the first headline) of an
Org file. It is toggled via customizable variable
@samp{org-transclusion-include-first-section}. Its default value is @samp{t}.
Set it to @samp{t} (or non-nil) to transclude the first section. It also works
when the first section is followed by headlines.
-
-@node Faces & fringe bitmap
-@section Faces & fringe bitmap
-
-@vindex org-transclusion-keyword
-@vindex org-transclusion-source-fringe
-@vindex org-transclusion-fringe
-@vindex org-transclusion-source
-@vindex org-transclusion-source-edit
-@vindex org-transclusion
-@vindex org-transclusion-edit
-@vindex org-transclusion-fringe-bitmap
-
-@menu
-* Face for the @samp{#+transclude} keyword::
-* Faces for the fringes next to transcluded region and source region::
-@end menu
-
-@node Face for the @samp{#+transclude} keyword
-@subsection Face for the @samp{#+transclude} keyword
-
-This feature is provided as an @ref{Extensions, , extension} (default on).
-
-@table @asis
-@item @samp{org-transclusion-keyword}
-You can set your own face to the @samp{#+transclude} keyword with using the
@samp{org-transclusion-keyword} face.
-@end table
-
-@node Faces for the fringes next to transcluded region and source region
-@subsection Faces for the fringes next to transcluded region and source region
-
-If the fringes that indicate transcluding and source regions are not visible
in your system (e.g. Doom), try adding background and/or foreground colors to
these custom faces.
-
-@itemize
-@item
-@samp{org-transclusion-source-fringe}
-@item
-@samp{org-transclusion-fringe}
-@end itemize
-
-To customize a face, it's probably the easiest to use @samp{M-x
customize-face}. If you want to use Elisp for some reason (e.g. on Doom),
something like this below should set faces. Experiment with the colors of your
choice. By default, the faces above have no values.
-
-@lisp
-(set-face-attribute
- 'org-transclusion-fringe nil
- :foreground "green"
- :background "green")
-@end lisp
-
-For colors, where "green" is, you can also use something like "#62c86a"
(Emacs calls it "RGB triple"; you can refer to in-system manual Emacs >
Colors). You might also like to refer to a list of currently defined faces in
your Emacs by @samp{list-faces-display}.
-
-Other faces:
-@itemize
-@item
-@samp{org-transclusion-source}
-@item
-@samp{org-transclusion-source-edit}
-@item
-@samp{org-transclusion}
-@item
-@samp{org-transclusion-edit}
-@item @samp{org-transclusion-fringe-bitmap}
-It is used for the fringe that indicates the transcluded region. It works only
in a graphical environment (not in terminal).
-@end itemize
-
-@node Keybindings
-@section Keybindings
-
-@vindex org-transclusion-map
-@vindex org-transclusion-live-sync-map
-
-@itemize
-@item
-@samp{org-transclusion-map}
-@end itemize
-@example
-key binding
---- -------
-
-C-c Prefix Command
-TAB org-cycle
-D org-transclusion-demote-subtree
-O org-transclusion-move-to-source
-P org-transclusion-promote-subtree
-d org-transclusion-remove
-e org-transclusion-live-sync-start
-g org-transclusion-refresh
-o org-transclusion-open-source
-
-C-c C-c org-ctrl-c-ctrl-c
-@end example
-
-
-@itemize
-@item
-@samp{org-transclusion-live-sync-map}
-@end itemize
-@example
-key binding
---- -------
-
-C-c Prefix Command
-C-y org-transclusion-live-sync-paste
-
-C-c C-c org-transclusion-live-sync-exit
-
-*Also inherits ‘org-mode-map’
-@end example
-
-@node Known Limitations
-@chapter Known Limitations
-
-Note this section is still incomplete, not exhaustive for "known" limitations.
-
-@itemize
-@item
-Org link's search-options @samp{::/regex/} and @samp{::number} do not work as
intended.
-
-@item @samp{org-transclusion-live-sync-start} does not support all Org elements
-For transclusions of Org elements or buffers, live-sync works only on the
following elements:
-@samp{center-block}, @samp{drawer}, @samp{dynamic-block},
@samp{latex-environment}, @samp{paragraph}, @samp{plain-list},
@samp{quote-block}, @samp{special-block}, @samp{table}, and @samp{verse-block}.
-
-It is known that live-sync does not work for the other elements; namely:
-@samp{comment-block}, @samp{export-block}, @samp{example-block},
@samp{fixed-width}, @samp{keyword}, @samp{src-block}, and
@samp{property-drawer}.
-
-More technical reason for this limitation is documented in the docstring of
function @samp{org-transclusion-live-sync-enclosing-element}.
-
-Work is in progress to lift this limitation but I'm still experimenting
different ideas.
-
-@item @samp{org-indent-mode} may not work well with Org-transclusion
-A new extension has been added to support @samp{org-indent-mode}
-Refer to @ref{Extensions, , this section}.
-
-@item Doom's customization may interfere with Org-transclusion
-Refer to issue @uref{https://github.com/nobiot/org-transclusion/issues/52,
#52}. The symptom is that in Doom you get an error message that includes this:
"progn: ‘recenter’ing a window that does not display current-buffer." Adding
this in your configuration has been reported to fix the issue:
-
-@samp{(advice-remove 'org-link-search '+org--recenter-after-follow-link-a)}
-
-It is probably rather drastic a measure. I will appreciate it if you find a
less drastic way that works. Thank you.
-
-@item Org refile does not work "properly" on the transcluded headlines
-Refer to issue @uref{https://github.com/nobiot/org-transclusion/issues/20,
#20}. I don't intend to support this -- refile the source, not the transcluded
copy.
-
-@item Org-transclusion does not support expansion of noweb references when a
transcluded source block code has them
-Refer to issue @uref{https://github.com/nobiot/org-transclusion/issues/86,
#86}. You will get "Text read-only" error when export tries to expand the noweb
references into the source code.
†@uref{https://orgmode.org/manual/Noweb-Reference-Syntax.html, noweb reference}
-@end itemize
-
-@node Credits
-@chapter Credits
-
-@menu
-* Original idea by John Kitchin::
-* Text-Clone::
-@end menu
-
-@node Original idea by John Kitchin
-@section Original idea by John Kitchin
-
-@uref{https://github.com/alphapapa/transclusion-in-emacs#org-mode}
-
-@quotation
-@{O@} transcluding some org-elements in multiple places
-@emph{[2016-12-09 ven.] } John Kitchin asks:
-
-I have an idea for how I could transclude “copies” or links to org-elements in
multiple places and keep them up to date. A prototypical example of this is I
have a set of org-contacts in one place, and I want to create a new list of
people for a committee in a new place made of “copies” of the contact
headlines. But I do not really want to duplicate the headlines, and if I modify
one, I want it reflected in the other places. I do not want just links to those
contacts, because then I can [...]
-
-This idea was inspired by @uref{https://github.com/gregdetre/emacs-freex}.
-
-The idea starts with creating (wait for it…) a new link ;) In a document where
I want to transclude a headline, I would enter something like:
-
-transclude:some-file.org::*headline title
-
-Then, I would rely on the font-lock system to replace that link with the
headline and its contents (via the :activate-func link property), and to put an
overlay on it with a bunch of useful properties, including modification hooks
that would update the source if I change the the element in this document, and
some visual indication that it is transcluded (e.g. light gray
background/tooltip).
-
-I would create a kill-buffer hook function that would replace that transcluded
content with the original link. A focus-in hook function would make sure the
transcluded content is updated when you enter the frame. So when the file is
not open, there is just a transclude link indicating what should be put there,
and when it is open, the overlay modification hooks and focus hook should
ensure everything stays synchronized (as long as external processes are not
modifying the contents).
-
-It seems like this could work well for headlines, and named tables, src
blocks, and probably any other element that can be addressed by a name/ID@.
-
-@end quotation
-
-@node Text-Clone
-@section Text-Clone
-
-@samp{text-clone.el} is an extension of text-clone functions written as part
of GNU Emacs in @samp{subr.el}. The first adaption to extend text-clone
functions to work across buffers was published in StackExchange by the user
named Tobias in March 2020. It can be found at
@uref{https://emacs.stackexchange.com/questions/56201/is-there-an-emacs-package-which-can-mirror-a-region/56202#56202}.
The text-clone library takes this line of work further.
-
-@node Contributing
-@chapter Contributing
-
-@itemize
-@item
-Get involved in a discussion in
@uref{https://org-roam.discourse.group/t/prototype-transclusion-block-reference-with-emacs-org-mode/830,
Org-roam forum} (the package is originally aimed for its users, me included)
-
-@item
-Create issues, discussion, and/or pull requests. All welcome.
-@end itemize
-
-@menu
-* Notes on pull requests and Free Software Foundation (FSF) copy right
assignment::
-@end menu
-
-@node Notes on pull requests and Free Software Foundation (FSF) copy right
assignment
-@section Notes on pull requests and Free Software Foundation (FSF) copy right
assignment
-
-Org-transclusion is part of GNU ELPA and thus copyrighted by the
@uref{http://fsf.org, Free Software Foundation} (FSF). This means that anyone
who is making a substantive code contribution will need to "assign the
copyright for your contributions to the FSF so that they can be included in GNU
Emacs" (@uref{https://orgmode.org/contribute.html#copyright, Org Mode website}).
-
-Thank you.
-
-@node Index - Features
-@appendix Index - Features
-
-@printindex cp
-
-@node Index - Commands
-@appendix Index - Commands
-
-@printindex fn
-
-@node Index - User Options
-@appendix Index - User Options
-
-@printindex vr
-
-@node GNU Free Documentation License
-@appendix GNU Free Documentation License
-
-@include docs/fdl.texi
-
-@bye
\ No newline at end of file