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


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

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

Subject: Re: DOCBOOK: MS files included with elements?

On Thursday 10 May 2001 20:21, Galen Boyer wrote:
> On Thu, 10 May 2001, david@usermode.org wrote:
> > You're looking at the problem from the wrong angle.
> I guess it might look that way, but I don't think I am.  I know
> what the author's say in the book as well, and I see the point of
> giving up control of formatting and style and why this is such a
> pain point.  But that seems to apply when one is starting the
> document in docbook.  It doesn't seem to apply when one is
> converting existing wysiwyg documentation.

Once you learn what tags are available and how they are applied, it's much 
easier to recognize the meaning behind the styles. Instead of seeing an 18pt 
Arial Bold font, you'll look at the context around it and see a sect2 title.

The trouble with going by the styles is that they're different from document 
to document. The only reason a certain paragraph is indented in Word or 
Framemaker may be simply because the author set up the style that way. If 
you're lucky enough that the word processor's style names were sensibly 
chosen and *consistantly* used, then you can use them as excellent guides. 
Otherwise most of the stylistic settings in WYSIWYG are useless as guides. 
Some pointers coming up...

> Maybe I'm wrong and still having my own issues with giving up the
> control, but I think there is meaning in them thar fonts.

If you chose the fonts then there's meaning for you in them. But all too 
often I find that fonts were chosen to look nice rather than convey meaning. 
Like my Mom, who sets her fonts very large so she can see them on her small 
monitor, but when I get them I wonder why she's emphasising everything...

> Most of the time, in a wysiwyg editor, it is pretty clear why
> someone has used a certain emphasis.  Looking at a wysiwyg page,
> one should be able to make the translation to docbook because
> there is meaning to the original authors wysiwyg organization and
> style.  I just am lost sometimes, because I know the meaning the
> author of the word doc is trying to get across but can't come up
> with the corresponding tag which would support that meaning.

The trick is to learn what tags are available and what they mean. You don't 
have to memorize their exact syntax (that's what the O'Reilly book is for), 
only know that they're available. If you see book title that's been 
italicized, your memory tells you that there's a tag available for marking up 
publication names. Looking up in your reference you find that it's 

> I will get it in time, but I was hoping there was some reference
> point for making those translations easier.  It is probably very
> similar to trying to translate between languages when their isn't
> a direct one-to-one translation.

Well, if there was a standard for word processing styles, then it would be a 
piece of cake. But unfortunately there isn't. Some people do itemized lists 
with bullets. Others with hanging paragraphs. Others by making the first word 
in the paragraphs bold.

> How would you, without the common body of knowledge, know that
> the list should have had the indentation
> States
>    Virginia
>    Maryland
>    Massachusetts
> Cities
>    Boston
>    New York
> Countries
>    US
>    Russia

I said convert it to ascii when "all else fails" :-) If there's an obvious 
structure to the document, then converting it can ruin it. Particularly if 
the word processor does an inept job of converting to ascii.

But looking at the above and imagining how it would look in a WYSIWYG 
environment, I could surmise that it's a <variablelist>. How do I know that? 
Because I know what kinds of tags are available and what they are generally 
used for. If you don't know what tags there are, you won't know what it 
corresponds to. It takes time to learn them so be patient.

And the above might not be a variable list! It's a pretty good guess, but 
without knowing the context, I don't know for sure. It might be part of a 
table of contents, or an outline, or the sample output of a computer program.

There aren't any hard and fast rules for converting stylistic markup to 
content markup. The other direction is much easier, which is why content 
markup is so great.

> I'll keep that in mind, but I am going to stick with the canned
> stylesheets for a little while.  I need to learn docbook and then
> sell it to a boatload of Word users.

If you absolutely have to have something formatted in a specific way, then 
fiddling with the stylesheet is the only proper way to do it.  For the most 
part, the canned stylesheets will give you what you want.

Oh, and I can't even get my fellow Word-hating developers at work to use 
DocBook for their reqs and specs (which are prime DocBook candidates) so good 
luck trying to convert Word users. Maybe you can sell them on Framemaker+SGML 
or Adept instead.

David Johnson

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

Powered by eList eXpress LLC