branch: externals/org-transclusion
commit af73bc76c5083927d28ac7948d89639806dd0650
Author: Noboru Ota <m...@nobiot.com>
Commit: Noboru Ota <m...@nobiot.com>
docs:improvinng README for Texinfo
---
NEWS | 73 ++++++++++++++++++++++++++++++++-
README.org | 133 ++++++++++++++-----------------------------------------------
2 files changed, 103 insertions(+), 103 deletions(-)
diff --git a/NEWS b/NEWS
index 9814e63..613ac40 100644
--- a/NEWS
+++ b/NEWS
@@ -5,4 +5,75 @@
* Version 1.0.0
-- Initial version available on ELPA (https://elpa.gnu.org/)
\ No newline at end of file
+- Initial version available on ELPA (https://elpa.gnu.org/)
+
+- Feature ::
+ - : =:end= property and a search term to dynamically define a range of lines
to transclude for text and
+ source code block
+
+- Change ::
+ - Now user option =org-transclusion-include-first-section='s default value
+ is changed to =t=. This seems to be more intuitive for more users
+
+- Fix ::
+ - =org-transclusion-before-kill= now checks if the buffer to be killed
+ contains any transclusion AND it is visting a file before saving. This
+ fixes some issues related to temp buffers, etc.
+ - fix: search options for src-lines extension for =:lines=, =:src=, and
=:end= properties
+
+
+* Changelog before Version 1.0.0
+
+** 0.2.2
+- New Features ::
+ - #+transclude font-lock and new face =org-transclusion-keyword=
+ - Selective extensions with =org-transclusion-extensions=
+ - (optional extension) Support for org-indent
+- Fix ::
+ - fix: #93 open-source error "Live sync cannot start here"
+
+** 0.2.1
+- New Features ::
+ - Transclude a source file into a =src= block
+ - Transclude a range of lines for text and source files
+ - Main relevant commits:
+ + 6e0e4bf * | feat: :src, :lines, :rest props (WIP)
+
+** 0.2.0
+- Breaking changes ::
+ Refer to the updated README on new features and changed command names
+ - Change names of commands
+ - Remove t/nil to #+transclude: syntax
+ - Add :disable-auto
+ - Main relevant commits:
+ + 2ba90f0 * break: change command and function names
+ + 6cdd836 * | intrnl: v0.2.0 (breaking change)
+ + 765d8ee * add :disable-auto
+
+- New features and improvements ::
+ Refer to the updated README on new features and changed command names
+ - 7e5c839 * feat: exclude-elements
+ - 765d8ee * add :disable-auto
+ - afd6d80 * add: :only-contents
+ - cbb1c25 * add: apply :level to buffer with first section ::
+ Fix #47 The first section itself does not get influenced by :level
property. The first headline, when present, is treated as the first headline,
thus :exclude-element "headline" affects its sub-headlines; this means that the
content of the first headline is transcluded even when with "headline" in the
list of excluded elements.
+
+** 0.1.2
+- e08df47 * add: live-sync for non-Org text file ::
+ So far Non-Org text files could be transcluded but live-sync was not
available. This version enables live-sync for them. Only for the whole file at
the moment (ability to specify parts of a text file is considered)
+
+- a576b34 * add: text-clone library (rename) ::
+ Live-sync features are now factored out into =text-clone= as a standalone
library (available with =text-clone.el= also included in this repo). Refactored
so that =org-transclusion= uses (and requires) =text-clone=.
+
+** 0.1.1
+- 49f03b1 * feat: current-indentation ::
+ Org-transclusion now keeps the original indentation of the keyword. When a
transclusion text region is removed, its keyword will be indented as it was
+
+- d55fc39 * chg: save-buffer hooks ::
+ Instead of blindly deactivate and activate all transclusions with t flag,
this variable is meant to provide mechanism to deactivate/activate only the
transclusions currently in effect to copy a text content.
+
+- 64fd182 * add: remove live-sync overlays when deleted ::
+ Closes issue [[https://github.com/nobiot/org-transclusion/issues/8][#8]]
Adding a mechanism to remove both of the live-sync overlays (transclusion and
source) when transclusion is completely deleted. This solves the problem of a
source overlay to be orphaned in such cases.
+
+** 0.1.0
+As described in this version.
diff --git a/README.org b/README.org
index c31bdf6..b927c86 100644
--- a/README.org
+++ b/README.org
@@ -10,36 +10,12 @@
# Note: I use the readme template that alphapapa shares on his GitHub repo
<https://github.com/alphapapa/emacs-package-dev-handbook#template>. It works
with the org-make-toc <https://github.com/alphapapa/org-make-toc> package,
which automatically updates the table of contents.
-[[https://en.wikipedia.org/wiki/Transclusion][Transclusion]] is the ability to
include content from one file into another by reference. Org-transclusion is an
Org Mode version of it. It lets you insert a copy of text content via a file
link or ID link within an Org file. It is my take on the
[[#original-idea-by-john-kitchin][idea by John Kitchin]].
-
-When I start writing a long-form material, I want to begin with looking
through my notes and assemble relevant ones to form a basis of the first draft
quickly. As I organise my notes in a repository, I also want to avoid having
multiple copies of notes flying around.
-
-Transclusion helps me do this.
-
-I am dabbling in the
[[https://writingcooperative.com/zettelkasten-how-one-german-scholar-was-so-freakishly-productive-997e4e0ca125][Zettelkasten
method]] with using [[https://www.orgroam.com/][Org-roam]] to feed my ideas
into the repository. As such, although Org-transclusion is a standalone
package, I would like to keep workflow seamless between Org-roam and
Org-transclusion.
-
-#+caption: Figure 1. Animation to show creation of a transclusion from an ID
link
-[[./resources/2021-09-10-transclusion.gif]]
-*Figure 1*. Animation to show transclusion from the buffer on the right
-
-#+caption: Figure 2. Animation to show live sync from transclusion to source
-[[./resources/2021-05-01-org-transclusion-0.1.0-live-sync.gif]]
-*Figure 2*. Animation to show live sync from transclusion to source
-
-[[./resources/demo9-title.png]]
-*Figure 3* [[https://youtu.be/ueaPiA622wA][Video demo on v0.2.1 on YouTube]]
demonstrating new features to transclude a source file into a src-block and
function to specify a range of text/source lines
-
-- Recent videos ::
- + [[https://youtu.be/idlFzWeygwA][Video demo on v0.2.0 on YouTube]]
featuring minor breaking changes and new transclusion filters
-
-- Older videos ::
- + [[https://youtu.be/idlFzWeygwA][Video demo on v0.1.1 on YouTube]]
featuring basic syntax and live-sync edit
-
* Contents :noexport:
:PROPERTIES:
:TOC: :include siblings
:END:
:CONTENTS:
+- [[#introduction][Introduction]]
- [[#installation][Installation]]
- [[#getting-started][Getting Started]]
- [[#usage][Usage]]
@@ -61,7 +37,6 @@ I am dabbling in the
[[https://writingcooperative.com/zettelkasten-how-one-germa
- [[#tips][Tips]]
- [[#moving-from-00x-to-01x][Moving from 0.0.x to 0.1.x]]
- [[#known-limitations][Known Limitations]]
-- [[#changelog][Changelog]]
- [[#credits][Credits]]
- [[#original-idea-by-john-kitchin][Original idea by John Kitchin]]
- [[#text-clone][Text-Clone]]
@@ -70,6 +45,36 @@ I am dabbling in the
[[https://writingcooperative.com/zettelkasten-how-one-germa
- [[#license][License]]
:END:
+* Introduction
+:PROPERTIES:
+:TOC: :depth 0
+:END:
+
+[[https://en.wikipedia.org/wiki/Transclusion][Transclusion]] is the ability to
include content from one file into another by reference. Org-transclusion is an
Org Mode version of it. It lets you insert a copy of text content via a file
link or ID link within an Org file. It is my take on the
[[#original-idea-by-john-kitchin][idea by John Kitchin]].
+
+When I start writing a long-form material, I want to begin with looking
through my notes and assemble relevant ones to form a basis of the first draft
quickly. As I organise my notes in a repository, I also want to avoid having
multiple copies of notes flying around.
+
+Transclusion helps me do this.
+
+I am dabbling in the
[[https://writingcooperative.com/zettelkasten-how-one-german-scholar-was-so-freakishly-productive-997e4e0ca125][Zettelkasten
method]] with using [[https://www.orgroam.com/][Org-roam]] to feed my ideas
into the repository. As such, although Org-transclusion is a standalone
package, I would like to keep workflow seamless between Org-roam and
Org-transclusion.
+
+#+caption: Animation to show creation of a transclusion from an ID link
+[[./resources/2021-09-10-transclusion.gif]]
+
+#+caption: Animation to show live sync from transclusion to source
+[[./resources/2021-05-01-org-transclusion-0.1.0-live-sync.gif]]
+
+#+caption: Video demo on v0.2.1 on YouTube demonstrating new features to
transclude a source file into a src-block and function to specify a range of
text/source line
+[[./resources/demo9-title.png]]
+
+- Recent videos ::
+ + [[https://youtu.be/ueaPiA622wA][Video demo on v0.2.1 on YouTube]]
demonstrating new features to transclude a source file into a src-block and
function to specify a range of text/source lines
+
+ + [[https://youtu.be/idlFzWeygwA][Video demo on v0.2.0 on YouTube]]
featuring minor breaking changes and new transclusion filters
+
+- Older videos ::
+ + [[https://youtu.be/idlFzWeygwA][Video demo on v0.1.1 on YouTube]]
featuring basic syntax and live-sync edit
+
* Installation
:PROPERTIES:
:TOC: :depth 0
@@ -591,82 +596,6 @@ Note this section is still incomplete, far from being
exhaustive for "known" lim
- Org-transclusion does not support expansion of
[[https://orgmode.org/manual/Noweb-Reference-Syntax.html][noweb references]]
when a transcluded source block code has them ::
Refer to [[https://github.com/nobiot/org-transclusion/issues/86][issue
#86]]. You will get "Text-only" error when export tries to expand the noweb
references into the source code.
-* Changelog
-:PROPERTIES:
-:TOC: :depth 0
-:END:
-Main features and changes only.
-
-** 1.0.0 (initial version on [[https://elpa.gnu.org/][ELPA]])
-
-- Feature ::
- - : =:end= property and a search term to dynamically define a range of lines
to transclude for text and
- source code block
-
-- Change ::
- - Now user option =org-transclusion-include-first-section='s default value
- is changed to =t=. This seems to be more intuitive for more users
-
-- Fix ::
- - =org-transclusion-before-kill= now checks if the buffer to be killed
- contains any transclusion AND it is visting a file before saving. This
- fixes some issues related to temp buffers, etc.
- - fix: search options for src-lines extension for =:lines=, =:src=, and
=:end= properties
-
-** 0.2.2
-- New Features ::
- - #+transclude font-lock and new face =org-transclusion-keyword=
- - Selective extensions with =org-transclusion-extensions=
- - (optional extension) Support for org-indent
-- Fix ::
- - fix: #93 open-source error "Live sync cannot start here"
-
-** 0.2.1
-- New Features ::
- - Transclude a source file into a =src= block
- - Transclude a range of lines for text and source files
- - Main relevant commits:
- + 6e0e4bf * | feat: :src, :lines, :rest props (WIP)
-
-** 0.2.0
-- Breaking changes ::
- Refer to the updated README on new features and changed command names
- - Change names of commands
- - Remove t/nil to #+transclude: syntax
- - Add :disable-auto
- - Main relevant commits:
- + 2ba90f0 * break: change command and function names
- + 6cdd836 * | intrnl: v0.2.0 (breaking change)
- + 765d8ee * add :disable-auto
-
-- New features and improvements ::
- Refer to the updated README on new features and changed command names
- - 7e5c839 * feat: exclude-elements
- - 765d8ee * add :disable-auto
- - afd6d80 * add: :only-contents
- - cbb1c25 * add: apply :level to buffer with first section ::
- Fix #47 The first section itself does not get influenced by :level
property. The first headline, when present, is treated as the first headline,
thus :exclude-element "headline" affects its sub-headlines; this means that the
content of the first headline is transcluded even when with "headline" in the
list of excluded elements.
-
-** 0.1.2
-- e08df47 * add: live-sync for non-Org text file ::
- So far Non-Org text files could be transcluded but live-sync was not
available. This version enables live-sync for them. Only for the whole file at
the moment (ability to specify parts of a text file is considered)
-
-- a576b34 * add: text-clone library (rename) ::
- Live-sync features are now factored out into =text-clone= as a standalone
library (available with =text-clone.el= also included in this repo). Refactored
so that =org-transclusion= uses (and requires) =text-clone=.
-
-** 0.1.1
-- 49f03b1 * feat: current-indentation ::
- Org-transclusion now keeps the original indentation of the keyword. When a
transclusion text region is removed, its keyword will be indented as it was
-
-- d55fc39 * chg: save-buffer hooks ::
- Instead of blindly deactivate and activate all transclusions with t flag,
this variable is meant to provide mechanism to deactivate/activate only the
transclusions currently in effect to copy a text content.
-
-- 64fd182 * add: remove live-sync overlays when deleted ::
- Closes issue [[https://github.com/nobiot/org-transclusion/issues/8][#8]]
Adding a mechanism to remove both of the live-sync overlays (transclusion and
source) when transclusion is completely deleted. This solves the problem of a
source overlay to be orphaned in such cases.
-
-** 0.1.0
-As described in this version.
-
* Credits
** Original idea by John Kitchin
:PROPERTIES:
