Re: [dita-lightweight-dita] Short descriptions in LwDITA

[Mark Giffin <mark@markgiffin.com>]

Hi Carlos!

Since we are talking about 3 different markups here (Markdown, HTML5, XML), I have 3 answers:

> - Should we go back to just treating the first paragraph in MDITA as a short description?

Yes. Because I think we should make MDITA as simple as possible, in keeping with the simplicity of Markdown. We can make it so it can be switched off, such as by an item in the YAML header like "shortdesc=no". This could handle the condition of a single long paragraph.

> - If we do that, do we really need <p data-hd-class="shortdesc"> in HDITA (HTML5?)

Yes I think so, since the markup actually exists to do it in HTML5, unlike with Markdown.

> - And do we even need that in XDITA as <shortdesc> if we are just defaulting to first paragraphs?

Yes I think we should keep <shortdesc> in XDITA.

Mark Giffin
Mark Giffin Consulting, Inc.
http://markgiffin.com/

On 2/7/2017 10:45 AM, Carlos Evia wrote:

Dear Lightweight DITA subcommittee members,

We didn't have time in yesterday's call to talk about an issue that has been buried in the agenda for a few weeks.

As I work on the committee note and detail (used as a verb here) the list of DITA elements in LwDITA and their equivalents in XDITA, HDITA, and MDITA, I go back to the question about shortdesc and how to represent it across our authoring formats.

In the initial MDITA draft I proposed to Michael back in... ooops... 2014??... shortdesc did not exist, and the first paragraph in a Markdown file was by default treated as a short description.

Then, Jarno asked "What if the topic only consists of one long paragraph?" and we decided to keep things simple and use "raw" HTML/HDITA in MDITA for elements that do not exist in Markdown but would be ok with CommonMark.

As a result, now a short descriptions is <p data-hd-class="shortdesc"> both in HDITA and MDITA.

Question:

- Should we go back to just treating the first paragraph in MDITA as a short description?

- If we do that, do we really need <p data-hd-class="shortdesc"> in HDITA (HTML5?)

- And do we even need that in XDITA as <shortdesc> if we are just defaulting to first paragraphs?

Best,

Carlos

-- 

Carlos Evia, Ph.D.

Director of Professional and Technical Writing

Associate Professor of Technical Communication

Department of English

Center for Human-Computer Interaction

Virginia Tech

Blacksburg, VA 24061-0112

(540)200-8201