jq manual remake

[01mf02]

I would like to extend the jq manual with information about diverging behaviour between different jq implementations (jq, gojq, jaq, ...). For this, I will have to go through the whole manual once, which I think would be a nice opportunity to adapt its format.

Currently, the jq manual is written as a YAML file, which mostly contains Markdown blocks and examples. I thought about transforming it to a pure Markdown file, and then creating HTML from it via Pandoc. The advantages of this would be:

• syntax highlighting of JSON / jq code
• smaller input file
• better support for editing (e.g. spellchecking)

To show the feasibility of it, I recreated a part of the "Conditionals and Comparisons" section of the jq manual in Markdown. You can use

pandoc conds.md -s -o conds.html --section-divs --lua-filter filter.lua

to render this to the following HTML (sorry, GitHub doesn't let me upload HTML directly, so I exported the HTML to PDF and uploaded that).

This requires the file filter.lua, which I wrote today in about 2 hours (I don't know Lua ^^) and which currently looks like this:

function Header(el)
  if el.content[1].text == "Examples" then
    --print(dump(el))
    el.attr.classes:insert("examples")
  end
  return el
end

function Code(code)
  code.classes[1] = "jq"
  --print(dump(code))
  return code
end

function CodeBlock(block)
  --print(dump(block))
  --if block.classes[1] == "jq-test" then
  rows = {}
  categories = {"Filter", "Input", "Output"}
  local i = 1
  for line in block.text:gmatch("[^\n]+") do
    local code = pandoc.Code(line)
    local lang = "json"
    if i == 1 then lang = "jq" end
    code.classes[1] = lang
    table.insert(rows, {pandoc.Plain(categories[i] or ""), code})
    i = i + 1
  end
  simple_table = pandoc.SimpleTable(
    "", -- caption
    {pandoc.AlignDefault, pandoc.AlignDefault},
    {0, 0}, -- let pandoc determine col widths,
    {}, -- headers
    rows
  )
  return pandoc.utils.from_simple_table(simple_table)
end

I am fairly confident that I would be able to convert the whole manual to this Markdown format. But I'm only going to do this if it's likely that this is going to be merged into jq. So the question is: Would you consider merging such a change?