This is the mail archive of the docbook@lists.oasis-open.org mailing list for the DocBook project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: doc domain vs. problem domain semantics (Re[2]: listitem)


/ "Matt G." <matt_g_@hotmail.com> was heard to say:
| As a matter of fact, I'd guess that more often than not, variablelist
| is used to list things other than variables.

Ah, the "variable" in variablelist isn't really for programming
language variables. It's really a description list. In fact, if HTML
had come first, we probably would have called it a descriptionlist. As
it is, I don't really recall the etymology.

| This gets the subject of
| my message, and the tangent the thread is getting off to, which is
| that since there aren't semantics rich enough to describe the types of
| formatting structures people use in documents, the more
| domain-specific ones are fallen back upon, as a crutch.  This has the
| effect of ruining the semantics of the domain-specific markup,
| particularly if it's uses are mixed, within a single document.

I'm not sure I understand what you're trying to say. 

But I will point out that there's a constant tension between general
markup and specific markup. DocBook tries to achieve a good balance
for computer software and hardware documentation. But that doesn't
mean there aren't specific applications where some more specific
markup would be desireable.

The entire design of DocBook is geared to make it possible for you to
write customization layers that provide the exact markup that you
need.

>>| More importantly (in the
>>| short-term) it doesn't even appear to be nested, at all, in the
>>| DSSSL print style-sheets (version 1.74b - the latest).

I've lost the beginning of this thread, what doesn't appear nested?

>>Using what backend?
>
| OpenJade 1.3.  Is there any other DSSSL implementation as complete and
| mature?

Nope.

| I don't really care whether the same constructs are available for use
| within a <listitem> as elsewhere; my point is that I think there might
| be valid reasons to subdivide <listitem>s further, into titled chunks.
| Do you agree?

I guess that depends on what you mean. Have you considered formalparas?

>>| Secondly, I'm surprised there's no sort of an element with a
>>| title on the same line (see my <namedproperty> block element
>>| example, in my previous message).
>>
>>"Title on the same line" is a presentational, not a semantic or
>>structural issue.
>
| True -- what I'm really concerned about is the structure of the
| construct, which it can be difficult to get into the habit of
| conceptually separating from the presentation.  However, I think that
| unless you have semantics for 99% of the problem domain, you need
| semantics specific to the document domain, on which to fall back.  If
| those aren't available, then people will resort to abusing what
| problem domain constructs you give them that have the presentational
| or structural properties similar to what's missing.

Yes. "Tag abuse".

| So, is there really no desire to augment it to be better suited for
| more general documentation tasks and more easily adaptable to other
| sorts of problem domains than HW/SW?

There are thousands of things that we could add that would ideally
suit the needs of one community or another. DocBook could be extended
to provide structures suitable for medical publishing, for legal
publishing, for automotive manufacturing publishing, etc. ad
infinitum.

But I'm not sure that's the best approach. People often complain that
DocBook is too big. Making it 10 times bigger is probably not a good
idea.

If DocBook is not ideally suited to your problem domain, it might make
a lot of sense for you to write a customization layer that is ideally
suited and augment the stylesheets to support those new elements.

| IMO, the DocBook DTD (which, admittedly, I haven't really spent much
| time dissecting) should be partitioned into document construct and
| HW/SW constructs (in addition to the various other classes of
| attribute and entity definitions).  Stylesheets, too.  This would make
| it easier for say a biotech publication or physics department of a
| major university to use the core documentation semantics as a
| foundation for their own field-specific documentation vocabulary,
| without carrying extra baggage or suffering with unnecessary name
| collisions with semantics foreign to their domain.

With respect, DocBook is designed *specifically* to make this possible.
Perhaps you ought to spend some time looking at it.

| Do you see that what I'm interested in is two things:
| 1) Preserving the semantics of HW/SW-specific constructs, by
|    providing suitable fall-backs
| 2) Allowing DocBook to be more easily adapted to other domains,
|    either through augmentation or as a richly structured
|    intermediate format.

I suppose. I think it would be helpful if you made some concrete
proposals. What you are suggesting is, in principal, entirely
rational. I'll say again that I believe DocBook is already designed to
make this possible.

| So, you don't have a tool to generate your dependencies automatically,
| do you?  I'll soon whip one up, in Python.  I probably won't bother to

Generating dependencies for things like entities is easy. But the
processing semantics of included fragments isn't self-evident so I'm
not sure there's a way to make a tool for it.

| FYI, I use this approach for both an Interface Definition Language,
| from which I generate portions of my API document (and both sides of
| the interface), as well as the embedded design documentation I
| mentioned, previously.  I'm using XSLT all around, and wish XalanC
| would support XSLT 1.1.  I also dearly wish it had a command-line flag
| for specifying an SYSTEM id search path (for external entities and DTD
| subsets), similar to the '-I' option supported by most C/C++
| compilers!!

Check out the XML Catalogs specification and try using public identifiers.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Do not seek to follow in the
http://www.oasis-open.org/docbook/ | footsteps of men of old; seek what
Chair, DocBook Technical Committee | they sought.--Matsuo Basho


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]