David Masterson <dsmaster...@icloud.com> writes:
> I'll put a new patch together tomorrow.
Patch (from git format-patch) attached.
>From 651863abef42faaabf60d829503f0da9393cfc88 Mon Sep 17 00:00:00 2001
From: David Masterson <dsmaster...@gmail.com>
Date: Wed, 30 Apr 2025 22:53:20 -0700
Subject: [PATCH] Cleanup documentation on definition of "headline level"
lisp/ox.el (org-export-headline-levels): change docstring to make use
of "ancestor" and "descendant" in describing headline levels.
doc/org-guide.org: cleanup use of "first" and "top" for levels.
doc/org-manual.org: cleanup use of "first" and "top" as well as add
"descendants" in describing headline levels.
---
doc/org-guide.org | 4 ++--
doc/org-manual.org | 11 ++++++-----
lisp/ox.el | 6 +++---
3 files changed, 11 insertions(+), 10 deletions(-)
diff --git a/doc/org-guide.org b/doc/org-guide.org
index 205623525..cc7155c61 100644
--- a/doc/org-guide.org
+++ b/doc/org-guide.org
@@ -117,13 +117,13 @@ Org start on the left margin[fn:1] with one or more stars followed by
a space. For example:
#+begin_example
-,* Top level headline
+,* First (top) level headline
,** Second level
,*** Third level
some text
,*** Third level
more text
-,* Another top level headline
+,* Another first (top) level headline
#+end_example
Note that a headline named after ~org-footnote-section~, which
diff --git a/doc/org-manual.org b/doc/org-manual.org
index f32d1271e..709edfc8f 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -508,13 +508,13 @@ start on the left margin[fn:1] with one or more stars followed by
a space. For example:
#+begin_example
-,* Top level headline
+,* First (top) level headline
,** Second level
,*** Third level
some text
,*** Third level
more text
-,* Another top level headline
+,* Another first (top) level headline
#+end_example
#+vindex: org-footnote-section
@@ -12521,9 +12521,10 @@ following arguments.
- ~H~ ::
#+vindex: org-export-headline-levels
- Set the number of headline levels for export
- (~org-export-headline-levels~). Below that level, headlines are
- treated differently. In most backends, they become list items.
+ Set the last headline level for export as a headline
+ (~org-export-headline-levels~). For descendants of that level,
+ headlines are treated differently. In most backends, they become
+ list items.
- ~inline~ ::
diff --git a/lisp/ox.el b/lisp/ox.el
index c5e3bab98..00ce86d69 100644
--- a/lisp/ox.el
+++ b/lisp/ox.el
@@ -534,10 +534,10 @@ t Allow export of math snippets."
:safe (lambda (x) (memq x '(t nil verbatim))))
(defcustom org-export-headline-levels 3
- "The last level which is still exported as a headline.
+ "This level and its ancestors will be exported as a headline.
-Inferior levels will usually produce itemize or enumerate lists
-when exported, but backend behavior may differ.
+Descendants of this level will usually produce itemized or
+enumerated lists when exported, but backend behavior may differ.
This option can also be set with the OPTIONS keyword,
e.g. \"H:2\"."
--
2.39.5
--
David Masterson
