Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[Kolen Cheung]

[-- Attachment #1.1: Type: text/plain, Size: 2795 bytes --]



This originally started from issue #3138 
<https://github.com/jgm/pandoc/issues/3138#issuecomment-253699552>. It 
concerns how pandoc should handle the case when YAML metadata collides with 
the command line options.
<#>An Example 

The example here concerns --include-in-header= in command line and 
header-include in YAML, but the issue itself is more general, e.g. 
--include-after-body=, etc.

From the manual (emphasis is mine):

-H *FILE*, --include-in-header=*FILE*

: Include contents of *FILE*, verbatim, at the end of the header. This can 
be used, for example, to include special CSS or javascript in HTML 
documents. This option *can be used repeatedly* to include multiple files 
in the header. They will be included in the order specified. Implies 
--standalone.

<#>Current behavior 

Whenever command line option is specified, it will override the YAML 
metadata defined. Example used in the issue is:

Command line: pandoc ... -H <file> ..., and in the md file’s yaml:

header-includes:
    - \usepackage{siunitx}

\usepackage{siunitx} will be ignored.
<#>“Expected” Behavior 

Since the manual said, “This option can be used repeatedly”, it seems 
natural to assume the same metadata can be defined through both the YAML 
and command line.

However, it can be imagined people might use command line option to 
override the YAML option. I agree the command line option should have 
priority: on option that cannot be repeated, command line option should 
override. But when an option is repeatable, priority could means command 
line metadata comes first and YAML comes second, not necessarily means 
ignoring the later.
<#>Related Discussion: Should Templates Be Recursively Resolved Into? 

This is the original purpose of issue #3138 
<https://github.com/jgm/pandoc/issues/3138#issuecomment-253699552>: should 
templates be recursively resolved into? An example is, if I wrote a 
template snippet, currently -H/--include-in-header=*SNIPPET* would not 
resolve it as a template but include it as is. (There’s a work around 
mentioned in Pandoc Tricks · jgm/pandoc Wiki 
<https://github.com/jgm/pandoc/wiki/Pandoc-Tricks>.)
​

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/836ca2d4-6e39-4f7e-b227-69dc06be6f15%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #1.2: Type: text/html, Size: 16247 bytes --]

Re: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[BP Jonsson]

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

My solution is very simple: I define a separate variable in my templates
and use that in metadata, with different keys for different output formats
as well as for the beginning/end of header/body, along with a filter which
converts codeblocks in said metadata fields into raw blocks of the right
format, which is important to prevent breakage. No conflict with
`--include-in-header` and its automatically raw semantics arises because
they use different template variables.

/bpj

Den 29 okt 2016 05:18 skrev "Kolen Cheung" <christian.kolen-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:

> This originally started from issue #3138
> <https://github.com/jgm/pandoc/issues/3138#issuecomment-253699552>. It
> concerns how pandoc should handle the case when YAML metadata collides with
> the command line options.
> <#m_6038354951767356229_>An Example
>
> The example here concerns --include-in-header= in command line and
> header-include in YAML, but the issue itself is more general, e.g.
> --include-after-body=, etc.
>
> From the manual (emphasis is mine):
>
> -H *FILE*, --include-in-header=*FILE*
>
> : Include contents of *FILE*, verbatim, at the end of the header. This
> can be used, for example, to include special CSS or javascript in HTML
> documents. This option *can be used repeatedly* to include multiple files
> in the header. They will be included in the order specified. Implies
> --standalone.
>
> <#m_6038354951767356229_>Current behavior
>
> Whenever command line option is specified, it will override the YAML
> metadata defined. Example used in the issue is:
>
> Command line: pandoc ... -H <file> ..., and in the md file’s yaml:
>
> header-includes:
>     - \usepackage{siunitx}
>
> \usepackage{siunitx} will be ignored.
> <#m_6038354951767356229_>“Expected” Behavior
>
> Since the manual said, “This option can be used repeatedly”, it seems
> natural to assume the same metadata can be defined through both the YAML
> and command line.
>
> However, it can be imagined people might use command line option to
> override the YAML option. I agree the command line option should have
> priority: on option that cannot be repeated, command line option should
> override. But when an option is repeatable, priority could means command
> line metadata comes first and YAML comes second, not necessarily means
> ignoring the later.
> <#m_6038354951767356229_>Related Discussion: Should Templates Be
> Recursively Resolved Into?
>
> This is the original purpose of issue #3138
> <https://github.com/jgm/pandoc/issues/3138#issuecomment-253699552>:
> should templates be recursively resolved into? An example is, if I wrote a
> template snippet, currently -H/--include-in-header=*SNIPPET* would not
> resolve it as a template but include it as is. (There’s a work around
> mentioned in Pandoc Tricks · jgm/pandoc Wiki
> <https://github.com/jgm/pandoc/wiki/Pandoc-Tricks>.)
> ​
>
> --
> You received this message because you are subscribed to the Google Groups
> "pandoc-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To view this discussion on the web visit https://groups.google.com/d/
> msgid/pandoc-discuss/836ca2d4-6e39-4f7e-b227-69dc06be6f15%
> 40googlegroups.com
> <https://groups.google.com/d/msgid/pandoc-discuss/836ca2d4-6e39-4f7e-b227-69dc06be6f15%40googlegroups.com?utm_medium=email&utm_source=footer>
> .
> For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CAFC_yuQZfyYuP6LzVtv02pVkr92Vx6zATosAdXbm%2BBCbxeTMMw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #2: Type: text/html, Size: 17786 bytes --]

Re: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[Kolen Cheung]

[-- Attachment #1.1: Type: text/plain, Size: 5783 bytes --]



Thanks for the solution.

I might not be clear enough in the original post (sometimes I get things 
too elaborated): probably @jgm is willing to change the behavior in the 
case that when metadata that is repeatable, collision of command line 
options and YAML will be catenated instead of ignoring YAML, but this 
breaks backward compatibility, so he wants to make sure no one is objected 
to the said new behavior. (because people might rely on the current 
behavior to *override* instead of expecting it to be catenated.)

The discussion actually referred to -H option only, but I generalized to 
“any metadata that is repeatable”.

May be the title is not precise enough. It might be better to say something 
like: “Discussion Needed—will you hate it if command line option do not 
override YAML’s metadata when it is repeatable”.

On Saturday, October 29, 2016 at 10:24:33 AM UTC-7, BP Jonsson wrote:

My solution is very simple: I define a separate variable in my templates 
> and use that in metadata, with different keys for different output formats 
> as well as for the beginning/end of header/body, along with a filter which 
> converts codeblocks in said metadata fields into raw blocks of the right 
> format, which is important to prevent breakage. No conflict with 
> `--include-in-header` and its automatically raw semantics arises because 
> they use different template variables.
>
> /bpj
>
> Den 29 okt 2016 05:18 skrev "Kolen Cheung" <christi...-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org 
> <javascript:>>:
>
>> This originally started from issue #3138 
>> <https://github.com/jgm/pandoc/issues/3138#issuecomment-253699552>. It 
>> concerns how pandoc should handle the case when YAML metadata collides with 
>> the command line options.
>>
>> <#CAFC_yuQZfyYuP6LzVtv02pVkr92Vx6zATosAdXbm+BCbxeTMMw-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org_m_6038354951767356229_>An 
>> Example 
>>
>> The example here concerns --include-in-header= in command line and 
>> header-include in YAML, but the issue itself is more general, e.g. 
>> --include-after-body=, etc.
>>
>> From the manual (emphasis is mine):
>>
>> -H *FILE*, --include-in-header=*FILE*
>>
>> : Include contents of *FILE*, verbatim, at the end of the header. This 
>> can be used, for example, to include special CSS or javascript in HTML 
>> documents. This option *can be used repeatedly* to include multiple 
>> files in the header. They will be included in the order specified. Implies 
>> --standalone.
>>
>>
>> <#CAFC_yuQZfyYuP6LzVtv02pVkr92Vx6zATosAdXbm+BCbxeTMMw-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org_m_6038354951767356229_>Current 
>> behavior 
>>
>> Whenever command line option is specified, it will override the YAML 
>> metadata defined. Example used in the issue is:
>>
>> Command line: pandoc ... -H <file> ..., and in the md file’s yaml:
>>
>> header-includes:
>>     - \usepackage{siunitx}
>>
>> \usepackage{siunitx} will be ignored.
>>
>> <#CAFC_yuQZfyYuP6LzVtv02pVkr92Vx6zATosAdXbm+BCbxeTMMw-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org_m_6038354951767356229_>“Expected” 
>> Behavior 
>>
>> Since the manual said, “This option can be used repeatedly”, it seems 
>> natural to assume the same metadata can be defined through both the YAML 
>> and command line.
>>
>> However, it can be imagined people might use command line option to 
>> override the YAML option. I agree the command line option should have 
>> priority: on option that cannot be repeated, command line option should 
>> override. But when an option is repeatable, priority could means command 
>> line metadata comes first and YAML comes second, not necessarily means 
>> ignoring the later.
>>
>> <#CAFC_yuQZfyYuP6LzVtv02pVkr92Vx6zATosAdXbm+BCbxeTMMw-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org_m_6038354951767356229_>Related 
>> Discussion: Should Templates Be Recursively Resolved Into? 
>>
>> This is the original purpose of issue #3138 
>> <https://github.com/jgm/pandoc/issues/3138#issuecomment-253699552>: 
>> should templates be recursively resolved into? An example is, if I wrote a 
>> template snippet, currently -H/--include-in-header=*SNIPPET* would not 
>> resolve it as a template but include it as is. (There’s a work around 
>> mentioned in Pandoc Tricks · jgm/pandoc Wiki 
>> <https://github.com/jgm/pandoc/wiki/Pandoc-Tricks>.)
>> ​
>>
>> -- 
>> You received this message because you are subscribed to the Google Groups 
>> "pandoc-discuss" group.
>> To unsubscribe from this group and stop receiving emails from it, send an 
>> email to pandoc-discus...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org <javascript:>.
>> To post to this group, send email to pandoc-...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org 
>> <javascript:>.
>> To view this discussion on the web visit 
>> https://groups.google.com/d/msgid/pandoc-discuss/836ca2d4-6e39-4f7e-b227-69dc06be6f15%40googlegroups.com 
>> <https://groups.google.com/d/msgid/pandoc-discuss/836ca2d4-6e39-4f7e-b227-69dc06be6f15%40googlegroups.com?utm_medium=email&utm_source=footer>
>> .
>> For more options, visit https://groups.google.com/d/optout.
>>
> ​

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/bd8aea27-38c3-4ace-af2e-6603a64fb977%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #1.2: Type: text/html, Size: 49770 bytes --]

Re: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[Melroch]

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

I *would* like it but in practice merging data structures is not so
straightforward. It can be done in many ways, which may be appropriate or
inappropriate depending on what you are going to use each substructure for.
See the link below for a nice illustration.

https://metacpan.org/pod/Hash::Merge#BUILT-IN-BEHAVIORS

(In case you are unfamiliar with Perl `$foo` is a scalar/string value,
`@foo` is an array and `%foo` is an associative array aka hash. `$$foo
@$foo %$foo` are dereferencing references to a scalar/array/hash -- nested
data structures are done with (usually anonymous) references in Perl)

Den 31 okt 2016 05:14 skrev "Kolen Cheung" <christian.kolen-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:

> Thanks for the solution.
>
> I might not be clear enough in the original post (sometimes I get things
> too elaborated): probably @jgm is willing to change the behavior in the
> case that when metadata that is repeatable, collision of command line
> options and YAML will be catenated instead of ignoring YAML, but this
> breaks backward compatibility, so he wants to make sure no one is objected
> to the said new behavior. (because people might rely on the current
> behavior to *override* instead of expecting it to be catenated.)
>
> The discussion actually referred to -H option only, but I generalized to
> “any metadata that is repeatable”.
>
> May be the title is not precise enough. It might be better to say
> something like: “Discussion Needed—will you hate it if command line option
> do not override YAML’s metadata when it is repeatable”.
>
> On Saturday, October 29, 2016 at 10:24:33 AM UTC-7, BP Jonsson wrote:
>
> My solution is very simple: I define a separate variable in my templates
>> and use that in metadata, with different keys for different output formats
>> as well as for the beginning/end of header/body, along with a filter which
>> converts codeblocks in said metadata fields into raw blocks of the right
>> format, which is important to prevent breakage. No conflict with
>> `--include-in-header` and its automatically raw semantics arises because
>> they use different template variables.
>>
>> /bpj
>>
>> Den 29 okt 2016 05:18 skrev "Kolen Cheung" <christi...-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:
>>
>>> This originally started from issue #3138
>>> <https://github.com/jgm/pandoc/issues/3138#issuecomment-253699552>. It
>>> concerns how pandoc should handle the case when YAML metadata collides with
>>> the command line options.
>>>
>>> <#m_7733005993067201441_CAFC_yuQZfyYuP6LzVtv02pVkr92Vx6zATosAdXbm+BCbxeTMMw-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org_m_6038354951767356229_>An
>>> Example
>>>
>>> The example here concerns --include-in-header= in command line and
>>> header-include in YAML, but the issue itself is more general, e.g.
>>> --include-after-body=, etc.
>>>
>>> From the manual (emphasis is mine):
>>>
>>> -H *FILE*, --include-in-header=*FILE*
>>>
>>> : Include contents of *FILE*, verbatim, at the end of the header. This
>>> can be used, for example, to include special CSS or javascript in HTML
>>> documents. This option *can be used repeatedly* to include multiple
>>> files in the header. They will be included in the order specified. Implies
>>> --standalone.
>>>
>>>
>>> <#m_7733005993067201441_CAFC_yuQZfyYuP6LzVtv02pVkr92Vx6zATosAdXbm+BCbxeTMMw-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org_m_6038354951767356229_>Current
>>> behavior
>>>
>>> Whenever command line option is specified, it will override the YAML
>>> metadata defined. Example used in the issue is:
>>>
>>> Command line: pandoc ... -H <file> ..., and in the md file’s yaml:
>>>
>>> header-includes:
>>>     - \usepackage{siunitx}
>>>
>>> \usepackage{siunitx} will be ignored.
>>>
>>> <#m_7733005993067201441_CAFC_yuQZfyYuP6LzVtv02pVkr92Vx6zATosAdXbm+BCbxeTMMw-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org_m_6038354951767356229_>“Expected”
>>> Behavior
>>>
>>> Since the manual said, “This option can be used repeatedly”, it seems
>>> natural to assume the same metadata can be defined through both the YAML
>>> and command line.
>>>
>>> However, it can be imagined people might use command line option to
>>> override the YAML option. I agree the command line option should have
>>> priority: on option that cannot be repeated, command line option should
>>> override. But when an option is repeatable, priority could means command
>>> line metadata comes first and YAML comes second, not necessarily means
>>> ignoring the later.
>>>
>>> <#m_7733005993067201441_CAFC_yuQZfyYuP6LzVtv02pVkr92Vx6zATosAdXbm+BCbxeTMMw-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org_m_6038354951767356229_>Related
>>> Discussion: Should Templates Be Recursively Resolved Into?
>>>
>>> This is the original purpose of issue #3138
>>> <https://github.com/jgm/pandoc/issues/3138#issuecomment-253699552>:
>>> should templates be recursively resolved into? An example is, if I wrote a
>>> template snippet, currently -H/--include-in-header=*SNIPPET* would not
>>> resolve it as a template but include it as is. (There’s a work around
>>> mentioned in Pandoc Tricks · jgm/pandoc Wiki
>>> <https://github.com/jgm/pandoc/wiki/Pandoc-Tricks>.)
>>> ​
>>>
>>> --
>>> You received this message because you are subscribed to the Google
>>> Groups "pandoc-discuss" group.
>>> To unsubscribe from this group and stop receiving emails from it, send
>>> an email to pandoc-discus...-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
>>> To post to this group, send email to pandoc-...-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
>>> To view this discussion on the web visit https://groups.google.com/d/ms
>>> gid/pandoc-discuss/836ca2d4-6e39-4f7e-b227-69dc06be6f15%40go
>>> oglegroups.com
>>> <https://groups.google.com/d/msgid/pandoc-discuss/836ca2d4-6e39-4f7e-b227-69dc06be6f15%40googlegroups.com?utm_medium=email&utm_source=footer>
>>> .
>>> For more options, visit https://groups.google.com/d/optout.
>>>
>> ​
>
> --
> You received this message because you are subscribed to the Google Groups
> "pandoc-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To view this discussion on the web visit https://groups.google.com/d/
> msgid/pandoc-discuss/bd8aea27-38c3-4ace-af2e-6603a64fb977%
> 40googlegroups.com
> <https://groups.google.com/d/msgid/pandoc-discuss/bd8aea27-38c3-4ace-af2e-6603a64fb977%40googlegroups.com?utm_medium=email&utm_source=footer>
> .
> For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CADAJKhAUZ2CRHXyeG83YxG4urCQG2yv6kvvOrPuyTfMFmXrDTQ%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #2: Type: text/html, Size: 51676 bytes --]

Re: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[Kolen Cheung]

[-- Attachment #1.1: Type: text/plain, Size: 1357 bytes --]

I was browsing some pandoc filters and see this comment:

> pandoc-crossref uses metadata variable `header-includes` to add LaTeX 
definitions to output. However, Pandoc's command line option 
`--include-in-header`/`-H` overrides this variable. If you need to use 
`--include-in-header`, add pandoc-crossref-specific definitions as well. 
See [LaTeX customization](#latex-customization) for more information.

I was thinking to use the `header-includes` in filters to put necessary 
"template" needed by the filter as well. But without the `-H` override the 
`header-includes` it won't be stable.

It seems that at least there aren't specific reasons/situations when the 
current behavior is preferred (that `-H` override `header-includes` in 
YAML). May be we should make the change?

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/1902649a-ac7f-4715-a80e-9d9c3659e025%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #1.2: Type: text/html, Size: 2208 bytes --]

Re: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[Melroch]

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

The simple solution would be for templates to contain something like this

````
$for(filter-header-includes.<output_format>)$
$filter-header-includes.<output_format>$

$endfor$
````

with filter authors being trusted to make sure that the relevant variable
is a MetaBlocks element where each child element is a RawBlock element of
the appropriate format. This wouldn't require any code changes at all, just
half an hour's work on the templates and some discipline on the part of
filter authors.

/bpj


Den 1 dec 2016 12:55 skrev "Kolen Cheung" <christian.kolen-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:

I was browsing some pandoc filters and see this comment:

> pandoc-crossref uses metadata variable `header-includes` to add LaTeX
definitions to output. However, Pandoc's command line option
`--include-in-header`/`-H` overrides this variable. If you need to use
`--include-in-header`, add pandoc-crossref-specific definitions as well.
See [LaTeX customization](#latex-customization) for more information.

I was thinking to use the `header-includes` in filters to put necessary
"template" needed by the filter as well. But without the `-H` override the
`header-includes` it won't be stable.

It seems that at least there aren't specific reasons/situations when the
current behavior is preferred (that `-H` override `header-includes` in
YAML). May be we should make the change?

-- 
You received this message because you are subscribed to the Google Groups
"pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/
msgid/pandoc-discuss/1902649a-ac7f-4715-a80e-9d9c3659e025%40googlegroups.com
<https://groups.google.com/d/msgid/pandoc-discuss/1902649a-ac7f-4715-a80e-9d9c3659e025%40googlegroups.com?utm_medium=email&utm_source=footer>
.

For more options, visit https://groups.google.com/d/optout.

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CADAJKhCfDzDaQYSn%3DiNzM0XXEpisontg%3DLxrOadmHD6_6aNriw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #2: Type: text/html, Size: 4527 bytes --]

Re: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[BP Jonsson]

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

> make sure that the relevant variable is a MetaBlocks element where each
child element is a RawBlock element

That should of course be a MetaList element with MetaBlocks elements with
RawBlock elements.

/bpj

Den 2 dec 2016 16:37 skrev "Melroch" <melroch-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:

The simple solution would be for templates to contain something like this

````
$for(filter-header-includes.<output_format>)$
$filter-header-includes.<output_format>$

$endfor$
````

with filter authors being trusted to make sure that the relevant variable
is a MetaBlocks element where each child element is a RawBlock element of
the appropriate format. This wouldn't require any code changes at all, just
half an hour's work on the templates and some discipline on the part of
filter authors.

/bpj


Den 1 dec 2016 12:55 skrev "Kolen Cheung" <christian.kolen-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:

I was browsing some pandoc filters and see this comment:

> pandoc-crossref uses metadata variable `header-includes` to add LaTeX
definitions to output. However, Pandoc's command line option
`--include-in-header`/`-H` overrides this variable. If you need to use
`--include-in-header`, add pandoc-crossref-specific definitions as well.
See [LaTeX customization](#latex-customization) for more information.

I was thinking to use the `header-includes` in filters to put necessary
"template" needed by the filter as well. But without the `-H` override the
`header-includes` it won't be stable.

It seems that at least there aren't specific reasons/situations when the
current behavior is preferred (that `-H` override `header-includes` in
YAML). May be we should make the change?

-- 
You received this message because you are subscribed to the Google Groups
"pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/ms
gid/pandoc-discuss/1902649a-ac7f-4715-a80e-9d9c3659e025%40googlegroups.com
<https://groups.google.com/d/msgid/pandoc-discuss/1902649a-ac7f-4715-a80e-9d9c3659e025%40googlegroups.com?utm_medium=email&utm_source=footer>
.

For more options, visit https://groups.google.com/d/optout.


-- 
You received this message because you are subscribed to the Google Groups
"pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/
msgid/pandoc-discuss/CADAJKhCfDzDaQYSn%3DiNzM0XXEpisontg%
3DLxrOadmHD6_6aNriw%40mail.gmail.com
<https://groups.google.com/d/msgid/pandoc-discuss/CADAJKhCfDzDaQYSn%3DiNzM0XXEpisontg%3DLxrOadmHD6_6aNriw%40mail.gmail.com?utm_medium=email&utm_source=footer>
.

For more options, visit https://groups.google.com/d/optout.

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CAFC_yuSvA%2BQ%3DOCBvBx4hCVMZft%3DhhXY-P96OUOGEQ2WB15ODGg%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #2: Type: text/html, Size: 6897 bytes --]

Re: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[Kolen Cheung]

[-- Attachment #1.1: Type: text/plain, Size: 3010 bytes --]

Ah... the whole point of this discussion is to get rid of custom template, 
either through a standalone template snippet, or a standalone filter, but 
not both.

On Friday, December 2, 2016 at 7:37:01 AM UTC-8, BP wrote:
>
> The simple solution would be for templates to contain something like this
>
> ````
> $for(filter-header-includes.<output_format>)$
> $filter-header-includes.<output_format>$
>
> $endfor$
> ````
>
> with filter authors being trusted to make sure that the relevant variable 
> is a MetaBlocks element where each child element is a RawBlock element of 
> the appropriate format. This wouldn't require any code changes at all, just 
> half an hour's work on the templates and some discipline on the part of 
> filter authors.
>
> /bpj
>
>
> Den 1 dec 2016 12:55 skrev "Kolen Cheung" <christi...-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org 
> <javascript:>>:
>
> I was browsing some pandoc filters and see this comment:
>
> > pandoc-crossref uses metadata variable `header-includes` to add LaTeX 
> definitions to output. However, Pandoc's command line option 
> `--include-in-header`/`-H` overrides this variable. If you need to use 
> `--include-in-header`, add pandoc-crossref-specific definitions as well. 
> See [LaTeX customization](#latex-customization) for more information.
>
> I was thinking to use the `header-includes` in filters to put necessary 
> "template" needed by the filter as well. But without the `-H` override the 
> `header-includes` it won't be stable.
>
> It seems that at least there aren't specific reasons/situations when the 
> current behavior is preferred (that `-H` override `header-includes` in 
> YAML). May be we should make the change?
>
> -- 
> You received this message because you are subscribed to the Google Groups 
> "pandoc-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an 
> email to pandoc-discus...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org <javascript:>.
> To post to this group, send email to pandoc-...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org 
> <javascript:>.
> To view this discussion on the web visit 
> https://groups.google.com/d/msgid/pandoc-discuss/1902649a-ac7f-4715-a80e-9d9c3659e025%40googlegroups.com 
> <https://groups.google.com/d/msgid/pandoc-discuss/1902649a-ac7f-4715-a80e-9d9c3659e025%40googlegroups.com?utm_medium=email&utm_source=footer>
> .
>
> For more options, visit https://groups.google.com/d/optout.
>
>
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/089593aa-75c3-42fb-9b94-1cf0c01643cd%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #1.2: Type: text/html, Size: 5738 bytes --]

Re: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[Melroch]

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

I mean the standard templates, but I don't see the point of "getting rid of
custom templates". The template and filter features are there because one
size does not fit all.

/bpj

Den 3 dec 2016 01:29 skrev "Kolen Cheung" <christian.kolen-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:

> Ah... the whole point of this discussion is to get rid of custom template,
> either through a standalone template snippet, or a standalone filter, but
> not both.
>
> On Friday, December 2, 2016 at 7:37:01 AM UTC-8, BP wrote:
>>
>> The simple solution would be for templates to contain something like this
>>
>> ````
>> $for(filter-header-includes.<output_format>)$
>> $filter-header-includes.<output_format>$
>>
>> $endfor$
>> ````
>>
>> with filter authors being trusted to make sure that the relevant variable
>> is a MetaBlocks element where each child element is a RawBlock element of
>> the appropriate format. This wouldn't require any code changes at all, just
>> half an hour's work on the templates and some discipline on the part of
>> filter authors.
>>
>> /bpj
>>
>>
>> Den 1 dec 2016 12:55 skrev "Kolen Cheung" <christi...-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:
>>
>> I was browsing some pandoc filters and see this comment:
>>
>> > pandoc-crossref uses metadata variable `header-includes` to add LaTeX
>> definitions to output. However, Pandoc's command line option
>> `--include-in-header`/`-H` overrides this variable. If you need to use
>> `--include-in-header`, add pandoc-crossref-specific definitions as well.
>> See [LaTeX customization](#latex-customization) for more information.
>>
>> I was thinking to use the `header-includes` in filters to put necessary
>> "template" needed by the filter as well. But without the `-H` override the
>> `header-includes` it won't be stable.
>>
>> It seems that at least there aren't specific reasons/situations when the
>> current behavior is preferred (that `-H` override `header-includes` in
>> YAML). May be we should make the change?
>>
>> --
>> You received this message because you are subscribed to the Google Groups
>> "pandoc-discuss" group.
>> To unsubscribe from this group and stop receiving emails from it, send an
>> email to pandoc-discus...-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
>> To post to this group, send email to pandoc-...-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
>> To view this discussion on the web visit https://groups.google.com/d/ms
>> gid/pandoc-discuss/1902649a-ac7f-4715-a80e-9d9c3659e025%40go
>> oglegroups.com
>> <https://groups.google.com/d/msgid/pandoc-discuss/1902649a-ac7f-4715-a80e-9d9c3659e025%40googlegroups.com?utm_medium=email&utm_source=footer>
>> .
>>
>> For more options, visit https://groups.google.com/d/optout.
>>
>>
>> --
> You received this message because you are subscribed to the Google Groups
> "pandoc-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To view this discussion on the web visit https://groups.google.com/d/
> msgid/pandoc-discuss/089593aa-75c3-42fb-9b94-1cf0c01643cd%
> 40googlegroups.com
> <https://groups.google.com/d/msgid/pandoc-discuss/089593aa-75c3-42fb-9b94-1cf0c01643cd%40googlegroups.com?utm_medium=email&utm_source=footer>
> .
> For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CADAJKhCkSC80BR8NDbFKArmRR%3D80DxxRXQYeEVcBVhiCgxWgYw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #2: Type: text/html, Size: 6255 bytes --]

Re: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[Kolen Cheung]

[-- Attachment #1.1: Type: text/plain, Size: 7738 bytes --]

So you mean sending a pull-request on that modification to the official 
default template? If @jgm accept it, it at least solves part of the 
problem: "embedding" the template in the filter so that filter can be 
standalone. But note that not only `header-include` but also the 
"before/after" kind of include should be included as well. So these 
"includes" alone would requires 3 additions per default templates, I'm not 
really sure if @jgm would accept this.

And the actual problem is even bigger, as long as an option can be 
configured both through YAML and cli, and can be applied repeatedly (i.e. a 
list), then it falls into this discussion. But this is the controversy, 
which behavior should be preferred? On one hand, being able to override the 
config in the documents through cli might be useful in batch processing. 
But as an author of the document, there should be a reason behind writing 
things *within* the documents and it is kind of odd it can be overridden 
*without* changing the markdown source. Even worse, this action is unknown 
to the author if it build successfully (at least not without manually 
reading the whole output document).

Note that @jgm said that to change pandoc such that the cli options will 
catenated with the YAML's:

> I don't think this would be too difficult a change.
> [Template snippet won't be resolved using `includes` such as `-H`, `-B`, 
`-A` · Issue #3138 · 
jgm/pandoc](https://github.com/jgm/pandoc/issues/3138#issuecomment-253728066)

So the only questions are really

1. would such change break current workflows
2. even if not, which behavior is preferred by the community

So far there's no report people are using the current behavior 
*intentionally* (i.e. their workflow benefit from the current behavior), 
but on the other hand, recall that the change made in the markdown writer 
about YAML delimiter: ended with `---` instead of `...`. People relying on 
the old behavior only start to complain when a new pandoc release 
implements the new behavior.


| -------- Digression ----------

A digression about the last point: this is kind of related to why even 
Apple nowadays offers beta release (which is so "un-Apple"), somethings 
just can't be caught by internal testings (or even a discussion group like 
this here). The end-users might do many "creative" things that the 
developers aren't aware of, and only knew when it is released (and 
end-users pissed...).

By having some kind of experimental releases (alpha/beta, etc.):

1. breaking change like the said YAML delimiter, or the current one in 
discussion (cli override YAML or not) can be releases in the experimental 
releases, which in principle should reach a much wider audiences (at least 
a significant part of the pandoc community are research students, who 
usually have the time, and like to, use beta softwares.)

2. include some changes that are just too incomplete to be in the stable 
pandoc release. Examples are #2818, or hypothetically an AST change which 
requires a change in all reader/writer-pairs, which is too daunting to do 
it all at once, but partial release is definitely not stable.

3. At least one of the major drawback is that it just complicated the 
release process. And I think it should be on a separate repository to not 
clutter the releases page.

| ----------------------------------

On Friday, December 2, 2016 at 4:38:30 PM UTC-8, BP wrote:
>
> I mean the standard templates, but I don't see the point of "getting rid 
> of custom templates". The template and filter features are there because 
> one size does not fit all. 
>
> /bpj
>
> Den 3 dec 2016 01:29 skrev "Kolen Cheung" <christi...-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org 
> <javascript:>>:
>
>> Ah... the whole point of this discussion is to get rid of custom 
>> template, either through a standalone template snippet, or a standalone 
>> filter, but not both.
>>
>> On Friday, December 2, 2016 at 7:37:01 AM UTC-8, BP wrote:
>>>
>>> The simple solution would be for templates to contain something like this
>>>
>>> ````
>>> $for(filter-header-includes.<output_format>)$
>>> $filter-header-includes.<output_format>$
>>>
>>> $endfor$
>>> ````
>>>
>>> with filter authors being trusted to make sure that the relevant 
>>> variable is a MetaBlocks element where each child element is a RawBlock 
>>> element of the appropriate format. This wouldn't require any code changes 
>>> at all, just half an hour's work on the templates and some discipline on 
>>> the part of filter authors.
>>>
>>> /bpj
>>>
>>>
>>> Den 1 dec 2016 12:55 skrev "Kolen Cheung" <christi...-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:
>>>
>>> I was browsing some pandoc filters and see this comment:
>>>
>>> > pandoc-crossref uses metadata variable `header-includes` to add LaTeX 
>>> definitions to output. However, Pandoc's command line option 
>>> `--include-in-header`/`-H` overrides this variable. If you need to use 
>>> `--include-in-header`, add pandoc-crossref-specific definitions as well. 
>>> See [LaTeX customization](#latex-customization) for more information.
>>>
>>> I was thinking to use the `header-includes` in filters to put necessary 
>>> "template" needed by the filter as well. But without the `-H` override the 
>>> `header-includes` it won't be stable.
>>>
>>> It seems that at least there aren't specific reasons/situations when the 
>>> current behavior is preferred (that `-H` override `header-includes` in 
>>> YAML). May be we should make the change?
>>>
>>> -- 
>>> You received this message because you are subscribed to the Google 
>>> Groups "pandoc-discuss" group.
>>> To unsubscribe from this group and stop receiving emails from it, send 
>>> an email to pandoc-discus...-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
>>> To post to this group, send email to pandoc-...-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
>>> To view this discussion on the web visit 
>>> https://groups.google.com/d/msgid/pandoc-discuss/1902649a-ac7f-4715-a80e-9d9c3659e025%40googlegroups.com 
>>> <https://groups.google.com/d/msgid/pandoc-discuss/1902649a-ac7f-4715-a80e-9d9c3659e025%40googlegroups.com?utm_medium=email&utm_source=footer>
>>> .
>>>
>>> For more options, visit https://groups.google.com/d/optout.
>>>
>>>
>>> -- 
>> You received this message because you are subscribed to the Google Groups 
>> "pandoc-discuss" group.
>> To unsubscribe from this group and stop receiving emails from it, send an 
>> email to pandoc-discus...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org <javascript:>.
>> To post to this group, send email to pandoc-...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org 
>> <javascript:>.
>> To view this discussion on the web visit 
>> https://groups.google.com/d/msgid/pandoc-discuss/089593aa-75c3-42fb-9b94-1cf0c01643cd%40googlegroups.com 
>> <https://groups.google.com/d/msgid/pandoc-discuss/089593aa-75c3-42fb-9b94-1cf0c01643cd%40googlegroups.com?utm_medium=email&utm_source=footer>
>> .
>> For more options, visit https://groups.google.com/d/optout.
>>
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/f57e9537-1701-4e48-8d1f-c3d9c43af24f%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #1.2: Type: text/html, Size: 11768 bytes --]

Re: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[Melroch]

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

Did I say anything about a pull request? I just pointed out the most
sensible way to do it.

Actually I think there should be four anchor points. Before the header (or
as near the top of the header as practical), at the end of the header,
before the user includes, before the body and after the body (but before
the user includes in both cases). The number of changes required is a
non-issue. The real issue is whether everyone -- filter authors, filter
library authors and jgm -- thinks this is the best way to do it. It
certainly seems so to me: maximum functionality with minimum added code
complexity. At the end of the day it does simply boil down to how both
filter authors and document authors should be able to inject code into
templates without trampling on each other's feet and without injections
showing up in inappropriate formats. There already is a mechanism for
injecting data into templates, but we need a separate namespace for doing
that with fillers, and subnamespaces for different output formats.

/bpj

Den 3 dec 2016 02:22 skrev "Kolen Cheung" <christian.kolen-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:

> So you mean sending a pull-request on that modification to the official
> default template? If @jgm accept it, it at least solves part of the
> problem: "embedding" the template in the filter so that filter can be
> standalone. But note that not only `header-include` but also the
> "before/after" kind of include should be included as well. So these
> "includes" alone would requires 3 additions per default templates, I'm not
> really sure if @jgm would accept this.
>
> And the actual problem is even bigger, as long as an option can be
> configured both through YAML and cli, and can be applied repeatedly (i.e. a
> list), then it falls into this discussion. But this is the controversy,
> which behavior should be preferred? On one hand, being able to override the
> config in the documents through cli might be useful in batch processing.
> But as an author of the document, there should be a reason behind writing
> things *within* the documents and it is kind of odd it can be overridden
> *without* changing the markdown source. Even worse, this action is unknown
> to the author if it build successfully (at least not without manually
> reading the whole output document).
>
> Note that @jgm said that to change pandoc such that the cli options will
> catenated with the YAML's:
>
> > I don't think this would be too difficult a change.
> > [Template snippet won't be resolved using `includes` such as `-H`, `-B`,
> `-A` · Issue #3138 · jgm/pandoc](https://github.
> com/jgm/pandoc/issues/3138#issuecomment-253728066)
>
> So the only questions are really
>
> 1. would such change break current workflows
> 2. even if not, which behavior is preferred by the community
>
> So far there's no report people are using the current behavior
> *intentionally* (i.e. their workflow benefit from the current behavior),
> but on the other hand, recall that the change made in the markdown writer
> about YAML delimiter: ended with `---` instead of `...`. People relying on
> the old behavior only start to complain when a new pandoc release
> implements the new behavior.
>
>
> | -------- Digression ----------
>
> A digression about the last point: this is kind of related to why even
> Apple nowadays offers beta release (which is so "un-Apple"), somethings
> just can't be caught by internal testings (or even a discussion group like
> this here). The end-users might do many "creative" things that the
> developers aren't aware of, and only knew when it is released (and
> end-users pissed...).
>
> By having some kind of experimental releases (alpha/beta, etc.):
>
> 1. breaking change like the said YAML delimiter, or the current one in
> discussion (cli override YAML or not) can be releases in the experimental
> releases, which in principle should reach a much wider audiences (at least
> a significant part of the pandoc community are research students, who
> usually have the time, and like to, use beta softwares.)
>
> 2. include some changes that are just too incomplete to be in the stable
> pandoc release. Examples are #2818, or hypothetically an AST change which
> requires a change in all reader/writer-pairs, which is too daunting to do
> it all at once, but partial release is definitely not stable.
>
> 3. At least one of the major drawback is that it just complicated the
> release process. And I think it should be on a separate repository to not
> clutter the releases page.
>
> | ----------------------------------
>
> On Friday, December 2, 2016 at 4:38:30 PM UTC-8, BP wrote:
>>
>> I mean the standard templates, but I don't see the point of "getting rid
>> of custom templates". The template and filter features are there because
>> one size does not fit all.
>>
>> /bpj
>>
>> Den 3 dec 2016 01:29 skrev "Kolen Cheung" <christi...-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:
>>
>>> Ah... the whole point of this discussion is to get rid of custom
>>> template, either through a standalone template snippet, or a standalone
>>> filter, but not both.
>>>
>>> On Friday, December 2, 2016 at 7:37:01 AM UTC-8, BP wrote:
>>>>
>>>> The simple solution would be for templates to contain something like
>>>> this
>>>>
>>>> ````
>>>> $for(filter-header-includes.<output_format>)$
>>>> $filter-header-includes.<output_format>$
>>>>
>>>> $endfor$
>>>> ````
>>>>
>>>> with filter authors being trusted to make sure that the relevant
>>>> variable is a MetaBlocks element where each child element is a RawBlock
>>>> element of the appropriate format. This wouldn't require any code changes
>>>> at all, just half an hour's work on the templates and some discipline on
>>>> the part of filter authors.
>>>>
>>>> /bpj
>>>>
>>>>
>>>> Den 1 dec 2016 12:55 skrev "Kolen Cheung" <christi...-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:
>>>>
>>>> I was browsing some pandoc filters and see this comment:
>>>>
>>>> > pandoc-crossref uses metadata variable `header-includes` to add
>>>> LaTeX definitions to output. However, Pandoc's command line option
>>>> `--include-in-header`/`-H` overrides this variable. If you need to use
>>>> `--include-in-header`, add pandoc-crossref-specific definitions as well.
>>>> See [LaTeX customization](#latex-customization) for more information.
>>>>
>>>> I was thinking to use the `header-includes` in filters to put necessary
>>>> "template" needed by the filter as well. But without the `-H` override the
>>>> `header-includes` it won't be stable.
>>>>
>>>> It seems that at least there aren't specific reasons/situations when
>>>> the current behavior is preferred (that `-H` override `header-includes` in
>>>> YAML). May be we should make the change?
>>>>
>>>> --
>>>> You received this message because you are subscribed to the Google
>>>> Groups "pandoc-discuss" group.
>>>> To unsubscribe from this group and stop receiving emails from it, send
>>>> an email to pandoc-discus...-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
>>>> To post to this group, send email to pandoc-...-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
>>>> To view this discussion on the web visit https://groups.google.com/d/ms
>>>> gid/pandoc-discuss/1902649a-ac7f-4715-a80e-9d9c3659e025%40go
>>>> oglegroups.com
>>>> <https://groups.google.com/d/msgid/pandoc-discuss/1902649a-ac7f-4715-a80e-9d9c3659e025%40googlegroups.com?utm_medium=email&utm_source=footer>
>>>> .
>>>>
>>>> For more options, visit https://groups.google.com/d/optout.
>>>>
>>>>
>>>> --
>>> You received this message because you are subscribed to the Google
>>> Groups "pandoc-discuss" group.
>>> To unsubscribe from this group and stop receiving emails from it, send
>>> an email to pandoc-discus...-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
>>> To post to this group, send email to pandoc-...-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
>>> To view this discussion on the web visit https://groups.google.com/d/ms
>>> gid/pandoc-discuss/089593aa-75c3-42fb-9b94-1cf0c01643cd%40go
>>> oglegroups.com
>>> <https://groups.google.com/d/msgid/pandoc-discuss/089593aa-75c3-42fb-9b94-1cf0c01643cd%40googlegroups.com?utm_medium=email&utm_source=footer>
>>> .
>>> For more options, visit https://groups.google.com/d/optout.
>>>
>> --
> You received this message because you are subscribed to the Google Groups
> "pandoc-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To view this discussion on the web visit https://groups.google.com/d/
> msgid/pandoc-discuss/f57e9537-1701-4e48-8d1f-c3d9c43af24f%
> 40googlegroups.com
> <https://groups.google.com/d/msgid/pandoc-discuss/f57e9537-1701-4e48-8d1f-c3d9c43af24f%40googlegroups.com?utm_medium=email&utm_source=footer>
> .
> For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CADAJKhDHskio7KYbEo0yXMvLQL%2BWYYWyh_gO3HNqwCTVRTJB8g%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #2: Type: text/html, Size: 12787 bytes --]

Re: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[Kolen Cheung]

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

Thanks, I understand more about what you said now.

Re: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[mb21]

[-- Attachment #1.1: Type: text/plain, Size: 1164 bytes --]

There are a few issues open around how the command line options and the 
YAML metadata fields interact.

https://github.com/jgm/pandoc/issues/3139
https://github.com/jgm/pandoc/issues/3115
https://github.com/jgm/pandoc/issues/3060

Should we consolidate this into one ticket with the docs label, or...? Is 
there such a ticket already?

@jgm How is this going to change in pandoc 2.0?
btw, maybe we should have a wiki page describing all the changes under way, 
or better yet: a "pandoc-2.0" label for all the issues? Also, have you 
decided when to merge the "typeclass" branch into master?

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/aed26351-9296-42f2-9711-94f029fb8b0d%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #1.2: Type: text/html, Size: 1874 bytes --]

Re: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[Kolen Cheung]

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

+1 on this, plus #3138.

After starting this thread: https://groups.google.com/forum/m/#!topic/pandoc-discuss/LIAfgkZKUiE
I realized the "fragmentation" between cli options and YAML options are non-trivial. Because YAML options will be preserved when doing `pandoc -t markdown -s ...`, but cli options are not. And there are problems with the variables under the section "Variables set by pandoc" in the MANUAL. e.g. i don't remember if setting `toc: true` in the yaml works or not, because it is supposed to be set automatically by pandoc when `--toc` is used.

I noticed that panzer is invented to solve this problem. Perhaps pandoc 2.0 can have a change on these matters, perhaps taking something from panzer's design.

On the other hand, pandoc 2.0, at least as far as the typeclass is concerned, are not meant to break backward compatibility for pandoc as a cli, but only for pandoc as a library (if I understand the 1.19.1 ANN correctly). But may be we should use this chance to break the compatility in cli too. Because this is what is expected from 2.0 anyway. Otherwise these potentially backward incompatibile change will either be never implemented or at least waiting for 3.0.

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/7bcf5965-a2fa-41d5-817e-bc27aeba7c7d%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[John MacFarlane]

+++ Kolen Cheung [Jan 17 17 10:24 ]:

>On the other hand, pandoc 2.0, at least as far as the typeclass is concerned, are not meant to break backward compatibility for pandoc as a cli, but only for pandoc as a library (if I understand the 1.19.1 ANN correctly). But may be we should use this chance to break the compatility in cli too. Because this is what is expected from 2.0 anyway. Otherwise these potentially backward incompatibile change will either be never implemented or at least waiting for 3.0.

I am not against breaking cli compatibility and in fact I
have already made a few small breaking changes.

However, I also don't want to pack so much into pandoc 2.0
that we never finish it.

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/20170118110317.GK42333%40Administrateurs-iMac-3.local.
For more options, visit https://groups.google.com/d/optout.

Re: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[John MacFarlane]

#2139 is also something I'd like to do something about.

Re: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[mb21]

[-- Attachment #1.1: Type: text/plain, Size: 798 bytes --]

Okay, I've started a wiki page to keep track of the major changes we've 
been thinking about.

https://github.com/jgm/pandoc/wiki/Roadmap

The idea is not to include all those in pandoc 2.0 but maybe we manage to 
do a few...

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/679bf64d-3de1-48e3-b738-0e9059c69a98%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #1.2: Type: text/html, Size: 1321 bytes --]

Re: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[John MacFarlane]

Great!  One change: We already have a LineBlock element!

+++ mb21 [Jan 23 17 02:13 ]:
>   Okay, I've started a wiki page to keep track of the major changes we've
>   been thinking about.
>   [1]https://github.com/jgm/pandoc/wiki/Roadmap
>   The idea is not to include all those in pandoc 2.0 but maybe we manage
>   to do a few...
>
>   --
>   You received this message because you are subscribed to the Google
>   Groups "pandoc-discuss" group.
>   To unsubscribe from this group and stop receiving emails from it, send
>   an email to [2]pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
>   To post to this group, send email to
>   [3]pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
>   To view this discussion on the web visit
>   [4]https://groups.google.com/d/msgid/pandoc-discuss/679bf64d-3de1-48e3-
>   b738-0e9059c69a98%40googlegroups.com.
>   For more options, visit [5]https://groups.google.com/d/optout.
>
>References
>
>   1. https://github.com/jgm/pandoc/wiki/Roadmap
>   2. mailto:pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
>   3. mailto:pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
>   4. https://groups.google.com/d/msgid/pandoc-discuss/679bf64d-3de1-48e3-b738-0e9059c69a98-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org?utm_medium=email&utm_source=footer
>   5. https://groups.google.com/d/optout

Re: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[mb21]

[-- Attachment #1.1: Type: text/plain, Size: 2189 bytes --]

Oh, awesome! Corrected in the wiki...


On Monday, January 23, 2017 at 11:24:25 AM UTC+1, John MacFarlane wrote:
>
> Great!  One change: We already have a LineBlock element! 
>
> +++ mb21 [Jan 23 17 02:13 ]: 
> >   Okay, I've started a wiki page to keep track of the major changes 
> we've 
> >   been thinking about. 
> >   [1]https://github.com/jgm/pandoc/wiki/Roadmap 
> >   The idea is not to include all those in pandoc 2.0 but maybe we manage 
> >   to do a few... 
> > 
> >   -- 
> >   You received this message because you are subscribed to the Google 
> >   Groups "pandoc-discuss" group. 
> >   To unsubscribe from this group and stop receiving emails from it, send 
> >   an email to [2]pandoc-discus...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org <javascript:>. 
> >   To post to this group, send email to 
> >   [3]pandoc-...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org <javascript:>. 
> >   To view this discussion on the web visit 
> >   [4]
> https://groups.google.com/d/msgid/pandoc-discuss/679bf64d-3de1-48e3- 
> >   b738-0e9059c69a98%40googlegroups.com. 
> >   For more options, visit [5]https://groups.google.com/d/optout. 
> > 
> >References 
> > 
> >   1. https://github.com/jgm/pandoc/wiki/Roadmap 
> >   2. mailto:pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org <javascript:> 
> >   3. mailto:pandoc-...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org <javascript:> 
> >   4. 
> https://groups.google.com/d/msgid/pandoc-discuss/679bf64d-3de1-48e3-b738-0e9059c69a98-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org?utm_medium=email&utm_source=footer 
> >   5. https://groups.google.com/d/optout 
>
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/5038f42b-77c9-4e63-a1ed-fbea1342828c%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #1.2: Type: text/html, Size: 6547 bytes --]

Re: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[Kolen Cheung]

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

Something like this could be in the "projects" page

Re: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[Albert Krewinkel]

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

Also related:

https://github.com/jgm/pandoc/issues/1960

Re: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[John MacFarlane]

+++ mb21 [Jan 17 17 09:54 ]:
>   There are a few issues open around how the command line options and the
>   YAML metadata fields interact.
>   [1]https://github.com/jgm/pandoc/issues/3139
>   [2]https://github.com/jgm/pandoc/issues/3115
>   [3]https://github.com/jgm/pandoc/issues/3060
>   Should we consolidate this into one ticket with the docs label, or...?

I see these as separate issues, so I'd favor keeping them
separate.

>   @jgm How is this going to change in pandoc 2.0?

No changes to this have yet been planned.

>   btw, maybe we should have a wiki page describing all the changes under
>   way, or better yet: a "pandoc-2.0" label for all the issues?

Ideally this would be good.  (And I wouldn't mind a
pandoc-2.0 label, so we could keep track of issues to come
back to after the typeclass branch has been merged.)

A wiki page probably exceeds what I have time for at the
moment, but if someone else wants to study the changes made
in the typeclass branch and write one, it would be welcome.

I've also got a personal list of changes to make in
typeclass, but it needs to be organized better before
I put it somewhere.  Also I'm waiting for feedback from
@jkr, who did the lion's share of the work in the changes
for pandoc 2.0.

>   Also, have
>   you decided when to merge the "typeclass" branch into master?

I think it's still premature, since I'm still not sure how
long it's going to take to get things to a stable state, and
we might want to release further versions in the 1.* series
if it takes a long time.

Re: Discussion needed—How should pandoc handle when meatada in YAML collide with command line option

[tolot27]

[-- Attachment #1.1: Type: text/plain, Size: 2019 bytes --]



> Note that @jgm said that to change pandoc such that the cli options will 
> catenated with the YAML's:
>
> > I don't think this would be too difficult a change.
> > [Template snippet won't be resolved using `includes` such as `-H`, `-B`, 
> `-A` · Issue #3138 · jgm/pandoc](
> https://github.com/jgm/pandoc/issues/3138#issuecomment-253728066)
>
> So the only questions are really
>
> 1. would such change break current workflows
> 2. even if not, which behavior is preferred by the community
>
> So far there's no report people are using the current behavior 
> *intentionally* (i.e. their workflow benefit from the current behavior), 
> but on the other hand, recall that the change made in the markdown writer 
> about YAML delimiter: ended with `---` instead of `...`. People relying on 
> the old behavior only start to complain when a new pandoc release 
> implements the new behavior.
>

I run into the overiding problem too and created the issue #4328 
<https://github.com/jgm/pandoc/issues/4328>. My original problem is that I 
add dynamic content to header-includes using a lua filter (https://github.com/pandoc/lua-filters/pull/12). 
With the cli parameter -H/--include-in-header it gets always overwritten 
and there is no workaround to circumvent this. Merging of metadata was 
already implemented for yaml files and yaml blocks using left-union. I vote 
the same for -H/--include-in-header.

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/3b614a95-7ade-4fb3-bf79-39d63b51a038%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #1.2: Type: text/html, Size: 3526 bytes --]