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


From: David J. B. Hollis <dhollis@AandOConsultancy.ltd.uk>
Date: 11 January 2009 20:43:16 GMT
To: Robert D Anderson <robander@us.ibm.com>
Subject: Re: DITA 1.2 Language Specification Comments

Hi, Rob

> I'm finally getting to my backlog of spec comments, and yours has  
> quite a
> few questions in it, so here are my answers:

Thanks for taking the trouble to go through them all. I appreciate  
some of them ended up with a bit of a XML tutorial! I think this is  
why I thought I'd join the Adoption TC - so that I wouldn't be  
involved in the Language Spec., and now here I am! ;-))


>> 1.2 seems to now include Machine Industry, Hazard, Learning and
>> probably others. Is this merely a convenience during the draft  
>> stages,
>> or is this the way the final Spec. will be constituted?
>
> It's mostly a convenience during the draft stages. A goal all along  
> has
> been to break the spec up into several groups; each document has its  
> own
> section in the review page here:
> http://wiki.oasis-open.org/dita/Draft_DITA_1.2_Specification_Review_Assignments

You might want to update the links on this page to the latest versions  
of the draft Language Spec.

Also, I'm not a member of the DITA TC, so I can't edit the assignments  
to say that I'm done.

> A pre-requisite for that is having the architectural spec, which has  
> not
> yet been released in draft form, so no real progress has been made  
> towards
> generating those separate versions. I think that addresses the next  
> few
> paragraphs of your note, so I'll move on to:

OK


>> As the Language Spec. is so large and complex, and is almost bound to
>> contain mistakes regardless of how thorough folk are, would it be an
>> idea to set up a reporting mechanism?
>
> 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
> (and of each version that comes out as an 'official' OASIS draft.  
> You can
> see what I mean under "Status" in the 1.1 language specification:
> http://docs.oasis-open.org/dita/v1.1/OS/langspec/ditaref-type.html
>
> As to whether we should have that information on every page - I'd  
> leave
> that up to the full TC and/or OASIS staff to determine.
>>

How effective is this reporting mechanism? Have you had any comments  
from it?


>> Inheritance paragraph. I appreciate that 'Inheritance' is a very
>> important core facet of DITA, but I'm not sure of the significance of
>> it in the spec.!
>
> By this - do you mean the section that lists the specialization
> inheritance, such as "- topic/ph task/cmd "?

Yes. Preceded by Contains & Contained By; followed by Examples.

> When I got started on the DITA
> 1.2 docs, I sent a note to the TC asking if anybody found that section
> useful. I got a pretty emphatic Yes from some tool vendors who use  
> that for
> their own reference, so it stayed in. I know that I find it useful  
> when
> trying to work out how some elements are specialized, but I was  
> willing to
> remove it if I was the only one using it...

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.


>> The other thing I don't understand about the Inheritance listing is
>> that it only includes the root, not the 'path' in between. E.G.
>> navtitle and searchtitle need either titlealts or topicmeta as
>> parents, but Inheritance just shows them inheriting directly from
>> topic or map. Again - confusing to me.
>
> The information is specific to how the elements are defined in DITA,  
> and is
> unrelated to how they are used within a document. For example,
> topic/navtitle and topic/ph mean that these two elements are defined  
> in the
> topic module (though they may be reused elsewhere). The value map/ 
> topicref
> means that topicref is defined in the map module, though it too may  
> appear
> in any specialized map. The value "map/topicref bookmap/chapter"  
> means that
> the chapter element is defined in the bookmap module, based upon the
> topicref element in the map module; it can be used within the bookmap
> module or any specialization of bookmap. Any suggestions on where to
> clarify this?

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.

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.


>> 'Element Re-use'! A number of elements are re-used in other parts of
>> the spec. I think it would help if the explanatory paragraphs at the
>> top contained links to these other usages. Possibly also reltable  
>> type
>> links at the bottom amongst the next/previous/parent links? It can be
>> confusing when stating that something within a topic 'is available'
>> within a map. What seems to be meant is that the element is 're-used'
>> in the map part of the Language Spec., however, it could possibly be
>> construed that something is going on in the processing. (My 2  
>> penn'orth)
>>
>> Why do these 're-used' elements only have one entry? If title can be
>> used in topic, map and reltable, why not include a relevant piece in
>> the two latter sections and not just the first? Or at least have a
>> link or conref from the latter two to the first. As there ought,
>> ideally, to be relevant examples for all uses, it would seem to make
>> sense to have tailored entries wherever an element is used.
>
> We want to be careful with this for a couple of reasons. First - the  
> goal
> is that, regardless of where it is used, an element will mean the same
> thing. So, <title> should semantically mean the same thing, whether  
> it is
> used in a topic, map, or reltable. If we have separate entries to  
> describe
> title in each case, we will end up reproducing much of the  
> description,
> only differing in the example. We would also be on a slippery slope  
> - do we
> need a new topic and/or example for title in figure, title in table,  
> title
> in linklist? What about ph - do we need a new topic or example for  
> each
> place it can be used? Particularly with the way DITA specialization  
> can
> create new elements, this could be an explosion of new topics /  
> examples
> that might cause more confusion than it saves. At least - if I'm
> understanding the request correctly. If I'm not, please let me know.

Firstly, I'm certainly not suggesting any topics should be fully  
duplicated ...

> I think the best way to address this might be to find those elements  
> where
> it would be useful to have examples of more than one usage, and simply
> include an extra example?

... that would be the exception, examples for different usages.

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.


>> TOC sidebar listings. Instead of just a straight listing of all the
>> elements associated with a parent, you could get 'real cute' and use
>> the TOC hierarchy to visibly display the DITA structure!
>
> In the end, I think we (the TC) will be using the standard OASIS  
> navigation
> format - next/previous links to go through each topic, along with the
> overview topic I linked to above. If somebody wants to pick up the  
> source
> files and render it using a structure based view ... I certainly  
> would not
> oppose the effort. I will say that one reason to be careful with  
> that is
> that it requires some knowledge of the context in order to find  
> information
> - to look up <cmd>, you would have to know that it is in task- 
> >taskbody->
> steps or steps-unordered -> step -> cmd. But - I have no problem  
> with that
> navigation being available alongside a flatter navigation structure.

Great! Now just need someone to do it! ;-)

Or sponsorship for me to do it! ;-)


