Motivation

In order to avoid text duplication, its nice to be able to specify a portion of text that should be included from another document. This will be extra handy if some notes should include answer from another note (e.g. exam note) or when creating a whole document as a compilation of notes.

Constrains

• users should only need to specify only a file path and a heading to search
• if two titles have name collision allow users to specify a unique link or some sort of ID of the heading they want to include
• users should be able to specify whether to include also heading or only the body part of specified node
• all images in the included nodes should be processed correctly
• allow users to input another options like depth of include

Technical implementation

This cannot be done with a pure org-mode since pandoc does not support including only portion of files org-doc (example: /tmp/file.org:*My heading).

• The files need to be preprocessed and all links (images, etc) needs to be normalized when the text is included
• We will write a preprocessor in python that will create a temporary file with all includes replaced with corresponding text
• I don't think there is a reason to support recursive references (this can potentially simplify implementation)
• I would like this to generate reasonable pdfs even without preprocessor, for example the references should not break the original org file syntax

Syntax - TBD

An example document showcasing the different ways to include other nodes.