Re: FM+SGML...will it help me?

[larry.kollar@xxxxxxxxxx]

Adrian Morse wrote:

> I currently use standard Frame and am wondering whether I might be able
> to do my job easier with FM+SGML. Our Frame files include conditional
> text for single sourcing of PDFs (software manuals) and HTML Help files
> (using mif2go). The Frame files also include numerous insets for text
> that is repeated for different products. 

There's a bit of a curve to get over, especially if you've never
worked in a structured environment before. Look into some training
if your budgets allow for it. You can figure it out on your own,
with some time, curiosity, and patience (that's how I did it) --
in that case, it's best to start with a new project & be prepared
to delete your first one or two efforts & start over.

I've also copied this response to Free Framers, since some seriously
high-level folks only post there -- they may chime in with more
helpful responses.


> i) The SGML nature of FM+SGML can be exploited in two ways: i) to
> provide a structured editing environment for normal Frame docs and/or
> ii) to create/edit SGML files. Is this right? 

Pretty much. With some effort, you can also import SGML into Frame
and have it automatically format. Deep magic. :-)

> ii) XML can be considered as a "subset" of SGML? What can SGML offer to
> a technical writer that XML can't? (Or vice versa.)

XML is mostly a subset, although it adds support for Unicode (which
isn't part of the SGML specification). Most of what was removed from
XML were optional features intended to minimize the amount of markup
in a file -- when SGML was first released in 1980, nearly everyone
used text terminals and had to add markup by hand. The minimization
features allowed writers to do things like skip close tags, or use
constructs like </> to close the last open tag, or imply markup (i.e.
a <section> tag could imply that the next line of text was a <title>
element and the line after that started a <para> element). As usual,
what makes life easier for users makes life harder for computers and
programmers... parsers had to figure all that stuff out.

XML starts from the assumption that most markup is computer-generated,
not tagged by hand, so the minimization features could be eliminated
(making parsers easier to write & maintain). XML also removes the
requirement for a DTD; again, I believe the assumption was that since
software (after debugging) would write proper markup, no validation
would be unnecessary.


> iii) FM+SGML's ability to create/edit SGML files implies that it also
> has the ability to create/edit XML files?

You can set up Frame so that the SGML it generates can be handled
by XML parsers, possibly with a little automatic cleanup.

> If so, what is the difference
> between this ability and the Save as XML command in standard FM?

Save as XML also allows you to save unstructured documents as XML.
The result is what I call "tag soup," well-formed but no structure.
If you start with a structured Frame document, Save as XML saves a
structured XML document that can be easily transformed (using XSLT)
into HTML or other formats.

> Is FM+SGML more like an authoring program for XML?

Not necessarily, but you can use it for that.


> iv) SGML, like XML, is a way of separating format and content, right?
> So, imagine that for now I just want to create a printout using SGML.
> (I'm not bothered about the fine detail, just the concepts)...So, I
> define a structure and enter the text. Then, for the printed output, I
> create a "stylesheet" that tells each of the structural elements how to
> behave. What I don't see is how I combine the text and stylesheet with
> the page layout? Do I switch from a SGML view to a WYSIWYG view and
> adjust text frames etc as per the standard version of Frame?

Frame uses an Element Definition Document (EDD), which is essentially
a combination DTD & stylesheet, to format structured documents. Page
layouts (margins, columns, etc.) are still controlled by Frame's master
pages. Working with a structured document in Frame is much like working
with unstructured documents, except that you cannot insert elements in
places where the EDD doesn't allow them.


> v) What if I want a HTML Help output. I can see why HTML conversions
> (using Save As HTML) are far more likely to be faithful representations
> of the source doc when SGML is used (as opposed to standard Frame), but
> what about the extra components needed for a Help system-the HHP, HHK
> and HHC files? Do I still need to use a converter like WWP or mif2go to
> create these?

Actually, you'll be better off using Save as XML. You'll get a structured
XML document; you can write an XSLT stylesheet to transform that to HTML
Help & possibly generate the auxiliary files as well. OTOH, if MIF2go
supports all that out of the box, you might be better off using it.


> vi) Also, I can see how a structured document might allow me to choose
> the elements to show in different outputs thereby avoiding the use of
> conditional text, but can FM+SGML help me avoid the use of text insets?
> For example, what if two software manuals share 10% of their text; does
> it mean that the remaining 90% of each manual also needs to be inside
> some single "master" Frame document as well as the shared 10%? Or are
> text insets still needed in such situations?

If you want to share that 10% between two documents, you'll either
have to use text insets or make them components of your book(s).
There's really no way around that if you continue to use Frame.


> vii) If I create SGML or XML source files I suppose the very fact that
> format and content are separated means that a localization agency does
> not need to have FM+SGML (or even plain old FM for that matter) in order
> to read and work with the files (to translate them)?

Correct in theory, but now you're getting into what's called "round-
tripping" (exporting & importing SGML/XML with no loss of formatting
either way). Most localization agencies can deal with Frame anyway.


> viii) My company is thinking of using a documentation database in the
> future (to store entire documents + reusable sections). I suppose that
> having our Frame documents tagged with SGML would make it far easier to
> add them to such a database?

Depends on the database & how you set it up. I've looked into such things
in the past & the prices were enough to give me a nosebleed. OTOH, if
you *do* make round-tripping work, XML database prices go all the way
down to zero (http://exist.sourceforge.net/). In a scenario like that,
you use Frame both to edit fragments of documents & to format documents
(for print/PDF) built from database queries -- for HTML Help & the like,
you would probably use a separate DB query & transform the result.

The thing is, *someone* has to do the work to set all that up. If that
someone is an outside consultant, you're still looking at a budget-
buster. Your IT folks might be able to do it; the problem is that the
people who can do it right are usually too busy doing other stuff. But
that would probably be the best way to go if you can set specific goals
and specifications for them.

If you do it, you'll have to learn XML, XSL(T), database programming,
and perhaps some general programming (Perl, C, etc.) as well as the
parts of Frame that make the import/export stuff work. That's a
completely different career from tech writing. It's likely a lucrative
career -- you could be the "outside consultant" -- but if you have to
do all that plus your writing tasks it'll be like working two jobs.


I've been working with structured documents for a few months now, and
building a content management database is the logical next step. It
may be a bigger step than the transition to structured documents....

--
Larry Kollar, Senior Technical Writer, ARRIS
"Content creators are the engine that drives
value in the information life cycle."
    -- Barry Schaeffer, on XML-Doc



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