Revisting Underline & Healthcare Documents


#1

I am project lead for FHIR, a widely endorsed specification developed by HL7 for the exchange of healthcare information (http://hl7.org/fhir). We are trying to converge the healthcare community on using CommonMark for rich text. One of the challenges we have with this is that CommonMark does not support underline. I’ve read Feature Request: underline text, and I understand the theoretical reasons why underlining has problems, but replacing the practice of underlining with some other text decoration is not a simple thing - people have been underlining text for a long time, and existing healthcare documents make heavy use of underling. In a few cases, the text will explicitly referenced ‘underlined text’, or existing clinical protocols will do so, but new software based on markdown instead of RTF cannot support the clinical protocol.

I’m not sure how to progress this. If CommonMark doesn’t and won’t support underline, we could define our own extension, but that has very obvious downsides, and we don’t want to do that. Alternatively, GFM could, because we’re actually using GFM, for strikethrough (critical for healthcare documents). Otherwise… maybe any consensus to use commonmark might be impossible (? not sure, but clinical users feel extremely strongly about text fidelity).

An aside: text color is also a problem, but since most systems have not supported color, and because of color blindness, color is used and depended on a lot less.


#2

What exactly do you need? Do you need to write texts
that contain both underline and italic emphasis? Or
is it sufficient if emphasized words are rendered
underlined?

In the latter case, nothing needs to change in
commonmark parsing; you just need to change the
renderer slightly to make *hello* come out underlined.


#3

Distinguishing _foo_ from *foo* in the AST would help extensions. Otherwise, I would suggest to use a sequence of four characters: ****foo****.


#4

@grahamegrieve In HTML5, the <u> element represents an Unarticulated Annotation. Would you consider this definition to be your use case?

If you’re referencing the underlined text as underlined elsewhere in the document then it’s meaningful beyond mere presentation and there probably needs to be a way making this portable between implementations. It’s similar to referencing an item in a letter ordered list; the meaning of the document changes if the list item type is changed in CSS, so there’s an attribute to define this in HTML.


#5

ahh yes, Clinicians have been using both bold and underline for many years in their reports


#6

<u> approximates the use case, yes.

In terms of references, some thing like this may be encountered in clinical narrative (real world sample):

“Based on the serious problems (see underlined text above), I discussed…”


#7

@grahamegrieve Is there a reason why markdown instead than asciidoctor? While it doesn’t support underline directly, it supports using custom inline and block elements, for example [.underline]#underlined text#.


#8

I had a quick look at your project. It looks like an XML format. I would think that the most natural representation of rich text in that format would be something XML-ish – perhaps HTML, or some custom subset. Commonmark could be used in the tooling for creating records, etc., but is it the best choice for the underlying representation?

Note also that this is perfectly valid commonmark, since you can include raw HTML tags:

This text is <u>underlined</u>.

#9

So we have prohibited HTML tags since we really want the content limited to markdown for both security and presentation reasons. And we do use XHTML where XML is appropriate, but implementers have expressed a strong preference for markdown where possible. And we would probably never have used XHTML if commonmark had existed earlier. It’s very difficult for us to reference a non-standard in the standard (e.g. asciidoctor).


#10

In Markua they use four underscores for underlined text, e.g. ____my underlined text____. So that’s an option. I’m not sure that it’s easier to read than <u>my underlined text</u> though. In this case, it might be preferable to make an exception to your no-HTML rule. If we are going to make unarticulated annotations a CommonMark extension, I might begrudgingly agree to this syntax for compatibility reasons.


#11

Marking text as bold and italic would give you a way to style the generated HTML with CSS while still using standard CommonMark.

See ***underlined*** text below

The CSS would be something like:

em strong, strong em {text-decoration: underline; font-style: normal; font-weight: normal}

#12

Another solution is that you could use consistent attribute syntax which seems most likely be turned into a CommonMark extension. E.g.

[My underlined text.]{ .clinical-term }

Although this may seem long-winded, the advantage is that is separates the styling from the structure of the document. Even if you always made the clinical-term class appear underlined (to preserve the meaning where this is referred to), it gives you options in the future if you want to, say, make all clinical terms appear in red to diffentiate them from other underlined text.


#13

Well, these are options - thanks. We’ll discuss it further. None of them are ideal, though I prefer ___. Does CommonMark have a formal process for extensions? I haven’t seen any process?


#14

I believe the plan is to release version 1.0 of the core spec before moving on to extensions.

In the Mozilla article I linked to above, did you have a look at the other elements to consider using section? Any of those of elements can styled as underlined and one or more of them is likely better suited for your use case than <u>. Although not all of these elements can be found in the primary CommonMark spec, some have been proposed as extensions already. Maybe the alternative mood/voice element which can be used for technical terms.