OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita-adoption message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Fwd: DITA 1.2 Language Specification Comments

The latest instalment ...

Rob's agreeing to our suggestion to use the .dita extension for  

Some of the items are being taken up by the DITA TC.


> From: Robert D Anderson <robander@us.ibm.com>
> Date: 3 February 2009 17:25:05 GMT
> To: "David J. B. Hollis" <dhollis@AandOConsultancy.ltd.uk>
> Subject: Re: DITA 1.2 Language Specification Comments
> Hi David,
> Thanks for the additional comments.
>>> OASIS has an official reporting mechanism that we don't get a lot of
>>> control over; it will be listed on the cover page of the final
>>> standard...
>> How effective is this reporting mechanism? Have you had any comments
>> from it?
> Comments on that list are not frequent, but they do come in.
>>> About the inheritance section...
>> I'm coming at it more from a tech. author's perspective. For me, the
>> information seemed almost to clash with the preceding Contains &
>> Contained By sections.
> JoAnn suggested today that we should have a topic about reading the
> architectural spec - I think that it should explain what the  
> inheritance
> section is doing. Alternatively, or in addition, we could change that
> section title to "Specialization ancestry" or something similar?  
> I'll ask
> the TC about this one.
>> There almost needs to be an 'Introduction to the DITA Language Spec.
>> for Technical Authors'. It's not feasible to include explanations
>> within each element.
> Agreed - JoAnn mentioned writing something like that which would also
> explain how to read the attribute tables.
>> An (ideal!) alternative would be to use @ audience round certain
>> sections, with 'architect' and 'author' values, say. The confusing
>> architectural stuff could then be kept away from authors, and perhaps
>> some explanations could be provided for authors, and kept away from
>> architects.
> I did have a thought along those lines when I set up all of the  
> topics for
> 1.2 - they now have otherprops="inheritance" on that section for all  
> of the
> elements. So, if you want to reformat without including those  
> sections, you
> can exclude otherprops="inheritance". The same is true for the  
> contains and
> contained-by sections, which have their own properties.
>> If, as a technical author, I'm looking at the Map area of the  
>> Language
>> Spec., I would ideally like to know that Maps can contain a title,  
>> and
>> to have this presented to me in some way within the Map area of the
>> Language Spec. Is this not possible via one of the linking  
>> mechanisms:
>> links, conrefs, reltables?
>> As a technical author, I don't want to have to remember that Maps can
>> contain titles, but titles inherit from topics, so I have to look at
>> the topic area of the Language Spec.
> I'm really not sure how to handle that, given that so many elements  
> are
> present in both maps and topics. If you read the spec "by type", the  
> Topic
> section should only contain elements that are available exclusively to
> topics. The body elements, meta elements, and others may appear in  
> both.
> I don't think that we can include links from the <map> topic to all  
> of the
> elements it can contain ... aside from in the contains/contained-by
> section. I'd be happy to go to the TC to ask for other suggestions  
> on how
> to list this sort of thing, but I'm having a bit of trouble  
> formulating the
> question in a general way. Something like - "When looking in one  
> section of
> the spec (such as <map>), how can I more easily identify the  
> elements that
> are available but are listed elsewhere in the spec (such as <title>)?"
>>> I'm working on getting some flags to highlight elements that were
>>> new in
>>> 1.1 or 1.2.
>> That's great! Will these include deprecated elements/attributes?
>> 1.1 flag - added in 1.1
>> 1.1d flag - deprecated in 1.1
>> 1. flag - added in 1.2
>> 1.2d flag - deprecated in 1.2
> I hadn't set it up for deprecated flags - it should be possible to  
> do that
> though, given that we have so few deprecated items at this point. If  
> I get
> time, I will do that.
>> Does lcDescription exist? It seems to be included in some Contained  
>> By
>> listings. I'm looking at langspectocjs20090108/alpha and it's
>> noticeable that lcDescription doesn't have a link whereas everything
>> else seems to be linked.
>> lcDescription has an entry in Complete Content Model Definitions, but
>> it says: Contained by: This element is not contained by any other
>> elements.
>> Really?!
> It does not exist. It was originally part of the DTDs, but was  
> removed from
> any content model; however, the definition was left in. I actually  
> noticed
> this in the contains/contained-by table, and asked the learning  
> group about
> it; they said the element should not be part of the DTD; I updated  
> the DTD
> and posted it, but forgot to re-generate the "contains/contained-by"  
> topic
> from the new version. It will be fixed in the next posting.
>> I appreciate tool vendors, developers and architects will know the  
>> XML
>> standards, and recognise these as such. But, quite frankly, CDATA
>> means nothing to a technical author!
> I asked the TC about this yesterday. JoAnn Hackos suggested defining  
> and the other values in the new "Reading the spec" topic.
>>>> Default value - #implied Where is #implied defined?
>>> That one is also an XML term. I can't say I understand why that is  
>>> the
>>> term, but in DTD terms, it means that the value is not defaulted.
>>> I'm not
>>> sure how to clarify that without leaving behind the standard XML
>>> terminology.
>> I don't understand what is meant by, "The Default Value is 'not
>> defaulted'." I'm simply replacing #implied with 'not defaulted'.
>> Surely, either there is or there isn't a Default Value? If there is,
>> why can't the value be specified?
>> W3Schools states this:
>> Use the #IMPLIED keyword if you don't want to force the author to
>> include an attribute, and you don't have an option for a default  
>> value.
>> The issue I'd have is that some times there ARE obvious contenders  
>> for
>> default values. Or, at least, it seems so to me ...
> The distinction here is between defaults enforced by the standard  
> (those
> specified in a DTD or Schema) and those enforced by a tool.
> The specification is listing only those defaults which are actually  
> defined
> as part of the standard - that is, defaults that a processing tool  
> cannot
> chose on its own, because when they see a document they pick up the  
> default
> value. One example that is core to DITA is the class attribute -  
> these are
> defaulted in the DTD or Schema, so any time a parser reads a DITA  
> topic, it
> picks up the class attribute from the DTD or Schema. A parser cannot  
> tell
> if an attribute was actually specified in a document, vs. defaulted  
> in the
> DTD or Schema. Another example is placement="inline", which is the  
> default
> for images - to get standalone display, an author *must* specify the
> attribute placement="standalone" on the image.
> As you say, there are frequently obvious contenders for a default  
> value -
> but those are typically defaults enforced by a tool. For example, the
> compact attribute on a list has no default in the DTD or Schema.  
> Tools are
> free to set the default, or to modify it to fit local style rules. For
> example, IBM's style generally forces lists to "not compact" when  
> there are
> block elements in the list, but leaves it as compact when the list  
> only
> contains phrases.
> The "Reading the spec" topic should make clear what the default  
> column is
> intended to do - that is, it lists the standard-enforced default,  
> rather
> than the generally anticipated default. As a side note, I've asked  
> the TC
> for advice on removing #IMPLIED ... I do agree that it's confusing  
> and I'd
> like to get rid of it.
> About spectitle:
>> Is it being deprecated in 1.2, then?
> I don't think the TC has made a ruling on it, so I haven't listed it  
> as
> deprecated. As you can probably tell, I would prefer that it be  
> deprecated.
> I'll check with the TC about it.
>> Contains seems to often, but not always, include 'text data'. Is this
>> another architectural/XML thing?
> Actually the XML thing in this case is #PCDATA, which means, user  
> entered
> text (as opposed to elements). We put in "text data" because it  
> seemed to
> make more general sense. Any other suggestions?
>> So, you seem to be saying that the DTD allows certain things which
>> would be stupid to implement?!
>> I suppose that's one of the penalties of inheritance?
>> Are processors obliged to handle this?
> Well, yes. It's really unrelated to inheritance, more related to  
> sharing
> elements between different document types. That is - we want to define
> something once and use it twice. But, to do that, we end up with  
> situations
> where the element allows things in one location that don't make as  
> much
> sense in the other. Most of these come in through the re-use of the  
> <desc>
> element, in which case the many elements that come in are  
> technically just
> as valid - even though it does rather blow the mind when you step  
> back and
> say "I can allow tables in my map???"
> I would say that processors are obliged to handle it in some manner,
> because it is valid. That is, you can't crash just because somebody  
> puts a
> table in their map. As with any element, how it is processed is  
> generally
> up to the processor.
>>> So far the namespace has remained the same between versions - I
>>> wouldn't be
>>> able to update that without input from the TC (some tools may depend
>>> on
>>> it). However, I've updated the spec so that it lists the version
>>> value as:
>>> "1.2" (version dependent; will increase)
>> I suppose it's also OASIS dependent?
> The namespace is up to OASIS, and the version is related to the  
> release of
> DITA (with 1.2 coming up, we up the version setting).
>>> I've added a reltable based link between the related links topic and
>>> the
>>> linking section - hopefully that helps.
>> I don't seem to be able to see that in langspectocjs20090108/alpha,
>> but sounds like it would help.
> Sorry - I meant to say that I was adding. It will be in the next  
> posted
> version.
>>>> note
>>>> Surely there should be a default value for @ type? 'note' seems
>>>> obvious to me!
>>>> I like the fact that the result from processing the example is  
>>>> shown.
>>>> I'd like to see more of this, if at all possible! ;-)
>>> While most processors probably treat 'note' as the default, the
>>> document
>>> type does not enforce a default, and at this point I think it would
>>> not
>>> want to change that in case some application treats it differently.
>> Hmmmm.... Just seems like an obvious gap to plug.
> I think this will be covered by the "Reading the spec" topic,  
> explaining
> that the spec can only list enforced defaults in the default column. I
> think <note> would make a good example for that topic - "There are  
> other
> generally recognized defaults, such as type="note" on the note  
> element,
> where..."
>> ... I was
>> looking at the Complete Content Model Definitions for base, and
>> thought a load of links had been left out - then realised why! It
>> looks odd to have links to term and ph, but not apiname, IMO.
> Yes, it does look odd - but when we don't have the apiname topic  
> available
> in that package, we can't really link to it. The 'official' version  
> of the
> standard will be the full "by type" version, which has all topics  
> included
> and all of those as links.
>>> Hmm. I've updated the title of "Prolog elements" to "Prolog  
>>> (metadata)
>>> elements" ... think that will help any? I've also added a "metadata"
>>> index
>>> term to that topic, for situations where we generate an index.
>> I can't see that in langspectocjs20090108/alpha, but it sounds better
>> to me.
> It will be in the next upload.
> Re: .xml versus .dita:
>> I just remember trying to pick up a 4GL database application, once.
>> The examples had been created by different folk, with different
>> methodologies, and at different times. I think I spent more time
>> trying to understand why one example did things one way, whilst other
>> examples did seemingly the same things another way, than actually
>> learning how it worked.
>> At the end of the day, it simply adds unnecessary confusion for
>> someone trying to learn DITA.
>> Just be brave and consistent, and use filename.dita throughout! Then
>> blame the Adoption TC when the flak comes! ;-))
> Oh, sure, you've won me over. I'll update it - in the next upload  
> they will
> all use .dita.
>>>> sl
>>>> Surely the default value for compact is 'no', not #implied?
>>> Covered above, I think - no default, which in DTD terms means
>>> #implied.
>>> Same for <dl>.
>> Surely it can only be one of 3 things: yes, no, or dita-use-conref-
>> target
>> So, which is it?!
>> If it's not required, and doesn't have a default value, then the
>> processor/toolkit has to decide. This could lead to a lack of
>> consistency between one transform and another.
> Yes, that's true. In this case though, I'm with the tool folks that  
> say the
> spec should not list a default. As described above - there are valid
> reasons that a company style or an output format might choose to go  
> one way
> or the other. If the spec says there is a default, then any output
> processor that does the opposite is no longer DITA-compliant. I do  
> think
> that the specification needs to be very strict about making sure that
> content is consistent - that is, if <xref> is supposed to pull  
> content from
> the target, then all applications should do it. However, how to  
> render an
> xref (or a list, or a figure) is always left up to the rendering tool.
> Anyway - my two cents on this one. As with the others, I think this  
> should
> be explained in the "Reading the spec" topic, and removing the  
> listing for a default value will also help.
>> There's surely a potential clash? E.G., scale could be defined in 2
>> places. Would one scale multiply with the other? What if scalefit is
>> used in the image, and the fig uses a scale from %display-atts?
>> I'd have thought it might be worth a discussion, but I'm ready to
>> concede that my argument is somewhat theoretical. Maybe the two don't
>> really clash, in practice?
> If you'd like, I can go to the TC to ask about how scale interacts...
> otherwise I will leave it up to implementations.
>>>> cite
>>>> What is the expectation, if any, from the processing?
>>> This is one where I'd prefer to stay away from formatting
>>> descriptions.
>>> While the pre and lines elements have formatting (line breaks) as
>>> part of
>>> their core purpose, this one is meant to define a citation. There  
>>> are
>>> enough style guidelines out there with different ideas about how
>>> citations
>>> should be formatted that I would rather keep the DITA spec out of  
>>> the
>>> debate. FWIW, I just checked how the HTML specification defines the
>>> cite
>>> element, and it says "The presentation of phrase elements depends on
>>> the
>>> user agent."
>> Sounds like a cop-out! ;-)
>> OK, I do understand the difficulties, but as a tech. author I don't
>> think it's unreasonable to know how something 'is likely' to be
>> rendered. Bold? Italic? Or is it more for semantic purposes, and not
>> to be rendered any differently?
> It is a bit of a cop-out, but it's one that standards like this are
> generally forced to go with. For citations in particular - there are  
> many
> conflicting style guides about how citations should be presented,  
> whether
> that is with quotes, in italics, or in plain text. I know that IBM  
> for one
> has pretty complex rules governing the presentation of citations. As  
> to
> whether this is for semantic purposes - with only a few exceptions,  
> all of
> the DITA elements are there for semantic reasons rather than for  
> rendering
> purposes. The highlighting domain elements are of course an  
> exception, as
> are some of the core elements like <bodydiv> that are present as  
> building
> blocks rather than for any semantic purpose.
> I will add this comment to the <cite> topic: "Though citations will  
> often
> be set apart from surrounding text, such as through italics,  
> rendering of
> the &lt;cite> element is left up to implementations."
>> It's certainly an interesting one! Should q correspond to single or
>> double quotes, for instance? Do all languages recognise their own
>> versions of single and double quotes?
> This one is an open topic for discussion at the TC right now. HTML 4  
> and
> XHTML 1 both said that quotes should be rendered automatically with  
> <q>.
> The working drafts for HTML 5 and XHTML 2 both reverse course and say
> authors must add them. I'm trying to track down their reasoning.
> The spec will have to address this, even if only to lay out the  
> concerns
> for both tools and authors. In this case the rendering will explicitly
> affect what authors enter - if tools are supposed to add quotes, they
> should not, and vice versa. So authors need to know what the  
> expectation or
> concerns are.
>> If at all possible, I would really like to see a version of the
>> Language Spec. tailored to an authoring audience.
> It is certainly possible, in fact trivial, to reformat the guide  
> without
> the inheritance section. It's possible, but less trivial, to filter  
> out the
> attribute columns so that it contains only the name and description  
> of each
> attribute (and drops the data type / default / required columns  
> entirely) -
> I know some groups have done that for their authors.
> When starting work on DITA 1.3, I think we should think from the  
> start if
> there is any way to set up the guide to make this multi-audience  
> aspect
> easier.
>> I don't know whether PIs would be appropriate for inclusion in a
>> Language Spec., but that seems a way out of the 'toolkit as main
>> processor' debacle.
> They are not technically part of the language, so they cannot really  
> be
> included at this point. PI's are also a bit of a religious debate in  
> the
> XML community - some love them, some hate them with a deep and abiding
> passion. There were long and fierce debates over whether they should  
> even
> be in XML in the first place. I'm in the middle - I prefer to avoid  
> them,
> and I've seen them used in terrible ways, but I feel they have do  
> have a
> valid role. It seems to be rather lonely in the middle though.
> Thanks again for the review -
> Robert D Anderson
> IBM Authoring Tools Development
> Chief Architect, DITA Open Toolkit

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]