TOC local for specified heading and its subheadings (in HTML export)?

TOC local for specified heading and its subheadings (in HTML export)?

[D. C. Toedt]

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

The #+TOC: headlines [n] local feature is really useful; I use it a lot.
How easy would it be to do a macro to generate a similar table of contents
for the subheadings of an arbitrary specified heading?  That would be an
alternative to transclusion <https://en.wikipedia.org/wiki/Transclusion>,
allowing re-use of text but with links instead of the actual text.  For UX
purposes this will sometimes be preferable to actual transclusion, e.g.,
with Angular.js.  I'm not even a cargo-cult programmer in elisp and
wouldn't have the level of skill to do this myself without spending a lot
of time.

EXAMPLE:  In the Common Draft contract form file
<http://www.CommonDraft.org>, I'd like to add a Model Confidentiality
Agreement, a Model Software Development Agreement, a Model Consulting
Services Agreement, etc.  Each of these model agreements would include
several TOC-style lists of clauses under various other headings, as shown
in the following hypothetical file excerpt:

* Model Confidentiality Agreement
  :PROPERTIES:
  :CUSTOM_ID: ConfAgrmt
  :END:

** Parties; Effective Date

This Agreement is entered into as of November 27, 2015, between ABC Ltd.
and XYZ Inc.

** Confidential Information

# ============= The next line is the desired feature: Generate a TOC list
(with links) of all subheadings in the specified heading
=====================
#+TOC: headlines 1 local ConfInfoClauses

** Notices

#+TOC: headlines 1 local NoticesClauses

* Signatures

AGREED:

ABC Ltd, by:

[Signature block]


AGREED:

XYZ Inc., by:

[Signature block]


* Confidential Information Clauses
  :PROPERTIES:
  :CUSTOM_ID: ConfInfoClauses
  :END:

** Confidential Information Definition
  :PROPERTIES:
  :CUSTOM_ID: ConfInfoDefn
  :END:

[text of clause]

** Confidentiality Obligation
  :PROPERTIES:
  :CUSTOM_ID: ConfInfoOblig
  :END:

[text of clause]


* Notices Clauses
  :PROPERTIES:
  :CUSTOM_ID: NoticesClauses
  :END:

​** Notices Must Be in Writing
  :PROPERTIES:
  :CUSTOM_ID: NoticesWriting
  :END:
​
​[text of clause]

** Notices by Email
  :PROPERTIES:
  :CUSTOM_ID: NoticesEmail
  :END:
​
​[text of clause]​

​I'd be happy to make a donation for this.

​


D. C. Toedt III
*(My last name is pronounced "Tate")*
Attorney & arbitrator -- tech contracts & IP
Common Draft <http://www.CommonDraft.org> contract clauses & checklists,
annotated
O: +1 (713) 364-6545   C: +1 (713) 516-8968
​​

dc@toedt.com    @dctoedt <https://twitter.com/DCToedt>
www.OnContracts.com/About

Unless expressly stated otherwise,
this message is not intended to serve
as assent to an agreement or other document,
even if attached to this message.

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

Re: TOC local for specified heading and its subheadings (in HTML export)?

[Sacha Chua]

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

Hello, D. C., all!

> # ============= The next line is the desired feature: Generate a TOC list
> (with links) of all subheadings in the specified heading
> =====================
> #+TOC: headlines 1 local ConfInfoClauses

This is totally a partial implementation since I've only bothered to
make it work for HTML export, but someone can make it work nicely for
everything else. =)

I think it will permit the use of lines like:

#+TOC: headlines 1 id:ConfInfoClauses

diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index effd387..3b0e239 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -2651,8 +2651,18 @@ CONTENTS is nil.  INFO is a plist holding contextual information."
 	 ((string-match "\\<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-html-toc depth info (and localp keyword))))
+		(localp (org-string-match-p "\\<local\\>" value))
+		(local-id (and (string-match "\\<id:\\(.+\\)\\>" value)
+			       (match-string 1 value))))
+	    (org-html-toc depth info
+			  (or
+			   (and local-id
+				(car (org-element-map (plist-get info :parse-tree)
+					 'headline
+				       (lambda (element)
+					 (and (string= (org-element-property :CUSTOM_ID element) local-id)
+					      element)))))
+			   (and localp keyword)))))
 	 ((string= "listings" value) (org-html-list-of-listings info))
 	 ((string= "tables" value) (org-html-list-of-tables info))))))))
 
D. C., are you okay with applying patches to your local copy, or do
you need someone to clean it up and merge it into core?

I have copyright assignment papers on file. Feel free to do what you
want with the code!

Sacha

Re: TOC local for specified heading and its subheadings (in HTML export)?

[Sacha Chua]

Sacha Chua <sacha@sachachua.com> writes:

Hello, all!

> This is totally a partial implementation since I've only bothered to
> make it work for HTML export, but someone can make it work nicely for
> everything else. =)
> I think it will permit the use of lines like:
> #+TOC: headlines 1 id:ConfInfoClauses
...
> D. C., are you okay with applying patches to your local copy, or do
> you need someone to clean it up and merge it into core?

I confirmed with D. C. that the modification works for him, yay! =) He
sends his compliments and thanks. And I learned how to work with
org-element-*, so that's a bonus. Neat!

Is this a long-term capability we'd like to add? I can look into getting
it to work with the other Org export options, if we're cool with the
syntax. =)

Sacha

Re: TOC local for specified heading and its subheadings (in HTML export)?

[Rasmus]

Hi Sacha,

Thanks for working on this.

Sacha Chua <sacha@sachachua.com> writes:

