Table of contents for just one section?

Table of contents for just one section?

[D. C. Toedt]

[-- Attachment #1: Type: text/plain, Size: 1334 bytes --]

I'd like to do sub-TOCs for individual sections and subsections.

EXAMPLE

*#+TOC: headlines 1*

** Business operations*

{{{SUBTOC}}}          # Inserts just the level-2 headings for this level-1
section

*** Services*

{{{SUBTOC}}}          # Shows just the level-3 headings for this level-2
section

*** Statements of work

*** Changes to statements of work

*** No obligation to agree to statement of work

*** Sales of goods*

{{{SUBTOC}}}

etc.

Any suggestions?

Regards, and thanks in advance,

--D. C.

D. C. (Dell Charles) Toedt III  *(my** last name is pronounced "Tate") *
Attorney and neutral arbitrator -- tech contracts and intellectual property
Lecturer, University of Houston Law Center
​Editor, ​​​Common Draft <http://www.commondraft.org/> project:  A readable
library of best-practices contract clauses,
     with extensive citations and commentary, updated often.
dc@toedt.com     LinkedIn: dctoedt <http://www.linkedin.com/in/dctoedt>
Calendar
<https://www.google.com/calendar/embed?src=dc.toedt@toedt.com&mode=WEEK>
(redacted)
O: +1 (713) 364-6545    C: +1 (713) 516-8968
​​

​
Houston, Texas (Central time zone)

Unless expressly stated otherwise, this message is not intended
to serve as an electronic signature nor as assent to an agreement.

[-- Attachment #2: Type: text/html, Size: 7070 bytes --]

Re: Table of contents for just one section?

[Nicolas Goaziou]

Hello,

"D. C. Toedt" <dc@toedt.com> writes:

> I'd like to do sub-TOCs for individual sections and subsections.

We could add a "local" keyword to TOC lines, e.g.,

  #+TOC: headlines 1 local

would mean only top level children in current headline.

This feature is trivial to add to ox-ascii, probably easy for ox-html or
ox-odt, assuming someone can provide the expected code.

Implementing it in ox-latex probably boils down to requiring another
package (minitoc?).

WDYT?


Regards,

-- 
Nicolas Goaziou

Re: Table of contents for just one section?

[D. C. Toedt]

[-- Attachment #1: Type: text/plain, Size: 1604 bytes --]

The local keyword would be great.

Right now I'm interested only in HTML export -- I can use Pandoc to convert
to anything else.

Thanks!



D. C. (Dell Charles) Toedt III  *(my** last name is pronounced "Tate") *
Attorney and neutral arbitrator -- tech contracts and intellectual property
Lecturer, University of Houston Law Center
​Editor, ​​​Common Draft <http://www.commondraft.org/> project:  A readable
library of best-practices contract clauses,
     with extensive citations and commentary, updated often.
dc@toedt.com     LinkedIn: dctoedt <http://www.linkedin.com/in/dctoedt>
Calendar
<https://www.google.com/calendar/embed?src=dc.toedt@toedt.com&mode=WEEK>
(redacted)
O: +1 (713) 364-6545    C: +1 (713) 516-8968
​​

​
Houston, Texas (Central time zone)

Unless expressly stated otherwise, this message is not intended
to serve as an electronic signature nor as assent to an agreement.



On Mon, Oct 20, 2014 at 8:41 AM, Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> Hello,
>
> "D. C. Toedt" <dc@toedt.com> writes:
>
> > I'd like to do sub-TOCs for individual sections and subsections.
>
> We could add a "local" keyword to TOC lines, e.g.,
>
>   #+TOC: headlines 1 local
>
> would mean only top level children in current headline.
>
> This feature is trivial to add to ox-ascii, probably easy for ox-html or
> ox-odt, assuming someone can provide the expected code.
>
> Implementing it in ox-latex probably boils down to requiring another
> package (minitoc?).
>
> WDYT?
>
>
> Regards,
>
> --
> Nicolas Goaziou
>

[-- Attachment #2: Type: text/html, Size: 5234 bytes --]

Re: Table of contents for just one section?

[Nicolas Goaziou]

[-- Attachment #1: Type: text/plain, Size: 286 bytes --]

Hello,

"D. C. Toedt" <dc@toedt.com> writes:

> The local keyword would be great.

The following patch implements local tocs for ascii, html and odt export
back-ends. I skipped latex because using minitoc looks too tricky to
automate.

Feedback welcome.


Regards,

-- 
Nicolas Goaziou

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ox-Implement-local-table-of-contents.patch --]
[-- Type: text/x-diff, Size: 13308 bytes --]

From 56e720f11c172b16a72fb1ddb9ad78405361646d Mon Sep 17 00:00:00 2001
From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Date: Sat, 25 Oct 2014 17:14:34 +0200
Subject: [PATCH] ox: Implement local table of contents

* lisp/ox.el (org-export-collect-headlines): Allow to collect
  headlines locally.
* testing/lisp/test-ox.el (test-org-export/collect-headlines): Add
  tests.

* lisp/ox-ascii.el (org-ascii--build-toc):
(org-ascii-keyword):
* lisp/ox-html.el (org-html-toc):
(org-html-keyword):
* lisp/ox-latex.el (org-latex-keyword):
* lisp/ox-odt.el (org-odt-toc): Allow local table of contents.
---
 lisp/ox-ascii.el        | 33 +++++++++++++++++----------------
 lisp/ox-html.el         | 21 +++++++++++----------
 lisp/ox-latex.el        | 16 +++++++---------
 lisp/ox-odt.el          | 35 ++++++++++++++++++-----------------
 lisp/ox.el              | 31 ++++++++++++++++++++++---------
 testing/lisp/test-ox.el | 14 +++++++++++++-
 6 files changed, 88 insertions(+), 62 deletions(-)

diff --git a/lisp/ox-ascii.el b/lisp/ox-ascii.el
index daad00f..ff0a5f4 100644
--- a/lisp/ox-ascii.el
+++ b/lisp/ox-ascii.el
@@ -744,7 +744,7 @@ caption keyword."
 		 (org-export-data caption info))
 	 (org-ascii--current-text-width element info) info)))))
 
