* TOC local for specified heading and its subheadings (in HTML export)?
@ 2015-11-27 12:02 D. C. Toedt
2015-11-28 4:58 ` Sacha Chua
0 siblings, 1 reply; 6+ messages in thread
From: D. C. Toedt @ 2015-11-27 12:02 UTC (permalink / raw)
To: emacs-orgmode
[-- 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 --]
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: TOC local for specified heading and its subheadings (in HTML export)?
2015-11-27 12:02 TOC local for specified heading and its subheadings (in HTML export)? D. C. Toedt
@ 2015-11-28 4:58 ` Sacha Chua
2015-11-28 17:37 ` Sacha Chua
2015-11-28 19:16 ` Rasmus
0 siblings, 2 replies; 6+ messages in thread
From: Sacha Chua @ 2015-11-28 4:58 UTC (permalink / raw)
To: emacs-orgmode
"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
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: TOC local for specified heading and its subheadings (in HTML export)?
2015-11-28 4:58 ` Sacha Chua
@ 2015-11-28 17:37 ` Sacha Chua
2015-11-28 19:16 ` Rasmus
1 sibling, 0 replies; 6+ messages in thread
From: Sacha Chua @ 2015-11-28 17:37 UTC (permalink / raw)
To: emacs-orgmode; +Cc: dc
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: TOC local for specified heading and its subheadings (in HTML export)?
2015-11-28 4:58 ` Sacha Chua
2015-11-28 17:37 ` Sacha Chua
@ 2015-11-28 19:16 ` Rasmus
2015-11-29 13:05 ` Nicolas Goaziou
2015-11-30 0:46 ` Sacha Chua
1 sibling, 2 replies; 6+ messages in thread
From: Rasmus @ 2015-11-28 19:16 UTC (permalink / raw)
To: emacs-orgmode
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
^ permalink raw reply [flat|nested] 6+ messages in thread* Re: TOC local for specified heading and its subheadings (in HTML export)?
2015-11-28 19:16 ` Rasmus
@ 2015-11-29 13:05 ` Nicolas Goaziou
2015-11-30 0:46 ` Sacha Chua
1 sibling, 0 replies; 6+ messages in thread
From: Nicolas Goaziou @ 2015-11-29 13:05 UTC (permalink / raw)
To: Rasmus; +Cc: emacs-orgmode
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: TOC local for specified heading and its subheadings (in HTML export)?
2015-11-28 19:16 ` Rasmus
2015-11-29 13:05 ` Nicolas Goaziou
@ 2015-11-30 0:46 ` Sacha Chua
1 sibling, 0 replies; 6+ messages in thread
From: Sacha Chua @ 2015-11-30 0:46 UTC (permalink / raw)
To: emacs-orgmode
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
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2015-11-30 0:47 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2015-11-27 12:02 TOC local for specified heading and its subheadings (in HTML export)? D. C. Toedt
2015-11-28 4:58 ` Sacha Chua
2015-11-28 17:37 ` Sacha Chua
2015-11-28 19:16 ` Rasmus
2015-11-29 13:05 ` Nicolas Goaziou
2015-11-30 0:46 ` Sacha Chua
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).