Here is the marketing topic specialization example originally provided by Birgit, with updates by me:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD LW DITA Topic//EN" "topic.dtd">
<topic id = "mk02"
outputclass = "marketingtopic" >
<title> Title </title>
<prolog>
<specmeta>
<ph outputclass = "brand" />
<ph outputclass = "category" />
<ph outputclass = "product" />
<ph outputclass = "company" />
</specmeta>
</prolog>
<body outputclass = "marketingbody" >
<section outputclass = "marketingsection"
importance = "optional" >
<!-- specmodel="choice" -->
<dl outputclass = "features"
importance = "optional" >
<dlentry outputclass = "feature"
specmodel = "sequence" >
<dt outputclass = "featureterm" />
<dd outputclass = "featuredef" />
</dlentry>
</dl>
<dl outputclass = "specifications"
importance = "optional" >
<dlentry outputclass = "specification"
specmodel = "sequence" >
<dt outputclass = "specifiedterm" />
<dd outputclass = "specifieddesc" />
</dlentry>
</dl>
<ul outputclass = "highlights"
importance = "optional" >
<li outputclass = "highlight" />
</ul>
<p outputclass = "action"
importance = "optional" >
<xref outputclass = "actionref" />
</p>
<fig outputclass = "quote"
importance = "optional" >
<xref outputclass = "quoteref" />
</fig>
</section>
<section outputclass = "legalsection"
importance = "optional" >
<!-- specmodel="choice" -->
<fig outputclass = "disclaimer" />
<p outputclass = "copyright"
specmodel = "sequence" >
<ph outputclass = "copyrightyear"
importance = "optional" />
<ph outputclass = "copyrightholder"
importance = "optional" />
</p>
<fig outputclass = "logo" ><image/></fig>
</section>
<section outputclass = "contact"
specmodel = "sequence"
importance = "optional" >
<p outputclass = "company"
importance = "optional" > ... </p>
<p outputclass = "contactperson"
importance = "optional" > ... </p>
<p outputclass = "address"
importance = "optional" > ... </p>
<p outputclass = "phonenumber"
importance = "optional" > ... </p>
<p outputclass = "email"
importance = "optional" > ... </p>
<p outputclass = "website"
importance = "optional" > ... </p>
<p outputclass = "addinfo"
importance = "optional" > ... </p>
</section>
</body>
</topic>
In a follow-up email, I will provide Carlos with the latest version of the DITA to RNG transform tool, and he can post it to the LW GitHub site.
Regards,
Tim.
From:
dita@lists.oasis-open.org [mailto:
dita@lists.oasis-open.org]
On Behalf Of Bob Thomas
Sent: Monday, January 23, 2017 6:55 PM
To: Eliot Kimber <
ekimber@contrext.com>
Cc: DITA TC <
dita@lists.oasis-open.org>
Subject: Re: [dita] My increasing concerns about LwDITA and template-based specialization
Would somebody on the LWDita SC provide a prototype of an annotated topic that is meant to be used as input for a template specialization tool? That way, we can see an example of the markup that would be needed to drive a specialization
tool.
Bob Thomas
On Mon, Jan 23, 2017 at 4:22 PM, Eliot Kimber <
ekimber@contrext.com > wrote:
I think we are not communicating.
Template-based specialization is necessarily a * tool * that takes as input templates with markup specific to
the details of the specialization * design * and produces as output grammar files that reflect that specialization design in the form of default values for @class attributes.
That is, the end result of using this tooling is a set of grammar files indistinguishable from grammar files created
* by any other method *, including hand-coding the grammars.
The details of what the tool does, including the requirements it’s designed to meet, how it’s implemented, etc.,
will all drive the markup design. There is no part of that markup design that requires standardization in order to be useful. But requiring it to be standardized would impose a huge additional set of requirements on the markup that would make designing it
significantly more expensive than it would otherwise be.
Given that the cost of standardizing * any markup * is very high, resistance to trying to define, as a standard,
markup that meets a specific data processing requirement will be very high. In addition, the actual cost of doing the standardization work, if the TC decided it was appropriate to do, would be very high, much higher than doing something in the context of a
specific processor implementation.
If there is sufficient human resource available to * implement * template-based specialization as it is understood
to be required for the success of LW Dita, then those resources need to do it: define the requirements, design the supporting markup, and implement the processing. They need to do it now. And it doesn’t need to be done in the context of any standards activity,
beyond perhaps putting the code in an OASIS-managed GitHub project.
I think it’s fair to say that at this point the TC is not simply going to accept any new markup as part of any TC-approved
standard that does not go through a design and development process at least as rigorous as what we did for DITA 1.3, which was much more rigorous than DITA 1.2 and yet was still not as rigorous as it should have been.
I don’t know how I can be any clearer about this: the issue is not the utility or need for template-based specialization,
the issue is whether or not the markup for such a mechanism should be standardized, either in the context of LW Dita specifically or the DITA standard generally.
As far as I’m concerned, such a mechanism has no place in any TC-defined standard: it’s not necessary, it’s not appropriate,
and we don’t have the resources to do the standardization work. Trying to standardize it would put LW Dita in jeopardy for no good reason.
Cheers,
E.
--
Eliot Kimber
http://contrext.com From:
Michael Priestley <
mpriestl@ca.ibm.com >
Date: Monday, January 23, 2017 at 3:19 PM
To: Eliot Kimber <
ekimber@contrext.com >
Cc: DITA TC <
dita@lists.oasis-open.org >
Subject: Re: [dita] My increasing concerns about LwDITA and template-based specialization
Just to be clear, we're not talking about a standard tool, but about a standard set of specialized elements and attributes
for annotating topics.
In the same way that filtering attributes (props, audience etc.) are not tools, and the assessment elements in the learning and training specializations are not tools.
They are fodder for tools, in the same way that all DITA markup is. But the specialized attributes or elements themselves, which capture the semantic intent of the person adding them, are not tools.
Michael Priestley, Senior Technical Staff Member (STSM)
Enterprise Content Technology Strategist
mpriestl@ca.ibm.com From: Eliot Kimber <
ekimber@contrext.com >
To: Michael Priestley/Toronto/IBM@IBMCA
Cc: DITA TC <
dita@lists.oasis-open.org >
Date: 01/23/2017 04:11 PM
Subject: Re: [dita] My increasing concerns about LwDITA and template-based specialization
Yes, it can be lightweight DITA without a * standard * tool for generating specializations from templates (or any other mechanism for producing grammars that validate documents that reflect
conforming specializations).
There are many ways that specialization can be made easier through tooling, of which template-based specialization is only one such. The TC does not standardize * tools * and should not be
privileging a particular implementation approach, as a matter of policy.
If having tooling for making specialization easy enough so that the LW Dita community can do it is a prerequisite for LW Dita’s success then somebody needs to build that tool. But the tool does
not need to be standardized, it simply needs to exist.
Requiring that it be part of the standard will not do anything to help ensure that it exists, and in fact with make it much more likely that it will never exist, for the simple reason that the
TC would have to agree that whatever was defined was sufficiently general, complete, and correct to be appropriate to codify as a standard.
On the other hand, if somebody just builds a tool that works then the work is done. Working is not the same as being appropriate for standardization.
Cheers,
E.
--
Eliot Kimber
http://contrext.com From: Michael Priestley <
mpriestl@ca.ibm.com >
Date: Monday, January 23, 2017 at 2:57 PM
To: Eliot Kimber <
ekimber@contrext.com >
Cc: DITA TC <
dita@lists.oasis-open.org >
Subject: Re: [dita] My increasing concerns about LwDITA and template-based specialization
So do you think we can call it a Lightweight DITA standard if it doesn't include a mechanism for lightweight specialization?
I don't think we can call it DITA without some kind of specialization support, and I don't think we can call it Lightweight if that specialization support is the full DITA option of editing doctypes by hand.
I'd also note that there are plenty of different approaches to making specialization simpler and easier. Since none of them are currently part of the standard, no one thinks of DITA as being easy to specialize.
Making lightweight specialization part of the standard accomplishes several goals:
- it enables interoperation of lightweight templates across tool chains (for example, your ABCType can use my toolchain to generate an HTML5 authoring template, someone else's toolchain to generate a schematron validator, and a third person's toolchain to generate
stylesheet overrides that will automatically insert appropriate headings for specialized sections into PDF, HTML and Word outputs)
- it explicitly addresses the complaint that (full) DITA specialization is too complex to use. Any solution we provide outside the standard space does not address complaints about the standard itself
- it explicitly addresses the content authoring needs of non-technical content strategists, who are key to one of the domains Lightweight DITA is explicitly targetting
Michael Priestley, Senior Technical Staff Member (STSM)
Enterprise Content Technology Strategist
mpriestl@ca.ibm.com From: Eliot Kimber <
ekimber@contrext.com >
To: DITA TC <
dita@lists.oasis-open.org >
Date: 01/23/2017 03:40 PM
Subject: Re: [dita] My increasing concerns about LwDITA and template-based specialization
Sent by: <
dita@lists.oasis-open.org >
Note that the question is not whether or not template-based specialization is useful—it almost certainly is.
The question is whether or not a particular template-based specialization approach should be part of the Lightweight DITA * standard *.
A working template-based specialization mechanism will be useful whether or not it is standardized. Standardizing it as part of the LW Dita effort is not necessary and would add significant cost and overhead to the LW Dita standardization process.
Cheers,
E.
--
Eliot Kimber
http://contrext.com From: Noz Urbina <
noz.urbina@urbinaconsulting.com >
Date: Monday, January 23, 2017 at 2:24 PM
To: Michael Priestley <
mpriestl@ca.ibm.com >, Eliot Kimber <
ekimber@contrext.com >
Cc: DITA TC <
dita@lists.oasis-open.org >
Subject: Re: [dita] My increasing concerns about LwDITA and template-based specialization
+1 to Michael's comments.
I have been asking for Templates-based attribute specialisation for years.
On Mon, 23 Jan 2017, 17:54 Michael Priestley, <
mpriestl@ca.ibm.com > wrote:
Hi Eliot,
They are currently defined as conforming specializations. There is absolutely no need to add anything to the base DITA vocabulary.
It is true that these are specializations with an audience type other than plain author - someone who is doing content typing for a project, but not technical enough to want to dive deep into XML schema definition using XSD or RNG. That responsibility might
be in the hands of the content strategist, or of the content engineer, depending on where the lines get drawn on technical skills/proficiency.
In my experience working on marketing projects (one of the target domains for Lightweight DITA) I've seen content type definition happen every time - they are rarely taking what's available out of the box, but instead defining fields/structure as required for
a particular set of use cases.
I don't anticipate everyone needing or wanting to use the Lightweight DITA template-based specialization process, but I also think it's important to recognize the needs of the content strategy role on a content project, just as we recognize other authoring
roles and requirements besides primary author (SME authoring requirements, for example, or reviewer requirements, or information architect requirements...)
Michael Priestley, Senior Technical Staff Member (STSM)
Enterprise Content Technology Strategist
mpriestl@ca.ibm.com From: Eliot Kimber <
ekimber@contrext.com >
To: DITA TC <
dita@lists.oasis-open.org >
Date: 01/23/2017 12:16 PM
Subject: Re: [dita] My increasing concerns about LwDITA and template-based specialization
Sent by: <
dita@lists.oasis-open.org >
Just because there are multiple potential uses for the markup that would also drive template-based specialization generation, it does not, by itself, motivate or justify standardization as part of the core DITA architecture.
That is, all of these use cases are still outside the scope of DITA * content* , the stuff that authors write and capture as conforming DITA documents.
If a body of practice and tools around template-based processing develops that is sufficiently well adopted that it is worth standardizing then that can be done separately from the core DITA architecture—there is no aspect of template-based tooling that requires
anything within the domain of * content * as authored.
For example, all new attributes and markup needed to augment otherwise-normal DITA maps and topics to support specialization generation or output processing could be put in namespaces, putting them explicitly outside the scope of normal DITA markup. Or they
could be defined as conforming specializations using @base, <data>, and other general-purpose elements, if that made more sense for some reason (which it might). And of course you can park a fleet of trucks in @outputclass.
Thus there’s no need to add anything to the base DITA vocabulary in order to support this type of tooling, certainly not as a prerequisite for developing such tools and proving their designs and usefulness.
Likewise, the existence of these tools is not a prerequisite for the use or adoption of a Lightweight DITA. Having such tools will definitely be useful and to everyone’s advantage, but they are not a prerequisite. If experience is any guide, the vast majority
of users will want something pre-defined that they can just pick up and use, which means that having a well-thought-out subset of DITA 1.3 markup is the most important thing and that by itself is hard enough.
Cheers,
Eliot
--
Eliot Kimber
http://contrext.com From: <
dita@lists.oasis-open.org >
on behalf of Michael Priestley <
mpriestl@ca.ibm.com >
Date: Saturday, January 21, 2017 at 9:33 PM
To: Kristen James Eberlein <
kris@eberleinconsulting.com >
Cc: DITA TC <
dita@lists.oasis-open.org >
Subject: Re: [dita] My increasing concerns about LwDITA and template-based specialization
Hi Kris,
Here's my perspective:
>I'm not sure that adding new attributes and elements in the spec in
>order to drive tool development is an appropriate thing to do.
I think as long as the markup is semantic, this is not only appropriate but normal. You could argue that every element and attribute in full DITA was added to drive tool development, in the sense that none of that markup had any meaning or effect until it was
turned into some kind of output by a tool. There are many examples of elements and attributes supporting specific tooling requirements, from the filtering attributes in DITA 1.0 to the assessment elements in the learning and training specialization.
>I think it would 100% appropriate if someone wants to build and sell an
>application, and include with the application directions on how to
>create an annotated XML file that can processed to get a monolithic DTD.
>Or have an Open Source project which produces a plug-in that oXygen will
>bundle with their application.
And if they use specialized elements and attributes to do that annotation, then their annotations will not be portable across template generation tools. It really will be bound to one tool, instead of being a standard. This is perfectly appropriate, of course,
but it's a different use case than having a standard that allows multiple tools to coexist and work on the same content set.
>However, I truly don't see an argument for adding new elements and
>attributes to the specification in order to develop one-time artifacts
>(the templates) that can be fed into tooling to autogenerate DTDs
Maybe this is where our different interpretations start. I don't see these as one-time artifacts. Over time the goal is to have the same annotated template support multiple outputs, many of which could require ongoing updates and maintenance:
- the documentation (update to address the requirements of new users, or just improve based on existing usage problems)
- stylesheet overrides (for example to generate section titles - update to address changing editorial rules/requirements)
- authoring templates (as with documentation, update to address requirements of new users etc.)
In addition to those use cases, there is the (re)use of the template by other designs - the goal is to allow reuse of specialized elements through conref between templates, which will be simpler and more direct for users to work with and understand compared
to our current full DITA modularization with multiple entity overrides.
I don't know if this helps to convince you, but I hope that I've addressed some of the concerns you've identified here.
Michael Priestley, Senior Technical Staff Member (STSM)
Enterprise Content Technology Strategist
mpriestl@ca.ibm.com From: Kristen James Eberlein <
kris@eberleinconsulting.com >
To: DITA TC <
dita@lists.oasis-open.org >
Date: 01/19/2017 08:15 AM
Subject: [dita] My increasing concerns about LwDITA and template-based specialization
Sent by: <
dita@lists.oasis-open.org >
I think we all would like to specialization easier to do. But ...
I'm not sure that adding new attributes and elements in the spec in
order to drive tool development is an appropriate thing to do.
I think it would 100% appropriate if someone wants to build and sell an
application, and include with the application directions on how to
create an annotated XML file that can processed to get a monolithic DTD.
Or have an Open Source project which produces a plug-in that oXygen will
bundle with their application.
However, I truly don't see an argument for adding new elements and
attributes to the specification in order to develop one-time artifacts
(the templates) that can be fed into tooling to autogenerate DTDs
I'm going to need a whole lot more convincing. It just seems wrong.
--
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype)
---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php --
Bob Thomas
+1 720 201 8260
Skype: bob.thomas.colorado
Instant messaging: Gmail chat (
bob.thomas@tagsmiths.com ) or Skype
Time zone: Mountain (GMT-7)