>> I feel it would be quite helpful to mention the version of the spec.
>> that introduced the element. E.G. bodydiv and sectiondiv were/are
>> introduced with 1.2. What happens when content with 1.2 structure
>> elements is processed with a previous version of the toolkit?
>
> 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


>> Could this be extended to attributes? I notice that 1.2 introduces  
>> the
>> scope attribute, so related-links has had this added for 1.2. Are
>> there any instances where existing attributes are introduced to an
>> existing element to augment it? I accept that could get tricky! But
>> it's crucial information for XML tool vendors, doc. architects,
>> service providers ....
>
> I've tried to mark this in the source, but haven't been able to do it
> everywhere. And yes, there are cases of existing attributes being  
> added to
> additional elements - see OASIS item 12050 for a whole list of them:
> http://lists.oasis-open.org/archives/dita/200707/msg00025.html

Wow!


>> I would like something to explain the 'why' behind bodydiv, section,
>> sectiondiv. Especially w.r.t. topic based authoring, which ought to
>> lead to short topics! Perhaps it's to do with chunking, or different
>> pieces for different audiences with DITAVal based processing?
>
> I've tried to put this information in for bodydiv and sectiondiv - for
> example, from bodydiv:
> "The bodydiv element is specifically designed to be a grouping  
> element,
> without any explicit semantics, other than to organize subsets of  
> content
> into logical groups that are not intended or should not be contained  
> as a
> topic. ... The bodydiv element may nest itself, which means that it  
> may be
> used by specializers to create structured information within a body."
>
> Those are the primary reasons I know of to use it - 1) to group  
> elements
> that logically go together, where a container is helpful (for  
> authoring, or
> for reuse, or for filtering, or whatever), and 2) for  
> specialization. Do
> you have any suggested text for sections? We already say that it is  
> "used
> to organize subsets of information that are directly related to the
> topic. ... Multiple sections within a single topic do not represent a
> hierarchy, but rather peer divisions of that topic." To me, that  
> pretty
> much explains it - but I'm pretty close to it so I could be missing
> something obvious.

I can't think of anything else to add.


>> There's something a bit peculiar with a number of the Contains
>> listings: Why has topic been separated from concept, ditabase,
>> glossary, reference, task? This wasn't the case with 1.1. It doesn't
>> look like there's any difference between topic and the rest. I've
>> highlighted where I've noticed this anomaly.
>
> Wow, thanks for noticing that. There was a tiny difference in the  
> order of
> the models - topic listed (syntaxdiagram or imagemap) while the  
> others were
> reversed, so my consolidation tool missed it. That was based on the
> declaration in the DTD, which is used to generate those models. I've  
> fixed
> the topic DTD to bring it in line with the others, so the problem  
> will be
> fixed.

My pleasure! ;-)

You might check Contains listings for:
abstract, body, bodydiv, dd, draft-comment, entry, example, fn,  
itemgroup, li, lq, note, p, pd.

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?!


