Include heading title in HTML section-number cross-reference, like LaTex \nameref?

Include heading title in HTML section-number cross-reference, like LaTex \nameref?

[D. C. Toedt]

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

I'm using Org-mode version 8.2.5f with Gnu Emacs 24.3 on a Macbook Air with
Mavericks. I'm using it to build building an annotated collection of
contract clauses that I'm releasing under a Creative Commons license (see
http://www.CommonDraft.org), which I hope to monetize with a book on
contract drafting and negotiation.

I've done a fair amount of Google searching and also searching within this
list. If the following isn't already implemented, I'd pay USD$100 (via
PayPal) to have that done to whoever implements it in an official org-mode
release, plus another USD$100 donation to the org-mode maintainer.

QUESTION:  When org-mode headings are NUMBERED, and the file is exported to
HTML, is there any way to have org-mode include the TITLE, not just the
section number, of a cross-referenced section, along the lines of the LaTex
\nameref{} function?  Here's an example:

==BEGIN EXAMPLE==

#+OPTIONS: H:7 TOC:nil @:t num:1 email:t author:t

* Introduction to Technology Contracts
  :PROPERTIES:
  :CUSTOM_ID: IntroTechContracts
  :END:

Lorem ipsum etc. etc.

* Dangerous Clauses
  :PROPERTIES:
  :CUSTOM_ID: DangerousClauses
  :END:

