Re: [FrameSGML] Structured Document Design for XML or SGML

[Larry Kollar <Larry.Kollar@xxxxxxxxxxx>]

First off -- Dan, that comment about structured & unstructured documents
being the same at the atomic level made my list of "insights that are
blindingly obvious *after* I heard it." In my own experiments trying
to add *some* structure to our disparate documents here, I've been slowly
groping toward that realization myself.

As for the brouhaha about formatting vs. content, I have to admit that
I'm of two minds. My experiments with structured documents has been a
learn-as-I-go thing as I try to add structure to certain reference
material -- log reports, alarms, and CLI commands. In our documentation,
all three of these have a fairly common format; I could rewrite them
all using troff's manpage format. In this context, structure vs. format
(IMO) boils down to something like this:

   Strictly-structured
   -------------------
   <command>
     <name>foobar</name>
     <syntax>...</syntax>
     <description>...</description>
     <parameters>...</parameters>
     <example>...</example>
     <success_resp>...</success_resp>
     <error_resp>...</error_resp>
   <command>


   Less-strict structuring
   -----------------------
   <command>
     <name>foobar</name>
     <subsection><name>Syntax</name>...</subsection>
     <subsection><name>Description</name>...</subsection>
     <subsection><name>Parameters</name>...</subsection>
     <subsection><name>Example Command</name>...</subsection>
     <subsection><name>Successful Response</name>...</subsection>
     <subsection><name>Error Response</name>...</subsection>
   </command>

In my mind, the strictly-structured version has the advantage of
enforcing inclusion (and proper ordering) of all information --
ensuring that the resulting document is both complete and consistent.
A script could easily extract the name and syntax for automatically
generating a quick reference.

The not-so-structured document is easier to implement, and could
apply to all three types of reference pages. A script could also
pull the name and syntax, but would need a bit more intelligence.


What Dan proposes in his "Information Design" paper, to me, seems
to suggest using attributes to produce a hybrid structure like so:

   <reference type="command">
     <name>foobar</name>
     <subsection type="syntax">...</subsection>
     <subsection type="description">...</subsection>
     <subsection type="parameters">...</subsection>
     <subsection type="example">...</subsection>
     <subsection type="success_resp">...</subsection>
     <subsection type="error_resp">...</subsection>
   </reference>

You still don't have enforcement and ordering, but you do gain
a more automation-friendly environment without losing ease of
implementation. The attributes describe each part of the command
(or log, or alarm). I'm waffling between "type" and "heading"
for the attribute name.

Are there any other merits or drawbacks to this approach? Like
I said, I'm learning this stuff as I go so I wouldn't be surprised
to find something missing in my thought process.

	Larry




** To unsubscribe, send a message to majordomo@omsys.com **
** with "unsubscribe framers" (no quotes) in the body.   **