>> CDATA Where is this defined? Sometimes the Attribute listing Data  
>> Type
>> lists the potential values, sometimes it just states, 'CDATA'.  
>> Looking
>> at related-links, for example, @ role has 12 potential values listed
>> out, but it's necessary to follow a link to find the 4 potential
>> values for format. For someone like me, it doesn't make sense!
>> Presumably the DITA structure does define the @ values for an  
>> element,
>> so why can't these just be listed? (OK, I'm probably being naive ...)
>
> CDATA is an XML term meaning character data. I'm not sure where best  
> to
> define it, but if you've got a suggestion, it wouldn't hurt. That is  
> - the
> value CDATA is very meaningful for those of us who work with a lot  
> of XML
> specifications, so I do not want to remove it, but I also do not  
> want to
> have an explanation every time it is used.
>
> For format - the attribute itself is CDATA, meaning that anything  
> can be
> typed in and be valid. The specification defines a few values that  
> must be
> recognized, but any other value is valid, and applications may add  
> their
> own values. The full explanation of @format is too complex to fit in  
> the
> usual table, so we link to another topic as we do for role;  
> unfortunately,
> the DTD does not force us into using one of 12 values, as it does  
> for role,
> so the table only lists it as CDATA.
>
> That's the explanation of current behavior, anyway - I'm happy to  
> hear any
> suggestions you've got for improving it.

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'd suggest something like 'User defined value' for @ audience = author

>> 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 ...


>> classifyMap Appears in Contains/Contained By listings, but I can't
>> find it in the element toc?
> classifyMap is a document type, rather than an element. A  
> classification
> map is simply a map with the classification domain added - no new
> classifyMap elements.

Oh, right!


>> @ spectitle I don't know the significance of this, but I have noticed
>> a number of elements which are assumed to be prime candidates for
>> specialisation but don't include this attribute?! Why is it included
>> in ol, ul & sl, but not li or sli? I'm missing the rationale behind
>> it. If a specialisation can modify elements and add attributes, then
>> what's the point of spectitle? If a specialisation needs such an
>> attribute, it could add it itself, surely?
>
> This was originally used on block elements, with the thought that a
> specialized DTD could pre-define titles for a specialized block.  
> That is
> really not a good idea from an NLS perspective, and I think it is  
> being
> phased out - that's why it has been intentionally left off of many  
> other
> elements. As a side note - a specialization is unable to define a new
> attribute for a single element.

Is it being deprecated in 1.2, then?


>> Tags in text. E.G. "Use the tagname <tag> ..." appears in the
>> description quite frequently. Technically, should it be "<tag/>" or
>> "<tag> </tag>"? Or am I just being pedantic? But isn't that what a
>> structure is all about?! BTW, I'm not talking about the examples,  
>> just
>> the descriptive passages.
>
> Right now I don't really want to go back and change them all - I  
> think that
> the point is clear by saying use <something> for this or that.  
> However, in
> the examples, I'm trying to correct any usage that leaves off an end  
> tag.
> My thought is that people should be able to cut/paste the example  
> and have
> it work, but I don't feel the same about the element name in the  
> middle of
> a sentence.

OK. I'm being pedantic!


>> Contain/Contained by listings. My guess is that this is an 'age
>> thing', but some of the listings are comma delimited, and some are
>> 'or' separated. I think I would like to see one or the other, not
>> both. Preferably comma delimited, but I'd be happy with just a space.
>
> Scanning the topic - I don't see commas used in the contains  
> section, only
> in contained by (where it is the only thing used). The contains  
> section
> uses other delimiters to indicate whether an order is required --  
> (this or
> that) when they may be used in any order, and (this then that) when  
> this
> must come before that. Of course contained-by has no order, so  
> commas are
> easier.

OK, I hadn't appreciated that different delimiters were used in the  
Contained and Contained By sections.

Contains seems to often, but not always, include 'text data'. Is this  
another architectural/XML thing?


>> Can you nest lists? ol inside a li within a ul, or vice versa. Do the
>> transforms expect and handle this eventuality? What depth of nesting
>> is catered for? Would it be possible to set up style sheets which  
>> have
>> the first level of ol nesting as a numerical sequence, and the next
>> as an alphabetical sequence, and so on? Increasing the left/first
>> indents, too. (You can do this stuff fairly easily with Word, so I
>> would hope so!)
>
> Yes, the DITA-OT switches numbering, and I would expect any  
> rendering tool
> to do so. Do you see someplace in the spec that needs to clarify  
> this? With
> the caveat that the spec is not really supposed to describe stylesheet
> formatting, as (in most cases) that is entirely up to the rendering
> application.

Something like that would help, but I'm sure it's outside the Language  
Spec.


>> Given that there is ol, ul, sl, DITA is coming close to crossing the
>> divide of divorcing presentation from content. If these normally
>> process to numbered, bulleted, none, then you might as well add
>> another for an alpha listing, or include a number/alpha attribute for
>> ol. Those style sheets can be very awkward to hack, and it may not be
>> unreasonable to allow the author the decision about the type of list
>> they expect to see? Maybe also a diamond/bullet attribute for ul? Is
>> that going too far? Re-hashing old arguments, again? ;-)
>
> Yes, old arguments. DITA defines core types that are generally  
> applicable -
> ordered, not ordered, and simple (no blocks). Applications can  
> choose how
> to render those, and they can also choose how easy it is for their  
> users to
> modify those styles.

OK

