different toc levels per headline?

different toc levels per headline?

[Adam Spiers]

Hi all,

If I have something like:

    #+OPTIONS: toc:1

    * h1 no options
    *** h2
    ***** h3
    * h1 toc:2
      :PROPERTIES:
      :EXPORT_OPTIONS: toc:2
      :END:
    *** h2
    ***** h3
    * h1 toc:3
      :PROPERTIES:
      :EXPORT_OPTIONS: toc:3
      :END:
    *** h2
    ***** h3

I would expect a ToC which looks like:

    Table of Contents
    _________________

    1 h1 no options
    2 h1 toc:1
    .. 2.1 h2
    3 h1 toc:2
    .. 3.1 h2
    ..... 3.1.1 h3

In otherwise, I would expect the EXPORT_OPTIONS in the subtrees to
override the file-wide setting for `toc'.  This expectation is based
on what the manual says:

    Export options can be set: globally with variables; for an
    individual file by making variables buffer-local with in-buffer
    settings (*note In-buffer settings::), by setting individual
    keywords, or by specifying them in a compact form with the
    `#+OPTIONS' keyword; or for a tree by setting properties (*note

    Properties and Columns::).  Options set at a specific level
    override options set at a more general level.

However instead I get:

    Table of Contents
    _________________

    1 h1 no options
    2 h1 toc:1
    3 h1 toc:2

What am I missing, and is there another way to vary the toc level per
subtree?

Thanks!
Adam

Re: different toc levels per headline?

[Carsten Dominik]

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

Hi Adam,

EXPORT_OPTIONS are for the special case that you only export that specific subtree, by restricting the export to a tree using C-s in the dispatcher.  They do not modify the behavior of a tree in a larger export of the document, and they also should not do so IMO.  Generating a single document should follow one set of rules, not many.

- Carsten

On 26.9.2013, at 13:01, Adam Spiers <orgmode@adamspiers.org> wrote:

> Hi all,
> 
> If I have something like:
> 
>    #+OPTIONS: toc:1
> 
>    * h1 no options
>    *** h2
>    ***** h3
>    * h1 toc:2
>      :PROPERTIES:
>      :EXPORT_OPTIONS: toc:2
>      :END:
>    *** h2
>    ***** h3
>    * h1 toc:3
>      :PROPERTIES:
>      :EXPORT_OPTIONS: toc:3
>      :END:
>    *** h2
>    ***** h3
> 
> I would expect a ToC which looks like:
> 
>    Table of Contents
>    _________________
> 
>    1 h1 no options
>    2 h1 toc:1
>    .. 2.1 h2
>    3 h1 toc:2
>    .. 3.1 h2
>    ..... 3.1.1 h3
> 
> In otherwise, I would expect the EXPORT_OPTIONS in the subtrees to
> override the file-wide setting for `toc'.  This expectation is based
> on what the manual says:
> 
>    Export options can be set: globally with variables; for an
>    individual file by making variables buffer-local with in-buffer
>    settings (*note In-buffer settings::), by setting individual
>    keywords, or by specifying them in a compact form with the
>    `#+OPTIONS' keyword; or for a tree by setting properties (*note
> 
>    Properties and Columns::).  Options set at a specific level
>    override options set at a more general level.
> 
> However instead I get:
> 
>    Table of Contents
>    _________________
> 
>    1 h1 no options
>    2 h1 toc:1
>    3 h1 toc:2
> 
> What am I missing, and is there another way to vary the toc level per
> subtree?
> 
> Thanks!
> Adam
> 


[-- Attachment #2: Message signed with OpenPGP using GPGMail --]
[-- Type: application/pgp-signature, Size: 455 bytes --]

Re: different toc levels per headline?

[Adam Spiers]

Hi Carsten,

On Thu, Sep 26, 2013 at 01:15:56PM +0200, Carsten Dominik wrote:
> Hi Adam,
> 
> EXPORT_OPTIONS are for the special case that you only export that
> specific subtree, by restricting the export to a tree using C-s in
> the dispatcher.  They do not modify the behavior of a tree in a
> larger export of the document, and they also should not do so IMO.

Thanks a lot for the reply.  However, what you say seems to directly
contradict this sentence in the manual:

    Options set at a specific level override options set at a more
    general level.

which is why this confused me.  I guess that sentence was intended to
refer only to subtree exports, not whole document exports, but that
meaning was not clear to me.  Perhaps it can be clarified via a small
tweak?

> Generating a single document should follow one set of rules, not
> many.

I agree that KISS is valuable when designing the rules.  However, it
also seems a perfectly reasonable requirement to be able to control
the toc: level per subtree during a whole document export, since in an
arbitrary document there's no guarantee that every headline has the
same depth.  E.g. one chapter may have a few deep subsections, whereas
another may contain lots of shallow subsections.  In these scenarios
it is clearly beneficial to allow the author to choose which
subsections appear in the ToC.

So is there a way of achieving this?  If not, please consider this a
feature request ;-)

Thanks!
Adam

Re: different toc levels per headline?

