freelanceprogrammers.org Forum Index » XML / XSL
Re: DocBook redux
Joined: 13 Jun 2003
Posts: 39
Re: DocBook redux
Don Day was kind enough to respond:
>> But the conversation led me back to something I`ve been thinking
>> about off & on: how much complexity do you *need* to express
>> a document`s structure?
> I`m tempted to repeat that too-obvious come-back, How long is a piece
> of string? But even it is too weak for the difficulties implicit in
> your conjecture.
LOL, I knew that was a bit open-ended when I wrote it. But
Tim Harvey (in another thread) made explicit what I implied,
that there`s a point beyond which further complexity only
becomes burdensome:
few think about things like periods as sentence
delimiters much less propose their replacement with
sentence tagging or even a more radical elimination
of "presenation" artifacts, like initial capitals
and periods to mark sentences, space to delimit words
and so on, used and understood in normal writing.
eg The dog barked.
<sentence>
<word>
<character encoding="ASCII">116</character>
<character encoding="ASCII">104</character>
<character encoding="ASCII">101</character>
</word>
<word>
:
etc.
Somewhere between that, and the too-generic:
<document>
undifferentiated blob of text
</document>
is an area (not a point, certainly) where the added
burden of tag differentiation and complexity begins to
outweigh the benefits in many cases. Jeff Beal talked about
a time when complex tagging was a big help, then pointed
out:
we then have to ask ourselves, was the extra time
spent in tagging our menu paths as <guimenu/> instead
of some more generic markup justified by the time
savings in this one instance?
One argument for added complexity is that it gives you
more handles to grab onto later, often for uses you didn`t
conceive of at the outset. Arguments against include longer
training and perhaps time wasted in, as Jeff said, "[having]
to look up the best element to use in each case."
Can we perhaps have it all, leveraging implied structure
to reduce DTD/schema complexity while still leaving us a
toehold to grab onto when needed? Ryan Germann points out
that Exegenix`s software can derive structure (and create
XML) from presentation markup, but I wasn`t thinking about
going *that* far. :-) My thought was that the same tag
might have different meanings in different contexts -- for
example, a <keyword> element might represent a menu choice
or dialog box widget in one context and an argument to a
CLI command in another (this is synonymous to "overloading"
in object-oriented programming). In a manual that describes
a GUI tool with no companion CLI utility, the context is
obvious; in other cases, an attribute or metadata could
specify the context:
<procedure interface="console">
...
Use <keyword>no</keyword> to disable this function.
Without such hints, it may still be possible to derive
the context by looking for certain strings in a parent
element:
<step>Choose <keyword>Save</keyword> from
the File menu.</step>
<step>Click <keyword>Save</keyword>.</step>
<step>Type <keyword>Save</keyword> at the
prompt.</step>
The explicit structure is identical for each -- a keyword
inside a step -- but I`ll bet you recognized a menu choice,
a dialog box item, and a CLI command when you saw them. An
XSLT could also recognize them, using the text() node and
XPath functions. This kind of implied structure depends on
the writers applying terms consistently, but that should
be one of the functions of a documentation department.
This kind of element overloading has several benefits --
smaller, more maintainable DTD/schema, faster response
time in the authoring tool (since it has fewer elements
to look at while building a list of valid choices), and
ease of choice by authors (who don`t have to try to figure
out which of N tags are best applicable). Drawbacks include
more complex XSLT and an even greater need for consistency.
In the same way that GUI applications require more effort
from a few developers in return for less effort from many
users, the principle of "least effort for most people"
applies here too.
--
Larry Kollar, Senior Technical Writer, ARRIS
"Content creators are the engine that drives
value in the information life cycle."
-- Barry Schaeffer, on XML-Doc
[Non-text portions of this message have been removed]
Joined: 13 Jun 2003
Posts: 5
Re: DocBook redux
> <procedure interface="console">
> ...
> Use <keyword>no</keyword> to disable this function.
(Being a bit pedantic...) Is `no` a button on the keyboard or what the user
is to type? I could assume the latter, but what if it were
<keyword>Insert</keyword>? Insert is a key on the keyboard, but it could
also be a reasonable command for some applications.
> <step>Choose <keyword>Save</keyword> from
> the File menu.</step>
>
> <step>Click <keyword>Save</keyword>.</step>
>
> <step>Type <keyword>Save</keyword> at the
> prompt.</step>
>
> The explicit structure is identical for each -- a keyword
> inside a step -- but I`ll bet you recognized a menu choice,
> a dialog box item, and a CLI command when you saw them. An
> XSLT could also recognize them, using the text() node and
> XPath functions. This kind of implied structure depends on
> the writers applying terms consistently, but that should
> be one of the functions of a documentation department.
What about "<step>Select <keyword>Tomato Soup</keyword> from the
menu</step>"? Am I at a restaurant or in a user interface? What does the
keyword in "<step lang="pt_BR">Clique <keyword>Fechar</keyword> para
terminar</step>" signify? If we could easily and consistently infer the
significance of one word based on the surrounding words, we wouldn`t need
XML at all!
The point I was trying to make with
> we then have to ask ourselves, was the extra time
> spent in tagging our menu paths as <guimenu/> instead
> of some more generic markup justified by the time
> savings in this one instance?
was that each organization has to determine the level of specificity they
will be using in their documentation based on their current and future
needs. In an ideal world, each organization would use their own DTD,
completely customized for what they do and what they write. In most cases,
that wouldn`t be practical, and it loses so much in terms of document
interchange.
The question DocBook (or any other DTD) has to answer is, do we want to be a
union of each of our user`s "perfect DTD", or do we want to be the
intersection. In other words, do we expect users to start with this DTD and
add their own elements, or start with this DTD and remove or ignore those
they don`t need or want? Personally, I think that the current "success" of
DocBook came about because they chose the former approach. If I had to
choose between starting over with a core set of 30 or 40 elements and
building up to my "ideal tag set", adding each element to the DTD and the
stylesheets as I needed them, or starting over with even 1500 tags and
choosing tags from that set as I need them, I`d take the latter.
Jeff Beal
Joined: 13 Jun 2003
Posts: 5
Re: DocBook redux
> The question DocBook (or any other DTD) has to answer is, do
> we want to be a
> union of each of our user`s "perfect DTD", or do we want to be the
> intersection. In other words, do we expect users to start
> with this DTD and
> add their own elements, or start with this DTD and remove or
> ignore those
> they don`t need or want? Personally, I think that the
> current "success" of
> DocBook came about because they chose the former approach.
> If I had to
> choose between starting over with a core set of 30 or 40 elements and
> building up to my "ideal tag set", adding each element to the
> DTD and the
> stylesheets as I needed them, or starting over with even 1500 tags and
> choosing tags from that set as I need them, I`d take the latter.
Just to clarify, my use of the phrase "former approach" above meant union as
opposed to intersection. Hmmmph.
Joined: 14 Jun 2003
Posts: 10
Re: DocBook redux
Jeff Beal wrote:
>
> The question DocBook (or any other DTD) has to answer is, do we want to be a
> union of each of our user`s "perfect DTD", or do we want to be the
> intersection. In other words, do we expect users to start with this DTD and
> add their own elements, or start with this DTD and remove or ignore those
> they don`t need or want?
>
When you were describing the different kinds of needs that organizations
have, I thought you were on the right track.
But here, I think you`ve created an inappropriate set of choices.
Certainly, the current scenario is that DocBook users get the union of
features and remove the ones they don`t need.
The alternative is not to start with something simple and add everything
avove that yourself, however.
The alternative is to start with a simple core and add one or more
standard layers. In the ideal world, the lewel of functionality you
select closely approximates the functionality you need, and you only
have to remove or add a very small number of elements for a perfect
fit.
Joined: 14 Jun 2003
Posts: 6
Re: DocBook redux
At 12:50 13/06/2003 -0700, Eric Armstrong wrote:
>Certainly, the current scenario is that DocBook users get the union of
>features and remove the ones they don`t need.
>
>The alternative is not to start with something simple and add everything
>avove that yourself, however.
Or my approach. Its all there (in docbook)
just ignore the stuff I don`t use... mostly.
Add to what I do use as I need it,
knowing it will be processed well by the stylesheets?
I guess I go to docbook, the definitive guide,
roughly every month or two for new markup.
>The alternative is to start with a simple core and add one or more
>standard layers.
Then you need to add to the styling for output each time.
Nominal downside.
regards DaveP
Joined: 16 Jun 2003
Posts: 3
Re: DocBook redux
Eric Armstrong:
>>The alternative is to start with a simple core and add one or more
>>standard layers.
Dave Pawson:
>Then you need to add to the styling for output each time.
>Nominal downside.
Michael Priestley:
Unless you use class-based inheritance to provide default styling for new
elements, as we do in DITA.
Considerable upside :-)
Michael Priestley
mpriestl@...
Dept 833 IBM Canada t/l: 969-3233 phone: 905-413-3233
Toronto Information Development
Dave Pawson
<dpawson@nildram. To: xml-doc@yahoogroups.com
co.uk> cc:
Subject: Re: [xml-doc] Re:
DocBook redux
06/14/2003 06:33
AM
Please respond to
xml-doc
At 12:50 13/06/2003 -0700, Eric Armstrong wrote:
>Certainly, the current scenario is that DocBook users get the union of
>features and remove the ones they don`t need.
>
>The alternative is not to start with something simple and add everything
>avove that yourself, however.
Or my approach. Its all there (in docbook)
just ignore the stuff I don`t use... mostly.
Add to what I do use as I need it,
knowing it will be processed well by the stylesheets?
I guess I go to docbook, the definitive guide,
roughly every month or two for new markup.
>The alternative is to start with a simple core and add one or more
>standard layers.
Then you need to add to the styling for output each time.
Nominal downside.
regards DaveP
-------------------------------------------------------------------
Post a message: mailto:xml-doc@yahoogroups.com
Unsubscribe: mailto:xml-doc-unsubscribe@yahoogroups.com
Switch to digest: mailto:xml-doc-digest@yahoogroups.com
Put mail on hold: mailto:xml-doc-nomail@yahoogroups.com
Contact adminstrator: mailto:xml-doc-owner@yahoogroups.com
Make changes via Web: http://groups.yahoo.com/subscribe/xml-doc/
Read archived messages: http://groups.yahoo.com/messages/xml-doc/
-------------------------------------------------------------------
Your use of Yahoo! Groups is subject to http://docs.yahoo.com/info/terms/
Joined: 14 Jun 2003
Posts: 6
Re: DocBook redux
At 18:01 15/06/2003 -0400, Michael Priestley wrote:
>Eric Armstrong:
> >>The alternative is to start with a simple core and add one or more
> >>standard layers.
>
>Dave Pawson:
> >Then you need to add to the styling for output each time.
> >Nominal downside.
>
>Michael Priestley:
>Unless you use class-based inheritance to provide default styling for new
>elements, as we do in DITA.
>Considerable upside :-)
<unnecessary class="comment"> OK smart ..... </unnecessary>
Grrr.
Thank you Michael :-)
regards DaveP
All times are GMT
Page 1 of 1
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
Freelace Website Designer - Customer web design and software building.
China Wholesale - Electronics Products
Character Studio - Tutorials and Help
China Wholesale - Electronics Products
Character Studio - Tutorials and Help