Lorem ipsum etc. etc. -- see Section [[#IntroTechContracts]].

==END EXAMPLE==

With numbering turned ON (#+OPTIONS: num:1), the link is exported to HTML
as:  Section <a href="#IntroTechContracts">1</a>.

With numbering turned OFF (#+OPTIONS: num:nil), the link is exported to
HTML as:  Section <a href="#IntroTechContracts">Introduction to Technology
Contracts</a>.

Using a macro, I'd like to be able to AUTOMATICALLY do the latter --- that
is, have the link text be the heading title --- even with numbering turned
ON, so that a macro such as {{{SECREF(IntroTechContracts)}}} would render
in HTML as, let's say:   Section <a href="#IntroTechContracts">1</a>,
entitled "<a href="#IntroTechContracts">Introduction to Technology
Contracts</a>."

Is that currently doable?

*D. C. Toedt III * *(my** last name is pronounced "Tate") *
Attorney and neutral arbitrator -- tech contracts and intellectual property

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)
*Common Draft* <http://www.commondraft.org> annotated collection of
contract clauses

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: 8162 bytes --]

Re: Include heading title in HTML section-number cross-reference, like LaTex \nameref?

[Nicolas Goaziou]

Hello,

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

> QUESTION:  When org-mode headings are NUMBERED, and the file is exported to
> HTML, is there any way to have org-mode include the TITLE, not just the
> section number, of a cross-referenced section, along the lines of the LaTex
> \nameref{} function?  Here's an example:
>
> ==BEGIN EXAMPLE==
>
> #+OPTIONS: H:7 TOC:nil @:t num:1 email:t author:t
>
> * Introduction to Technology Contracts
>   :PROPERTIES:
>   :CUSTOM_ID: IntroTechContracts
>   :END:
>
> Lorem ipsum etc. etc.
>
> * Dangerous Clauses
>   :PROPERTIES:
>   :CUSTOM_ID: DangerousClauses
>   :END:
>
> Lorem ipsum etc. etc. -- see Section [[#IntroTechContracts]].
>
> ==END EXAMPLE==

[...]

> Is that currently doable?

I think so. Not trivial, but doable nonetheless.

--8<---------------cut here---------------start------------->8---
#+MACRO: get-title (eval (save-excursion (org-open-link-from-string "[[#$1]]") (org-get-heading nil nil)))
#+MACRO: SECREF [[#$1][{{{get-title($1)}}}]]
#+OPTIONS: H:7 toc:nil num:1 email:t author:t

* Introduction to Technology Contracts
  :PROPERTIES:
  :CUSTOM_ID: IntroTechContracts
  :END:

Lorem ipsum etc. etc.

* Dangerous Clauses
  :PROPERTIES:
  :CUSTOM_ID: DangerousClauses
  :END:

Lorem ipsum etc. etc. -- see Section {{{SECREF(IntroTechContracts)}}}
--8<---------------cut here---------------end--------------->8---


Regards,

-- 
Nicolas Goaziou

Re: Include heading title in HTML section-number cross-reference, like LaTex \nameref?

[D. C. Toedt]

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

That works -- please email me privately with where to send the $100 via
PayPal.  Thanks!

(Org-mode maintainer [Bastien, still?], can you please let me know if /
when this gets implemented in an official release.)

Regards,

D. C.


*D. C. Toedt III * *(my** last name is pronounced "Tate") *
Attorney and neutral arbitrator -- tech contracts and intellectual property

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)
*Common Draft* <http://www.commondraft.org> annotated collection of
contract clauses

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




On Sat, Feb 8, 2014 at 3:50 PM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:

> Hello,
>
> "D. C. Toedt" <dc@toedt.com> writes:
>
> > QUESTION:  When org-mode headings are NUMBERED, and the file is exported
> to
> > HTML, is there any way to have org-mode include the TITLE, not just the
> > section number, of a cross-referenced section, along the lines of the
> LaTex
> > \nameref{} function?  Here's an example:
> >
> > ==BEGIN EXAMPLE==
> >
> > #+OPTIONS: H:7 TOC:nil @:t num:1 email:t author:t
> >
> > * Introduction to Technology Contracts
> >   :PROPERTIES:
> >   :CUSTOM_ID: IntroTechContracts
> >   :END:
> >
> > Lorem ipsum etc. etc.
> >
> > * Dangerous Clauses
> >   :PROPERTIES:
> >   :CUSTOM_ID: DangerousClauses
> >   :END:
> >
> > Lorem ipsum etc. etc. -- see Section [[#IntroTechContracts]].
> >
> > ==END EXAMPLE==
>
> [...]
>
> > Is that currently doable?
>
> I think so. Not trivial, but doable nonetheless.
>
> --8<---------------cut here---------------start------------->8---
> #+MACRO: get-title (eval (save-excursion (org-open-link-from-string
> "[[#$1]]") (org-get-heading nil nil)))
> #+MACRO: SECREF [[#$1][{{{get-title($1)}}}]]
> #+OPTIONS: H:7 toc:nil num:1 email:t author:t
>
> * Introduction to Technology Contracts
>   :PROPERTIES:
>   :CUSTOM_ID: IntroTechContracts
>   :END:
>
> Lorem ipsum etc. etc.
>
> * Dangerous Clauses
>   :PROPERTIES:
>   :CUSTOM_ID: DangerousClauses
>   :END:
>
> Lorem ipsum etc. etc. -- see Section {{{SECREF(IntroTechContracts)}}}
> --8<---------------cut here---------------end--------------->8---
>
>
> Regards,
>
> --
> Nicolas Goaziou
>

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

Re: Include heading title in HTML section-number cross-reference, like LaTex \nameref?

[D. C. Toedt]

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

I found a problem when trying this on a bigger file (my book file):  If $1
(actually, #$1) is for a link target that doesn't exist, then org-mode goes
into its "No match - create this as a new heading? (y or n)" routine. That
causes the rest of the export to fail.  It'd be better if get-title could
do the same thing org-mode does natively, that is, including the text of $1
as italics to indicate a non-existent link.

Example file below:

--8<---------------cut here---------------start------------->8---

#+MACRO: get-title (eval (save-excursion (org-open-link-from-string
"[[#$1]]") (org-get-heading nil nil)))
#+MACRO: SECREF [[#$1][{{{get-title($1)}}}]]
#+OPTIONS: H:7 toc:nil num:1 email:t author:t

* Introduction to Technology Contracts
  :PROPERTIES:
  :CUSTOM_ID: IntroTechContracts
  :END:

Lorem ipsum etc. etc.

* Dangerous Clauses
  :PROPERTIES:
  :CUSTOM_ID: DangerousClauses
  :END:

Lorem ipsum etc. etc. -- see Section {{{SECREF(
BogusLinkTarget
)}}}

--8<---------------cut here---------------end--------------->8---



>

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

Re: Include heading title in HTML section-number cross-reference, like LaTex \nameref?

[Bastien]

Hello,

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

> (Org-mode maintainer [Bastien, still?], can you please let me know if
> / when this gets implemented in an official release.)