>> Content in maps? I've been looking through topic & body, and later
>> ditaval. With just the first two, I've been a bit surprised at how
>> many of these elements can be used in maps. This would lead to the
>> implication that maps could contain a significant quantity of  
>> content.
>> I think I can see the rationale that maps may need to contain prolog/
>> metadata, descriptions, abstracts and possibly indexing terms.
>
> Most of the elements that will confuse you, such as fig and table,  
> are only
> there because the DTD makes us do it. The only way to put them in is  
> to put
> in <xref>, which allows <desc>, which allows all of those other  
> elements
> (just as it does in topics). The only elements that are really easy to
> enter, and that users will tend to see, are the phrase level ones like
> index terms and keywords (and their specializations). Generally  
> they're
> only going to be used in titles and short descriptions, which are  
> available
> in all topicrefs but are particularly important when referencing non- 
> DITA
> content.
>
>> ... Anyway, the
>> point is, if it can be inherited from both topic and map, please  
>> state
>> this fact - we need to know it! ;-)
>
> Does this mean that if an element can appear in both topics and  
> maps, you
> want a note to that effect in the spec? That will be difficult -  
> most topic
> based elements can now be used in either spot, due to the issues I
> mentioned. Of those, many probably should not be encouraged (such as  
> fig
> and table). Additionally - DITA lets you plug domains in and out,  
> which
> means that in many cases, it will be up to the user whether or not an
> element (like imagemap) becomes available in maps.

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?


>> Deprecation. I've just noticed that some attributes have been
>> deprecated in favour of nested elements. I imagine it wouldn't be
>> difficult to come up with XSLT transforms which convert attributes to
>> elements?
>
> I agree, though at this point we're leaving that up to the  
> applications. If
> you want to post transforms that do it, I'd be happy to point people  
> that
> way...

;-)

>> BTW, this is a thought in passing ... can DITA do the equivalent of
>> JavaDoc, etc.? In other words, is it possible to have a single source
>> doc which produces both the software build and, say, the API Ref.? I
>> suppose there are 2 obvious things: filename extensions, and being
>> able to ignore the 'other' content. Software ignoring DITA, and vice
>> versa.
>
> I know of a lot of people discussing things like this, but I think  
> this
> isn't the spot to go in to it. For example, one person in IBM has  
> created a
> utility that scans Javadoc and produces DITA using the JAVA Api
> Specialization (she presented it at a conference this fall, and will
> publish an article with demos soon).

I didn't know there was a  JAVA API Specialisation!


>> More ponderings ... What about a newsletter and newsfeed  
>> transforms? A
>> way of breaking into marcomms! Give them a tool which single sources
>> an xhtml page, an email which can be sent to a list, and a message  
>> for
>> a RSS newsfeed. Then all they have to do is lean on IT to get the  
>> page
>> up quickly! ;-) Or maybe they're using DITA2Wiki! ;-)
>
> If you want to put together transforms to do this, I'd help you set  
> them up
> as DITA-OT plugins, and I'd be thrilled to post them up at the DITA- 
> OT page
> with other plugins...

Yes, maybe! ;-)


>> Specific Comments
>>
>> Topic elements
>>
>> topic
>>
>> ditaarch:DITAArchVersion="1.0"
>> xmlns:ditaarch="http://dita.oasis-open.org/architecture/2005/";
>>
>> Whilst there is consistency between 1.1 and 1.2, IMO, both are wrong!
>> Surely each should define its own version: 1.0, 1.1, 1.2 and the
>> correct URL?
>
> 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?


>> Does an xmlns only ever point to a single instance, which by default
>> will be the latest version? Or is this an OASIS thing? Surely that
>> would imply an xmlns MUST ALWAYS be backwards compatible? Hmmmm?!
>> Surely there'll be some dead wood along the way? How do you deprecate
>> something?
>
> I make no claims to being a namespace expert - but I know that  
> namespaces
> do not have to reflect a real existing URL, and as such,
> "http://dita.oasis-open.org/architecture/2005/"; can be interpreted  
> simply
> as the DITA namespace, without making any claims about versions and/or
> dates. I do see the confusion, but the TC will have to discuss that  
> if it's
> ever to be updated.

OK.


>> title
>>
>> Title can be used in Maps, 1.1, and RelTables, 1.2. Shouldn't the
>> Inheritance and Examples reflect this? Shouldn't there be title
>> sections in these other two areas?
>>
>> It seems that title is also used in Machinery and Learning. Should
>> this be mentioned?
>
> That was just intended to highlight that prior to 1.1, title could  
> not be
> used in maps, and prior to 1.2 it could not be used in reltables. Do  
> they
> really need examples? Or does the language need clarification? In all
> cases, the title has the same meaning - provides a title for the  
> topic,
> map, or reltable, along with the other use contexts. It is used in  
> many
> other locations as well.

OK


