emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* [BUG] New exporter exports TOC twice
@ 2013-04-24 11:13 Thorsten Jolitz
  2013-04-24 11:50 ` Nicolas Goaziou
  0 siblings, 1 reply; 12+ messages in thread
From: Thorsten Jolitz @ 2013-04-24 11:13 UTC (permalink / raw)
  To: emacs-orgmode


[double-post to bring this issue to the attention of Nicolas]

Exporting a Worg file with this header (#+TOC: headlines 2) 

,-----------------------------------------------------------------------------------------
| #+OPTIONS: H:3 num:nil \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:t
|             skip:nil d:(HIDE) tags:not-in-toc
| #+TOC:        headlines 2
| #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
| #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
| #+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
| #+TITLE:      Header arguments and result types in Org Babel
| #+AUTHOR:     Thorsten Jolitz, Eric Schulte
| #+EMAIL:      tj[at]data-driven[dot]de
| #+LANGUAGE:   en
| #+LINK_UP:    index.php
| #+LINK_HOME:  http://orgmode.org/worg/
| #+EXPORT_EXCLUDE_TAGS: noexport
| 
| For a complete header argument reference see the Org-mode manual's page
| which lists all
| [[http://orgmode.org/manual/Specific-header-arguments.html][Specific-header-arguments]].
| This page holds ancillary notes and tricks which have not made it into
| the manual.
| 
| * Generally use =verbatim= when using =drawer=, =raw= or =org=
| We often want to add =verbatim= (which inhibits interpretation as a
| value, which can often result in a list or table result), when
| inserting results directly into the buffer using =drawer=, =raw= or
| =org= which don't do tabular interpretation. [...]
`-----------------------------------------------------------------------------------------

exports the TOC twice in HTML export and ASCII export. 

HTML:
,--------------------------------------------------------------------------------
| Header arguments and result types in Org Babel
| 
| Table of Contents
| 
|   * Generally use verbatim when using drawer, raw or org
|   * Common combinations of header-args and result types
|   * Setting language and file specific default header argument values
| 
| Table of Contents
| 
|   * Generally use verbatim when using drawer, raw or org
|   * Common combinations of header-args and result types
|   * Setting language and file specific default header argument values
| 
| For a complete header argument reference see the Org-mode manual's page which
| lists all Specific-header-arguments. This page holds ancillary notes and tricks
| which have not made it into the manual.
`--------------------------------------------------------------------------------

ASCII:
,------------------------------------------------------------------------
| 
|             ________________________________________________
| 
|              HEADER ARGUMENTS AND RESULT TYPES IN ORG BABEL
| 
|                      Thorsten Jolitz, Eric Schulte
|             ________________________________________________
| 
| 
| Table of Contents
| _________________
| 
| Generally use `verbatim' when using `drawer', `raw' or `org'
| Common combinations of header-args and result types
| Setting language and file specific default header argument values
| 
| 
| Table of Contents
| _________________
| 
| Generally use `verbatim' when using `drawer', `raw' or `org'
| Common combinations of header-args and result types
| Setting language and file specific default header argument values
| For a complete header argument reference see the Org-mode manual's page
| which lists all [Specific-header-arguments]. This page holds ancillary
| notes and tricks which have not made it into the manual.
`------------------------------------------------------------------------


-- 
cheers,
Thorsten

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [BUG] New exporter exports TOC twice
  2013-04-24 11:13 [BUG] New exporter exports TOC twice Thorsten Jolitz
