TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Kimberly McClintock wrote:
> What I want is to be able to see the change I've made to the text in
> something friendlier to the eye than the marked up ascii file without
> having to go through a cumbersome (15 minute) build process. So, I'm
> hoping for a tool that will resolve the entities into something more
> readable.
You're talking about a file that contains a bunch of entity
substitutions that you might reference from _within_ a DTD? Kinda
like this one:
I think consistent column spacing is your best friend, here. That
done, any decent text editor that'll let you set "bookmarks" (or
similar) and does pattern-based find (and replace) would let you
tool-around a neatly formatted entity file easily. I use Bluefish.
Keeping track of your changes is trickier.
If it were me, as soon as I started a session, I'd open
`filename.ent` (my monolithic entities file) in a text editor and
immediately save it off with a UNIX timestamp in the name (e.g.,
`filename_1149790832.ent`). Your editor should have a tool for
inserting such timestamp in the file, so I'd insert the timestamp
temporarily on a blank line, highlight it, "cut" it, "Save As ...",
and paste it into the filename.
At this point, `filename.ent` is pristine, and we have a
serially-named duplicate for a working copy.
Make your changes. Before saving, do the timestamp / "Save As"
trick *again*. Let's say it's now `filename_1149791660.ent`.
Here's what's in your directory now:
/filename.ent <== original file
/filename_1149790832.ent <== duplicate original
/filename_1149791660.ent <== first round of changes
...
Do this every time you save, or at least every time you want to set
a milestone. Sorting by filename gives a chronological display,
thanks to the timestamp.
To place one of the versions into use, overwrite `filename.ent` with
it. You can obviously roll-back (and forward) to any version.
Lots of ways to vary this. You could set the original file
read-only, as a safeguard, so you'd have to take an explicit step to
overwrite it. And there's nothing magic about UNIX timestamps,
they're just terse and handy. You might serialize artificially
(`filename_000001.ent`, `filename_000002`, etc.).
You *could* name the duplicate original something like
`filename.ext.bak` to set it off, but that's not a good idea if your
editing sessions will span more than one day. You can't break the
timestamp method; there's nothing to remember.
To view the differences between your original and a revision (well,
any two versions, really) you just need a diff viewer. Here are some:
Natch this is poor-man's version control. A CVS or Svn server and
client will go this one better -- but there's a learning curve.
> Anybody know of an editor (by the by) that recognizes the entity markup?
Again, consistent column spacing within the file is the primary
visual enhancement. If you want more, any text editor that offers
custom syntax highlighting will do. Bluefish. HTML-Kit for
Windows. This stuff's all free. Paying money to jockey text files
seems excessive.
Oh, and once your text files are formatted neatly, a text editor
that sorts lines would be a big help, too. Just run the same sort
on each revision before saving. Your diffs will be clearer.
Good idea to leave a README in your directory, too, to let others
know how you're working.
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today!. http://www.webworks.com/techwr-l