>> I can't see reltable in Contains/Contained by - is that just me?!
>
> I'm not sure about that - it is in my copy of the contained-by  
> section for
> title:
> map, learningMap:  data, fig, figgroup, table, map, reltable,  
> relcolspec
> bookmap, learningBookmap:  data, fig, figgroup, table, map, reltable,
> relcolspec, bookmap
> etc...
>
> Reltable is also in the contains/contained-by topic, and lists title  
> under
> "contains".

Seems to be there ... ?


>> navtitle
>>
>> This could do with being edited:
>>
>> Beginning with DITA 1.2, the navtitle element is also available in
>> topicmeta in a map, and its use is preferred over the navtitle
>> attribute.
>>
>> Does that mean that metadata in the topic is being 'drawn into' and
>> used within the map? Is 'topicmeta' an accepted word? Is it part of
>> the Language Spec.?
>>
>> ... OK, answered my own question! May I suggest a link to
>> Map:topicmeta, please?
>
> In general I shy away from links within the initial short  
> description - we
> try to follow DITA principles and keep them to the end, so as not to
> distract the reader. However - I have updated this to <topicmeta> so  
> that
> it is clear that this is an element.

OK


>> Should Inheritance reflect the use of navtitle in topicmeta? There  
>> are
>> Examples of both uses - Good! ;-) Should there be a navtitle section
>> in the map area?
>
> Do you mean within the TOC section? We've tried to have the elements  
> appear
> only once, so I'm a little hesitant. I'd be happy to raise this with  
> others
> though to see if I'm outvoted.
>
>> The use in topic is within titlealts, but the use in topicmeta  
>> doesn't
>> involve titlealts, even though Map can have a title!
>
> The usage is different. Within maps, it is not an alternate title  
> for the
> map - it is a navigation title for the target of a topicref. I've  
> updated
> the description to clarify that this applies to the topicref target,  
> rather
> than to a map - I can see where the confusion came from.
>
>> searchtitle
>>
>> searchtitle can be used anywhere navtitle can, e.g. in maps, so why
>> not similar explanations, Examples, etc., etc.?
>
> The explanations are missing because searchtitle has always been in  
> both
> spots, while navtitle is only appearing in topicmeta with DITA 1.2.  
> I've
> added an example with maps now.
>
>> searchtitle is contained by topicmeta, bookmeta, but navtitle by only
>> topicmeta, NOT bookmeta. Is this correct? Why leave navtitle out of
>> bookmeta?
>
> Bookmeta is a specialization of topicmeta, where we initially went  
> through
> and decided which topicmeta contents to preserve (in DITA 1.1). With  
> DITA
> 1.2, we added navtitle to topicmeta, but did not go back and decide  
> whether
> to put it into bookmeta. This was probably an oversight, but not  
> something
> I can correct without discussion at the TC.
>
>> Peculiarly, it has what I've been suggesting re. Inheritance:
>>
>> "- topic/searchtitle " when used in topics, and "- map/searchtitle "
>> when used in maps.
>
> Searchtitle is one of 2 elements (the other being shortdesc) that are
> declared twice in DITA, with two different inheritance values.  
> Again, it
> has nothing to do with the parent - it is related to the module that
> defines the element. With DITA 1.0, searchtitle and shortdesc were  
> each
> defined in both the topic and map modules, with differing class  
> values.
> With DITA 1.1, we made the content models the same, but we cannot  
> change
> the class attribute (which defines these values) without breaking  
> existing
> tools. It will be changed in DITA 2.0. These are the only two  
> elements with
> 2 different inheritance values - I'm not sure how to clarify them,  
> given
> that these are the only two elements, and those are the only two  
> values in
> each case. The listing should not affect any other elements.

OK

>> abstract
>>
>> Contains: why has topic been separated from concept, ditabase,
>> glossary, reference, task?
>
> Answered above; I've dropped this comment from the remaining elements.

OK

>> shortdesc
>>
>> Personally, I think Examples are probably one of the most important
>> aspects, so I'd prefer to see these examples conref-ed in, rather  
>> than
>> linked to.
>
> Done.

Thanks!

>> An excellent description! Shame there aren't more like this! ;-)
>>
>> Hmmm, having said that, there's no mention it can be used in maps,
>> except in Inheritance. With so many of these elements turning up in
>> topic as well as map, it's really important to ensure folk understand
>> the implications of where they are placed, and how and why maps
>> override topics - assuming they do?! Oh, yes, not forgetting all the
>> prolog elements, which include metadata and othermeta! Oh wow! ;-)
>
> Given the importance of short descriptions - I've added a section on  
> the
> use of shortdesc within maps. I've also added an example. As a side- 
> note,
> there is a topic on how these items override topics within the
> architectural specification.

OK

>> bodydiv
>>
>> Does this assist chunking? If so, why not say so? Why use bodydiv,
>> rather than section?
>
> See comments above.

OK

