Add topic element to DocBook?

We've talked about adding some sort of topic element to
DocBook for
almost a decade, off and on. (Back at least as far as the
days when
Novell was an active participant in the Davenport Group.)

The DITA folks make a lot of marketing hay out of their
conceptual use
of topics. I don't think there's a single, solitary
technical
advantage to DITA, but marketing doesn't depend on technical
accuracy.
It's also possible to argue that task-based authoring is not
a good
idea in general. It's ideal in some circumstances, but
results in less
useful and less usable documentation in other circumstances.

However, DocBook has never been principally about imposing a
particular documentation style on authors. For the most
part, we leave
stylistic choices to authors.

With this in mind, I think we should consider, perhaps once
and for
all, whether we want to add a <topic> element to
DocBook.

If we decide to do so, I think something along the following
lines
fits into the design of DocBook:

1. Add a <topic> element with the same content model
as <section>
   except that where section allows
(sect1|section|simplesect), we
   allow <topic>. So a topic contains subtopics
analagous to the way a
   section contains subsections.

2. Give topic a class attribute so that authors can have
different
   kinds of topics. DITA has all this funky weirdness about
the
   content models of various kinds of topics; I don't think
we should
   go there.

3. Allow topic as an alternative to
(chapter|appendix|preface) in books.
   This allows one to have a book of topics.

4. Allow topic as an alternative to
(sect1|section|simplesect) in
   chapters and appendixes. This allows one to have a
chapter of
   topics.

As a slight extension of this model, we could also add a
<tasktopic>
element. This would address the feature request[1] for
"task" as a
peer to "section". If we did this, then I'd expect
"topic" or
"tasktopic" to be allowed anywhere I've mentioned
topic above.

Given that topics are often composed in a fairly arbitrary
order for
publishing in print, we might want to consider adding a
"contentmap"
element as well for describing the order of topics. But we
might be
able to get "toc" to serve this purpose.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndwnwalsh.com>      | No victor believes
in chance.--
http://www.oasis-o
pen.org/docbook/ | Nietzsche
Chair, DocBook Technical Committee |

Norman Walsh <ndwnwalsh.com>, 2006-10-26 08:59 -0400:

> As a slight extension of this model, we could also add
a <tasktopic>
> element. This would address the feature request[1] for
"task" as a
> peer to "section". If we did this, then I'd
expect "topic" or
> "tasktopic" to be allowed anywhere I've
mentioned topic above.

What content model would Tasktopic have?

And "tasktopic" ain't a pretty name. What about
naming it
"process" or "operation" instead? (Yeah
I know those stink too,
but they stink less than "tasktopic".)

  --Mike

-- 
Michael(tm) Smith
xmpp:smithsideshowbarker.net
irc://irc.freenode.net/mobile-web

/ "Michael(tm) Smith" <smithsideshowbarker.net> was heard to say:
| Norman Walsh <ndwnwalsh.com>, 2006-10-26 08:59 -0400:
|
|> As a slight extension of this model, we could also add
a <tasktopic>
|> element. This would address the feature request[1] for
"task" as a
|> peer to "section". If we did this, then I'd
expect "topic" or
|> "tasktopic" to be allowed anywhere I've
mentioned topic above.
|
| What content model would Tasktopic have?

Roughly the same content model as topic, I assume.

| And "tasktopic" ain't a pretty name. What about
naming it
| "process" or "operation" instead?
(Yeah I know those stink too,
| but they stink less than "tasktopic".)

Well, I kind of like having "topic" in the name if
its a kind of topic
because topics represent a pretty high-level design choice
in your
documentation.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndwnwalsh.com>      | 'All is vanity,'
saith the
http://www.oasis-o
pen.org/docbook/ | Preacher. But if all were only
Chair, DocBook Technical Committee | vanity, who would mind?
Alas, it
                                   | is too often worse than
vanity:
                                   | agony, darkness, death
                                   | also.--Thomas Hardy

Norman Walsh <ndwnwalsh.com>, 2006-10-26 10:33 -0400:

> / "Michael(tm) Smith" <smithsideshowbarker.net> was heard to say:
> |
> | What content model would Tasktopic have?
> 
> Roughly the same content model as topic, I assume.

What relationship would it have to the existing Task
element?

> | And "tasktopic" ain't a pretty name. What
about naming it
> | "process" or "operation" instead?
(Yeah I know those stink too,
> | but they stink less than "tasktopic".)
> 
> Well, I kind of like having "topic" in the
name if its a kind of topic
> because topics represent a pretty high-level design
choice in your
> documentation.

