Re: [dita-lightweight-dita] About YAML headers and other MDITA elements

Carlos,

    

    I think we should keep the sloppiness of Markdown in mind as we
    begin crafting our lwdita conformance statements. I have the opinion
    that if rigid compliance is not the way Markdown works in the real
    world, then the conformance statements for MDITA will simply state
    that explicitly, in some form or another.

    

    Mark Giffin

    Mark Giffin Consulting, Inc.

    http://markgiffin.com/

    

    
On 3/7/2017 9:54 AM, Carlos Evia wrote:

    

    
      
Dear Keith and all,
        

        

        
Indeed, mixing and matching is pretty common in the
          Markdown world. Look at Pandoc's syntax and find all the
          points of intersection with, say, GitHub Flavored Markdown.

        
However, I keep seeing in our future those conformance
          statements that we need to build for the spec... and if we are
          open to wild mixing and matching, then we probably are
          damaging our proposed standard. 

        

        

        
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, Mar 7, 2017 at 12:51 PM, Keith
          Schengili-Roberts <>
          wrote:

          
            

              

                
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 

                                    

                                  
 
                                        / 
                                      www.ixiasoft.com

                                  

                                  

                                

                              

                                  

                            

                          

                        

                      

                      

                        

                        

                      

                      
                        

                        

                      
                      

                      

                      

                        

                        

                      

                      

                          

                          

                        
                        

                        

                        

                          

                          

                        

                      

                    

                  

                

              

              
              
From: 
                  <>
                  on behalf of Carlos Evia <>

                  Sent: Tuesday, March 7, 2017 10:40:38 AM

                  To: 

                  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