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] About YAML headers and other MDITA elements


Thanks Carlos, this goes a long way towards answering my original question from the LwDITA meeting.


The issue of whether we are asking people to mix the various flavours of Markdown as a necessity to write "valid" MDITA remains. I suspect that if we require YAML headers we would that section of our audience that uses a strict version of CommonMark.


Possibly mitigating against this are the sample settings in a professional Markdown tool (MarkdownPad 2) I have been using to create some sample MDITA code, which not only allows you to choose which flavour of Markdown, but also to ignore (i.e. not display) YAML header info. See below:



This *suggests* that some mixing-and-matching of Markdown flavours is not out-of-the-ordinary.


Am going to do some more prodding in the Markdown community to see if I can get more info on this issue.


Cheers!

 

-

Keith Schengili-Roberts
Market Researcher and DITA Evangelist
 
IXIASOFT 
825 Querbes, Suite 200, Montréal, Québec, Canada, H2V 3X1
tel  + 1 514 279-4942  /  toll free + 1 877 279-4942 



From: dita-lightweight-dita@lists.oasis-open.org <dita-lightweight-dita@lists.oasis-open.org> on behalf of Carlos Evia <cevia@vt.edu>
Sent: Tuesday, March 7, 2017 10:40:38 AM
To: dita-lightweight-dita@lists.oasis-open.org
Subject: [dita-lightweight-dita] About YAML headers and other MDITA elements
 
Dear Lightweight DITA SC members,

I had a conversation with Jarno Elovirta and Radu Coravu about YAML headers in Markdown and when/how to use them. I am waiting to hear from George Bina, who will be presenting about Markdown and DITA at DITA NA in San Diego.
Their input was excellent and made me remember the original vision for MDITA that Michael and I talked about with Jenifer Schlotfeld and Mike Wilson back in 2014. Insert Alan Houser comment about LwDITA being slow... ;-)

The original plan was that an author could bring any well-formed Markdown file (well-formed here means following CommonMark) and MDITA will let it play with other DITA files, giving it an id attribute based on its title (Jarno mentioned that Wikipedia uses that kind of mechanism) and treating its first paragraph as a short description by default.
If the author wants DITA features like conrefs, then she needs to use raw XML (which CommonMark allows). Example: 

# Basic Concepts of Network Lighting
   
You can network LED light bulbs together from your <ph keyref="product-name" /> to operate wirelessly from a remote control.
    
<p id="power-off">Make sure power to the fixture where you are installing the light bulb is turned OFF.</p>
   
<p conref="low-power.dita#low-power/disconnect-warning" />

If the author does not need conrefs or any other DITA-like features, then pretty much any CommonMark-friendly file will be ok.
Then we have optional (I am thinking about the conformance statements OASIS needs in the spec) features that can come in a YAML header: don't want your first paragraph to be a shortdesc? Then check it off here. Need to add more topic metadata? Do it here. Need to specify an ID attribute? Here you can do it. Example:

---
id: basic-concepts
author: Juan Smith
shortdesc: no
---

Answering Keith's question: I am worried that if we make the YAML header required, nobody is going to adopt this baby.

Thoughts?

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]