inline code vs monospace in JATS

[castedo]

I am wondering if anyone has advice or suggestions regarding a technicality I am hammering out in a small dialect of JATS (Baseprint JATS [1]) which is output by a pandoc wrapper tool (named "Baseprinter" [2], developed by me).

As best I can tell, JATS has no commonly used XML elements or transformation to HTML where a distinction is made between these two cases of "presentational semantics":

1. display in a monospace font (but otherwise look like adjacent text)

2. display in a monospace font and MORE visual distinction like color change, background change, and/or border (e.g., styling for inline "code" by Bootstrap CSS, GitHub and Wikipedia)

This is roughly the de-facto presentational semantics of HTML <tt> vs HTML <code>.

PubMed Central JATS XML articles with inline code only gets transformed into (1) and never (2), via the JATS <monospace> element. The JATS <code> element is not inline like the HTML <code> element. There is no equivalent to the HTML <code> element in JATS.

HTML has many tags for code-like text which are styled in different ways depending on the website, namely <tt>, <kbd>, <samp>, and <code>. In part due to these many HTML tags, the markdown dialects for Wikipedia and GitHub have mechanisms for authors to choose (1) or (2).

Currently pandoc converts inline verbatim markdown (using backticks) into a "Code" type data structure and then a JATS element.

My current plan is to use an XML attribute/value of specific-use="code" for JATS <monospace> and the markdown inline attribute {specific-use=code} after verbatim back-ticks. Pandoc currently recognizes this attribute and will perform this markdown-to-JATS conversion.

Since some authors (like me) probably want the specific-use="code" by default for all inline verbatim markdown, I am thinking of adding a Lua filter to the Baseprinter tool. I figure there is a way to have a Lua filter add this automatically when it detects a particular flag in the document metadata.

I am disinclined to have Baseprint JATS readers automatically convert <monospace> to Bootstrap/GitHub/Wikipedia code styling because:

A) PubMed Central does not do this,
B) not all verbatim text is code, and
C) it seems reasonable that some authors might want just a slight visual change in text (a
la PubMed Central) but not as much "ink" as what Bootstrap/GitHub/Wikipedia styling adds to code text.

I'm also disinclined to start resorting to the JATS <styled-content style="..."> element/attribute because it will be over-specific and not let websites render code in different CSS styles (e.g. Bootstrap CSS, GitHub and Wikipedia make slightly different trade-offs and attempt dark mode support).

To me, it's a bit like single vs double quote or italic vs bold. One can argue about semantics, but the de-facto reality is there are two options that are very similar and sometimes authors want one vs other, but don't need to get into the exact precise presentational details of each of the two alternatives, but there are some rough de-facto presentional expectations.

Thank you for any advice, warnings, suggestions, wisdom on this inline verbatim text distinction.

[1] https://perm.pub/DPRkAz3vwSj85mBCgG49DeyndaE/
[2] https://try.perm.pub/baseprinter/

[denismaier]

I'm not sure @specific-use should be used for this, see https://jats.nlm.nih.gov/publishing/tag-library/1.1/attribute/specific-use.html

This Tag Set does not limit the uses of the @specific-use attribute. For example, @specific-use could be used to mark content (such as a paragraph, note, or section) that:
- only appears in one format (“web-only”, “print-only”, “voice-only”, “electronic-only”);
- is intended for a particular audience (the set “for-teachers” versus the set for “for-students”, or the sets “for-doctors”, “for-nurses”, or “for-the-patient”);
- is organization-sensitive material (“company-only” or “limited-distribution”) and thus not shown to all audiences;
- has a specific use that cannot be determined from the content of the material, for example, is part of continuing medical or legal education (“CME”); or
- contains an accessibility alternative that screen readers could “read” but that visual display devices would ignore. (See also the @alt attribute.)

But:

Best Practice: This attribute is not used to make semantic distinctions; the attribute @content-type is more appropriate to tell, for example, “skeletal” system material, “circulatory” system material, and “lymphatic” system material, or “legal” material from “engineering” material. The @specific-use attribute is used to make usage or processing distinctions, for example, audience or sorting distinctions. The attributes can be used together, for example, to mark “content-type="dosage" specific-use="for-the-patient"”. The attribute can also be used in combination with the @xml:lang attribute to indicate, for example, that a name given in a second language is a transliteration of the primary name. This attribute is not appropriate for differences in appearance; the element is typically better for that use. Nor should this attribute be used to record lifecycle or version distinctions.

[castedo]

