Re: Is there a YAML metadata option for `--shift-heading-level-by` on the command line?

[John MacFarlane <jgm-TVLZxgkOlNX2fBVCVOL8/A@public.gmane.org>]

"R (Chandra) Chandrasekhar" <chyavana-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:

> So far, I have succeeded in getting the desired numbering by:
>
> 1. Adding
>
> shift-heading-level-by: -1
>
> after the line specifying the reader in my defaults file.
>
> 2. Adding
>
> numbersections: true

This works, because of the way it is implemented for your
output format, but this is not the documented way to set
this option, and it won't work for all output formats.  Instead, use

number-sections: true

in your defaults files.

> However, if I move the line
>
> shift-heading-level-by: -1
>
> from the defaults file to the YAML metadata block in my source file, the 
> numbering starts at 0.1 rather than 1 for the first level-2 heading.

You can't, in general, set command line options from YAML
metadata.  Options are one thing, metadata is another.
Defaults files are where you set options.

> Finally, I have found that there are three ways to turn numbering on or off:
>
> (a) to turn section numbering on in the
>
> command line, I need to use
>
> `--number-sections`
>
> (b) to turn it on in the defaults file I need to specify
>
> `number-sections: true`
>
> (c) but to turn it on in the YAML metadata block, I need to specify
>
> `numbersections: true` without an intervening hyphen.
>
> Is this deliberate or an artefact of history?

The last method works because of an implementation detail,
but this is not a documented or supported way of doing it.