@ 2013-04-24 11:50 ` Nicolas Goaziou
  2013-04-24 11:56   ` Thorsten Jolitz
  2013-04-27  8:44   ` Carsten Dominik
  0 siblings, 2 replies; 12+ messages in thread
From: Nicolas Goaziou @ 2013-04-24 11:50 UTC (permalink / raw)
  To: Thorsten Jolitz; +Cc: emacs-orgmode

Hello,

Thorsten Jolitz <tjolitz@gmail.com> writes:

> Exporting a Worg file with this header (#+TOC: headlines 2) 
>
> ,-----------------------------------------------------------------------------------------
> | #+OPTIONS: H:3 num:nil \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:t
> |             skip:nil d:(HIDE) tags:not-in-toc
> | #+TOC:        headlines 2
> | #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
> | #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
> | #+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
> | #+TITLE:      Header arguments and result types in Org Babel
> | #+AUTHOR:     Thorsten Jolitz, Eric Schulte
> | #+EMAIL:      tj[at]data-driven[dot]de
> | #+LANGUAGE:   en
> | #+LINK_UP:    index.php
> | #+LINK_HOME:  http://orgmode.org/worg/
> | #+EXPORT_EXCLUDE_TAGS: noexport
> | 
> | For a complete header argument reference see the Org-mode manual's page
> | which lists all
> | [[http://orgmode.org/manual/Specific-header-arguments.html][Specific-header-arguments]].
> | This page holds ancillary notes and tricks which have not made it into
> | the manual.
> | 
> | * Generally use =verbatim= when using =drawer=, =raw= or =org=
> | We often want to add =verbatim= (which inhibits interpretation as a
> | value, which can often result in a list or table result), when
> | inserting results directly into the buffer using =drawer=, =raw= or
> | =org= which don't do tabular interpretation. [...]
> `-----------------------------------------------------------------------------------------
>
> exports the TOC twice in HTML export and ASCII export. 

If you don't specify a toc item in the OPTIONS line, Org will use the
value of `org-export-with-toc', which is non-nil by default.

So, your example is equivalent to:

  #+OPTIONS: toc:t
  #+TOC: headline 2

Hence you get two tables of contents.


Regards,

-- 
Nicolas Goaziou

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [BUG] New exporter exports TOC twice
  2013-04-24 11:50 ` Nicolas Goaziou
@ 2013-04-24 11:56   ` Thorsten Jolitz
  2013-04-24 12:11     ` Nicolas Goaziou
  2013-04-27  8:44   ` Carsten Dominik
  1 sibling, 1 reply; 12+ messages in thread
From: Thorsten Jolitz @ 2013-04-24 11:56 UTC (permalink / raw)
  To: emacs-orgmode

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> If you don't specify a toc item in the OPTIONS line, Org will use the
> value of `org-export-with-toc', which is non-nil by default.
>
> So, your example is equivalent to:
>
>   #+OPTIONS: toc:t
>   #+TOC: headline 2
>
> Hence you get two tables of contents.

Ok, but then with 

,----------------
| #+OPTIONS: toc:2
`----------------

the 

,-----------------
| #+TOC: headline 2
`-----------------

is actually redundant - I would need it only if I want to export other
things than headlines, right?

-- 
cheers,
Thorsten

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [BUG] New exporter exports TOC twice
  2013-04-24 11:56   ` Thorsten Jolitz
@ 2013-04-24 12:11     ` Nicolas Goaziou
  0 siblings, 0 replies; 12+ messages in thread
From: Nicolas Goaziou @ 2013-04-24 12:11 UTC (permalink / raw)
  To: Thorsten Jolitz; +Cc: emacs-orgmode

Thorsten Jolitz <tjolitz@gmail.com> writes:

