Contents
Scope
of TechPubTools xi
TechPub
Tools Features xiii
Jump
Start xiv
Chapter 1
Single-Sourcing and API Documentation 1
The
Naysayers Argument 1
Single-Sourcing
Naysayers 1
API
Documentation Naysayers 2
Reality
Check 3
Single-Sourcing
Rant 4
Dont
let perfect be the enemy of the good. 4
Time
Heals 4
Give
the Readers Credit 5
Analog
Not Anal 5
Dysfunctional
Online 6
Online
Disadvantages 6
Lots
of Plumbing but Little Water 7
Three
Strikes and Youre Out 7
Pop-Up
Happy Hell 7
Context-Sensitive
Suggestion 8
Tried
and True Printed Manuals 8
The
Best of Both Worlds 9
Foundation
and Structure 9
Plumbing
with Water 10
Moving
Day 10
Withholding
Tax 11
API
Documentation Rant 12
Software
Engineering 13
Information
Repository and Tools 13
Reusability
13
Send
in the Tech Writer 14
What
You Get 14
Source
Code Extraction Tools 15
Concerns
about Auto-Documentation Tools 16
Writing
Quality in the API Documentation 16
Auto-Documentation
Benefits 17
The
Code Can Contain More Information 18
Software
Engineers as Technical Writers 18
The
Future of (API) Documentation 18
Code
Generation 19
Software
Public Libraries 19
Get
More Thinkers Involved 20
Royalties
for Their Efforts 20
(New)
Copyright Protection 20
What
You Get 21
Chapter 2
Environment and Tools 23
My
Environment 23
Home-Grown
Tools 25
Directory
Structure 26
Chapter 3
FrameMaker and Mif2Go 29
FrameMaker
29
FM
Formats 30
Mapping
FM Formats to HTML Constructs 31
Online
Use and Conditional Text 33
Cascading
Style Sheet 33
Mif2Go
34
Fonts
Mapping 34
File
Splitting 36
Post-Processing
Tags in Splitting 37
Chapter
Ordering 40
[FileIDs]
in the mif2go.ini 41
[FileSequence]
in the mif2htm.ini 41
[HTMLStyles]
in the mif2htm.ini 42
[HTMLStyleFilePrefix]
in the mif2htm.ini 42
[HTMLOptions]
in the mif2htm.ini 43
Index
Tokens 44
Chapter 4
Doxygen 47
Preparation
for Using Doxygen 47
The
Doxygen Project File 48
Input
Filters 48
HTML
Output 49
PDF
Output 49
Chapter 5
Java TOC Applet 51
Chapter 6
Shell Scripts 53
00_build_tp_tools.b
54
20_cp_com_files.b
55
30_tp_tools.b
55
31_perl.b
and 31_script.b 55
32_perl.b
and 32_script.b 56
35_gen_dox.b
56
40_latex_build.b
57
45_latex_build.b
57
50_nav_update.b
58
55_nav_gen.b
59
55_nav_cp.b
60
56_nav_index.b
60
56_nav_script.b
61
Chapter 7
globe.pm 63
Overview
63
Variable
and Data Structures 64
Common
Routines 65
Chapter 8
voyant_nav.pl 67
Overview
67
The
Beginnings 68
The
Extensions 68
CYA
68
Data
Structures 69
Topic
Browsing 69
Index
Tokens 70
Input
71
Output
72
Chapter 9
voyant_mt_app.pl 75
Overview
75
The
Beginnings 76
The
Extensions 76
Input
76
Output
77
Chapter 10
voyant_indexer.pl 79
Overview
79
The
Beginnings 80
The
Extensions 80
Building
on the Java TOC Applet 82
Input
82
Output
83
Chapter 11
voyant_latex.pl 85
Input
85
Output
86
Chapter 12
find_extract.pl 87
Overview
87
Input
88
Output
88
Implementation
Details 90
Chapter 13
tree_js_2_script.pl 91
Overview
91
Input
92
Output
92
Chapter 14
html_look_integrate.pl 93
Overview
93
Input
94
Output
95
Chapter 15
ini_html_gen.pl 97
Overview
97
Input
98
Output
99
Chapter 16
log_html_gen.pl 103
Overview
103
Input
104
Output
105
Chapter 17
Input Filters to Doxygen 107
dox_bug_filter.pl
107
dox_ive_filter.pl
108
dox_chg_not.pl
108
dox_comment_chg.pl
108
pl_comment_change.pl
109
csh_comment_change.pl
109
Chapter 18
voyant_master_nav.html 111
Overview
111
Minimum
Master Definition 112
Variables
113
Chapter 19
TOC Implementation 115
m_tree.script
115
m_toc.html
116
Logical
Extensions of the Applet 116
Chapter 20
voyant_master_index.html 119
Chapter 21
Common Files 121
Default
HTML Files for Doxygen 121
Navigation
GIF files 122
Cascading
Style Sheet 122
Index
123
Open-Source tools compliments of Voyant Technologies, Inc. and Glenn C. Maxey.
01/13/2003
TP Tools v2-00-0a
# tpt-hug-02