>> There seems to be the equivalent conbodydiv and refbodydiv, but not
>> taskbodydiv?!
>
> Yes. Conbody and refbody both have loose content models with no  
> enforced
> order -- (this or that or theOther). So, like topic, it is easy to  
> create a
> grouping element that can contain those items and float among them.  
> Tasks
> have a very specific order, which really prohibits the creation of a
> taskbodydiv element; if it allowed all of the taskbody contents, as  
> refbody
> and bodydiv do, it would no longer be possible to enforce an order of
> (context then steps then result).

OK

>> This begs the question whether the Contained By info. is correct? Are
>> body & bodydiv really contained by concept, task, reference, or  
>> should
>> these be conbody/div, refbody/div, taskbody/div? Please don't say  
>> both
>> are possible?!
>
> I'm not sure I follow. For example - concept allows conbody, which  
> allows
> conbodydiv, which nests itself. The <body> element cannot contain
> conbodydiv, and the conbody element cannot contain bodydiv.

It's the list of Doctypes, which seems to be very inclusive.

> The confusion may come from the fact that within the concept  
> document type,
> body is listed as the parent for bodydiv? This is due to a  
> requirement of
> the DTDs and Schemas for DITA. Because concept is based off of  
> topic, the
> topic elements are defined in the concept document type. So, the body
> element is defined, even if it is not possible to use it directly  
> inside of
> the <concept> element. It would, technically, be legal to create a  
> topic
> that you call concept, which starts with <topic> or <body> ... I say
> technically because the rules of XML cannot prevent it, although  
> some DITA
> processors might rebel.

OK

>> example
>>
>> The significance of the spectitle attribute is lost on me!
>
> In my opinion, that may be for the best, as it discourages use. ;-)  
> I feel
> that we've discussed deprecating this attribute, though I can't find  
> any
> record of that so I can't say that in the docs.

Probably best to try to formally deprecate it?

>> related-links
>>
>> It would be very useful to have a link into the related links  
>> elements
>> from here. I appreciate it needs to be part of topic, but it is
>> somewhat divorced from its 'natural context'. It would also be useful
>> to have a link to reltable.
>>
>> Something about the trade-offs between topic based linking and map
>> based linking might be useful.
>
> 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.

> The topic vs. map based linking
> should be covered in the architectural specification.

OK

>> Body elements
>>
>> p
>>
>> Inheritance should include - map/
>
> I think that's been covered above.

Yup!

>> 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.

> As to
> processing - this one's an exception to the general rule of leaving  
> that
> stuff out, though I think that some people would like this one  
> removed as
> well. I do feel that it is more important here than in many other  
> spots.

OK

>> keyword
>>
>> As it mentions <text/>, how about a link?! OK, it is the next one
>> along, but ....
>
> Done.

Great!

>> Should definitely have link to keywords
>>
>> Why, oh why, is keyword under body, but keywords under prolog?!
>> Confused - I is!?!
>
> Hmm. It's because keyword itself is an inline text element, while  
> keywords
> is meant to specify metadata about the topic (and is thus included in
> topicmeta and prolog). I've added a bit more explanation, and a link
> between the two.

Great!

>> If a keyword can be used for, e.g., a product name, could it be  
>> conref-
>> ed in and effectively become a text variable? Example, please?
>
> I've added an example where this is used as a product name.

Great!

>> Is this something which folk might wish to specialise? If so, would @
>> spectitle be useful?
>
> Even when used as originally designed, spectitle was only meant to  
> be used
> on block elements, so it would not be appropriate here. As a side  
> note -
> any element can be specialized (and most already have been by  
> somebody).

OK

>> I really like the idea of element descriptions pointing to other
>> elements which may be more appropriate for certain situations, but
>> could these include links, please?
>
> I've included links for some of these. As mentioned above, we  
> generally shy
> away from this in the descriptions, but in some spots it is clearly  
> a good
> idea. In this case - we do not want to add links for elements like
> <apiname>, because that is part of another DITA module. As such,  
> it's quite
> possible - and likely, starting with DITA 1.2 - that the keyword  
> topic will
> be published in a situation where apiname does not exist, and the link
> would be invalid.

Would you not expect a processor to handle this eventuality? 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.

>> "In metadata, a keyword is used to create additional XHTML metadata"
>> OK, I know what it means, but firstly it's a poor sentence, and
>> secondly DITA seems to refer to 'metadata' as 'prolog elements'.  
>> Link,
>> please! ;-)
>
> I've deleted that sentence - I don't think it added much which wasn't
> covered elsewhere (partially by the new edits re: keywords).

OK

>> There's a following paragraph which continues this 'metadata' theme.
>> I'm thinking of folks (like me!) who'll go hunting for a section on
>> 'metadata elements'. The nearest is probably 'Bookmap metadata
>> elements', so folks will end up there and may never find 'prolog
>> elements'!!!!! (The DITA Structure Maze! .....) ;-)
>
> 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.

