Hi Nicolas,
On 2.5.2013, at 00:08, Nicolas Goaziou <n.goaz...@gmail.com> wrote:
> Hello,
>
> Carsten Dominik <carsten.domi...@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