OK. Then how about "module" and
"taskmodule" instead? (Since the
purpose of the proposed changes would be to provide elements
that
are better suited to creating modular content).

  --Mike

Michael(tm) Smith wrote:
> What content model would Tasktopic have?
> 
> And "tasktopic" ain't a pretty name. What
about naming it
> "process" or "operation" instead?
(Yeah I know those stink too,
> but they stink less than "tasktopic".)



I strongly believe that task should be in the name of the
element.  It's
important for people to associate the tasktopic with task.

I would also be in favor of simply adding task as a peer to
topic, but I
suspect others would not agree.

-Steve Cogorno
Sun Microsystems

------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org

/ Steve Cogorno <Steven.CogornoSun.COM> was heard to
say:
| Michael(tm) Smith wrote:
|> What content model would Tasktopic have?
|> 
|> And "tasktopic" ain't a pretty name. What
about naming it
|> "process" or "operation" instead?
(Yeah I know those stink too,
|> but they stink less than "tasktopic".)
|
| I strongly believe that task should be in the name of the
element.  It's
| important for people to associate the tasktopic with task.
|
| I would also be in favor of simply adding task as a peer
to topic, but I
| suspect others would not agree.

I suppose if we agreed to remove task as a block element, we
could
simpy use the name "task" for the peer of topic.
It would seem truely
odd however to allow:

  <topic>
    <para>...</para>
    <task>...</task>
    <para>...</para>
  <topic>
  <task>
    ...
  </task>
  <topic>
    ...
  </topic>

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndwnwalsh.com>      | Endurance is
frequently a form of
http://www.oasis-o
pen.org/docbook/ | indecision.--Elizabeth Bibesco
Chair, DocBook Technical Committee |

Norman Walsh <ndwnwalsh.com>, 2006-10-26 12:32 -0400:

> I suppose if we agreed to remove task as a block
element, we could
> simpy use the name "task" for the peer of
topic.

Sounds like a lot better solution than adding a tasktopic
element.

  --Mike

I tried to inscribe here  http://www.oasis-
open.org/mlmanage/ but it
doesn't work.

Thanks for your pointer.


tj

------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org

I think I missed something. What does <topic> better
allow the author
to express semantically than <section> or
<chapter>?

On 10/26/06, Norman Walsh <ndwnwalsh.com> wrote:
> We've talked about adding some sort of topic element to
DocBook for
> almost a decade, off and on. (Back at least as far as
the days when
> Novell was an active participant in the Davenport
Group.)
>
> The DITA folks make a lot of marketing hay out of their
conceptual use
> of topics. I don't think there's a single, solitary
technical
> advantage to DITA, but marketing doesn't depend on
technical accuracy.
> It's also possible to argue that task-based authoring
is not a good
> idea in general. It's ideal in some circumstances, but
results in less
> useful and less usable documentation in other
circumstances.
>
> However, DocBook has never been principally about
imposing a
> particular documentation style on authors. For the most
part, we leave
> stylistic choices to authors.
>
> With this in mind, I think we should consider, perhaps
once and for
> all, whether we want to add a <topic> element to
DocBook.
>
> If we decide to do so, I think something along the
following lines
> fits into the design of DocBook:
>
> 1. Add a <topic> element with the same content
model as <section>
>    except that where section allows
(sect1|section|simplesect), we
>    allow <topic>. So a topic contains subtopics
analagous to the way a
>    section contains subsections.
>
> 2. Give topic a class attribute so that authors can
have different
>    kinds of topics. DITA has all this funky weirdness
about the
>    content models of various kinds of topics; I don't
think we should
>    go there.
>
> 3. Allow topic as an alternative to
(chapter|appendix|preface) in books.
>    This allows one to have a book of topics.
>
> 4. Allow topic as an alternative to
(sect1|section|simplesect) in
>    chapters and appendixes. This allows one to have a
chapter of
>    topics.
>
> As a slight extension of this model, we could also add
a <tasktopic>
> element. This would address the feature request[1] for
"task" as a
> peer to "section". If we did this, then I'd
expect "topic" or
> "tasktopic" to be allowed anywhere I've
mentioned topic above.
>
> Given that topics are often composed in a fairly
arbitrary order for
> publishing in print, we might want to consider adding a
"contentmap"
> element as well for describing the order of topics. But
we might be
> able to get "toc" to serve this purpose.
>
>                                         Be seeing you,
>                                           norm
>
> --
> Norman Walsh <ndwnwalsh.com>      | No
victor believes in chance.--
> http://www.oasis-o
pen.org/docbook/ | Nietzsche
> Chair, DocBook Technical Committee |
>
>
>


-- 
http://chris.chiasson.nam
e/

------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org