>> What does the toolkit do with keyword in body? Anything, or is it
>> assumed to be mainly semantic? OK, someone will point out that
>> processing can be customised, but it would be nice to know the
>> original intention.
>
> It simply outputs it as phrase content - does not attach any specific
> presentation to the element.

OK

>> text
>>
>> I'm curious to know why text would not be contained by p? You're
>> forced to nest it within something else.
>
> It's to discourage use of the element where something more semantic is
> available. Keyword was originally intended to be this semantic-free
> element, but the specification did not make that clear enough, and it
> developed the semantic of "key word" ... though I'm not sure what that
> means. There is a lot of discussion about this on the OASIS TC list,  
> I'm
> not sure how much belongs in the spec. Do you think the spec should  
> cover
> this as well?

It's clear to use alternatives first, so probably best to leave it as  
that.

I've got something of  a dtp background, and 'body text' is often used  
as a base style. Hence, there's a degree of confusion - for me, at  
least.

>> xref
>>
>> "<p>Background information about DITA is provided in the topic
>> titled ..." should be 'entitled'.
>
> Got it, thanks.

OK

>> filename.xml# ... should that be filename.dita? Can we have
>> consistency & examples of best practice, please?!
>
> The architectural spec makes clear that .xml and .dita should both be
> supported by DITA applications, though it does not rule out other
> extensions. I know people on both sides who insist their choice is  
> correct,
> as well as those who insist you should mix both freely. I find that  
> makes
> it a bit more difficult to be consistent ... any more thoughts on it?
> Personally, in my life, I use .dita all the time ... but I know of  
> tools
> that create them each way.

I once worked for someone who advocated consistency, even if it  
transpired later that it was wrong! The point being that it is easier  
to correct something which is consistently 'wrong' than something  
which is inconsistent.

I appreciate that there could be an almighty ding-dong argument about  
which is right, but someone new to DITA IS NOT interested in that!  
They just need a steer in a 'sensible' direction.

For someone new to DITA, they are going to be confused by obvious  
inconsistencies. filename.dita mixed in with filename.xml may 'work',  
but it doesn't necessarily 'make sense'.

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! ;-))

... IMO!

>> " ... IDs of topics in DITA must be unique within a file ... " That
>> seems to be implying that a file may contain more than one topic? Or
>> does it really mean that the IDs of topics must be unique across the
>> set of files to be processed?
>
> Yes, a file may contain one topic - they may nest. The ID  
> requirement is
> only for uniqueness within a given topic.

OK

>> The examples don't appear to have changed from 1.1 to 1.2, however  
>> RFC
>> 3986 has been adopted for the href attribute.
>
> I don't know if that has any impact on the samples - DITA has not  
> changed
> its definition of the href attribute.

OK

>> ol
>>
>> I would appreciate something which explains what is anticipated to be
>> different between the processing of ol & ul, please. I could imagine
>> that ul includes a bullet, but ol a numerical or alphabetical
>> sequence. ul does mention bullets, but ol doesn't mention anything.
>> What's the default processing for the toolkit?
>>
>> I take it that the ol list must be placed in the correct order
>> manually? That is implicit in the example, but not explicitly
>> mentioned. Who knows? Someone might assume the toolkit has psychic
>> powers to divine the author's wishes! ;-)
>
> I started to add a comment that ordered lists will appear numbered,  
> but to
> have that, I think I would have to add a comment about nesting  
> depth. At
> that point, I'd have to say that nesting depth determines the way  
> numbers
> are rendered ... but not everybody will want to do that. I think  
> that I
> would really rather leave the <ol> rendering up to applications -  
> which
> will generally number lists as they do an ordered list in any other  
> format.

OK

>> li
>>
>> It seems li has the processing info. I was looking for with ol!
>
> Hmm. I wonder if people on the other side of the argument will come  
> after
> me to remove that. Probably not.

Depends if they notice! Glad I'm not in your shoes! ;-))

>> 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.

>> dt
>>
>> Repeats one of the dl examples, whereas most of the other related
>> elements link back to the example in dl?
>
> This is because I edited the <dt> topic more recently. Same for  
> <dd>. I've
> updated the others.

Great!

>> fig
>>
>> How does the use of @ display-atts at the fig level work? How do  
>> these
>> interact with the image attributes? It would be really helpful to see
>> some rendered examples!
>
> I think that they work exactly as described (for applications that  
> support
> the values). I hadn't considered how this might interact with  
> images, which
> (I think) means this is implementation dependent. I'd have to get  
> the TC to
> agree on a behavior before I define one in the spec.

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?


>> figgroup
>>
>> Frankly, I think the terminology here is very poor! Groups contain
>> more than one item. It's not a case of several groups within a single
>> item. An item can have parts. Hence, IMO, it ought to be figpart, or
>> figpt, not figgroup!
>>
>> But, having said all that, the example doesn't make much sense, so I
>> might be completely wrong!
>>
>> I guess it depends upon whether you think in terms of a 'group of
>> figures', or a 'multi-part figure/image'. However, the confusion
>> really stems from figgroup being inside fig.
>
> I've updated the example and tweaked the wording for figgroup. As
> background - the element was created simply to group other elements  
> within
> a figure. The primary use that I know of is in the syntax diagram
> specialization, where various syntax groups are specialized from  
> figgroup.
> As to the name of the element - that can't change at this point, but  
> I can
> certainly clarify the example.

