Re: sgml (long)

[Michael Priestley <mpriestley -at- VNET -dot- IBM -dot- COM>]

>Michael, you turncoat scum!  Actually, we agree about quite a bit of this
>(as we always have).  However, on the issue of separating content from
>format, see my posting on that subject.

Unfortunately my news server no longer has the article.  Am I right in
remembering, though, that it was primarily talking about HTML?

To clarify: I am in favour of separating content and format for the
purposes of writing and maintaining the information; I am _not_
suggesting that the writer should abdicate responsibility for the format in
favour of a browser.  I'll explain more fully further down.

>>  - Keep the source free of formatting considerations:
>>    ...by keeping the source content-oriented, we can concentrate on
>>    technical accuracy...

>But technical accuracy is not all (or nearly all there is to documentation).
 If
>it were, we'd let the programming geeks (I speak here on behalf of such
>geeks) do the doc.

Poorly phrased on my part.  Let me try again.  Formatting considerations
can be categorized according to their scope: global or local.

Example (local): I have a large block of text.  Should I break it into
two paragraphs or three?  Is there a way to rewrite part of it into
a list or subtopics?

Example (global): Each of my descriptions has a section called
"portability considerations" at the end of it.  How should I flag this
info (heading, icon, change in text colour)?  What format should the
information be in (itemized list, table showing diff platforms)?

Now, the local considerations still have to be addressed as you write;
however, most of the global considerations can be taken out of the text,
so that I am no longer worrying about font size or table setups or
artwork names; instead, I write:

<portability>
<unix>blah blah blah
<os2>blah dee blah
<windows> blah de blech
</portability>

And, when I generate my INF or Postscript files, the information is
formatted appropriately for the target medium, according to the format
spelled out by the output filter.

>I acknowledge the possibility for paper doc
>and online doc that is isomorphic to the paper doc.  I am *very* skeptical
>about extending this to online help since I believe that the *structure* of
>that is necessarily quite different from the others.

This is absolutely true for any half-way decent contextual help system.
Note that there may be parts of the help system that are non-contextual
(eg reference or task-oriented info, linked to from the contextual help
but not in itself contextual), and these parts may still be amenable
to a singlesourcing solution.

>There is only so much "customization" that can be done since the *structure*
>must be preserved.

I think we may have been talking at cross-purposes here.  The structure
being preserved in the portability example above is very amenable to
customisation.

>>  This buys us maintainability (the source is easy to read) and flexibility

>At the cost of better and more useable documentation?  That is my fear.

If we had ten people to work on these books, and only one release to
worry about, we might have taken a different approach.  Given our
situation (many releases with few writers), this solution bought us
the most usability and quality possible.  Any other solution, I am
convinced, would have resulted in either poorer quality (so no benefit)
or slipped schedules (so no job) (1/2 a :-)

>Books, yes.  But books are books -- whether on paper or on the screen.
>Help, wizards, tutorials are *different*.  And suppose that your output format
>needs to be *sound*.  Do we assume that *that* maps straightforwardly
>via the same structure?

No, we don't.  My experience here was with reference material only, and
in online and hardcopy forms only.

>> that lets me: 1) lay out the DTD and 2) set up the FOSI.  Not if they're
>> selling me a one-size-fits all DTD with a "professionally designed"
>> output format that will be outdated before the next version of Netscape
>> appears.

>But geez, Michael,   I took your arguments to be in *support* of a "one size
>its all" approach -- at least in the case of "structure" or "content".

Nope.  For my example above, I want a DTD that has a portability tag. And
I want FOSIs that give me the portability info in a table for hardcopy,
a separately sizable window for INF, a definition list for HTML, and
automatically indexes it under both "foobar(portability considerations)"
and "portability considerations(foobar)".

>> So, I definitely endorse SGML's division of content and form, especially with
>> large homogenous sets of information.  However, they can take control of the
>> format away from me when they pry it from my cold, dead hands.
>>
>> I hope this makes sense,
>>

>Yes and no.  As a writer, you see, the form shouldn't *matter* to you.  Why
>should it?  You should be concerned only with *content*.  Get with the program.
>You can't have your cake and eat it too.  (It is far from obvious to me exactly
>who *is* supposed to be concerned with format.  I guess it would be geeks like
>me who might implement one or another viewer.  How does *that* make you feel?)

That's not the snake-oil I'm selling.  I'm selling an entirely different
brand: separate content from form, but still address both.  I'm _not_
talking about shipping the source (whether SGML or some other content-
based solution) to the customer.  I don't trust the customer to have
the right browser, or use a browser in the right way.  However, I am
happy to add another output filter, that will dump out all the info
in HTML format, in addition to INF and Postscript.  But I do take
responsibility for how my HTML output will look under various browsers.
Indeed, as the capabilities of HTML and browsers evolve, I can keep
my information up-to-date in its appearance simply by tweaking the
output filter.


>> PS: sorry I've been away so long.  Vacation, then work, then trying to
>> subscribe to the list so I could post again.  Bah.

>Vacation?  What's that?  You think you've got it bad?  Bet you don't
>have an '81 CM400T with a blown head gasket.

"A blown head gasket?  I used to _dream_ of having a blown head gasket.
I would've given me eye teeth for a blown head gasket.  I used to
whittle rocks with my teeth and _pretend_ they were blown head gaskets."

All I've got is sub-zero temperatures and a bus pass.  Luckily bus
passes don't blow gaskets often....


Michael Priestley
mpriestley -at- vnet -dot- ibm -dot- com
Disclaimer: speaking on my own behalf, not IBM's.