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

[Carlos Evia <cevia@vt.edu>]

Dear people,

Thank you for your active participation in this discussion.

I agree: we need to keep shortdesc as a structural element in XDITA and HDITA.

For MDITA, the best approach looks like a combination of what Joe Pairman and Mark Giffin mentioned (let's deal with that in the YAML header).

At one point, that's what we had... when we were expecting that the template-based specialization would affect MDITA topics. 

Therefore, I suggest we go with something like this,

---

id: ride-bike

shortdesc: yes

author: Mark Giffin

---

# How to ride a motorcycle

This paragraph will be my shortdesc because the YAML header says so. If the value of the variable were "no," then I would not have a shortdesc.

Does that sound/look good?

Thank you,

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

On Wed, Feb 8, 2017 at 12:13 AM, Ullakaisa Kalander <Ullakaisa.Kalander@citec.com> wrote:

Hi all,

 

I’m for keeping <shortdesc> in XDITA.

 

Best,

 

Ullakaisa

From: dita-lightweight-dita@lists.oasis-open.org [mailto:dita-lightweight-dita@lists.oasis-open.org] On Behalf Of Mark Giffin
Sent: 07 February 2017 23:23
To: dita-lightweight-dita@lists.oasis-open.org
Subject: Re: [dita-lightweight-dita] Short descriptions in LwDITA

 

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