headers
Suhail Shergill | 7 Jul 2012 22:00
Picon
Gravatar

org-html: subtree specific footnote references

running org-export-as-html on a subtree is currently problematic if the result
is to be merged into a document which contains html-ized versions of other
subtrees: the footnote references and definitions get clobbered.

this patch uses the CUSTOM_ID property of the subtree to generate unique
footnote references and definitions. if the subtree does not have the CUSTOM_ID
property set the result is a nop.
Attachment (0001-org-html.el-Make-footnotes-unique-to-an-entry.patch): text/x-diff, 2291 bytes

--

-- 
Suhail
Permalink | Reply |
headers
Suhail Shergill | 7 Jul 2012 22:16
Picon
Gravatar

Re: org-html: subtree specific footnote references

oops. attached the wrong patch. amended patch follows.
Attachment (0001-org-html.el-Make-footnotes-unique-to-an-entry.patch): text/x-diff, 2128 bytes

Suhail Shergill <suhailshergill <at> gmail.com> writes:

> running org-export-as-html on a subtree is currently problematic if the result
> is to be merged into a document which contains html-ized versions of other
> subtrees: the footnote references and definitions get clobbered.
>
> this patch uses the CUSTOM_ID property of the subtree to generate unique
> footnote references and definitions. if the subtree does not have the CUSTOM_ID
> property set the result is a nop.
>
>
> From 27f89f8bfff334810aba5c33af621e351fa0be79 Mon Sep 17 00:00:00 2001
> From: Suhail Shergill <suhailshergill <at> gmail.com>
> Date: Sun, 8 Apr 2012 10:49:51 -0400
> Subject: [PATCH] org-html.el: Make footnotes unique to an entry
>
> * lisp/org-html.el (org-export-as-html): Assign unique ids to footnotes
>   if possible
>
> If the entry (or its ancestor) has the CUSTOM_ID property defined, then
> use that as part of the generated footnote references and definitions.
> ---
>  lisp/org-html.el |   12 ++++++++----
>  1 file changed, 8 insertions(+), 4 deletions(-)
(Continue reading)

Permalink | Reply |
headers
Jambunathan K | 10 Jul 2012 05:48
Picon

Re: org-html: subtree specific footnote references


>> running org-export-as-html on a subtree is currently problematic if
>> the result is to be merged into a document which contains html-ized
>> versions of other subtrees: the footnote references and definitions
>> get clobbered.

Do the subtrees come from the same org file?

Won't it look odd and confusing to a reader, when there are two
different footnote definitions with the same number.  Confusion is like
to be pronounced, if the reader chooses to also print out the document
as a pdf or into paper.
--

--
Permalink | Reply |
headers
Suhail Shergill | 10 Jul 2012 06:18
Picon
Gravatar

Re: org-html: subtree specific footnote references

Jambunathan K <kjambunathan <at> gmail.com> writes:

>>> running org-export-as-html on a subtree is currently problematic if
>>> the result is to be merged into a document which contains html-ized
>>> versions of other subtrees: the footnote references and definitions
>>> get clobbered.
>
> Do the subtrees come from the same org file?

that is the use case, yes.

> Won't it look odd and confusing to a reader, when there are two
> different footnote definitions with the same number. 

yes i agree that would be very confusing. but why, pray tell, would there be two
different definitions with the same number?

> Confusion is like to be pronounced, if the reader chooses to also print out
> the document as a pdf or into paper.

again, i'm not sure what scenario you're describing.

i was only describing a scenario where the patch is useful. allow me to try
again.

