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

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

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


Subject: RE: DOCBOOK-APPS: Help project structure


I don't know whether this will go through to docbook-apps, since I'm not
subscribed to the list.

DITA's base design (the design of the three main topic types - concept,
task, and reference) is lifted straight out of our existing IBM user
assistance architecture. So people have been authoring chunked,
information-typed articles within IBM for quite some time, although not
using DITA - using HTML for the most part. And they've been repurposing
that information for print, using a variety of internal processes.

So while DITA hasn't been used for singlesourcing yet, it's implementing an
existing information design that has been used extensively for
singlesourcing.

To answer your particular questions:

>1. accomodate the 'glue text' that books need to connect physically
>sequential topics

You can factor this out into a map document, that effectively holds both
the TOC for the output book and the glue text - see the example in the
current DITA package, although I don't think the provided transform
actually does anything with the glue text right now :-)

We're currently proceeding on the assumption that the glue text is actually
low-priority - ie, that books operate better as topic-oriented collections
of articles with the glue text deferred to explicit intro and summary
topics, rather than within each topic. I'm not personally convinced of
this, it's just FYI - you can implement a mapping document either way.
We're not currently providing a lot of map-based support in the external
package, we're working things through internally first. I can't give you
dates on if/when that support will be provided, unfortunately. Our main
priority was getting the topic-oriented authoring stuff out the door - our
mapping approach depends on having topic-oriented chunks to play with, so
we needed to get the topic stuff done first.

>2. accomodate the necessity for some topics being literally (and
>physically) subcomponents of other topics, rather than simply being
pointed
>to by the parent topic.

The ditabase.dtd allows you to nest topics any way you want. In fact, you
should be able to create fairly complete booklike structures just using
that DTD (which is an aggregation of the separate topic, concept, task, and
reftopic DTD modules). I personally think it's easier to write reusable
topics when they aren't nested, though - it helps keep in mind that the
nesting may not exist on output (depending on how you chunk your output, or
what topics get reused in a particular collection/delivery context/output).

The concept, task, and reftopic individual DTDs don't currently allow
nesting, I believe, though that's something we're revisiting (to allow
child reference topics in a reference topic, particularly). It's something
you can set in the DTD fairly easily (there's an entity named "info-types"
that determines what's allowed as nested content in each DTD). The
transforms/stylesheets work fine with nested content, it's only prevented
by the DTD settings in the individual topic type DTDs.

So for now, you can either use ditabase (that already allows nesting) or
change the info-types switch in the other DTDs (to enable nesting).

Michael Priestley
DITA Specialization Architect
mpriestl@ca.ibm.com
Dept 833 IBM Canada    t/l: 969-3233    phone: 905-413-3233
Toronto Information Development


"Nancy (Paisner) Harrison" <nancyh@rational.com> on 03/18/2002 02:55:30 PM

Please respond to "Nancy (Paisner) Harrison" <nancyh@rational.com>

To:   "Bradford, Denis" <denisb@rational.com>, Michael
      Priestley/Toronto/IBM@IBMCA, docbook-apps@lists.oasis-open.org
cc:
Subject:  RE: DOCBOOK-APPS: Help project structure


Michael,

The last time I asked (Don Day, I think it was) for a pointer to someone at

IBM who was using DITA as a model for print books, I was told that no one
there was doing it yet. That was a while ago, and DITA was fairly new then.

Now that it's been around a bit, could you point me to someone using it for

both types of output?  As Denis says, we at Rational need to single-source
for online and print, and the printed versions of the material tend to be
fairly hierarchical technical manuals.

In particular, I'd be very interested in seeing how DITA can be used to

1. accomodate the 'glue text' that books need to connect physically
sequential topics
2. accomodate the necessity for some topics being literally (and
physically) subcomponents of other topics, rather than simply being pointed

to by the parent topic.


Thanks,


Nancy

At 01:53 PM 3/18/2002 -0500, Bradford, Denis wrote:
>I appreciate the correction, apologize for not reading more carefully.
Your
>point is particularly well-taken that topic-oriented information works
just
>as well for books.
>
>Denis
>
> > -----Original Message-----
> > From: mpriestl@ca.ibm.com [mailto:mpriestl@ca.ibm.com]
> > Sent: Monday, March 18, 2002 11:52 AM
> > To: denisb@Rational.Com
> > Subject: re your post on docbook-apps
> >
> >> In fact, even if some
> >> specialized
> >> online DTD becomes widely accepted, lots of folks (like us)
> >> need to publish
> >> both print and online docs, and may not be able to use it.
> >> Those people
> >> will
> >> still need the flexibility and extensibility of DocBook.
> >> _____
> >> Denis
> >>
> >
> > This isn't true. DITA is designed specifically for
> > singlesourcing, not for
> > online information.  Topic-oriented information often gets
> > talked of as
> > "the online model", but it works just as well for books.
> >
> > I'm not subscribed to the docbook-apps list, but if you want
> > to continue
> > this on xml-docs, I will respond to it there. (Feel free to
> > forward this
> > reply to docbook-apps as well).
> >
> > Michael Priestley
> > DITA Specialization Architect
> > mpriestl@ca.ibm.com
> > Dept 833 IBM Canada    t/l: 969-3233    phone: 905-413-3233
> > Toronto Information Development
> >


________________________
Nancy (Paisner) Harrison
Rational Software
Lexington  MA
nancyh@rational.com






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


Powered by eList eXpress LLC