[Carsten Dominik]

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


On 26.9.2013, at 14:16, Adam Spiers <orgmode@adamspiers.org> wrote:

> Hi Carsten,
> 
> On Thu, Sep 26, 2013 at 01:15:56PM +0200, Carsten Dominik wrote:
>> Hi Adam,
>> 
>> EXPORT_OPTIONS are for the special case that you only export that
>> specific subtree, by restricting the export to a tree using C-s in
>> the dispatcher.  They do not modify the behavior of a tree in a
>> larger export of the document, and they also should not do so IMO.
> 
> Thanks a lot for the reply.  However, what you say seems to directly
> contradict this sentence in the manual:
> 
>    Options set at a specific level override options set at a more
>    general level.
> 
> which is why this confused me.  I guess that sentence was intended to
> refer only to subtree exports, not whole document exports, but that
> meaning was not clear to me.

I think it means this in general, but I also think that toc creation
is done at a global level, and not recursive in the tree.  Maybe Nicolas
has an authoritative answer on this one.

- Carsten

>  Perhaps it can be clarified via a small
> tweak?
> 
>> Generating a single document should follow one set of rules, not
>> many.
> 
> I agree that KISS is valuable when designing the rules.  However, it
> also seems a perfectly reasonable requirement to be able to control
> the toc: level per subtree during a whole document export, since in an
> arbitrary document there's no guarantee that every headline has the
> same depth.  E.g. one chapter may have a few deep subsections, whereas
> another may contain lots of shallow subsections.  In these scenarios
> it is clearly beneficial to allow the author to choose which
> subsections appear in the ToC.
> 
> So is there a way of achieving this?  If not, please consider this a
> feature request ;-)
> 
> Thanks!
> Adam
> 


[-- Attachment #2: Message signed with OpenPGP using GPGMail --]
[-- Type: application/pgp-signature, Size: 455 bytes --]

Re: different toc levels per headline?

[Nicolas Goaziou]

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

> On 26.9.2013, at 14:16, Adam Spiers <orgmode@adamspiers.org> wrote:

>> Thanks a lot for the reply.  However, what you say seems to directly
>> contradict this sentence in the manual:
>> 
>>    Options set at a specific level override options set at a more
>>    general level.
>> 
>> which is why this confused me.  I guess that sentence was intended to
>> refer only to subtree exports, not whole document exports, but that
>> meaning was not clear to me.
>
> I think it means this in general, but I also think that toc creation
> is done at a global level, and not recursive in the tree.  Maybe Nicolas
> has an authoritative answer on this one.

Not really. For the record, the full paragraph is:

  Export options can be set: globally with variables; for an individual
  file by making variables buffer-local with in-buffer settings, by
  setting individual keywords, or by specifying them in a compact form
  with the '#+OPTIONS' keyword; or for a tree by setting properties.
  Options set at a specific level override options set at a more general
  level.

There are three ways (four if you use a subtree export) to tweak export
settings. The last sentence means that more specific ways have
precedence over more general ones. IOW:

  #+OPTIONS or #+KEYWORDS > variables

and in the case of a subtree export:

  Properties > #+OPTIONS or #+KEYWORDS > variables


Regards,

-- 
Nicolas Goaziou

Re: different toc levels per headline?

[Adam Spiers]

On Thu, Sep 26, 2013 at 04:24:57PM +0200, Nicolas Goaziou wrote:
> Carsten Dominik <carsten.dominik@gmail.com> writes:
> > On 26.9.2013, at 14:16, Adam Spiers <orgmode@adamspiers.org> wrote:
> >> Thanks a lot for the reply.  However, what you say seems to directly
> >> contradict this sentence in the manual:
> >> 
> >>    Options set at a specific level override options set at a more
> >>    general level.
> >> 
> >> which is why this confused me.  I guess that sentence was intended to
> >> refer only to subtree exports, not whole document exports, but that
> >> meaning was not clear to me.
> >
> > I think it means this in general, but I also think that toc creation
> > is done at a global level, and not recursive in the tree.  Maybe Nicolas
> > has an authoritative answer on this one.
> 
> Not really. For the record, the full paragraph is:
> 
>   Export options can be set: globally with variables; for an individual
>   file by making variables buffer-local with in-buffer settings, by
>   setting individual keywords, or by specifying them in a compact form
>   with the '#+OPTIONS' keyword; or for a tree by setting properties.
>   Options set at a specific level override options set at a more general
>   level.

Right, I quoted that in my original post :-)

> There are three ways (four if you use a subtree export) to tweak export
> settings. The last sentence means that more specific ways have
> precedence over more general ones. IOW:
> 
>   #+OPTIONS or #+KEYWORDS > variables
> 
> and in the case of a subtree export:
> 
>   Properties > #+OPTIONS or #+KEYWORDS > variables

Sure, I understood that.  But AFAICS it doesn't provide a way of
controlling the depth of headings within the ToC _per_heading_,
which as I suggested in my previous email shouldn't be a particularly
rare use case.

Cheers,
Adam