I'm not Org's maintainer anymore, I'm just /de facto/ taking decisions
in accordance with the other core maintainers, our level of trust lets
us move forward happily.

To come back to you original question:

,----
| #+OPTIONS: H:7 TOC:nil @:t num:1 email:t author:t
| 
| * Introduction to Technology Contracts
|   :PROPERTIES:
|   :CUSTOM_ID: IntroTechContracts
|   :END:
| 
| Lorem ipsum etc. etc.
| 
| * Dangerous Clauses
|   :PROPERTIES:
|   :CUSTOM_ID: DangerousClauses
|   :END:
| 
| Lorem ipsum etc. etc. -- see Section [[#IntroTechContracts]].
`----

Why don't you use

[[#IntroTechContracts][Introduction to Technology Contracts]]

as a link?  It is the link stored by org-store-link, and later
inserted by org-insert-link, and AFAICS it is correctly exported.

But it's true there are a few things we can make more consistent
in this area though, so thanks for bringing this up.

Best,

-- 
 Bastien

Re: Include heading title in HTML section-number cross-reference, like LaTex \nameref?

[Nicolas Goaziou]

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

> I found a problem when trying this on a bigger file (my book file):  If $1
> (actually, #$1) is for a link target that doesn't exist, then org-mode goes
> into its "No match - create this as a new heading? (y or n)" routine. That
> causes the rest of the export to fail.  It'd be better if get-title could
> do the same thing org-mode does natively, that is, including the text of $1
> as italics to indicate a non-existent link.
>
> Example file below:
>
>
> #+MACRO: get-title (eval (save-excursion (org-open-link-from-string
> "[[#$1]]") (org-get-heading nil nil)))
> #+MACRO: SECREF [[#$1][{{{get-title($1)}}}]]
> #+OPTIONS: H:7 toc:nil num:1 email:t author:t
>
> * Introduction to Technology Contracts
>   :PROPERTIES:
>   :CUSTOM_ID: IntroTechContracts
>   :END:
>
> Lorem ipsum etc. etc.
>
> * Dangerous Clauses
>   :PROPERTIES:
>   :CUSTOM_ID: DangerousClauses
>   :END:
>
> Lorem ipsum etc. etc. -- see Section {{{SECREF(
> BogusLinkTarget
> )}}}

The following should work.

  #+MACRO: get-title (eval (or (save-excursion (ignore-errors (let ((org-link-search-inhibit-query t)) (org-open-link-from-string "[[#$1]]") (org-get-heading nil nil)))) "/$1/"))


Regards,

-- 
Nicolas Goaziou

Re: Include heading title in HTML section-number cross-reference, like LaTex \nameref?

[D. C. Toedt]

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

> Why don't you use [[#IntroTechContracts][Introduction to Technology
Contracts]]
 as a link?

I routinely tweak the text of the target headings as I edit the document.
 For example, the section heading "Introduction to Technology Contracts"
might become, say, "Introduction:  Why Technology Contracts are Fun."

I don't want to have to manually revise the link text for the many internal
cross-reference links that exist in the document.  I'd really like to have
a way for a link to automatically retrieve the heading text during HTML
export.





On Sun, Feb 9, 2014 at 2:19 AM, Bastien <bzg@gnu.org> wrote:

> Hello,
>
> "D. C. Toedt" <dc@toedt.com> writes:
>
> > (Org-mode maintainer [Bastien, still?], can you please let me know if
> > / when this gets implemented in an official release.)
>
> I'm not Org's maintainer anymore, I'm just /de facto/ taking decisions
> in accordance with the other core maintainers, our level of trust lets
> us move forward happily.
>
> To come back to you original question:
>
> ,----
> | #+OPTIONS: H:7 TOC:nil @:t num:1 email:t author:t
> |
> | * Introduction to Technology Contracts
> |   :PROPERTIES:
> |   :CUSTOM_ID: IntroTechContracts
> |   :END:
> |
> | Lorem ipsum etc. etc.
> |
> | * Dangerous Clauses
> |   :PROPERTIES:
> |   :CUSTOM_ID: DangerousClauses
> |   :END:
> |
> | Lorem ipsum etc. etc. -- see Section [[#IntroTechContracts]].
> `----
>
> Why don't you use
>
> [[#IntroTechContracts][Introduction to Technology Contracts]]
>
> as a link?  It is the link stored by org-store-link, and later
> inserted by org-insert-link, and AFAICS it is correctly exported.
>
> But it's true there are a few things we can make more consistent
> in this area though, so thanks for bringing this up.
>
> Best,
>
> --
>  Bastien
>

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

Re: Include heading title in HTML section-number cross-reference, like LaTex \nameref?

[D. C. Toedt]

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

Excellent -- that seems to export just fine.

Interestingly, the export now generates the message, "Position saved to
mark ring, go back with C-c & ."  I presume that comes from the
((org-link-search-inhibit-query t)) argument in the "let" function.  It doesn't
seem to harm the export results.

One of these years I'll have to start poking around the Emacs-Lisp code to
try to puzzle out the workings of the functions being called, especially
org-get-heading
--- is there a comparable one (or arguments) to get the section number of a
heading?

Many thanks, Nicolas.



On Sun, Feb 9, 2014 at 2:29 AM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:

> "D. C. Toedt" <dc@toedt.com> writes:
>
> > I found a problem when trying this on a bigger file (my book file):  If
> $1
> > (actually, #$1) is for a link target that doesn't exist, then org-mode
> goes
> > into its "No match - create this as a new heading? (y or n)" routine.
> That
> > causes the rest of the export to fail.  It'd be better if get-title could
> > do the same thing org-mode does natively, that is, including the text of
> $1
> > as italics to indicate a non-existent link.
> >
> > Example file below:
> >
> >
> > #+MACRO: get-title (eval (save-excursion (org-open-link-from-string
> > "[[#$1]]") (org-get-heading nil nil)))
> > #+MACRO: SECREF [[#$1][{{{get-title($1)}}}]]
> > #+OPTIONS: H:7 toc:nil num:1 email:t author:t
> >
> > * Introduction to Technology Contracts
> >   :PROPERTIES:
> >   :CUSTOM_ID: IntroTechContracts
> >   :END:
> >
> > Lorem ipsum etc. etc.
> >
> > * Dangerous Clauses
> >   :PROPERTIES:
> >   :CUSTOM_ID: DangerousClauses
> >   :END:
> >
> > Lorem ipsum etc. etc. -- see Section {{{SECREF(
> > BogusLinkTarget
> > )}}}
>
> The following should work.
>
>   #+MACRO: get-title (eval (or (save-excursion (ignore-errors (let
> ((org-link-search-inhibit-query t)) (org-open-link-from-string "[[#$1]]")
> (org-get-heading nil nil)))) "/$1/"))
>
>
> Regards,
>
> --
> Nicolas Goaziou
>

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