> Nicolas Goaziou <n.goaziou@gmail.com> writes:
>
>> If you don't specify a toc item in the OPTIONS line, Org will use the
>> value of `org-export-with-toc', which is non-nil by default.
>>
>> So, your example is equivalent to:
>>
>>   #+OPTIONS: toc:t
>>   #+TOC: headline 2
>>
>> Hence you get two tables of contents.
>
> Ok, but then with 
>
> ,----------------
> | #+OPTIONS: toc:2
> `----------------
>
> the 
>
> ,-----------------
> | #+TOC: headline 2
> `-----------------
>
> is actually redundant - I would need it only if I want to export other
> things than headlines, right?

They are not equivalent, but are indeed redundant.


Regards,

-- 
Nicolas Goaziou

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [BUG] New exporter exports TOC twice
  2013-04-24 11:50 ` Nicolas Goaziou
  2013-04-24 11:56   ` Thorsten Jolitz
@ 2013-04-27  8:44   ` Carsten Dominik
  2013-04-27  8:52     ` Sebastien Vauban
  1 sibling, 1 reply; 12+ messages in thread
From: Carsten Dominik @ 2013-04-27  8:44 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: emacs-orgmode, Thorsten Jolitz


On 24.4.2013, at 13:50, Nicolas Goaziou <n.goaziou@gmail.com> wrote:

> Hello,
> 
> Thorsten Jolitz <tjolitz@gmail.com> writes:
> 
>> Exporting a Worg file with this header (#+TOC: headlines 2) 
>> 
>> ,-----------------------------------------------------------------------------------------
>> | #+OPTIONS: H:3 num:nil \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:t
>> |             skip:nil d:(HIDE) tags:not-in-toc
>> | #+TOC:        headlines 2
>> | #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
>> | #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
>> | #+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
>> | #+TITLE:      Header arguments and result types in Org Babel
>> | #+AUTHOR:     Thorsten Jolitz, Eric Schulte
>> | #+EMAIL:      tj[at]data-driven[dot]de
>> | #+LANGUAGE:   en
>> | #+LINK_UP:    index.php
>> | #+LINK_HOME:  http://orgmode.org/worg/
>> | #+EXPORT_EXCLUDE_TAGS: noexport
>> | 
>> | For a complete header argument reference see the Org-mode manual's page
>> | which lists all
>> | [[http://orgmode.org/manual/Specific-header-arguments.html][Specific-header-arguments]].
>> | This page holds ancillary notes and tricks which have not made it into
>> | the manual.
>> | 
>> | * Generally use =verbatim= when using =drawer=, =raw= or =org=
>> | We often want to add =verbatim= (which inhibits interpretation as a
>> | value, which can often result in a list or table result), when
>> | inserting results directly into the buffer using =drawer=, =raw= or
>> | =org= which don't do tabular interpretation. [...]
>> `-----------------------------------------------------------------------------------------
>> 
>> exports the TOC twice in HTML export and ASCII export. 
> 
> If you don't specify a toc item in the OPTIONS line, Org will use the
> value of `org-export-with-toc', which is non-nil by default.
> 
> So, your example is equivalent to:
> 
>  #+OPTIONS: toc:t
>  #+TOC: headline 2
> 
> Hence you get two tables of contents.


Hmm, I understand the reasoning here - but my feeling says that
the presence of one or more #+TOC lines in a file should probably
overrule both #+OPTIONS: toc: and the content of org-export-with-toc.
So in that case, your would then only get one TOC, at the
location of that line.

What do you think?  Are there good reasons for not doing it
as I propose?

- Carsten

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [BUG] New exporter exports TOC twice
  2013-04-27  8:44   ` Carsten Dominik
@ 2013-04-27  8:52     ` Sebastien Vauban
  2013-04-27 11:14       ` Carsten Dominik
  0 siblings, 1 reply; 12+ messages in thread
From: Sebastien Vauban @ 2013-04-27  8:52 UTC (permalink / raw)
  To: emacs-orgmode-mXXj517/zsQ

Hi Carsten,

