Docbook to GFM: When the <note> element has no <title>, it's not converted to the note markdown representation

[tomaskrulis]

I would like to ask the community about the following behavior:

I have the following docbook XML as an MWE:

<?xml version="1.0"?>
<section xmlns="http://docbook.org/ns/docbook" xmlns:xinfo="http://ns.expertinfo.se/cms/xmlns/1.0" xml:id="UUID-ec928802-2645-4d29-3bc6-b59da32feeed" version="5.0" xml:lang="en" xinfo:resource="UUID-ec928802-2645-4d29-3bc6-b59da32feeed" xinfo:resource-id="2201157" xinfo:resource-type="component" xinfo:resource-title="Standard app article template - Jen" xinfo:resource-titlelabel="" xinfo:version-major="1" xinfo:version-minor="0">
  <title>Note test.</title>
      <note>
        <para>A note without title not recognized, regardless of the <code>alerts</code> extension.</para>
      </note>
        <para>Spacer.</para>
    <note>
      <title>
        A note with a title. Works, but the title is discarded.
      </title>
      <para>Some content</para>
    </note>
  </section>

The first <note> element doesn't have the <title>, the second does.

WIth the current pandoc version, when converting with:

pandoc -f docbook -t gfm --wrap=none -o mwe.md mwe.xml

I get the following conversion result:

# Note test.

<div class="note">

A note without title not recognized, regardless of the `alerts` extension.

</div>

Spacer.

> [!NOTE]
> Some content

It seems like the <note> has to have the <title> element to be recognized as a note. Even empty <title> element makes it work.

Is this intended? Would it be possible to make the <title> element within the <note> element optional?

I think that the responsible part in the Markdown writer is this: permalink to the blockToMarkdown' function.

Thank you for any guidance on this!

[jgm]

Not sure whether it would be better to improve this by (a) having the docbook reader add an empty title Div or by (b) having the markdown writer not care about whether the title Div is present.

(a) is a bit more conservative; it only affects docbook. (b) might risk capturing things that aren't intended as admonitions? I'm not sure.

Here's a patch that works for (b):

diff --git a/src/Text/Pandoc/Writers/Markdown.hs b/src/Text/Pandoc/Writers/Markdown.hs
index 941557e0e..f833d669c 100644
--- a/src/Text/Pandoc/Writers/Markdown.hs
+++ b/src/Text/Pandoc/Writers/Markdown.hs
@@ -372,15 +372,23 @@ blockToMarkdown' opts (Div attrs@(_,classes,_) bs)
   | isEnabled Ext_alerts opts
   , (cls:_) <- classes
   , cls `elem` ["note", "tip", "warning", "caution", "important"]
-  , (Div ("", ["title"], []) _ : Para ils : bs') <- bs
-   = blockToMarkdown' opts $ BlockQuote $
-       (Para (RawInline (Format "markdown") (case cls of
-         "note" -> "[!NOTE]\n"
-         "tip" -> "[!TIP]\n"
-         "warning" -> "[!WARNING]\n"
-         "caution" -> "[!CAUTION]\n"
-         "important" -> "[!IMPORTANT]\n"
-         _ -> "[!NOTE]\n") : ils)) : bs'
+   = do let admonition =
+              case cls of
+                 "note" -> "[!NOTE]"
+                 "tip" -> "[!TIP]"
+                 "warning" -> "[!WARNING]"
+                 "caution" -> "[!CAUTION]"
+                 "important" -> "[!IMPORTANT]"
+                 _ -> "[!NOTE]"
+        let dropTitle (Div ("", ["title"], []) _ : bs') = bs'
+            dropTitle bs' = bs'
+        variant <- asks envVariant
+        let leader
+             | isEnabled Ext_literate_haskell opts = " > "
+             | variant == PlainText = "  "
+             | otherwise            = "> "
+        contents <- blockListToMarkdown opts (dropTitle bs)
+        pure $ prefixed leader (admonition $$ contents) <> blankline
   | otherwise = do
     contents <- blockListToMarkdown opts bs
     variant <- asks envVariant

[tomaskrulis]

I am not successful with the insert function either:

local formats = {
  'markdown',
  'gfm',
  'json',  -- testing
  'native' -- testing
}

local admonitions = {
  'note',
  'caution',
  'warning',
  'tip'
}

function Div(elem)
  for _, format in ipairs(formats) do
    if FORMAT:match(format) then
      for _, admonition in ipairs(admonitions) do
        if elem.classes:includes(admonition) then -- OK
          for _, block in ipairs(elem.content) do
            if block.t == 'Div' and block.classes:includes('title') then -- OK
              return nil
            else
--              return pandoc.Str("test") -- works, the original Div is replaced
              return elem.content:insert(pandoc.Div("",
                pandoc.Attr('', {'title'}, {}))) -- no insertion happens
            end
          end
        end
      end
    end
  end
end

It seems to me like I am making a syntax error or that I am not grasping a bit of the concept of creating new Div elements.

I tried also elem.content:insert(1, pandoc.Div("", pandoc.Attr('', {'title'}, {}))) ; the other way around elem.content:insert(pandoc.Div("", pandoc.Attr('', {'title'}, {})), 1) gives me a syntax error.

[jgm]

Right, the index has to come first, I always forget the order.

I think what you want is

elem.content:insert(1, pandoc.Div("", pandoc.Attr('', {'title'}, {})))
return elem

[tomaskrulis]

This works perfectly, thank you! I tried a few options, didn't try to separate the insert method call and the return statement. I thought that the insert returns the modified list.

If it's OK, I will wait for follow-up discussion, but if there's none, I would mark the lua filter as a solution, since it achieves the result I need without any potential breaking changes :)

[jgm]

I still think we should do either (a) or (b) in pandoc. Neither is difficult. You could open an issue for this?

[tomaskrulis]

Sure thing, I created: #9590

Labeled as a feature request, since it doesn't seem like this is a "bug" per se.