I agree with Bob. While
I have not read the paper all the way through, I see some
glaring problems.
In addition to the markup and problematic short
descriptions, the paper contradicts the spec. The section
"How and Where Short Descriptions Appear" states that
"Depending on the output type and setup, short descriptions
may or may not appear above body content within a topic." It
then suggests that short descriptions are not rendered in
PDF output. While implementations might build their PDF
style sheets so that short descriptions are not rendered,
this is not the rendering expectation that is outlined in
the DITA specification.
See the DITA spec at
http://docs.oasis-open.org/dita/dita/v1.3/cos02/part1-base/langRef/base/shortdesc.html#shortdesc
It clearly makes a normative statement about short
descriptions: "The content of the
<shortdesc>
element
SHOULD be rendered as the
initial paragraph of the topic."
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)
On 1/4/2016 12:43 AM, Bob
Thomas wrote:
I spent a couple of hours reviewing the
latest draft. I didn't finish, but I have attached what
I have done so far.
While the paper has improved, I don't believe that
it is ready to publish. It still contains technical
inaccuracies, and I am concerned that our audience
will find it unclear in places. The DITA source markup
also needs some refactoring.
Regards,
--
Bob Thomas
+1 720 201 8260
Skype: bob.thomas.colorado
Time zone: Mountain (GMT-7)
---------------------------------------------------------------------
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
---------------------------------------------------------------------
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