Demoting sections on org-export

Question

Context Last weekend I had some discussion with a friend about how I could improve my writing skills. As a result I would like to experiment with a new document structure to guide the process of scientific writing. Therefore I want to introduce for each section of my document several subsections:

• Goals that describe what should be achieved in this section, i.e. what is the reader expected to know at the beginning and what should he know afterwards.
• Strategies that sketch how this goal can be met (i.e. argumentation or text flow)
• Literature which contains a review of related publications that forms the theoretical foundation for this section and has a subsubsection for each publication.
• Notes contains all information (ordered according to the strategy) that is needed to write the final text
• Text written in the last step. The text may contain a paragraph with a heading.

For each of these tasks I would like to track the time spent on it by having a separate logbook for each of them.

I am not sure if it is a good idea to have everything in a single document but I could imagine that it's easier to manage in the case of re-organisations. The draw back is that exporting gets somehow complicated. This is the reason for this request of help.

Document structure

* Section (can be everything from one to five stars)
****** Goals                                   :Goal:
:LOGBOOK:
:END:

****** Strategy                            :Strategy:
:LOGBOOK:
:END:

****** Literature                        :Literature:
:LOGBOOK:
:END:

******* Publication 1
:LOGBOOK:
:END:

******* Publication 2
:LOGBOOK:
:END:

****** Notes                                  :Notes:
:LOGBOOK:
:END:

- Argument 1
- Argument 2
- Argument 3

****** Text                                    :Text:
:LOGBOOK:
:END:

Some introductory words.

******* Paragraph 1
Some text.

******** Subparagraph (unlikely but for completeness)
Some text.

******* Paragraph 2
Some text.

You can see that the headings start with indentation of six. This is because it seems that the LaTeX exporter only supports five levels of headings. In order to do not run into conflicts I think that it's better to avoid overlaps. This requires us to perform some demotes to lower levels.

Exporting

I would like to export three separate documents from this:

• Goals and strategy. Hide all other sections and demote to level 4 (paragraph).
• Literature. Hide all other sections, remove heading and demote each subsection to level six, thus making it a enumerated list item.
• Notes. Hide all other sections and remove heading.
• Text. Hide all other sections and remove heading and demote each subsection to level four (paragraph).

What do I have so far?

I have defined a new export configuration, such that each of the documents described above is generated. It's using :preparation-function and :completion-function (docs) to perform the changes to the original document. The code to remove sections and headings is based on the this answer.

(defun org-prepare-export-strategy (backend)
  "Remove sections with :Literature|Notes|Text: tag."
  (org-map-entries (lambda () (let ((beg (point)))
                                (outline-next-visible-heading 1)
                                (backward-char)
                                (delete-region beg (point))))
                   "Literature|Notes|Text" tree)
)

(defun org-prepare-export-literature (backend)
  "Remove sections with :Goal|Strategy|Notes|Text: tag."
  (org-map-entries (lambda () (let ((beg (point)))
                                (outline-next-visible-heading 1)
                                (backward-char)
                                (delete-region beg (point))))
                   "Goal|Strategy|Notes|Text" tree)
  (org-map-entries (lambda () (delete-region (point-at-bol) (point-at-eol)))
                   "Literature")
)

(defun org-prepare-export-notes (backend)
  "Remove sections with :Goal|Strategy|Literature|Text: tag."
  (org-map-entries (lambda () (let ((beg (point)))
                                (outline-next-visible-heading 1)
                                (backward-char)
                                (delete-region beg (point))))
                   "Goal|Strategy|Literature|Text" tree)
  (org-map-entries (lambda () (delete-region (point-at-bol) (point-at-eol)))
                   "Notes")
)

(defun org-prepare-export-draft (backend)
  "Remove sections with :Goal|Strategy|Literature|Notes: tag."
  (org-map-entries (lambda () (let ((beg (point)))
                                (outline-next-visible-heading 1)
                                (backward-char)
                                (delete-region beg (point))))
                   "Goal|Strategy|Literature|Notes" tree)
  (org-map-entries (lambda () (delete-region (point-at-bol) (point-at-eol)))
                   "Text")
)

(defun org-enable-prepare-export-strategy () (add-hook 'org-export-before-processing-hook #'org-prepare-export-strategy))
(defun org-disable-prepare-export-strategy () (remove-hook 'org-export-before-processing-hook #'org-prepare-export-strategy))

