Re: [dita-lightweight-dita] Draft LwDITA topics with metadata

Don,

You are absolutely right. All my previous MDITA and HDITA examples have headings instead of sections. I made a boo-boo in this example because I started with XDITA (which requires sections… probably needing their own titles) and then moved on to HDITA and XDITA. My HDITA task example, however, does require sections if we are still interested in elements like <section data-hd-class="task/prereq”>, but even that would need a heading/title unless it’s generated by a template.

I will update the examples to include beautiful headings.

Thank you for paying attention,

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 Sep 14, 2016, at 11:52 AM, Don Day <> wrote:

  
    
  
  

Hi, Carlos. Let me try this interpretation on you to see if it
      bears upsetting the group with my late-to-the-party suggestion for
      a different way of looking at the authoring usability:
    

Seeing the MDITA compared to HDITA reminds me that perhaps the
      pattern should make direct use of required subheadings (salient, 
      though implied structure) rather than sections (real structure
      with unrendered metadata).  The first approach still makes authors
      responsible to "not do the obvious" (put in a heading) and do the
      non-intuitive thing (directly manipulate a class attribute value).
    

An HTML fragment with properly nested H2 titles can imply the
      section scope without requiring an author to directly encode a
      wrapper (and risk leaving out closing markup). Attribution of the
      section then relies on using consistent H2 title text, but that is
      the same level of author responsibility as knowing what class
      value to insert (after all, an autogenerated title is always
      firmly bound to the class value that generates it, so they serve
      the same role).

This matters in the Markdown case because Markdown is extremely
      regular in its conversion to HTML (to some extent representing a
      validation role for the quality of HTML--generated rather than
      authored). The pipeline that produces DITA necessarily makes use
      of this HTML intermediary, which as mentioned before has the overt
      structural and semantic cue (<h2>Ingredients</h2>) to
      programmatically scope its coverage and produce the wrapper used
      as the eventual XSLT task section match structure). 
    

So if the authoring practice makes use of salient heading
      features in both Markdown and its up-converted equivalent HTML
      "HDITA", then a single analytical step on the H2 headings can
      fully  infer the structure and the semantic intent of each scoped
      chunk. Authors are happier because the overt heading makes the
      intent clear. 
    

Granted, use of direct title text is language dependent, but the
      process now formalizes the "heading to attribute" mapping as a
      lookup table--the exact inverse of the toolkit's
      autogeneration of headings from class values--, which is an easily
      localized external asset that can be seen as a type of structural
      schema.

Demo: paste this fragment into the HTML source panel (the default
      tab) at http://any2dita.com/?tab=admin and click Migrate. In the
      result view, click on the "proto.xml" link to see the structure
      that can be implied from that simple submitted result. (Note there
      is no article wrapper because this is intended to be "just as if
      upconverted from Markdown.)
    

--------------------

 <h1>Marinara sauce</h1>
      
       <p>Prepare a crowd-pleasing red sauce for pasta in about 30
      minutes.</p>
      
      <h2>Ingredients</h2>
       <ul>
         <li><p>2 tbsp. of olive oil</p></li>
         <li><p>2 cloves of garlic,
      minced</p></li>
         <li><p>1/2 tsp. of hot red
      pepper</p></li>
         <li><p>28 oz. of canned tomatoes, preferably San
      Marzano</p></li>
         <li><p>2 tbsp. of parsley,
      chopped</p></li>
       </ul>
      
       <h2>Preparation</h2>
       <ol>
         <li><p>Heat olive oil in a large saucepan on
      medium</p></li>
         <li><p>Add garlic and hot red pepper and sweat
      until fragrant</p></li>
         <li><p>Add tomatoes, breaking up into smaller
      pieces</p></li>
         <li><p>Simmer on medium-low heat for at least 20
      minutes</p></li>
         <li><p>Add parsley</p></li>
         <li><p>Simmer for another five
      minutes</p></li>
         <li><p>Serve over long pasta.</p></li>
       </ol>
    

--------------------
    

Likewise, try this more direct Markdown version through the
      Markdown tab, and again compare the proto.xml view--it should be
      nearly identical because the intermediate HTML is the same:

--------------------
    

# Marinara Sauce
      
      Prepare a crowd-pleasing red sauce for pasta in about 30 minutes.
      <!-- Template will treat this as a shortesc if specified -->
      
      ## Ingredients
       -   2 tbsp. of olive oil
       -   2 cloves of garlic, minced
       -   1/2 tsp. of hot red pepper
       -   28 oz. of canned tomatoes, preferably San Marzano
       -   2 tbsp. of parsley, chopped
      
      ## Preparation
       1.   Heat olive oil in a large saucepan on medium
       2.   Add garlic and hot red pepper and sweat until fragrant
       3.   Add tomatoes, breaking up into smaller pieces
       4.   Simmer on medium-low heat for at least 20 minutes
       5.   Add parsley
       6.   Simmer for another five minutes
       7.   Serve over long pasta.
    

    --------------------
The converter's default mode is to produce separated topics for
      nested heading events, but the task intent could be used as an
      XSLT mode to handle the prototopic as a section instead. That's a
      beauty of doing final transforms from an intermediate format that
      fully exposes the parsed structure for who-knows-what final use.

--
      Don
    

    
On 9/13/2016 8:46 AM, Carlos Evia
      wrote:
    

    
      
      
Dear LwDITA subcommittee people,

      

      

      
At our meeting of the syntax taskforce, I promised
        some updated examples incorporating YAML headers for identifying
        metadata and processing information. I am planning to schedule a
        follow-up call of the taskforce soon, but it won’t hurt if we
        all take a look at these (adapted from an old XML example by
        Sarah O’Keefe). We need to address the possibility that authors
        will bring HTML5 and Markdown files with zero special
        DITA/LwDITA tags and that is ok, but if they want to follow our
        recommendation and standard, then they can make them better.

      
I am working on detailed mappings of XDITA, HDITA,
        and MDITA based on our previous examples, but the draft topics
        are here:

      

      

      
https://github.com/VT-CHCI/mixedlightweightdita/tree/master/drafts

      

      

      

      

      
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

                              

                              

                              

                            

                          

                      

                  

              

            
          

          
        

        
        
      

      
    
    
    
-- 
      
      

        Don R. Day
        Founding Chair, OASIS DITA Technical Committee (current version:
        DITA
          1.3)
        LinkedIn: donrday   Twitter:
        @donrday
        About.me: Don R. Day   Skype:
        don.r.day
      

      

        "Where is the wisdom we have lost in knowledge?
        Where is the knowledge we have lost in information?"
        --T.S. Eliot 
      

    

  

	

        
		Virus-free. www.avast.com