Custom writers: Adding a file header with pandoc.scaffolding

[bpj]

I'm trying to write a custom writer for Perl's Pod documentation format with the help of pandoc.scaffolding.

A Pod file should start with a "paragraph" declaring the encoding of the file, in this case always

=encoding UTF-8

otherwise Latin-1 will be assumed for historical reasons.

I suppose this should be added in a function called Writer.Blocks.Pandoc; is this correct and if so how should I go about it specifically? Should I return a list consisting of the header and the value passed to the function or in some other way?

[massifrg]

The function should be pandoc.scaffolding.Writer.Pandoc.

Here's why I think so:

$ pandoc lua
Lua 5.4.6  Copyright (C) 1994-2023 Lua.org, PUC-Rio
Embedded in pandoc 3.1.13
> pandoc.scaffolding.Writer
table: 0x7fcf5a90d240
> for k,v in pairs(pandoc.scaffolding.Writer) do print(k) end
Block
Inline
Blocks
Pandoc
Inlines
> pandoc.scaffolding.Writer.Pandoc
function: 0x7fcf5a8f7680

For the return value, the documentation says:

The render functions must return a string, a pandoc.layout Doc element, or a list of such elements.
In the latter case, the values are concatenated as if they were passed to pandoc.layout.concat.
If the value does not depend on the input, a constant can be used as well.

[tarleb]

Exactly. The default implementation for Pandoc basically does the equivalent to

Writer = pandoc.scaffolding.Writer
function Writer.Pandoc (doc, opts)
  return Writer.Blocks(doc.blocks)
end

So something like this should work:

function Writer.Pandoc (doc, opts)
  return {'=encoding UTF-8\n', Writer.Blocks(doc.blocks)
end

[bpj]

I realized that this probably should go in a template.I'll see how that goes and open (an)other question(s) for that if needed.