John,
I still stand by my statement. Even many of the common DTD/schemas I've worked with tend not to be well thought out according to the document requirements. Using one of my pet peeves in S1000D (and really any DTD/schema for that matter). The element <step1>
ELEMENT step1 - - (((applic?, title?), (warning*, caution*), (((note | para) | (figure | foldout | table))*)), ((step2 | step2-alt)*))>
First, there is no required content here. One would thing that if either the <title> or the <para> would be required.Yes, I may want the <title> rather than the <para>, but the model can be written so one or the other is required (personnally, until I started working with S1000D, I'd never seen a title on a step, I've seen titles preceed a group of steps in a procedure [i.e., "Remove access panel"]). The large group starting with the (note | para) is the "fix" (??) to solve the problem of no inclusions in XML (yes, this is an SGML DTD, but it is derived from the XML Schema and they must match as closely as possible).
Second, I can have a step with no text, justone or morefoldouts or figures or tables(okay, there is text in the table, but what purpose is the table serving?).
Lastly, and we've had some discussions on this in the S1000D groups, is there can be more than one paragraph in the step. I don't know, but to me a step is a single concise bit of information, not "Gone With the Wind". The comment here is well we can write a business rule to say only one para is allowed then write a Schematron (or some other evaluation routine) to ensure we follow the business rule. There are people who say they use the extra paragraphs for 'metadata' (poor tagging for that IMHO). I have seen cases where authors (or company policy) is to use the multiple paragraphs for individual steps (i.e., there are four <step1> level steps, so the <step1> has four paragraphs and the style sheet numbers each paragraph. This may work well until some one else uses four <step1> elements with ONE paragraph and they expect the step number to increment properly based on the step1 and not the paragraph in the step. Where it REALLY gets to be fun is if one <step1> has any child steps (i.e., <step2>'s) then revert back to <step1>. If they are using the multiple paragraphs in <step1>, then the <step1> following the <step2> will be numbered how?
Lastly (and I just found this one and will be submitting a CPF on it), I can have warnings and cautions prior to figures, foldouts and tables, but the way the model is set up, I cannot have a note.
These all allow inconsistent authoring of data and could have been alleviated with a bit more planning. My recommended model would have looked more like this
And I am not to fond of the way the <note> is entered. My personal choice here is to include the <figure>, <foldout>, and <table> elements inside the <para>.
One can still alias element names to make them more understanable. But with the long 'name' length quantity in the XML declaration, why we see short cryptic names is beyond me. I can understand why in the early SGML days, before they (I wasn't involved at that time [yet and wouldn't have known anyway]) learned the SGML declaration quantity values could be changed the element names were ALWAYS 8 or less charaters and thus very cryptic (though I still cannot for the life of me figure out where <entry> for a table cell came from).
Okay, I'm off my soapbox.
Lynn
-----"Hanratty, John (LNG-LON)" <john.hanratty@lexisnexis.co.uk> wrote: -----
To: <adepters@arbortext.com>
From: "Hanratty, John (LNG-LON)" <john.hanratty@lexisnexis.co.uk>
Date: 05/22/2007 05:00AM
Subject: RE: Tips & Tricks -- hiding tags & attributes
"Hiding tags and attributes is (like SGML exceptions)
a sign of poor design." 🙂
And poor design is sometimes unavoidable, for example (and I pick this
example randomly from the air) say you inherit a typesetting DTD, and
are obliged because of corporate policy to use it upstream as a
single-source dtd. All those elements and attributes to do with
horizontal and vertical alignment, leader characters, whitespace: you
want them all to go away.
Even more useful is the ability to alias elements and attributes, which
we use extensively. Many of the element names in our DTDs have
"pseudo-namespace" prefixes like "core:" "case:" "jrnl:" etc which we
use to add a semantic context to the element. Some element names are
therefore pretty unwieldy, and would look both ugly & scary to authors,
so we present to them markup with a much more friendly face. It also
enables us to use the same DTD across multiple user groups, just with a
different DCF and FOSI. To me, this sort of functionality is real
value-add: it's why I would choose Epic over another XML editor. I have
a small team, only 2 people, and with an ever-expanding list of internal
user groups and applications to support, any tool that helps us limit
the number of DTDs and/or schemas we have to maintain is very welcome.
I'm not familiar with this: " * Sort attributes according to DTD instead
of alphabetically."
Could someone explain to me in what context this occurs?
John Hanratty
Senior XML Analyst
LexisNexis UK
