jgm / doctemplates Goto Github PK

Currently, only the predefined set of pipes is supported. A way to specify custom pipes through the API might be nice.

This should be accomplishable by identifying a pipe through it's Text name instead of through a predefined Pipe constructor and looking the name up in a map (something along the lines of TemplateTarget a => [(Pipe, Val a -> Val a)]) when applying the pipe instead of through a pattern match directly. Such a map could then be provided through the API if extra pipe functionality is desired.

A downside would be that that would lose some safety, invalid pipes could not be detected during parsing but only on compilation of the template. It would also add some complexity, but not much (I think).

What do you think?

The error is:

src/Text/DocTemplates.hs:104:27: error:
    • No instance for (Semigroup Template)
        arising from the 'deriving' clause of a data type declaration
      Possible fix:
        use a standalone 'deriving instance' declaration,
          so you can specify the instance context yourself
    • When deriving the instance for (Monoid Template)
    |
104 |                  deriving Monoid
    |                           ^^^^^^

When the pandoc output format is beamer (which uses the default template extension of .latex) and using a custom pandoc latex template which includes partials with no extension, pandoc cannot compile a document due to looking for the partials with the .beamer extension. When the partials are referenced explicitly with the .latex extension pandoc compiles successfully.

$ pandoc --version
pandoc 3.1.2

Is there a way to throw an error if there is a missing variable instead of defaulting to blank?

Can we get the file name of a partial from a variable?
This would be useful for customizing pandoc template, e.g. we would be able to refer to different
partial files in the pandoc frontmatter to be included in the template.

Conceptual example:

${ $partial-file-name$() }

I can not get it to work with the current incarnation of doctemplates.
This might be by design.

Hi,
I don't know if it's complicated but it would be nice to have some
functions (plus, minus...).

Something like that :
https://shopify.github.io/liquid/filters/plus/
https://shopify.github.io/liquid/filters/minus/

Best regards

Trying to build 0.8.2 against hsyaml-0.1.20

Building library for doctemplates-0.8.2..
[1 of 3] Compiling Text.DocTemplates.Internal ( src/Text/DocTemplates/Internal.hs, dist/build/Text/DocTemplates/Internal.o, dist/build/Text/DocTemplates/Internal.dyn_o )

src/Text/DocTemplates/Internal.hs:43:19: error:
    Module ‘Data.YAML’ does not export ‘ToYAML(..)’
   |
43 | import Data.YAML (ToYAML(..), FromYAML(..), Node(..), Scalar(..))
   |                   ^^^^^^^^^^

While trying to add support for association lists, I noticed that there's a comment in the source code asking why ToContext String String is needed. I am still not sure about association lists, but can address the comment now. However, I do not know what @jgm would like to have and thus did not make a PR.

The core issue is that GHC only looks at the target constraints when resolving overlapping instances. The constraints in the contexts are not used. Taking String for example, only these two parts matter:

instance ... ToContext a [b] where

instance ... ToContext a a where

For any code involving ToContext [a] [a], GHC would have trouble determining which instance to use, regardless of whether the contexts of the instances could be satisfied. String = [Char] is a special case of [a]. The current code provides a special instance ToContext String String (that is, ToContext [Char] [Char]) but GHC would still have trouble for the following cases:

ToContext [a] [a] -- actually, the situation might have become worse with `ToContext String String`
ToContext (Doc a) (Doc a)
ToContext (M.Map Text a) (M.Map Text a)
ToContext Bool Bool
ToContext Value Value

I am not sure what to do here. To what degree we want to solve the issue of overlapping instances? Some instances such as ToContext Bool Bool look strange to me, but on the other hand, there is no technical obstacle in supporting them. (The only needed constraint for Bool Bool is HasChars Bool, which looks weird but again technically possible.) Let me stop here.

Explain the problem.
The Reveal.js center option does not trigger, due to it being default true and its not possible to set it to false.

As explained in jgm/pandoc#7105 the centering does not trigger, when centering is set to false.
jgm said, that the template language does not support some kind to check the definedness of a value, therefore does not support this currently.

A possible fix is to add the center parameter as dont_center and then set center: !$center$.
This is counter intuitive and should be documented for anybody to find this.

I can't estimate how often such "default true" parameters happen to appear, but a better fix would of course be to add a definedness check

In the example below, I would expect that $pages.slug$ always refers to the item of the outer loop, even inside the inner loop. From what I could gather, there appears to be no way to access the outer slug from within the inner for loop. Is this the expected behavior?

data.md:

---
title: nested arrays
pages:
  - slug: page-1
    subpages:
      - slug: subpage-1
      - slug: subpage-2
  - slug: page-2
    subpages:
      - slug: subpage-1
      - slug: subpage-2
---

template.md:

