Re: Using SGML as HTML and publishable source

[Dave Walker <walker -at- ASPENTEC -dot- COM>]

Noreen Casey (casey -at- osf -dot- org) wrote:

: My current project is to write an
: internal system administration guide in SGML (with the ADEPT
: editor). I plan to convert the SGML source to HTML for
: online reading (via Mosaic), and LaTex for hardcopy.  Will this
: work? I have some doubts about the efficacy of using a single
: source. I anticipate that the users will primarily be reading
: this document online. If I  take full advantage of the hypertext
: capabilities of the online version (icons, "click here" buttons,
: etc.), the hardcopy version will look very strange! On the other
: hand, if I write the source so that it formats appropriately in
: both types of output, I'm afraid the the hypertext version will
: be dry and uninteresting. (The people I am writing for like
: bright, shiny things...)

It could work.

: I'm leaning towards some type of conditional markup (e.g., #ifdefs)
: in the source, but the documentation tools designer thinks it would
: be better to just avoid hypertext-specific phrasing.

Conditional markup would get really messy, and would be a nightmare to
maintain.
I agree with the doc tools designer. Just avoid hypertext-specific
phrasing. I think you can get almost the same mileage from hyperlinked
text on screen, and hyperlinked text on paper. Hyperlinked text on paper
shouldn't look that strange. I'd avoid phrases like "click here".
(which, IMHO, are annoying anyway). When I read hypertext, I
scan the highlighted text for words or phrases that relate to information
I'm looking for. When I see "click here" highlighted, it slows down my
reading/scanning because I have to read the complete sentence to find
out where "here" goes to.
In most cases, it shouldn't be difficult to have some explanatory sentence
or phrase about the info you want to link to, and highlight a meaningful
word or words in that sentence.

I don't think formatting one source for both types of output will make
the hypertext version dry and uninteresting. You could still put lots
of fun into the hypertext version (pictures, colors, sound, etc.).
I look at writing/designing one source for online and paper part
of the challenge of authoring hypertext.

You should look at a variety of hypertext documents to see what people
are doing. Don't use just Mosaic hypertext docs as your model (some I've
seen could a lot more thought in design/oganization)

Good Luck

: Senior Documentation Engineer (I am not making this up!)
: Open Software Foundation
: Cambridge, MA
: casey -at- osf -dot- org

regards,

dave walker
development engineer
for documentation    (My boss made this up)
AspenTech, Inc.
Cambridge, MA 02141
walker -at- aspentec -dot- com