Carsten Dominik wrote:
> On 24.4.2013, at 13:50, Nicolas Goaziou <n.goaziou-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>> Thorsten Jolitz <tjolitz-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:
>> 
>>> Exporting a Worg file with this header (#+TOC: headlines 2) 
>>> exports the TOC twice in HTML export and ASCII export. 
>> 
>> If you don't specify a toc item in the OPTIONS line, Org will use the
>> value of `org-export-with-toc', which is non-nil by default.
>> 
>> So, your example is equivalent to:
>> 
>>  #+OPTIONS: toc:t
>>  #+TOC: headline 2
>> 
>> Hence you get two tables of contents.
>
> Hmm, I understand the reasoning here - but my feeling says that
> the presence of one or more #+TOC lines in a file should probably
> overrule both #+OPTIONS: toc: and the content of org-export-with-toc.
> So in that case, your would then only get one TOC, at the
> location of that line.
>
> What do you think?  Are there good reasons for not doing it
> as I propose?

Maybe what I'll say is stupid, but, in LaTeX, there's the minitoc package for
having a big TOC at the beginning of the document (default) + TOC per chapter,
which can be limited to less (or more) sublevels.

Maybe allowing to insert extra TOC here and there would allow one to make
something like that available to other backends?  Though, as of today, I don't
think the TOC is limitable per org-level-1 headline...

Best regards,
  Seb

-- 
Sebastien Vauban

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [BUG] New exporter exports TOC twice
  2013-04-27  8:52     ` Sebastien Vauban
@ 2013-04-27 11:14       ` Carsten Dominik
  2013-04-27 14:15         ` Sebastien Vauban
  2013-04-28  7:28         ` Nicolas Goaziou
  0 siblings, 2 replies; 12+ messages in thread
From: Carsten Dominik @ 2013-04-27 11:14 UTC (permalink / raw)
  To: Sebastien Vauban; +Cc: emacs-orgmode


On 27.4.2013, at 10:52, Sebastien Vauban <sva-news@mygooglest.com> wrote:

> Hi Carsten,
> 
> Carsten Dominik wrote:
>> On 24.4.2013, at 13:50, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
>>> Thorsten Jolitz <tjolitz@gmail.com> writes:
>>> 
>>>> Exporting a Worg file with this header (#+TOC: headlines 2) 
>>>> exports the TOC twice in HTML export and ASCII export. 
>>> 
>>> If you don't specify a toc item in the OPTIONS line, Org will use the
>>> value of `org-export-with-toc', which is non-nil by default.
>>> 
>>> So, your example is equivalent to:
>>> 
>>> #+OPTIONS: toc:t
>>> #+TOC: headline 2
>>> 
>>> Hence you get two tables of contents.
>> 
>> Hmm, I understand the reasoning here - but my feeling says that
>> the presence of one or more #+TOC lines in a file should probably
>> overrule both #+OPTIONS: toc: and the content of org-export-with-toc.
>> So in that case, your would then only get one TOC, at the
>> location of that line.
>> 
>> What do you think?  Are there good reasons for not doing it
>> as I propose?
> 
> Maybe what I'll say is stupid, but, in LaTeX, there's the minitoc package for
> having a big TOC at the beginning of the document (default) + TOC per chapter,
> which can be limited to less (or more) sublevels.
> 
> Maybe allowing to insert extra TOC here and there would allow one to make
> something like that available to other backends?  Though, as of today, I don't
> think the TOC is limitable per org-level-1 headline...
> 

Hi Sebastien,

I am not saying multiple tocs should not be allowed.  I am all for that.
However, I think that by inserting a #+TOC line, the user indicates
desire for local control.  Therefore, org-export-with-toc should be ignored,
and, by extension, also #+OPTIONS: toc (because this is really a local way
to set org-export-with-toc).

- Carsten

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [BUG] New exporter exports TOC twice
  2013-04-27 11:14       ` Carsten Dominik
@ 2013-04-27 14:15         ` Sebastien Vauban
  2013-04-28  7:28         ` Nicolas Goaziou
  1 sibling, 0 replies; 12+ messages in thread
From: Sebastien Vauban @ 2013-04-27 14:15 UTC (permalink / raw)
  To: emacs-orgmode-mXXj517/zsQ

Hi Carsten,

Carsten Dominik wrote:
> On 27.4.2013, at 10:52, Sebastien Vauban <sva-news-D0wtAvR13HarG/iDocfnWg@public.gmane.org> wrote:
>> Carsten Dominik wrote:
>>> On 24.4.2013, at 13:50, Nicolas Goaziou <n.goaziou-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>>>> Thorsten Jolitz <tjolitz-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:
>>>> 
>>>>> Exporting a Worg file with this header (#+TOC: headlines 2) 
>>>>> exports the TOC twice in HTML export and ASCII export. 
>>>> 
>>>> If you don't specify a toc item in the OPTIONS line, Org will use the
>>>> value of `org-export-with-toc', which is non-nil by default.
>>>> 
>>>> So, your example is equivalent to:
>>>> 
>>>> #+OPTIONS: toc:t
>>>> #+TOC: headline 2
>>>> 
>>>> Hence you get two tables of contents.
>>> 
>>> Hmm, I understand the reasoning here - but my feeling says that
>>> the presence of one or more #+TOC lines in a file should probably
>>> overrule both #+OPTIONS: toc: and the content of org-export-with-toc.
>>> So in that case, your would then only get one TOC, at the
>>> location of that line.
>>> 
>>> What do you think?  Are there good reasons for not doing it
>>> as I propose?
>> 
>> Maybe what I'll say is stupid, but, in LaTeX, there's the minitoc package for
>> having a big TOC at the beginning of the document (default) + TOC per chapter,
>> which can be limited to less (or more) sublevels.
>> 
>> Maybe allowing to insert extra TOC here and there would allow one to make
>> something like that available to other backends?  Though, as of today, I don't
>> think the TOC is limitable per org-level-1 headline...
>
> I am not saying multiple tocs should not be allowed.  I am all for that.
> However, I think that by inserting a #+TOC line, the user indicates
> desire for local control.  Therefore, org-export-with-toc should be ignored,
> and, by extension, also #+OPTIONS: toc (because this is really a local way
> to set org-export-with-toc).