$for(pages)$
/$pages.slug$
$for(pages.subpages)$
  /$pages.slug$/$pages.subpages.slug$
$endfor$
$endfor$

$ pandoc --template=template.md data.md
/page-1
  /subpage-1/subpage-1
  /subpage-2/subpage-2
/page-2
  /subpage-1/subpage-1
  /subpage-2/subpage-2
$ pandoc --version
pandoc 2.11.2
Compiled with pandoc-types 1.22, texmath 0.12.0.3, skylighting 0.10.0.3,
citeproc 0.2, ipynb 0.1.0.1
User data directory: /home/mfsch/.local/share/pandoc or /home/mfsch/.pandoc
Copyright (C) 2006-2020 John MacFarlane. Web:  https://pandoc.org
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.

(moved from jgm/pandoc#2952)
YAML seems to understand timestamps: http://www.yaml.org/spec/1.2/spec.html
You it be possible to add support for timestamps in markdown variables?
Something like:

mydate: 2015-12-31
...
$mydate.year$ $mydate.month$ $mydate.day$

I want to use the template partials and make a conditional on the number of authors. Is there a way to do something like $if(author/length>1)$?

In pandoc 2.5, a template with an unmatched template conditional causes pandoc to fail with an error:

$ cat test.md 
Foo.
$endif$

$ echo 'Test' | pandoc --template=test.md
[WARNING] This document format requires a nonempty [...]
"template" (line 2, column 7):
unexpected "$"

Any non-keyword (e.g. $endi$) is replaced by an empty string and a document is created. While the error message indicates the correct position, it should also include the keyword, i.e. "template" (line 2, column 7): unexpected "$else$"

Hi!

I would like to propose to add the possibility to include templates written in a different format in a way that they are translated to another target format.

Use Case

In scientific oder technical documents it is often necessary to include a certain front- and back-matter including e.g. tables with legal information, change records and general preamble sections which partly come before and after the TOC or other templated sections. With partial translation, these parts could be once prepared in a format and then be included in templates for many different other formats, rendering the need to synchronize many different complete templates when changing e.g. front-matter styling obsolete. So there could be "one source of truth" to populate many different templates.

Current state

Currently we use chains of multiple pandoc conversation steps to prepare documents including this header information. This way we can start from a common markdown template for the front- and backmatter and still convert to any final format. But this introduces some problems, as pandoc lacks the knowledge of the final target format in earlier steps resulting in different hiccups with e.g. the TOC and even some markup-errors like intertwined tags in html (like <p></nav></p> which is invalid).

Proposed solution

Include an option or a pipe to render a partial from another format to a given target format, defaulting to the target format of the including template when none is given.

Thanks and have a good time!

Jörn

It would be nice, if it were possible to include other files into the template.

e.g.

This is some text. 

$include table.txt$

Some other text

I have found that I seem to be able to force the conversion of a JSON variable when it is used for interpolation in a template by using xx.c to force conversion to a character string. Without the appended .c the variable is included as a boolean.

The ReadMe file states:

When a Context is derived from an aeson (JSON) Value, the following conversions are done:

    If the value is a number, it will be rendered as an integer if possible, otherwise as a floating-point number.

which hints that my accidental discovery is intentional in the code - but I cannot discover where in the source this is done.

Would it be possible to add a list of the respective codes to the ReadMe file? Thank you!

Something like

$forpairs(meta)$
- $meta.key$: $meta.value$
$endforpairs$

And when forpairs is applied to a regular array, key should be set to the index (starting with 1). This would allow us to create numbered lists, for example:

$forpairs(items)$
$item.key$. $item.value.name$ ($item.value.price$)
$endforpairs$

An alternative approach would be to provide some general mechanism for turning a map into an array with key/value objects:

$for(meta/pairs)$
$it.key$ = $it.value$
$endfor$

$meta/pairs:partial()$

Thinking ahead, the / could perhaps be reserved for filters that alter a variable:

$date/iso8601$
$name/uppercase/underscores$

@mb21

Just a heads-up: pipes are called, well, "pipes" in the readme, the Pandoc manual and the code itself, but in the haddock doc they're called "filters".

Is that intentional? Using the same name consistently would probably be a good idea to prevent confusion.

This is a proposal to add a new pipe transform that will remove whitespace from a variable's value. (recommended name: strip)

Example usage:

---
var: My Variable
---

...

$var/strip$ -> MyVariable

My usage for this would be for generating CSS class/id names from variables in an html template (which hold chapter/section names). There are probably many other use cases.

It would be nice to use a delimiter other than '$' in my source. As far as I can tell, if we add to Text.DocTemplates.Parser PState the following fields:

data PState =
  PState { ...
         , delimiter :: Char
         , delimiterString :: String
         , doubleDelString :: String
         }

(which are '$', "$", and "$$", by default), then we can access those within the parsing functions.

What do you think?