with the current patch, if the user selects the entire org file and exports it,
there will only be *one* footnotes section, albeit the footnote references and
definitions (which aren't visible unless someone inspects the source) will be
annotated with the CUSTOM_ID property value should it be defined.
(Continue reading)

Permalink | Reply |
headers
Jambunathan K | 10 Jul 2012 06:38
Picon

Re: org-html: subtree specific footnote references

Suhail Shergill <suhailshergill <at> gmail.com> writes:

> Jambunathan K <kjambunathan <at> gmail.com> writes:
>
>>>> running org-export-as-html on a subtree is currently problematic if
>>>> the result is to be merged into a document which contains html-ized
>>>> versions of other subtrees: the footnote references and definitions
>>>> get clobbered.
>>
>> Do the subtrees come from the same org file?
>
> that is the use case, yes.

Try marking the subtrees with :export: tag.  Lookup the following in the
mailing list, worg or the info manual.

     #+EXPORT_SELECT_TAGS:   Tags that select a tree for export
     #+EXPORT_EXCLUDE_TAGS:  Tags that exclude a tree from export

With this, do footnotes come out along the expected lines?

>> Won't it look odd and confusing to a reader, when there are two
>> different footnote definitions with the same number. 
>
> yes i agree that would be very confusing. but why, pray tell, would
> there be two different definitions with the same number?

<a>you haven't modified the description have you?</a>

>> Confusion is like to be pronounced, if the reader chooses to also print out
(Continue reading)

Permalink | Reply |
headers
Suhail Shergill | 10 Jul 2012 07:03
Picon
Gravatar

Re: org-html: subtree specific footnote references

Jambunathan K <kjambunathan <at> gmail.com> writes:

> Suhail Shergill <suhailshergill <at> gmail.com> writes:
>
>> Jambunathan K <kjambunathan <at> gmail.com> writes:
>>
>>>>> running org-export-as-html on a subtree is currently problematic if
>>>>> the result is to be merged into a document which contains html-ized
>>>>> versions of other subtrees: the footnote references and definitions
>>>>> get clobbered.
>>>
>>> Do the subtrees come from the same org file?
>>
>> that is the use case, yes.
>
> Try marking the subtrees with :export: tag.  Lookup the following in the
> mailing list, worg or the info manual.
>
>      #+EXPORT_SELECT_TAGS:   Tags that select a tree for export
>      #+EXPORT_EXCLUDE_TAGS:  Tags that exclude a tree from export
>
> With this, do footnotes come out along the expected lines?

*if* you were to generate the entire file again, things will be fine yes. i'm
talking about a scenario where for one reason or another you may not want to do
that, but may instead only want to export the most recent subtree which has been
added (since the last time it was exported). earlier when you tried to do that,
the footnote links would no longer work because of name attribute
collisions. this patch provides a way to prevent that.
(Continue reading)

Permalink | Reply |
headers
Jambunathan K | 10 Jul 2012 07:20
Picon

Re: org-html: subtree specific footnote references


>>>> Won't it look odd and confusing to a reader, when there are two
>>>> different footnote definitions with the same number. 
>>>
>>> yes i agree that would be very confusing. but why, pray tell, would
>>> there be two different definitions with the same number?
>>
>> <a>you haven't modified the description have you?</a>
>
> no, i haven't. also, you could look at the patch. the code is pretty
> self-explanatory.

It was not a question. It was a suggestion.

Btw, I will not be the one integrating or reviewing this patch.
--

--
Permalink | Reply |
headers
Jambunathan K | 10 Jul 2012 07:54
Picon

Re: org-html: subtree specific footnote references

Suhail Shergill <suhailshergill <at> gmail.com> writes:

> i'm talking about a scenario where for one reason or another you may
> not want to do that, but may instead only want to export the most
> recent subtree which has been added (since the last time it was
> exported).

You are trying to merge two /instances of export command/ and not two
/instances of subtrees/.  It only so happens that, in your specific
case, you are selecting different subtrees for different export
instances.

What is the value of `org-footnote-section' in your case?

Wrt footnotes, what you see in the Org file is not what the exporter
sees.  Footnote definitions get collected in to the buffer at a suitable
point as part of pre-processing (see `org-footnote-normalize').  Also
footnote definitions can be placed by hand at arbitrary points through
out your Org file.

I have a feeling that patch requires more additions.  Furthermore, you
also need to submit a patch to org-e-html.el which will replace
org-html.el in the future.

I will let the owners of org-html.el to take over from here.
Permalink | Reply |
headers
Suhail Shergill | 16 Jul 2012 19:31
Picon
Gravatar

Re: org-html: subtree specific footnote references

Jambunathan K <kjambunathan <at> gmail.com> writes:

> Suhail Shergill <suhailshergill <at> gmail.com> writes:
>
>> i'm talking about a scenario where for one reason or another you may
>> not want to do that, but may instead only want to export the most
>> recent subtree which has been added (since the last time it was
>> exported).
>
> You are trying to merge two /instances of export command/ and not two
> /instances of subtrees/.  It only so happens that, in your specific
> case, you are selecting different subtrees for different export
> instances.

yes

> What is the value of `org-footnote-section' in your case?

the string "Footnotes"

> Wrt footnotes, what you see in the Org file is not what the exporter
> sees.  Footnote definitions get collected in to the buffer at a suitable
> point as part of pre-processing (see `org-footnote-normalize').  Also
> footnote definitions can be placed by hand at arbitrary points through
> out your Org file.

hmm right.

> I have a feeling that patch requires more additions.
(Continue reading)

Permalink | Reply |
headers
Bastien | 2 Aug 2012 18:26
Picon
Gravatar

Re: org-html: subtree specific footnote references

Hi Suhail,

I have accepted the patch.  I added a TINYCHANGE cookie at the end 
of the git commit message: this is requested for tiny changes made 
by people who did not sign the FSF papers.

Suhail Shergill <suhailshergill <at> gmail.com> writes:

> *if* this patch makes sense, i'm willing to submit a patch for
> org-e-html.el. 

The patch makes sense but is still a bit hackish.  I accepted it
because the functionality is useful in some cases and because it 
only affects org-html.el, which days are counted.

> does anyone have any views?

My view is that org-e-html.el should also make sure that we always
have unique ids for all the footnotes of the current files, even when 
we export only part of it.

This is not a trivial change though, because org-export.el has to 
change the way it retrieves the footnote number.

Can you have a look at this?

> does this patch 'make sense', and is this the right place for it?

Yes, it is the right place for such patches.
(Continue reading)

Permalink | Reply |
headers
Suhail Shergill | 4 Aug 2012 02:17
Picon
Gravatar

Re: org-html: subtree specific footnote references

Bastien <bzg <at> gnu.org> writes:

> My view is that org-e-html.el should also make sure that we always
> have unique ids for all the footnotes of the current files, even when 
> we export only part of it.
>
> This is not a trivial change though, because org-export.el has to 
> change the way it retrieves the footnote number.
>
> Can you have a look at this?

sure

--

-- 
Suhail
Permalink | Reply |

Gmane