> I think it will permit the use of lines like:
>
> #+TOC: headlines 1 id:ConfInfoClauses

"id:headline" is a special type of links (see org-id.el).  A reference to
a custom-ids is typically prefixed by "#" in Org, e.g. ’[[#heading]]’ or
’#+include: "file.org::#head"’.

Further, IMO it might be better to extend the ’#+toc: headlines local’
declaration.  Of course you could argue that ’local’ becomes a special
case of the above "id:whatever-is-the-name-of-the-local-headline".

Personally, I would like a more explicit syntax, though I recognize that
it doesn’t necessarily make a difference if it’s an extension, in the
sense of suffixing.  E.g.:

        #+toc: headlines local 1 :headline "* my headline"
        #+toc: headlines local 1 :headline "#headline"

Or closer to your suggestion,

       #+toc: headlines 1 :headline "#headline"
       #+toc: headlines 1 :headline local

Which as a special case can be written as,

      #+toc: headlines 1 local

> diff --git a/lisp/ox-html.el b/lisp/ox-html.el
> index effd387..3b0e239 100644
> --- a/lisp/ox-html.el
> +++ b/lisp/ox-html.el
> @@ -2651,8 +2651,18 @@ CONTENTS is nil.  INFO is a plist holding contextual information."
>  	 ((string-match "\\<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-html-toc depth info (and localp keyword))))
> +		(localp (org-string-match-p "\\<local\\>" value))
> +		(local-id (and (string-match "\\<id:\\(.+\\)\\>" value)
> +			       (match-string 1 value))))

Keyword options are typically prefixed with colon.  See e.g. #+include or
ob source blocks.

> +	    (org-html-toc depth info
> +			  (or
> +			   (and local-id
> +				(car (org-element-map (plist-get info :parse-tree)
> +					 'headline
> +				       (lambda (element)
> +					 (and (string= (org-element-property :CUSTOM_ID element) local-id)
> +					      element)))))

Wouldn’t it better to use org-link-search and get the element at point?

> +			   (and localp keyword)))))
>  	 ((string= "listings" value) (org-html-list-of-listings info))
>  	 ((string= "tables" value) (org-html-list-of-tables info))))))))
>  
> D. C., are you okay with applying patches to your local copy, or do
> you need someone to clean it up and merge it into core?

Complete patches are of course welcome, including a change log commit
message, an update to org.texi, and an entry in NEWS.  See:

     http://orgmode.org/worg/org-contribute.html

We’d need support across all backends where it makes sense, so I guess at
least, latex, beamer, odt, html, ascii, texinfo (if possible).

Rasmus

-- 
Dobbelt-A

Re: TOC local for specified heading and its subheadings (in HTML export)?

[Nicolas Goaziou]

Hello,

Rasmus <rasmus@gmx.us> writes:

> Further, IMO it might be better to extend the ’#+toc: headlines local’
> declaration.  Of course you could argue that ’local’ becomes a special
> case of the above "id:whatever-is-the-name-of-the-local-headline".
>
> Personally, I would like a more explicit syntax, though I recognize that
> it doesn’t necessarily make a difference if it’s an extension, in the
> sense of suffixing.  E.g.:
>
>         #+toc: headlines local 1 :headline "* my headline"
>         #+toc: headlines local 1 :headline "#headline"
>
> Or closer to your suggestion,
>
>        #+toc: headlines 1 :headline "#headline"
>        #+toc: headlines 1 :headline local
>
> Which as a special case can be written as,
>
>       #+toc: headlines 1 local

I agree. However, I suggest to ignore quotes:

  #+toc: headlines 1 :headline #headline

or 

  #+toc: headlines 1 :target #headline

since TOC keywords always refer to headlines.

Using quotes may also be supported for destinations containing spaces.

>> +	    (org-html-toc depth info
>> +			  (or
>> +			   (and local-id
>> +				(car (org-element-map (plist-get info :parse-tree)
>> +					 'headline
>> +				       (lambda (element)
>> +					 (and (string= (org-element-property :CUSTOM_ID element) local-id)
>> +					      element)))))
>
> Wouldn’t it better to use org-link-search and get the element at
> point?

Or even work at the parse tree level and use
`org-export-resolve-id-link' and `org-export-resolve-fuzzy-link'.


Regards,

-- 
Nicolas Goaziou

Re: TOC local for specified heading and its subheadings (in HTML export)?

[Sacha Chua]

Rasmus <rasmus@gmx.us> writes:

Hello, Rasmus, all!

> "id:headline" is a special type of links (see org-id.el).  A reference to
> a custom-ids is typically prefixed by "#" in Org, e.g. ’[[#heading]]’ or

Excellent point. I picked id: as a quick and dirty regexp match, but
:headline makes more sense. :headline "#headline" will later permit the
use of :headline "file.org::#headline" if someone is inclined. =)

>> +					 (and (string= (org-element-property :CUSTOM_ID element) local-id)
>> +					      element)))))
> Wouldn’t it better to use org-link-search and get the element at
> point?

That would definitely be better. I wasn't sure if I could reuse that
function at that point, but I'll look into it if I find myself
revisiting this hack.

> We’d need support across all backends where it makes sense, so I guess at
> least, latex, beamer, odt, html, ascii, texinfo (if possible).

I might not get to all of those (I'll tell the list if I do), so
consider this open season for anyone who wants to implement it! =) I'll
see if I have some time to explore all those backends over the next
while. I've just shifted back to dual-booting Linux (was formerly just
on Windows), so it'll be a little easier for me to try things out.

Sacha