OK

>> desc
>>
>> The first time I've noticed the tags in the example are highlighted!
>> Great! Could we have more of this, please! ;-)
>>
>> But I suppose that gets tricky where examples are re-used for more
>> than one element, e.g. dl, etc.
>
> As you say - it's not possible to do that when reusing elements. I  
> started
> adding that on several items in the DITA 1.1 spec (in particular, the
> complicated XNal examples).

OK

>> image
>>
>> It would be nice to see some rendered examples. Also a list of image
>> types which can be handled. I seem to recall that tiffs can't be
>> handled, or has the toolkit been altered?
>
> That's a space the specification isn't allowed to go in to -  
> anything that
> somebody considers an image is legal to point to. Some applications  
> may not
> support all formats, but that's solely related to the application.  
> (As a
> side-note -- the toolkit should not care what type of image you're  
> pointing
> to. It's been updated for this, though I'm not sure if it works with  
> every
> format. The plan was for it to let you reference any type, and then  
> for
> XHTML it's up to your browser to support it, and for PDF it's up to  
> your
> XSL-FO renderer.)

Ah, right.


>> The corollary is that specific rendering depends upon the toolkit,  
>> and
>> the structure doesn't, strictly speaking, depend upon the toolkit.
>> However, with so many users using the toolkit, and many vendors, too,
>> I think this is valid.
>
> The 1.0 version of the specification included some comments about  
> toolkit
> support. Those were all removed in 1.1, because while the toolkit is  
> a well
> known implementation of the standard, it is not the only one, and its
> behavior should not affect what is or is not possible in the  
> specification.
> Describing support also risks making the specification quickly out  
> of date
> - if we say in the spec that the OT does not support something, but  
> a patch
> is submitted the next week, then the spec will spend 2 or more years  
> being
> out of date.
>
> Aside from that, vendors who write their own implementations get  
> pretty
> upset when the toolkit is presented as the sole implementation. I can
> understand their annoyance.
>
> Does that make sense?

I think there's been some recent comments on the list about Processing  
Instructions. I'm not sure what PIs entail, but it sounds like a way  
out of the difficulty.

>> It would also be worthwhile to mention any image difficulties caused
>> by specific formats. I believe CHM is limited to gif, for instance.
>
> Similar to above - listing that risks making us out of date very  
> quickly.
> The sole purpose of the DITA specification is to describe what the  
> various
> DITA concepts and elements mean, and it is out of our scope to track
> related tools (even the toolkit).

OK

>> Would it be at all possible to include image conversions and
>> transformations using the toolkit, rather than simply copying images
>> to the output directory?
>
> Certainly. I know that the PDF2 plugin includes the Batik image  
> converter,
> although I do not know what types they will convert. If you or  
> anyone else
> wants to submit a patch that allows users to automatically convert  
> image
> types during a build, we'd be happy to add it.

;-))

>> 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?

>> lq
>>
>> What is the expectation, if any, from the processing?
>>
>> Does this add linguistically appropriate quotation marks?
>
> I added the following comment, most of which is taken from the HTML
> specification: "Although rendering is left up to implementations,  
> visual
> user agents generally render <lq> as an indented block."

OK

>> longquoteref
>>
>> What is the expectation, if any, from the processing?
>>
>> What is the purpose of this, when lq includes a href attribute?
>
> I expanded the description, although processing is left completely  
> up to
> implementations. I can see cases where it might be ignored, might  
> result in
> a link, or might turn the entire quote into a link; I added a note  
> to this
> effect.

OK

>> q
>>
>> What is the expectation, if any, from the processing?
>>
>> Is the purpose of this to add linguistically appropriate quotation
>> marks? 'George said, <q>Disengage ... </q>' becomes 'George said,
>> "Disengage ... "' for English?
>
> I would say yes, that is the purpose. I checked the HTML spec, which  
> says
> rendering agents MUST add quotes. As this is a pretty strong  
> statement -
> MUST means a tool does not comply unless it does that - I've sent a  
> note to
> the TC list to ask if we should make the same statement. I'm wary of  
> adding
> MUST statements without calling them out to the group, though in  
> this case
> it's probably appropriate.

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?

> I think that's everything. Thanks for the very detailed comments,  
> and I
> hope you were able to make it through the detailed responses.

Oh, yes! Great reading! Thank you for taking the trouble to go through  
it all!

For me, I now have a greater appreciation of what's behind the  
Language Spec., and why it's written as it is.

If at all possible, I would really like to see a version of the  
Language Spec. tailored to an authoring audience.

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.

Thanks, once again.

David



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