Suggestion: Implement `html_to_docbook()` function in EML package

[sannegovaert]

Overview

We have developed the html_to_docbook() function in the R package movepub, which converts HTML-formatted text to DocBook markup. We propose to implement this functionality directly within the EML package.

Rationale

Movepub streamlines the publication of animal tracking data from Movebank to the Global Biodiversity Information Facility (GBIF). When converting Movebank metadata to EML with movepub::write_eml(), we aim to support rich text formatting (e.g., bold, hyperlinks) in dataset descriptions.

The only consistent way to provide rich text that:

• passes EML validation,
• is accepted by the Integrated Publishing Toolkit (IPT), and
• displays correctly on GBIF.org

is to follow the EML specification for <para> elements, using a subset of DocBook syntax.

While EML::set_TextType() addresses this partially, it is difficult to use and only works for external files—not for inline text strings.

See related discussion and evaluation of alternatives in movepub issue #101.

Proposed Solution

After reviewing several options, we implemented a custom converter for movepub that transforms HTML syntax into DocBook, splitting paragraphs and headers into separate elements.

Benefits of integrating this into EML:

• It is a better fit for EML than for movepub, because it is specifically desgined for EML para
• More users can prepare EML with rich text descriptions using familiar HTML syntax.
• Ensures interoperability with IPT and GBIF.org.
• Reduces duplicated effort across EML-related packages.

Implementation reference:

• html_to_docbook() in movepub

Reproducible example

library(movepub)
html <- "This is <b>bold</b>.\nParagraph 1\n\nParagraph 2<p></p>What follows is a list: <ul><li>Item 1</li><li>Item 2</li></ul>"
html_to_docbook(html)
#> [1] "This is <emphasis>bold</emphasis>."                                                                                                   
#> [2] "Paragraph 1"                                                                                                                          
#> [3] "Paragraph 2"                                                                                                                          
#> [4] "What follows is a list: <itemizedlist><listitem><para>Item 1</para></listitem><listitem><para>Item 2</para></listitem></itemizedlist>"

^{Created on 2025-10-15 with reprex v2.1.1}

Next Steps

• Would the maintainers be receptive to integrating this converter?
• We can provide a PR or collaborate on adapting the code to EML’s conventions and requirements.

[jeanetteclark]

This looks like a great tool. I'm not a maintainer of this package but am frequent flier and sometimes contributor and I can definitely say that it could use something along these lines. Some relevant background reading is here: #298. I don't think we ever made any headway on that issue though, so any contribution to make formatting text a bit easier would be welcome I think.

Seems to me that this functionality could be incorporated into set_textType. set_textType nominally supports inline text as a character string (using the text argument) but in my testing just now I'm not sure that it actually does anything. Although set_textType currently targets markdown and docx as the input, I don't see any reason why it can't also look at html.

Can I ask why you are targeting docbook instead of markdown? Since EML 2.2.0 came out we have used the markdown element pretty regularly, though we run into similar issues where the R package doesn't support it that well, so our team mostly resorts to editing the xml doc by hand 😬 .

[mbjones]

Fully agree with @jeanetteclark that this would be a great addition -- thanks for working on it! We have been steering people towards using Markdown for formatting in text elements rather than the docbook-derived structures, mainly because we have seen difficulty for tools to work with the docbook elements. So, an option to serialize the formatted text either as a docbook block or as a markdown block would be useful, as it would enable a more seamless transition to markdown. The docbook tags have proven onerous enough that the core editing team for EML considered completely removing that in 2.2.0 in favor of markdown -- we only kept it to minimize backwards compatibility issues. So, can we support both, or at least leave a pathway for supporting both?

[sannegovaert]

Can I ask why you are targeting docbook instead of markdown? Since EML 2.2.0 came out we have used the markdown element pretty regularly, though we run into similar issues where the R package doesn't support it that well, so our team mostly resorts to editing the xml doc by hand 😬 .

Of course! I am also not a big fan of Docbook, but GBIF does not handle markdown in EML (see this issue) because Markdown support doesn't include multilingual support.
So for our goals (publishing on GBIF), we can only use Docbook.