Good tip on @content-type. I haven't really looked into that because it's not an attribute of <monospace>. But it is an attribute of <named-content> which I now see seems to be closer in spirit to the HTML <tt> vs <code> distinction: https://jats.nlm.nih.gov/archiving/tag-library/1.4/element/named-content.html "Word or phrase whose content/subject matter has distinct semantics or content-related significance. ... such semantic content is likely to be treated differently, for example, given a stand-out typographic style ... background shading."

I'm going to investigate how <named content> is getting used in archived XML in the PubMed Central Open Subset. That might shed some light on existing relevant XML rendering.

[castedo]

I see a great variety of uses of <named-content content-type= in PMC, ranging from incredibly presentation specific, like content-type="color:#0071c4", to very semantic like content-type="'teaching-point". So it looks like it's getting used in a number of publisher-specific ways with no particular standard for how these content types should be rendered into HTML/CSS (apart from the CSS color styles, but it seems those should be <styled-content>).

[castedo]

@denismaier Thanks for suggesting not using @specific-use! I'm currently thinking of following your suggestion and instead doing this:

Some [`inline code`]{content-type=code} in markdown.

which pandoc turns into the following JATS:

<p>Some
<named-content content-type="code"><monospace>inline code</monospace></named-content>
in markdown.</p>

For convenience I'm thinking of adding some functionality (perhaps a Lua filter) to have this wrapping automatically when an author does just back-ticks for verbatim inline text. Regardless, the example output JATS above seems a better approach.

[castedo]

Or even better:

Some ['inline code`]{.code} in markdown.

generates the same JATS above.

[castedo]

<named-content> is not a great option currently because currently PMC transforms this to HTML <em>. But computer code really should not be styled as italic.

[denismaier]

what about using styled-content? Does PMC always transform this named-content to <em> regardless of the value of @content-type? I use my own xsl to convert the jats xml to html so I can take care of these issues.

[castedo]

So far from all my searching/inspections of XML in the Open Access Subset and testing the PMC Article Viewer it appears <named-content> is indeed getting transformed to HTML <em> regardless of the value of @content-type. I've emailed PMC to see whether they want to stick to this behavior or change to transform to <span>. Interoperability with pandoc will definite suffer if PMC wants to stick to <named-content> meaning HTML <em>.

Regarding <styled-content>, I am very disinclined to add <styled-content> to Baseprint JATS XML (in BpDF) [1] because

1. BpDF is not supposed to be a format of most JATS XML doc in existence
2. a principle of "established presentational variation preferable to fixed presentation"

The <style-content> element is basically begging authors to violate 2. and it's very much not clear what CSS properties are permitted or not. For instance, Europe PMC appears to blind complete copy all CSS in <styled-content> and inject all of the CSS into HTML. This seems like just asking for all kinds of trouble and problems. So at the moment I think <styled-content> should not be in BpDF. I'm cooking up something analogous to CSS but for JATS to address this issue. I'm probably going to call it GSS (for Guideline Style Sheets).

However I do have a goal of graceful degradation in PMC pipelines [3]. So maybe <styled-content> would enter the picture when BpDF is transformed to proper PMC JATS XML (after processing the assigned GSS) I Already have XSTL that does transformation to proper PMC JATS [4]. However BpDF to proper PMC JATS transformation is not something anybody is asking for so i'm not sure how relevant it is. And GSS processing is too advanced for XSTL. No sane person will want to use XSTL for GSS processing.

[1] https://perm.pub/DPRkAz3vwSj85mBCgG49DeyndaE/
[2] singlesourcepub/baseprints#13
[3] singlesourcepub/baseprints#12
[4] https://gitlab.com/perm.pub/epijats/-/tree/main/compat/pmc/fakestyle

[castedo]

For a number of reasons (partly because of the "CSS for JATS" idea), another path I'm considering is making Baseprint XML of BpDF a combination of a small subset of JATS + a small subset of XHTML. The way tables are handled in JATS is essentially taking this approach of just adding a subset of XHTML to JATS. So in this case <span class=> would be added to Baseprint XML. This has lots of tricky issues yet to be thought out.

[castedo]

More details on my plan to use XHTML rather than HTML-like JATS elements is at singlesourcepub/baseprints#18

So for inline code vs monospace I plan to use XHTML and not JATS. If there is reason to transform XHTML to JATS (not clear there is any reason) then inline HTML gets transformed to JATS and there is some loss of information. No such loss of information occurs transforming XHTML to HTML.