OK, that's another point of view. I clearly have no objection for that
behavior.

Best regards,
  Seb

-- 
Sebastien Vauban

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [BUG] New exporter exports TOC twice
  2013-04-27 11:14       ` Carsten Dominik
  2013-04-27 14:15         ` Sebastien Vauban
@ 2013-04-28  7:28         ` Nicolas Goaziou
  2013-05-01 20:45           ` Carsten Dominik
  1 sibling, 1 reply; 12+ messages in thread
From: Nicolas Goaziou @ 2013-04-28  7:28 UTC (permalink / raw)
  To: Carsten Dominik; +Cc: Sebastien Vauban, emacs-orgmode

Hello,

Carsten Dominik <carsten.dominik@gmail.com> writes:

> I am not saying multiple tocs should not be allowed.  I am all for that.
> However, I think that by inserting a #+TOC line, the user indicates
> desire for local control.  Therefore, org-export-with-toc should be ignored,
> and, by extension, also #+OPTIONS: toc (because this is really a local way
> to set org-export-with-toc).

The problem is that #+TOC cannot be a strict equivalent to
`org-export-with-toc', since the former cannot be introduced in the
document template.

Also, this change would require each user back-end developer to check
for the presence of a TOC keyword with "headlines" value in the parse
tree when handling :with-toc property. This is not complicated, but
there are already many uncomplicated issues to think about when writing
a back-end.

In a nutshell, I don't think we should try to outsmart the user by
ignoring his setup here. I suggest to improve the manual, if needed,
instead.


Regards,

-- 
Nicolas Goaziou

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [BUG] New exporter exports TOC twice
  2013-04-28  7:28         ` Nicolas Goaziou
@ 2013-05-01 20:45           ` Carsten Dominik
  2013-05-01 22:08             ` Nicolas Goaziou
  0 siblings, 1 reply; 12+ messages in thread
From: Carsten Dominik @ 2013-05-01 20:45 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: Sebastien Vauban, emacs-orgmode

Hi Nicolas,

On 28.4.2013, at 09:28, Nicolas Goaziou <n.goaziou@gmail.com> wrote:

> Hello,
> 
> Carsten Dominik <carsten.dominik@gmail.com> writes:
> 
>> I am not saying multiple tocs should not be allowed.  I am all for that.
>> However, I think that by inserting a #+TOC line, the user indicates
>> desire for local control.  Therefore, org-export-with-toc should be ignored,
>> and, by extension, also #+OPTIONS: toc (because this is really a local way
>> to set org-export-with-toc).
> 
> The problem is that #+TOC cannot be a strict equivalent to
> `org-export-with-toc', since the former cannot be introduced in the
> document template.

I am not sure I understand.  What do you mean?

> Also, this change would require each user back-end developer to check
> for the presence of a TOC keyword with "headlines" value in the parse
> tree when handling :with-toc property. This is not complicated, but
> there are already many uncomplicated issues to think about when writing
> a back-end.

An alternative would be that the parser already makes this change.  Upon
finding #+TOC, it would change the OPTION value in the parse tree.

> 
> In a nutshell, I don't think we should try to outsmart the user by
> ignoring his setup here. I suggest to improve the manual, if needed,
> instead.

That is certainly an alternative, once I have understood the issues.

Thanks for your patience.

- Carsten

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [BUG] New exporter exports TOC twice
  2013-05-01 20:45           ` Carsten Dominik
@ 2013-05-01 22:08             ` Nicolas Goaziou
  2013-05-02  3:22               ` Carsten Dominik
  0 siblings, 1 reply; 12+ messages in thread
From: Nicolas Goaziou @ 2013-05-01 22:08 UTC (permalink / raw)
  To: Carsten Dominik; +Cc: Sebastien Vauban, emacs-orgmode

Hello,

Carsten Dominik <carsten.dominik@gmail.com> writes:

