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.
> Many of our clients customize their interface - user-defined field labels,
> different dialog box names, different error messages, etc. We allow them
to
> do this via a language database that ships with the program. For our next
> online help system (WebHelp or HTMLHelp), we'd like each interface element
> in our help system to reference this language database, and then
dynamically
> display the correct content. So, this content:
>
> <H1>
> Entering a Punch List Item</H1>
> <P>
> <B>To enter a punch list item</B></P>
>
> Becomes
>
> <H1>
> Entering a <%=HelpLangMan.LanguageString("db.PunchList")%> Item</H1>
> <P>
> <B>To enter a <%=HelpLangMan.LanguageString("db.PunchList")%>
> item</B></P>
I generally don't like embedding code into data. It makes it very difficult
to validate the data or the code and it makes it very difficult for other
processing applications to use the data.
My approach would be to do something like this:
> Entering a <term "PunchList"> Item</H1>
and then let the processing application figure out how to look up this term.
>
> The problem is: How do we handle indexing and full-text searches?
Obviously
> these bits of code won't index very well, and the full-text search will
just
> be a big mess. Any advice you've got would be appreciated.
This is a fundamental problem. You can't index a document until its content
is determined. It is no use indexing the data used to generate the content.
Indexing only makes sense once the document has been generated.
You can do one of 2 things:
1. Don't index. Indexing is just a primitive means of providing custom
navigation of information. Generating information on the fly is a more
sophisticated approach, which, if done properly, removes the need for
indexing. (But, of course, just substituting terms isn't going to achieve
this.)
2. Have the customization process generate a static document which is then
indexed. This is the best solution if the material is customized rarely. It
won't work so well if customization occurs every time someone access the
data.
You could implement solution 2 just as I described before, having an
OmniMark program generate the appropriate help markup and call the help
compiler to create the file you deliver to the customer.
