On Sep 14, 2016, at 11:52 AM, Don Day <donday@donrday.com> 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:
Thank you,
Carlos
---Carlos Evia, Ph.D.Director of Professional and Technical WritingAssociate Professor of Technical CommunicationDepartment of EnglishCenter for Human-Computer InteractionVirginia TechBlacksburg, 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