OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita-lightweight-dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: RE: [dita-lightweight-dita] Short descriptions in LwDITA


As a co-author of a White Paper on the importance of short descriptions (https://www.oasis-open.org/committees/download.php/57803/DITA-Adoption_2016_Writing-Effective-Short-Descriptions.pdf), I strongly vote to keep the short description tag and NOT to default to the first paragraph.

 

Regards,

 

Joe

 

Joseph Storbeck

Senior Structured Data Analyst

 

1717 Universal City Blvd | Universal City, TX 78148

Phone: (512) 438-9457 | Fax: (210) 616-0088

e-mail: jstorbeck@janacorp.com

JANA, Inc. is an Equal Opportunity Employer.

If you have received this e-mail by mistake please inform us and destroy this e-mail and any documents it might contain.

 

From: dita-lightweight-dita@lists.oasis-open.org [mailto:dita-lightweight-dita@lists.oasis-open.org] On Behalf Of Carlos Evia
Sent: Tuesday, February 07, 2017 12:46 PM
To: dita-lightweight-dita@lists.oasis-open.org
Subject: [dita-lightweight-dita] Short descriptions in LwDITA

 

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

 



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]