dita-lightweight-dita — archive

Short descriptions in LwDITA

From: Joe Pairman <[email protected]>
To: [email protected]
Date: Tue, 07 Feb 2017 21:04:00 -0000

I thought it might be worth pointing out that the idiomatic way to tag descriptions/summaries in Markdown, at least in static site generators such as Jekyll, Hugo, Octopress, and Pelican, is to include them in the metadata at the top of the file. Jekyll, Hugo, and Octopress use YAML, so it would look like this: --- title: Some Title description: Short description goes here and is available for use on index/home pages as well as in the meta description keywords: one keyword, another, and another --- (Jekyll uses “excerpt:” instead of “description:”.) Pelican uses Multimarkdown metadata, so it’s even simpler; you omit the dashed lines from the top and bottom of the block. But the description key is “summary:”. The typical default if you do not explicitly set a description is to use the first paragraph of the post. References: https://gohugo.io/content/front-matter/ http://sweetme.at/2013/08/06/how-to-set-your-octopress-description-and-keyword-meta-tags/ https://jekyllrb.com/docs/posts/#post-excerpts http://docs.getpelican.com/en/3.6.3/content.html https://github.com/fletcher/MultiMarkdown/wiki/MultiMarkdown-Syntax-Guide#metadata Apologies is this is ground that’s been covered before — I try to keep up with the discussions but have had gaps. Regards, Joe — Joe Pairman Mekon Tel: +44-20-8722-8400 Mobile: +44-7472-745-063? Skype: joepairman From: <[email protected]> on behalf of Carlos Evia <[email protected]> Date: Tuesday, February 7, 2017 at 20:32 To: Keith Schengili-Roberts <[email protected]>, "[email protected]" <[email protected]> Subject: Re: [dita-lightweight-dita] Short descriptions in LwDITA Keith, Section 6.8 of the CommonMark spec says we can use any raw HTML or XML, so from their side there's nothing they could add... they just recommend using raw HTML or XML. To be honest, the shortdesc in MDITA could even be <shortdesc>... Joe and Scott, I hear you loud and clear: the short description is important and deserves its own markup. Let's see what other voices from the SC say. 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 On Tue, Feb 7, 2017 at 2:35 PM, Keith Schengili-Roberts < [email protected] > wrote: Here's a crazy thought: has anyone thought about approaching the people who manage CommonMark Markdown about the possibility of *them* adding shortdesc to their spec? I'd be happy to make the case on https://talk.commonmark.org/ to see what they say... Cheers! - Keith Schengili-Roberts Market Researcher and DITA Evangelist IXIASOFT 825 Querb es, Suite 200, Montréal, Québec, Canada, H2V 3X1 tel + 1 514 279-4942 / toll free + 1 877 279-4942 [email protected] / www.ixiasoft.com From: [email protected] < [email protected] > on behalf of Scott Hudson < [email protected] > Sent: Tuesday, February 7, 2017 2:07:16 PM To: Storbeck, Joe; Carlos Evia; [email protected] Subject: Re: [dita-lightweight-dita] Short descriptions in LwDITA I would also support the retention of shortdesc, especially with its use in supporting SEO and display in search results. It is semantically distinct, and IMO should not be oversimplified to using the first paragraph. Thanks and best regards, --Scott Scott Hudson Content Strategist Digital Aviation Learning & Development Voting member: OASIS DocBook TC, Publishers SC OASIS DITA TC, Tech Comm SC, LW DITA SC, Learning Content SC OASIS Augmented Reality in Information Products (ARIP) TC Jeppesen Digital Aviation Boeing 55 Inverness Drive East Englewood, CO 80112 www.jeppesen.com From: < [email protected] > on behalf of "Storbeck, Joe" < [email protected] > Date: Tuesday, February 7, 2017 at 12:00 PM To: Carlos Evia < [email protected] >, " [email protected] " < [email protected] > 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: [email protected] 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: [email protected] [ mailto:[email protected] ] On Behalf Of Carlos Evia Sent: Tuesday, February 07, 2017 12:46 PM To: [email protected] 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