-(defun org-ascii--build-toc (info &optional n keyword)
+(defun org-ascii--build-toc (info &optional n keyword local)
   "Return a table of contents.
 
 INFO is a plist used as a communication channel.
@@ -753,7 +753,10 @@ Optional argument N, when non-nil, is an integer specifying the
 depth of the table.
 
 Optional argument KEYWORD specifies the TOC keyword, if any, from
-which the table of contents generation has been initiated."
+which the table of contents generation has been initiated.
+
+When optional argument LOCAL is non-nil, build a table of
+contents according to the current headline."
   (let ((title (org-ascii--translate "Table of Contents" info)))
     (concat
      title "\n"
@@ -775,7 +778,7 @@ which the table of contents generation has been initiated."
 	      (or (not (plist-get info :with-tags))
 		  (eq (plist-get info :with-tags) 'not-in-toc))
 	      'toc))))
-	(org-export-collect-headlines info n) "\n")))))
+	(org-export-collect-headlines info n keyword) "\n")))))
 
 (defun org-ascii--list-listings (keyword info)
   "Return a list of listings.
@@ -1452,24 +1455,22 @@ contextual information."
   "Transcode a KEYWORD element from Org to ASCII.
 CONTENTS is nil.  INFO is a plist holding contextual
 information."
-  (let ((key (org-element-property :key keyword)))
+  (let ((key (org-element-property :key keyword))
+	(value (org-element-property :value keyword)))
     (cond
-     ((string= key "ASCII")
-      (org-ascii--justify-element
-       (org-element-property :value keyword) keyword info))
+     ((string= key "ASCII") (org-ascii--justify-element value keyword info))
      ((string= key "TOC")
       (org-ascii--justify-element
-       (let ((value (downcase (org-element-property :value keyword))))
+       (let ((case-fold-search t))
 	 (cond
-	  ((string-match "\\<headlines\\>" value)
-	   (let ((depth (or (and (string-match "[0-9]+" value)
-				 (string-to-number (match-string 0 value)))
-			    (plist-get info :with-toc))))
-	     (org-ascii--build-toc
-	      info (and (wholenump depth) depth) keyword)))
-	  ((string= "tables" value)
+	  ((org-string-match-p "\\<headlines\\>" value)
+	   (let ((depth (and (string-match "\\<[0-9]+\\>" value)
+			     (string-to-number (match-string 0 value))))
+		 (localp (org-string-match-p "\\<local\\>" value)))
+	     (org-ascii--build-toc info depth keyword localp)))
+	  ((org-string-match-p "\\<tables\\>" value)
 	   (org-ascii--list-tables keyword info))
-	  ((string= "listings" value)
+	  ((org-string-match-p "\\<listings\\>" value)
 	   (org-ascii--list-listings keyword info))))
        keyword info)))))
 
diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index c2152d9..276cb67 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -2017,16 +2017,17 @@ a plist used as a communication channel."
 \f
 ;;; Tables of Contents
 
-(defun org-html-toc (depth info)
+(defun org-html-toc (depth info &optional scope)
   "Build a table of contents.
-DEPTH is an integer specifying the depth of the table.  INFO is a
-plist used as a communication channel.  Return the table of
-contents as a string, or nil if it is empty."
+DEPTH is an integer specifying the depth of the table.  INFO is
+a plist used as a communication channel.  Optional argument SCOPE
+is an element defining the scope of the table.  Return the table
+of contents as a string, or nil if it is empty."
   (let ((toc-entries
 	 (mapcar (lambda (headline)
 		   (cons (org-html--format-toc-headline headline info)
 			 (org-export-get-relative-level headline info)))
-		 (org-export-collect-headlines info depth)))
+		 (org-export-collect-headlines info depth scope)))
 	(outer-tag (if (and (org-html-html5-p info)
 			    (plist-get info :html-html5-fancy))
 		       "nav"
@@ -2539,13 +2540,13 @@ CONTENTS is nil.  INFO is a plist holding contextual information."
     (cond
      ((string= key "HTML") value)
      ((string= key "TOC")
-      (let ((value (downcase value)))
+      (let ((case-fold-search t))
 	(cond
 	 ((string-match "\\<headlines\\>" value)
-	  (let ((depth (or (and (string-match "[0-9]+" value)
-				(string-to-number (match-string 0 value)))
-			   (plist-get info :with-toc))))
-	    (org-html-toc depth info)))
+	  (let ((depth (and (string-match "\\<[0-9]+\\>" value)
+			    (string-to-number (match-string 0 value))))
+		(localp (org-string-match-p "\\<local\\>" value)))
+	    (org-html-toc depth info (and localp keyword))))
 	 ((string= "listings" value) (org-html-list-of-listings info))
 	 ((string= "tables" value) (org-html-list-of-tables info))))))))
 
diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
index 501648d..2010cc1 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -1755,18 +1755,16 @@ CONTENTS is nil.  INFO is a plist holding contextual information."
      ((string= key "LATEX") value)
      ((string= key "INDEX") (format "\\index{%s}" value))
      ((string= key "TOC")
-      (let ((value (downcase value)))
+      (let ((case-fold-search t))
 	(cond
-	 ((string-match "\\<headlines\\>" value)
-	  (let ((depth (or (and (string-match "[0-9]+" value)
-				(string-to-number (match-string 0 value)))
-			   (plist-get info :with-toc))))
+	 ((org-string-match-p "\\<headlines\\>" value)
+	  (let ((depth (and (string-match "\\<[0-9]+\\>" value)
+			    (string-to-number (match-string 0 value)))))
 	    (concat
-	     (when (wholenump depth)
-	       (format "\\setcounter{tocdepth}{%s}\n" depth))
+	     (when depth (format "\\setcounter{tocdepth}{%s}\n" depth))
 	     "\\tableofcontents")))
-	 ((string= "tables" value) "\\listoftables")
-	 ((string= "listings" value)
+	 ((org-string-match-p "\\<tables\\>" value) "\\listoftables")
+	 ((org-string-match-p "\\<listings\\>" value)
 	  (case (plist-get info :latex-listings)
 	    ((nil) "\\listoffigures")
 	    (minted "\\listoflistings")
diff --git a/lisp/ox-odt.el b/lisp/ox-odt.el
index cc156ff..fb7be31 100644
--- a/lisp/ox-odt.el
+++ b/lisp/ox-odt.el
@@ -1149,7 +1149,12 @@ See `org-odt--build-date-styles' for implementation details."
   (format "<text:a xlink:type=\"simple\" xlink:href=\"#%s\">%s</text:a>"
 	  headline-label text))
 
-(defun org-odt-toc (depth info)
+(defun org-odt-toc (depth info &optional scope)
+  "Build a table of contents.
+DEPTH is an integer specifying the depth of the table.  INFO is
+a plist containing current export properties.  Optional argument
+SCOPE, when non-nil, defines the scope of the table.  Return the
+table of contents as a string, or nil."
   (assert (wholenump depth))
   ;; When a headline is marked as a radio target, as in the example below:
   ;;
@@ -1161,18 +1166,12 @@ See `org-odt--build-date-styles' for implementation details."
   ;; /TOC/, as otherwise there will be duplicated anchors one in TOC
   ;; and one in the document body.
   ;;
-  ;; FIXME-1: Currently exported headings are memoized.  `org-export.el'
-  ;; doesn't provide a way to disable memoization.  So this doesn't
-  ;; work.
-  ;;
-  ;; FIXME-2: Are there any other objects that need to be suppressed
+  ;; FIXME: Are there any other objects that need to be suppressed
   ;; within TOC?
   (let* ((title (org-export-translate "Table of Contents" :utf-8 info))
-	 (headlines (org-export-collect-headlines
-		     info (and (wholenump depth) depth)))
+	 (headlines (org-export-collect-headlines info depth local))
 	 (backend (org-export-create-backend
-		   :parent (org-export-backend-name
-			    (plist-get info :back-end))
+		   :parent (org-export-backend-name (plist-get info :back-end))
 		   :transcoders (mapcar
 				 (lambda (type) (cons type (lambda (d c i) c)))
 				 (list 'radio-target)))))
@@ -2013,7 +2012,8 @@ contextual information."
 
 (defun org-odt-keyword (keyword contents info)
   "Transcode a KEYWORD element from Org to ODT.
-CONTENTS is nil.  INFO is a plist holding contextual information."
+CONTENTS is nil.  INFO is a plist holding contextual
+information."
   (let ((key (org-element-property :key keyword))
 	(value (org-element-property :value keyword)))
     (cond
@@ -2022,14 +2022,15 @@ CONTENTS is nil.  INFO is a plist holding contextual information."
       ;; FIXME
       (ignore))
      ((string= key "TOC")
-      (let ((value (downcase value)))
+      (let ((case-fold-search t))
 	(cond
-	 ((string-match "\\<headlines\\>" value)
-	  (let ((depth (or (and (string-match "[0-9]+" value)
+	 ((org-string-match-p "\\<headlines\\>" value)
+	  (let ((depth (or (and (string-match "\\<[0-9]+\\>" value)
 				(string-to-number (match-string 0 value)))
-			   (plist-get info :with-toc))))
-	    (when (wholenump depth) (org-odt-toc depth info))))
-	 ((member value '("tables" "figures" "listings"))
+			   (plist-get info :headline-levels)))
+		(localp (org-string-match-p "\\<local\\>" value)))
+	    (org-odt-toc depth info (and localp keyword))))
+	 ((org-string-match-p "tables\\|figures\\|listings" value)
 	  ;; FIXME
 	  (ignore))))))))
 
diff --git a/lisp/ox.el b/lisp/ox.el
index f018497..317a0ad 100644
--- a/lisp/ox.el
+++ b/lisp/ox.el
@@ -4774,7 +4774,7 @@ return nil."
 ;; `org-export-collect-tables', `org-export-collect-figures' and
 ;; `org-export-collect-listings' can be derived from it.
 
-(defun org-export-collect-headlines (info &optional n)
+(defun org-export-collect-headlines (info &optional n scope)
   "Collect headlines in order to build a table of contents.
 
 INFO is a plist used as a communication channel.
@@ -4784,15 +4784,28 @@ the table of contents.  Otherwise, it is set to the value of the
 last headline level.  See `org-export-headline-levels' for more
 information.
 
+Optional argument SCOPE, when non-nil, is an element.  If it is
+a headline, only children of SCOPE are collected.  Otherwise,
+collect children of the headline containing provided element.  If
+there is no such headline, collect all headlines.  In any case,
+argument N becomes relative to the level of that headline.
+
 Return a list of all exportable headlines as parsed elements.
-Footnote sections, if any, will be ignored."
-  (let ((limit (plist-get info :headline-levels)))
-    (setq n (if (wholenump n) (min n limit) limit))
-    (org-element-map (plist-get info :parse-tree) 'headline
-      #'(lambda (headline)
-	  (unless (org-element-property :footnote-section-p headline)
-	    (let ((level (org-export-get-relative-level headline info)))
-	      (and (<= level n) headline))))
+Footnote sections are ignored."
+  (let* ((scope (cond ((not scope) (plist-get info :parse-tree))
+		      ((eq (org-element-type scope) 'headline) scope)
+		      ((org-export-get-parent-headline scope))
+		      (t (plist-get info :parse-tree))))
+	 (limit (plist-get info :headline-levels))
+	 (n (if (not (wholenump n)) limit
+	      (min (if (eq (org-element-type scope) 'org-data) n
+		     (+ (org-export-get-relative-level scope info) n))
+		   limit))))
+    (org-element-map (org-element-contents scope) 'headline
+      (lambda (headline)
+	(unless (org-element-property :footnote-section-p headline)
+	  (let ((level (org-export-get-relative-level headline info)))
+	    (and (<= level n) headline))))
       info)))
 
 (defun org-export-collect-elements (type info &optional predicate)
diff --git a/testing/lisp/test-ox.el b/testing/lisp/test-ox.el
index 9a0e787..e74220c 100644
--- a/testing/lisp/test-ox.el
+++ b/testing/lisp/test-ox.el
@@ -3075,7 +3075,19 @@ Another text. (ref:text)
    (= 1
       (length
        (org-test-with-parsed-data "#+OPTIONS: H:1\n* H1\n** H2"
-	 (org-export-collect-headlines info 2))))))
+	 (org-export-collect-headlines info 2)))))
+  ;; Collect headlines locally.
+  (should
+   (= 2
+      (org-test-with-parsed-data "* H1\n** H2\n** H3"
+	(let ((scope (org-element-map tree 'headline #'identity info t)))
+	  (length (org-export-collect-headlines info nil scope))))))
+  ;; When collecting locally, optional level is relative.
+  (should
+   (= 1
+      (org-test-with-parsed-data "* H1\n** H2\n*** H3"
+	(let ((scope (org-element-map tree 'headline #'identity info t)))
+	  (length (org-export-collect-headlines info 1 scope)))))))
 
 
 \f
-- 
2.1.2

Re: Table of contents for just one section?

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> "D. C. Toedt" <dc@toedt.com> writes:
>
>> I'd like to do sub-TOCs for individual sections and subsections.
>
> We could add a "local" keyword to TOC lines, e.g.,
>
>   #+TOC: headlines 1 local
>
> would mean only top level children in current headline.
>
> This feature is trivial to add to ox-ascii, probably easy for ox-html or
> ox-odt, assuming someone can provide the expected code.
>
> Implementing it in ox-latex probably boils down to requiring another
> package (minitoc?).

I'm pretty sure you need an exernal package.  titletoc or minitoc.  At
least memoir seems to have issues with minitoc.  KOMA-Script seems to
be ok.  titletoc scores points for having a 24 pages manual, versus
800+ pages.  Personally, I don't like the default style of minitoc.

> WDYT?

It's neat and I'd probably never use it.

—Rasmus

-- 
Hooray!

Re: Table of contents for just one section?

[D. C. Toedt]

[-- Attachment #1: Type: text/plain, Size: 1272 bytes --]

Many thanks!  I'll wait till this shows up in the package updater (I've
toyed with Git only enough to be dangerous) but am eagerly looking forward
to trying it.



D. C. (Dell Charles) Toedt III  *(my** last name is pronounced "Tate") *
Attorney and neutral arbitrator -- tech contracts and intellectual property
Lecturer, University of Houston Law Center
​Editor, ​​​Common Draft <http://www.commondraft.org/> contract form file
dc@toedt.com     LinkedIn: dctoedt <http://www.linkedin.com/in/dctoedt>
Calendar
<https://www.google.com/calendar/embed?src=dc.toedt@toedt.com&mode=WEEK>
(redacted)
O: +1 (713) 364-6545    C: +1 (713) 516-8968
​​

​
Houston, Texas (Central time zone)

Unless expressly stated otherwise, this message is not intended
to serve as an electronic signature nor as assent to an agreement.



On Sun, Oct 26, 2014 at 3:15 AM, Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> Hello,
>
> "D. C. Toedt" <dc@toedt.com> writes:
>
> > The local keyword would be great.
>
> The following patch implements local tocs for ascii, html and odt export
> back-ends. I skipped latex because using minitoc looks too tricky to
> automate.
>
> Feedback welcome.
>
>
> Regards,
>
> --
> Nicolas Goaziou
>

[-- Attachment #2: Type: text/html, Size: 4503 bytes --]

Re: Table of contents for just one section?

[Rasmus]

Hi,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> I skipped latex because using minitoc looks too tricky to
> automate.

Sorry, I didn't see this when I posted my other post.

I think we can do it with titletoc.  I have used other functionality
of titletoc, and it 'doesn't sucks'ᵀᴹ.  Below is an example.  The
output is more inline with normal tocs, but you can also style it
[I've used this for making paragraph-TOCs in the past].

So ox-latex needs to insert at least the following to initialize a
local TOC

   \startcontents[ID-level] % need not be unique and might not be neceasary
   \printcontents[ID-level]{}{(1+ level)}{TOC OPTIONS}

And, importantly — and mildely annoyingly — \startcontents[ID] *after*
the next heading of the same level.  There are some preamble options,
but since we are doing it programically, it might be safer to insert
it into the body.

It seems it need not be same unique ID.

An example:

    \documentclass{book}
    \usepackage{titletoc}
    \begin{document}
    \part{p1}
    \startcontents[level-0]
    \printcontents[level-0]{}{0}{\setcounter{tocdepth}{2}}
    \chapter{c1}
    \startcontents[level-1]
    \printcontents[level-1]{}{1}{\setcounter{tocdepth}{1}}
    \section{s1} \subsection{s2}
    \chapter{c2}
    \startcontents[level-1]
    \section{s3}
    \part{p2}
    \startcontents[level-0]
    \chapter{c3}
    \end{document}

The only "challenge" is to insert \startcontents[ID] in the next
headline of same level.  The brute force method would be very bad.
Maybe doing it like section numbers are determined?

Let me know what you think and whether you will do it.

—Rasmus

-- 
What will be next?

Re: Table of contents for just one section?

[Nicolas Goaziou]

Hello,

Rasmus <rasmus@gmx.us> writes:

> I think we can do it with titletoc.  I have used other functionality
> of titletoc, and it 'doesn't sucks'ᵀᴹ.  Below is an example.  The
> output is more inline with normal tocs, but you can also style it
> [I've used this for making paragraph-TOCs in the past].
>
> So ox-latex needs to insert at least the following to initialize a
> local TOC
>
>    \startcontents[ID-level] % need not be unique and might not be neceasary
>    \printcontents[ID-level]{}{(1+ level)}{TOC OPTIONS}
>
> And, importantly — and mildely annoyingly — \startcontents[ID] *after*
> the next heading of the same level.

I don't quite get this part. Does that string need to be inserted only
after the second sibling (i.e., not after the third, too)? What happens
if there is no other sibling?

> There are some preamble options, but since we are doing it
> programically, it might be safer to insert it into the body.

The patch will not insert "\usepackage{titletoc}" for the user, however,
à la `org-latex-listings'.

> It seems it need not be same unique ID.
>
> An example:
>
>     \documentclass{book}
>     \usepackage{titletoc}
>     \begin{document}
>     \part{p1}
>     \startcontents[level-0]
>     \printcontents[level-0]{}{0}{\setcounter{tocdepth}{2}}
>     \chapter{c1}
>     \startcontents[level-1]
>     \printcontents[level-1]{}{1}{\setcounter{tocdepth}{1}}
>     \section{s1} \subsection{s2}
>     \chapter{c2}
>     \startcontents[level-1]
>     \section{s3}
>     \part{p2}
>     \startcontents[level-0]
>     \chapter{c3}
>     \end{document}
>
> The only "challenge" is to insert \startcontents[ID] in the next
> headline of same level.  The brute force method would be very bad.

What do you call the "brute force"?

> Maybe doing it like section numbers are determined?

What do you mean?

> Let me know what you think and whether you will do it.

I can try to implement it.

I also note that these tocs do not have any title. Would it make sense
to remove title from local tocs in other back-ends too?

Thanks for your feedback.


Regards,

-- 
Nicolas Goaziou

Re: Table of contents for just one section?

[Rasmus]

Hi,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Rasmus <rasmus@gmx.us> writes:
>
>> I think we can do it with titletoc.  I have used other functionality
>> of titletoc, and it 'doesn't sucks'ᵀᴹ.  Below is an example.  The
>> output is more inline with normal tocs, but you can also style it
>> [I've used this for making paragraph-TOCs in the past].
>>
>> So ox-latex needs to insert at least the following to initialize a
>> local TOC
>>
>>    \startcontents[ID-level] % need not be unique and might not be neceasary
>>    \printcontents[ID-level]{}{(1+ level)}{TOC OPTIONS}
>>
>> And, importantly — and mildely annoyingly — \startcontents[ID] *after*
>> the next heading of the same level.
>
> I don't quite get this part. Does that string need to be inserted only
> after the second sibling (i.e., not after the third, too)? What happens
> if there is no other sibling?

Ah, it's much easier to use \stopcontents[level-i] to end contents
collection.  Revising the example:

     \documentclass{book}
     \usepackage{titletoc}
     \begin{document}
     \part{p1}
     \startcontents[level-0]
     \printcontents[level-0]{}{0}{\setcounter{tocdepth}{2}}
     \chapter{c1}
     \startcontents[level-1]
     \printcontents[level-1]{}{1}{\setcounter{tocdepth}{1}}
     \section{s1} \subsection{s2}
     \stopcontents[level-1]
     \chapter{c2}
     \section{s3}
     \stopcontents[level-0]
     \part{p2}\chapter{c3}
     \end{document}

Note that the contents is determined by the .pcf file.  Maybe that's
easier to to understand than my babeling.  Also, "pcf" should be added
to `org-latex-logfiles-extensions'.

>> There are some preamble options, but since we are doing it
>> programically, it might be safer to insert it into the body.
>
> The patch will not insert "\usepackage{titletoc}" for the user, however,
> à la `org-latex-listings'.

Great.

> What do you call the "brute force"?

I meant to insert \startcontents[ID-level] after each, say, chapter
unconditionally rather than inserterting as few
\startcontents[ID-level] as possible.  But ignore that:
\stopcontents[ID-level] it's much cleaner.

>> Let me know what you think and whether you will do it.
>
> I can try to implement it.
>
> I also note that these tocs do not have any title. Would it make sense
> to remove title from local tocs in other back-ends too?

No idea.  Both makes sense, but maybe including the TOC-title is too
verbose?  In any case, I think it's easy to add a title if you.  Based
on article.cls and book.cls, I think we can generalize the toc-title
to "heading one level down in level and unnumbered with title
\contentsname".  The TOC title for chapter is thus
\section*{\contentsname}.  For \part it's \chapter*{\contentsname}.  I
guess you can use the cdr in level part of `org-latex-classes', though
it would be incompatible with e.g. \addsec{·} of KOMA-Script.

—Rasmus

Article.cls:

\newcommand\tableofcontents{%
    \section*{\contentsname
        \@mkboth{%
           \MakeUppercase\contentsname}{\MakeUppercase\contentsname}}%
    \@starttoc{toc}%
    }

Book.cls:

\newcommand\tableofcontents{%
    \if@twocolumn
      \@restonecoltrue\onecolumn
    \else
      \@restonecolfalse
    \fi
    \chapter*{\contentsname
        \@mkboth{%
           \MakeUppercase\contentsname}{\MakeUppercase\contentsname}}%
    \@starttoc{toc}%
    \if@restonecol\twocolumn\fi
    }

—Rasmus

-- 
And I faced endless streams of vendor-approved Ikea furniture. . .

Re: Table of contents for just one section?

[Rasmus]

Rasmus <rasmus@gmx.us> writes:

>> I also note that these tocs do not have any title. Would it make sense
>> to remove title from local tocs in other back-ends too?
>
> No idea.  Both makes sense, but maybe including the TOC-title is too
> verbose?  In any case, I think it's easy to add a title if you.  Based
> on article.cls and book.cls, I think we can generalize the toc-title
> to "heading one level down in level and unnumbered with title
> \contentsname".  The TOC title for chapter is thus
> \section*{\contentsname}.  For \part it's \chapter*{\contentsname}.  I
> guess you can use the cdr in level part of `org-latex-classes', though
> it would be incompatible with e.g. \addsec{·} of KOMA-Script.

To be clear for chapters the command would be:

    \printcontents[level-1]{}{0}{\setcounter{tocdepth}{1}%
        \section*{\contentsname}}

-- 
C is for Cookie

Re: Table of contents for just one section?

[Nicolas Goaziou]

Hello,

Rasmus <rasmus@gmx.us> writes:

> Ah, it's much easier to use \stopcontents[level-i] to end contents
> collection.  Revising the example:
>
>      \documentclass{book}
>      \usepackage{titletoc}
>      \begin{document}
>      \part{p1}
>      \startcontents[level-0]
>      \printcontents[level-0]{}{0}{\setcounter{tocdepth}{2}}
>      \chapter{c1}
>      \startcontents[level-1]
>      \printcontents[level-1]{}{1}{\setcounter{tocdepth}{1}}
>      \section{s1} \subsection{s2}
>      \stopcontents[level-1]
>      \chapter{c2}
>      \section{s3}
>      \stopcontents[level-0]
>      \part{p2}\chapter{c3}
>      \end{document}
>
> Note that the contents is determined by the .pcf file.  Maybe that's
> easier to to understand than my babeling.  Also, "pcf" should be added
> to `org-latex-logfiles-extensions'.

Done.

> No idea.  Both makes sense, but maybe including the TOC-title is too
> verbose?

Local TOC have no title.


Regards,

-- 
Nicolas Goaziou

Re: Table of contents for just one section?

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Rasmus <rasmus@gmx.us> writes:
>
>> Ah, it's much easier to use \stopcontents[level-i] to end contents
>> collection.  Revising the example:
>>
>>      \documentclass{book}
>>      \usepackage{titletoc}
>>      \begin{document}
>>      \part{p1}
>>      \startcontents[level-0]
>>      \printcontents[level-0]{}{0}{\setcounter{tocdepth}{2}}
>>      \chapter{c1}
>>      \startcontents[level-1]
>>      \printcontents[level-1]{}{1}{\setcounter{tocdepth}{1}}
>>      \section{s1} \subsection{s2}
>>      \stopcontents[level-1]
>>      \chapter{c2}
>>      \section{s3}
>>      \stopcontents[level-0]
>>      \part{p2}\chapter{c3}
>>      \end{document}
>>
>> Note that the contents is determined by the .pcf file.  Maybe that's
>> easier to to understand than my babeling.  Also, "pcf" should be
>> added
>> to `org-latex-logfiles-extensions'.
>
> Done.

That looks cool!  Thanks!

One more thing.  For LaTeX, *we must load titletoc before hyperref*.

E.g. cf. here:

    http://tex.stackexchange.com/questions/79547/weird-behavior-of-partial-toc-with-titletoc

Or just try this document:

#+LATEX_HEADER: \usepackage{titletoc}
* section 1
  #+TOC: headlines 1 local
** sub 1

Which produces (in LaTeX):

    [full-TOC]
    1. SECTION 1
    section.1 ← artifact from loading after hyperref
    [sub-toc]
    1.1 SUB 1

* Solutions 

1. We could use org-latex-packages-alist but that's another forced
   dependency; ugh!

2. Alternatively, we could ensure that hyperref is always loaded last
   which is the almost-always safe rule of thumb rule anyway¹.  Since we
   already have org-latex-hyperref-template we could drop hyperref from
   org-latex-packages-alist and make its presence implicit based on that
   variable.

3. Or we can add to the manual this deficit and advice how to solve it "manually".

4. It's also possible to solve it on the LaTeX side with something like
   \BeforePackage from KOMA-Script.  Again, more dependencies.

5. We could provide placement mechanisms to #+LATEX_HEADER-keywords 

Of these I think 2. or 1. are the acceptable solutions.  1. is easier, but
as adds more dependencies which sucks.  So I prefer 2.

WDYT?

—Rasmus

Footnotes: 
¹  Exceptions, including some notable ones (it's a mess):
     http://tex.stackexchange.com/questions/1863/which-packages-should-be-loaded-after-hyperref-instead-of-before

-- 
A page of history is worth a volume of logic

Re: Table of contents for just one section?

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

> One more thing.  For LaTeX, *we must load titletoc before hyperref*.

Requiring packages is not our problem.

> 3. Or we can add to the manual this deficit and advice how to solve it
> "manually".

I don't mind updating the footnote relative to titletoc package in the
manual. Do you want to provide a patch?

Regards,

Re: Table of contents for just one section?

[Rasmus]

Hi,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

>> One more thing.  For LaTeX, *we must load titletoc before hyperref*.
>
> Requiring packages is not our problem.

For titletoc, you can only enable it by either

    1. adding a new org-latex-class
    2. insert titletoc in org-latex-default-packages-alist manually.
       org-latex-packages-alist won't work as it's inserted later.
       
This seems like a problem to me.  [I'm sure there also exits a clever
filter that can do it].

>> 3. Or we can add to the manual this deficit and advice how to solve it
>> "manually".
>
> I don't mind updating the footnote relative to titletoc package in the
> manual. Do you want to provide a patch?

I can add documentation, but please reconfirm that you find the above
limitations acceptable and want to see suggestions of modifying
org-latex-packages-alist in the manual!

—Rasmus

-- 
m-mm-mmm-mmmm bacon!

Re: Table of contents for just one section?

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

> I can add documentation, but please reconfirm that you find the above
> limitations acceptable and want to see suggestions of modifying
> org-latex-packages-alist in the manual!

AFAIU, this is the only solution since we do not support titletoc in
core. The modification is pretty trivial, too.


Regards,

Re: Table of contents for just one section?

[Rasmus]

Hi,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> AFAIU, this is the only solution since we do not support titletoc in
> core. 

As said, I'd prefer load hyperref via org-latex-hyperref-template, but
it's probably too big a change too late.  Though, it would resolve the
"issue" that if I do

   (setq org-latex-default-packages-alist
         (delete '("" "hyperref" nil)
                 org-latex-default-packages-alist))

Hypersetup is still inserted.

> The modification is pretty trivial, too.

Of course, but isn't it contradicting the docstring of
org-latex-default-packages-alist?

> Therefore you should not modify this variable unless you know what you
> are doing.

Unless I've managed to convenience you otherwise I will add a footnote
explaining and recommending the following snippet

(with-eval-after-load 'ox-latex
  (require 'cl)
  (let* ((packages (mapcar (lambda (elt) (and (listp elt) (nth 1 elt)))
                           org-latex-default-packages-alist))
         (pos (position "hyperref" packages :test 'equal))
         (titletocp (member "titletoc" packages)))
    (when (and pos (not titletocp))
      (push '("" "titletoc" nil)
            (nthcdr pos org-latex-default-packages-alist)))))


Cheers,
Rasmus

-- 
. . . The proofs are technical in nature and provides no real
understanding

Re: Table of contents for just one section?

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

> As said, I'd prefer load hyperref via org-latex-hyperref-template, but
> it's probably too big a change too late.  Though, it would resolve the
> "issue" that if I do
>
>    (setq org-latex-default-packages-alist
>          (delete '("" "hyperref" nil)
>                  org-latex-default-packages-alist))
>
> Hypersetup is still inserted.

The issue is not to remove hyperref, which is a default package for
a good reason. The problem is to require titletoc before hyperref.

IOW, this is orthogonal to the problem at hand.

> Of course, but isn't it contradicting the docstring of
> org-latex-default-packages-alist?

No it isn't. It is a defcustom after all, and the manual can ensure the
user knows what he is doing.

> Unless I've managed to convenience you otherwise I will add a footnote
> explaining and recommending the following snippet
>
> (with-eval-after-load 'ox-latex
>   (require 'cl)
>   (let* ((packages (mapcar (lambda (elt) (and (listp elt) (nth 1 elt)))
>                            org-latex-default-packages-alist))
>          (pos (position "hyperref" packages :test 'equal))
>          (titletocp (member "titletoc" packages)))
>     (when (and pos (not titletocp))
>       (push '("" "titletoc" nil)
>             (nthcdr pos org-latex-default-packages-alist)))))

It is way too opaque IMO. Suggesting to put ("" "titletoc" nil) before
("" hyperref nil) should be enough.

Regards,

Re: Table of contents for just one section?

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Rasmus <rasmus@gmx.us> writes:
>
>> As said, I'd prefer load hyperref via org-latex-hyperref-template, but
>> it's probably too big a change too late.  Though, it would resolve the
>> "issue" that if I do
>>
>>    (setq org-latex-default-packages-alist
>>          (delete '("" "hyperref" nil)
>>                  org-latex-default-packages-alist))
>>
>> Hypersetup is still inserted.
>
> The issue is not to remove hyperref, which is a default package for
> a good reason. The problem is to require titletoc before hyperref.

I was putting this to further support another solution, namely moving
hyperref to a single defcustom, allowing hyperref to be inserted after all
other header-lines.

> IOW, this is orthogonal to the problem at hand.

I disagree.

>> Unless I've managed to convenience you otherwise I will add a footnote
>> explaining and recommending the following snippet
>>
>> (with-eval-after-load 'ox-latex
>>   (require 'cl)
>>   (let* ((packages (mapcar (lambda (elt) (and (listp elt) (nth 1 elt)))
>>                            org-latex-default-packages-alist))
>>          (pos (position "hyperref" packages :test 'equal))
>>          (titletocp (member "titletoc" packages)))
>>     (when (and pos (not titletocp))
>>       (push '("" "titletoc" nil)
>>             (nthcdr pos org-latex-default-packages-alist)))))
>
> It is way too opaque IMO. Suggesting to put ("" "titletoc" nil) before
> ("" hyperref nil) should be enough.

That's what it does...  But without the need of having a direct copy of
org-latex-default-packages-alist in your init.el.  I'm not suggesting to
put the snippet there without any prose.

—Rasmus

-- 
When in doubt, do it!

Re: Table of contents for just one section?

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

> I was putting this to further support another solution, namely moving
> hyperref to a single defcustom, allowing hyperref to be inserted after all
> other header-lines.

As you pointed out already, moving hyperref after all other header lines
introduces problems with another set of packages. Therefore, we could
end up with package combinations that this variable couldn't handle.

> That's what it does...  But without the need of having a direct copy of
> org-latex-default-packages-alist in your init.el.  I'm not suggesting to
> put the snippet there without any prose.

`org-latex-default-packages-alist' can be customized, and customization
allows to easily add "titletoc" before "hyperref". No need to rely on
this confusing snippet.


Regards,

Re: Table of contents for just one section?

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Rasmus <rasmus@gmx.us> writes:
>
>> I was putting this to further support another solution, namely moving
>> hyperref to a single defcustom, allowing hyperref to be inserted after all
>> other header-lines.
>
> As you pointed out already, moving hyperref after all other header lines
> introduces problems with another set of packages. Therefore, we could
> end up with package combinations that this variable couldn't handle.

Of which we do not rely at the moment.  From a user POW it's easy to load
stuff at the end of the preamble e.g. using scrfile (\AfterPackage{}{}) or
etoolbox (\AtEndPreamble{}).

>> That's what it does...  But without the need of having a direct copy of
>> org-latex-default-packages-alist in your init.el.  I'm not suggesting to
>> put the snippet there without any prose.
>
> `org-latex-default-packages-alist' can be customized, and customization
> allows to easily add "titletoc" before "hyperref". No need to rely on
> this confusing snippet.

Which again will copy the current value into your init, potentially
ignoring future updates of the variable (say if we add or remove packages
at a later point).  [Correct me if I'm wrong].

Anyway, I edited the org.texi as we won't agreement.

—Rasmus

-- 
Tack, ni svenska vakttorn. Med plutonium tvingar vi dansken på knä!

Re: Table of contents for just one section?

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

>> As you pointed out already, moving hyperref after all other header lines
>> introduces problems with another set of packages. Therefore, we could
>> end up with package combinations that this variable couldn't handle.
>
> Of which we do not rely at the moment.

Of course, but I'm just pointing out that silently postponing the
problem is worse than admitting there is one and let the user sort it
out, with guidance.

We should really stay away from the LaTeX packages mess.

> From a user POW it's easy to load
> stuff at the end of the preamble e.g. using scrfile (\AfterPackage{}{}) or
> etoolbox (\AtEndPreamble{}).

For an intermediate LaTeX user, this is easy. It is also for an
intermediate Org user (e.g., who knows how to modify
`org-latex-classes'). For beginners in both topics, there is the
footnote in org.texi.

> Which again will copy the current value into your init, potentially
> ignoring future updates of the variable (say if we add or remove packages
> at a later point).  [Correct me if I'm wrong].

You're right. But I don't see why we should try to get around this
common issue specifically for this problem, even though it exists for
every defcustom.

There is :version keyword for this matter.

> Anyway, I edited the org.texi as we won't agreement.

Thank you.

I don't want to separate "hyperref" from
`org-latex-default-packages-alist' and treat it differently.

Regards,

Re: Table of contents for just one section?

[D. C. Toedt]

[-- Attachment #1: Type: text/plain, Size: 2580 bytes --]

I see this feature is now in the beta of Org-Mode 8.3.  Excellent!   I'm
doing several things with it in the forthcoming release of the Common Draft
contract clause library (linked below).

I also see that there now seems to be some reluctance by the maintainers to
accept donations. (See http://comments.gmane.org/gmane.emacs.orgmode/83318).
Has that been resolved?  I'd like to do a donation.




*D. C. Toedt III  **(I go by "D. C.," which stands for Dell Charles; my** last
name is pronounced "Tate") *
Attorney and neutral arbitrator -- tech contracts and intellectual property
​Editor, ​​​Common Draft <http://www.commondraft.org/> contract clauses and
templates, with research notes
Lecturer, University of Houston Law Center
dc@toedt.com     LinkedIn: dctoedt <http://www.linkedin.com/in/dctoedt>
Calendar
<https://www.google.com/calendar/embed?src=dc.toedt@toedt.com&mode=WEEK>
(redacted)
O: +1 (713) 364-6545    C: +1 (713) 516-8968
​​

​
Houston, Texas (Central time zone)

Unless expressly stated otherwise, this message is not intended
to serve as an electronic signature nor as assent to an agreement.



On Sun, Oct 26, 2014 at 6:03 AM, D. C. Toedt <dc@toedt.com> wrote:

> Many thanks!  I'll wait till this shows up in the package updater (I've
> toyed with Git only enough to be dangerous) but am eagerly looking forward
> to trying it.
>
>
>
> D. C. (Dell Charles) Toedt III  *(my** last name is pronounced "Tate") *
> Attorney and neutral arbitrator -- tech contracts and intellectual property
> Lecturer, University of Houston Law Center
> ​Editor, ​​​Common Draft <http://www.commondraft.org/> contract form file
> dc@toedt.com     LinkedIn: dctoedt <http://www.linkedin.com/in/dctoedt>
>   Calendar
> <https://www.google.com/calendar/embed?src=dc.toedt@toedt.com&mode=WEEK>
> (redacted)
> O: +1 (713) 364-6545    C: +1 (713) 516-8968
> ​​
>
> ​
> Houston, Texas (Central time zone)
>
> Unless expressly stated otherwise, this message is not intended
> to serve as an electronic signature nor as assent to an agreement.
>
>
>
> On Sun, Oct 26, 2014 at 3:15 AM, Nicolas Goaziou <mail@nicolasgoaziou.fr>
> wrote:
>
>> Hello,
>>
>> "D. C. Toedt" <dc@toedt.com> writes:
>>
>> > The local keyword would be great.
>>
>> The following patch implements local tocs for ascii, html and odt export
>> back-ends. I skipped latex because using minitoc looks too tricky to
>> automate.
>>
>> Feedback welcome.
>>
>>
>> Regards,
>>
>> --
>> Nicolas Goaziou
>>
>
>

[-- Attachment #2: Type: text/html, Size: 10102 bytes --]

Re: Table of contents for just one section?

[Rasmus]

Hi,

"D. C. Toedt" <dc@toedt.com> writes:

> I see this feature is now in the beta of Org-Mode 8.3.  Excellent!   I'm
> doing several things with it in the forthcoming release of the Common Draft
> contract clause library (linked below).
>
> I also see that there now seems to be some reluctance by the maintainers to
> accept donations. (See http://comments.gmane.org/gmane.emacs.orgmode/83318).
> Has that been resolved?  I'd like to do a donation.

Nicolas implemented the feature you are talking about.  You could get in
touch with him.

For general donations there's a button on the main Org site.

As to the discussion you cite, I don't know.

Hope it helps,
Rasmus

-- 
I feel emotional landscapes they puzzle me

Re: Table of contents for just one section?

[Thomas S. Dye]

Aloha D. C.,

"D. C. Toedt" <dc@toedt.com> writes:

> I also see that there now seems to be some reluctance by the maintainers to
> accept donations. (See http://comments.gmane.org/gmane.emacs.orgmode/83318).
> Has that been resolved?  I'd like to do a donation.

I think that was just Carsten's reluctance as he scaled back his Org
mode work.  So, yes, I believe it has been resolved.

All the best,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com