Contents 
 Index 
 "TPT User's Guide" 
 < Previous 
 Next > 

Chapter 2 Environment and Tools

Aside from discussing the environment that I work in and the tools that I acquired to achieve my organization’s goals, this chapter also serves as a disclaimer regarding the suitability of TechPubTools in your environment.

Your network environment can vary greatly from mine.

What is important to note about my environment is that I use a UNIX file server that both my Windows 2000 and UNIX workstation access. I use an X-Windows emulation program on Windows 2000, so that I can go back and forth between my Windows applications and my UNIX applications without thinking about it.

There are many ways to achieve the same or equivalent functionality that I enjoy. Moreover, it is possible to achieve the same goals of the TechPubTools in a pure-Windows environment and possibly even a pure UNIX/Linux environment. This is left as an exercise for you to accomplish.

My Environment

Below are the operating systems and off-the-shelf tools that I use or have access to in order to implement the TechPubTools.

Microsoft Windows 2000, version 5.0095 with Service Pack 1. This is my main work environment from which I operate FrameMaker, Mif2Go, my HTML editor of choice, and DevaSearch. For more information, refer to www.microsoft.com.

Adobe’s FrameMaker 6 running under Windows 2000 is used to create the printed and PDF documentation. FrameMaker (FM) files are single-sourced into an HTML system. For more information, refer to www.adobe.com.

FrameMaker is used to create “structured” information that is intended to be handled like a printed book even if electronic in nature. In particular, this means that:

• Information is organized with a table of contents.

• Die-hard readers can go from the beginning to the end of this documentation and not miss any topics.

• All topics link to their previous and next topics, which helps orient the reader when displayed from the index or table of contents.

Omni Systems Inc. Mif2Go, version upg33u20.zip, an add-on program for FM that among other things can convert from FrameMaker’s MIF format to HTML. For more information, refer to www.omsys.com.

WebWorks Publisher Professional (WWP) could also be used to achieve the same goal as MIF2Go.

• At the time of writing, Mif2Go was a lower cost solution over WWP and seemed to provide more flexibility.

Ulli Meybohm’s HTML EDITOR Phase 5 (Release 22.09.1999). This is a FreeWare program in German for editing HTML files. If you already have a good HTML editor or don’t understand German, you don’t need this. For more information, refer to www.meybohm.de.

Sun Microsystem’s Solaris 2.7 (UNIX) on a Sun workstation. This is a machine owned by Voyant’s Software Engineering department that I use infrequently to run Shell scripts and Perl programs. More importantly, we use a UNIX file server that both Windows and UNIX can access. This is not needed if you port everything into a Windows-only environment. Refer to www.sun.com.

• UNIX Shell scripts are used to create control much of the process, because this is Voyant’s development environment.

• Some of the Shell scripts perform CVS commands, a source code management and version control system.

• Batch files in the Windows environment could accomplish much of the same thing.

StarNet Communications Corp.’s X-Win32, version 5.1.1. This is an X-Windows desktop emulation environment for Windows 2000. This is what gets me access to the Sun workstation. This is not needed if you port everything into a Windows-only environment. You can find many ways to access a UNIX environment, if that is even a requirement. For more information, refer to support@starnet.com.

Dimitri van Heesch’s Doxygen, version-1.2.11. This is under the terms of the GNU General Public License (e.g., open-source). This can be ported to a Windows-only environment. For more information, refer to www.doxygen.org.

• Doxygen is a documentation system for C++, Java, IDL (Corba, Microsoft and KDE-DCOP flavors) and C. Doxygen is an open-source tool used to extract code prototypes and specially flagged code comments from C/C++ source code.

• JavaDoc is another open-source tool that accomplish many of the same things for the Java language; JavaDoc output could easily be incorporated into this solution.

• Doxygen is also used imperfectly on Perl files and on an in-house Pascal-like programming language (IVE) files. This required the use of input filters which fake out Doxygen in what it sees and recognizes.

DevaHelp’s DevaSearch. This is used to implement the full-text search. Although the tool is used in the Windows 2000 environment, the resulting HTML and Javascript is cross-browser, cross-platform. For more information, refer to www.devahelp.com.

Perl, the programming language used in the scripts. Perl programs are used to change the content of the HTML files in specific areas. You’ll need the Perl interpreter for your environment. I use Perl in the UNIX environment. Perl is available in Windows-only environment. For more information, refer to www.perl.org.

Just because this solution uses these off-the-shelf tools does not mean that other tools cannot be used instead or in addition. This open-source solution is meant to provide you with ideas and foundation upon which your technical publication’s solution can be built.



 "TPT User's Guide" 
 < Previous 
 Next > 


Open-Source tools compliments of Voyant Technologies, Inc. and Glenn C. Maxey.
01/13/2003

TP Tools v2-00-0a

# tpt-hug-02