Re: Revisiting Web Tools

[Maynard Hogg <maynard -at- GOL -dot- COM>]

Mary McCauley-Stiff <Mary_McCauley-Stiff -at- STRATUS -dot- COM> wrote:

>I don't think it makes sense to use a word-processor or desktop
>publisher HTML converter, since I don't need Word or Frame docs in
>addition to the HTML.

If you've got an HTML editor that you like, more power to you. You
are, I take it, working by yourself on this project. But if you're
working on a team, you should allow people to use the text editor,
word processor, or desktop publisher that they're most comfortable
with (i.e., most productive)--provided, of course, that there's an
HTML converter for it. Then--and this is the important step--use make
to automatically update your collection HTML files for you. make isn't
just for programmers. If you can spell out a list of commands to
convert one file type into another, you can use make.

Technical note: My MKS Toolkit (Unix-like) quick on-line help
describes the purpose of make as "maintain program generated and
interdependent files". (Terse? What do expect from something
originally from the Unix world? <g>) Nowhere does it say anything
about programming. With make, you lay down the rules (in a makefile)
and specify the targets, and then make runs around checking file dates
to see what has to be updated. In the simplest case, you have rules
for converting a file in a particular type into another--here, from
.txt, .doc, .wp5, their Mac equivalent, whatever, into .html. If you
want to get fancy, you then write rules for updating particular files
based on a list of files--here, generating index.html from all the
other .html files in the directory, for example. (This requires
programming in awk, sed, perl, and all those other fun languages,
however. <g>)

Aside: I'm an editor man myself. HTML is just another set of formatter
tags to define key bindings and formatter macros for. I also know some
high-powered HTML mavens who swear by BBEdit ("Bare Bones Edit") on
the Mac for similar reasons. Why limit yourself to a Ginsu knife HTML
editor when you can edit in your choice of editor in one window and
display the results in your choice of browser in another? <g>

>I need as "pure" HTML as I can get. Therefore, I cannot use Microsoft
>or Netscape HTML-based help development environments because the HTML
>viewer doesn't support their extensions.

If you can draw up a hit list of unsupported tags, you can have make
run the programs (e.g., a member of the grep family) to check for them
and complain back to the writer.

>I am very interested in what people are doing out there in regards to
>HTML-based help.

I haven't done any help files (my client use Windows and DOS-based
help formats), but I'm working on formatter macros for HTML.
Conceptually, it's like writing a printer driver except that instead
of generating the appropriate PCL or Postscript commands for changing
the font size, using bold face, etc., the macro brackets the text with
<H1> and </H2>. Anyone who has ever used "print to disk" under MacOS
of Windows to create Postscript files will get the idea.

One problem that has me flummoxed: paragraph breaks. The formatter's
"We're Unix" attitude (impertinence from a DOS real mode program <g>)
insists that a blank line is enough. Alas, HTML follows the
programming side of Unix when it comes to "white space", not the text
processing side. I therefore have to resort to another step, a tiny
program to fix that one problem when I'd rather do everything in a
single pass.

===

    |\^/|     Maynard Hogg
 _|\|   |/|_  #306, 4-30-10 Yoga, Setagaya-ku, Tokyo, Japan 158
 >         <  Fax: +81-3-3700-7399
  >_./|\._<   Internet: maynard -at- gol -dot- com
Unsolicited commercial electronic mail sent to this address will be
proofread at a cost of US$200/hour (half-hour minimum).

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html