>> The problem is that #+TOC cannot be a strict equivalent to
>> `org-export-with-toc', since the former cannot be introduced in the
>> document template.
>
> I am not sure I understand.  What do you mean?

A TOC keyword belongs to the contents of the document. On the other
hand, :with-toc is handled in a "template" function, which has access to
both the contents and the meta-data around it. Therefore, :with-toc can
insert a table of contents in more places than TOC.

For example, in latex back-end, TOC cannot insert a \tableofcontents
before \begin{document}, but toc:t can. Of course, this example doesn't
make sense as per LaTeX syntax, but it is possible that some other
back-end wants to allow this.

>> Also, this change would require each user back-end developer to check
>> for the presence of a TOC keyword with "headlines" value in the parse
>> tree when handling :with-toc property. This is not complicated, but
>> there are already many uncomplicated issues to think about when writing
>> a back-end.
>
> An alternative would be that the parser already makes this change.  Upon
> finding #+TOC, it would change the OPTION value in the parse tree.

The parser doesn't handle the OPTION keyword (it's just another
keyword), and neither should it (export options mustn't influence how
the parsing is done).

It belongs to the export framework to read export options and handle
them. Upon reading the with-toc value, it is indeed possible to check
for the presence of a TOC keyword in the parse tree.

However, in this case, I don't see the need to go out of our way just to
interpret differently what the user specified. Getting two tables of
contents is not surprising when you understand that "toc:t" and "#+TOC:
headlines" are independent ways of requesting a table of contents.


Regards,

-- 
Nicolas Goaziou

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [BUG] New exporter exports TOC twice
  2013-05-01 22:08             ` Nicolas Goaziou
@ 2013-05-02  3:22               ` Carsten Dominik
  0 siblings, 0 replies; 12+ messages in thread
From: Carsten Dominik @ 2013-05-02  3:22 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: Sebastien Vauban, emacs-orgmode

Hi Nicolas,

On 2.5.2013, at 00:08, Nicolas Goaziou <n.goaziou@gmail.com> wrote:

> Hello,
> 
> Carsten Dominik <carsten.dominik@gmail.com> writes:
> 
>>> The problem is that #+TOC cannot be a strict equivalent to
>>> `org-export-with-toc', since the former cannot be introduced in the
>>> document template.
>> 
>> I am not sure I understand.  What do you mean?
> 
> A TOC keyword belongs to the contents of the document. On the other
> hand, :with-toc is handled in a "template" function, which has access to
> both the contents and the meta-data around it. Therefore, :with-toc can
> insert a table of contents in more places than TOC.
> 
> For example, in latex back-end, TOC cannot insert a \tableofcontents
> before \begin{document}, but toc:t can. Of course, this example doesn't
> make sense as per LaTeX syntax, but it is possible that some other
> back-end wants to allow this.

OK.

> 
>>> Also, this change would require each user back-end developer to check
>>> for the presence of a TOC keyword with "headlines" value in the parse
>>> tree when handling :with-toc property. This is not complicated, but
>>> there are already many uncomplicated issues to think about when writing
>>> a back-end.
>> 
>> An alternative would be that the parser already makes this change.  Upon
>> finding #+TOC, it would change the OPTION value in the parse tree.
> 
> The parser doesn't handle the OPTION keyword (it's just another
> keyword), and neither should it (export options mustn't influence how
> the parsing is done).
> 
> It belongs to the export framework to read export options and handle
> them. Upon reading the with-toc value, it is indeed possible to check
> for the presence of a TOC keyword in the parse tree.
> 
> However, in this case, I don't see the need to go out of our way just to
> interpret differently what the user specified. Getting two tables of
> contents is not surprising when you understand that "toc:t" and "#+TOC:
> headlines" are independent ways of requesting a table of contents.


This is clear enough.  I have pushed a fix to the manual which should
make this clearer.

Regards

- Carsten

^ permalink raw reply	[flat|nested] 12+ messages in thread

end of thread, other threads:[~2013-05-02  3:22 UTC | newest]

Thread overview: 12+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2013-04-24 11:13 [BUG] New exporter exports TOC twice Thorsten Jolitz
2013-04-24 11:50 ` Nicolas Goaziou
2013-04-24 11:56   ` Thorsten Jolitz
2013-04-24 12:11     ` Nicolas Goaziou
2013-04-27  8:44   ` Carsten Dominik
2013-04-27  8:52     ` Sebastien Vauban
2013-04-27 11:14       ` Carsten Dominik
2013-04-27 14:15         ` Sebastien Vauban
2013-04-28  7:28         ` Nicolas Goaziou
2013-05-01 20:45           ` Carsten Dominik
2013-05-01 22:08             ` Nicolas Goaziou
2013-05-02  3:22               ` Carsten Dominik

Code repositories for project(s) associated with this 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).