(defun org-enable-prepare-export-literature () (add-hook 'org-export-before-processing-hook #'org-prepare-export-literature))
(defun org-disable-prepare-export-literature () (remove-hook 'org-export-before-processing-hook #'org-prepare-export-literature))

(defun org-enable-prepare-export-notes () (add-hook 'org-export-before-processing-hook #'org-prepare-export-notes))
(defun org-disable-prepare-export-notes () (remove-hook 'org-export-before-processing-hook #'org-prepare-export-notes))

(defun org-enable-prepare-export-draft () (add-hook 'org-export-before-processing-hook #'org-prepare-export-draft))
(defun org-disable-prepare-export-draft () (remove-hook 'org-export-before-processing-hook #'org-prepare-export-draft))

(setq org-publish-project-alist
      '(
        ("outline-strategy"
         :base-directory "~/org-mode/test/"
         :base-extension "org"
         :publishing-directory "~/org-mode/test/strategy"
     :preparation-function org-enable-prepare-export-strategy
     :completion-function  org-disable-prepare-export-strategy
         :publishing-function org-latex-publish-to-latex
         :include ("Test.org")
         :exclude "\\.org$"
         )
        ("outline-literature"
         :base-directory "~/org-mode/test/"
         :base-extension "org"
         :publishing-directory "~/org-mode/test/literature"
     :preparation-function org-enable-prepare-export-literature
     :completion-function  org-disable-prepare-export-literature
         :publishing-function org-latex-publish-to-latex
         :include ("Test.org")
         :exclude "\\.org$"
         )
        ("outline-notes"
         :base-directory "~/org-mode/test/"
         :base-extension "org"
         :publishing-directory "~/org-mode/test/notes"
     :preparation-function org-enable-prepare-export-notes
     :completion-function  org-disable-prepare-export-notes
         :publishing-function org-latex-publish-to-latex
         :include ("Test.org")
         :exclude "\\.org$"
         )
        ("outline-draft"
         :base-directory "~/org-mode/test/"
         :base-extension "org"
         :publishing-directory "~/org-mode/test/draft"
     :preparation-function org-enable-prepare-export-draft
     :completion-function  org-disable-prepare-export-draft
         :publishing-function org-latex-publish-to-latex
         :include ("Test.org")
         :exclude "\\.org$"
         )
        ))

Issues

• Subsection headings are removed because of the inherited tags.
• Goals and Strategy are not demoted to paragraph level.

Questions

• How do I call org-demote (mapping API docs) for the section matched by org-map-entries and it's childs?

Changelog

• Added working preparation functions (2015-05-25)

Answer 1

You can promote tags on org-publish by specifying a preparation-function as follows:

(defun org-prepare-export-literature (backend)
  "Remove sections with :Goal|Strategy|Notes|Text: tag,
  remove headings from sections with :Literature|References: tag and 
  promote sections with :Reference: tag."
  (show-all)
  (org-map-entries (lambda () (let ((beg (point)))
                                (outline-next-visible-heading 1)
                                (backward-char)
                                (delete-region beg (point))))
                   "Goal|Strategy|Notes|Text" tree)
  (org-map-entries (lambda () (delete-region (point-at-bol) (point-at-eol)))
                   "Literature|References")
  (org-map-entries (lambda () (org-promote))
                   "Reference")
)

org-map-entries matches all sections having a given tag and executes the lambda function on them. Within this it's possible to simply call org-promote, org-demote or org-promote-subtree and org-demote-subtree correspondingly. This function is then registered as a preparation function as shown in the question.

The code to remove of sections and to remove headings is left for completeness. The call to show-all is required because hidden sections are removed when they appear after a section that should be removed. It is only effective in the internal buffer and will not change visibility in the user's frame.

Answer 2

Check your org-export-headline-levels variable, it is probably set to 5, should be set to 2 or 3 to get rid of the extra starts. It will improve the readability a lot I think.

Also, I don't understand org-publish mechanism, but the following workflow can solve the distributing problem as well:

1. Use search-forward to locate headline, and do all sort of editing, then pass the start and end point of the subtree to...

2. Use write-region to append/write the subtree to a file which depends on the keywords just being searched in step 1.

3. do 1. and 2. for different headlines,

4. wrap 3. in a while loop to make sure it apply to the whole buffer.