Re: Include heading title in HTML section-number cross-reference, like LaTex \nameref?

[Nicolas Goaziou]

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

> --- is there a comparable one (or arguments) to get the section number of a
> heading?

There is `org-export-get-headline-number' but is only accessible during
export, so it cannot be called from a macro or a Babel block.

Anyway, in your case, you just need to use [[#custom-id]].


Regards,

-- 
Nicolas Goaziou

Re: Include heading title in HTML section-number cross-reference, like LaTex \nameref?

[Bastien]

I think the whole thread calls for a variable to let the user
configure the way she wants references to be inserted.

Because \nameref could be useful in LaTeX/Beamer too.

And maybe ODT could enjoy such a function too.

Nicolas, what do you think?

-- 
 Bastien

Re: Include heading title in HTML section-number cross-reference, like LaTex \nameref?

[Nicolas Goaziou]

Hello,

Bastien <bzg@gnu.org> writes:

> I think the whole thread calls for a variable to let the user
> configure the way she wants references to be inserted.
>
> Because \nameref could be useful in LaTeX/Beamer too.

Internal links in Beamer are complicated, because there's no way to know
which slide we're referring to. So I don't think \nameref would help
here.

> And maybe ODT could enjoy such a function too.
>
> Nicolas, what do you think?

This is something that cannot be easily achieved with filters, so it
could make sense to have a defcustom, or maybe two (one when headlines
are numbered and another one when they are not).

Anyway, patches welcome.


Regards,

-- 
Nicolas Goaziou