Help & Manual ®

The new standard in

technical documentation

User
Manual
Version 5.1

© 1997 - 2009 by EC Software, all rights reserved

 2 Help & Manual 5 - User Help

Table of Contents
Part I Welcome to Help & Manual 5 14

Part II Introduction 16
1 About Help &
...................................................................................................................................
Manual 16
2 Why Help & ...................................................................................................................................
Manual? 16
3 FAQ for Upgraders
...................................................................................................................................
from HM4 18
4 The User Interface
................................................................................................................................... 23
Toolbars .......................................................................................................................................................... 24
The Project Explorer
.......................................................................................................................................................... 25
The Editor .......................................................................................................................................................... 29
Options & Keyboard
..........................................................................................................................................................
Shortcuts 31
5 Getting help................................................................................................................................... 37
6 How to buy Help
...................................................................................................................................
& Manual 39

Part III Quick Start Tutorials 41

1 Using the Project
...................................................................................................................................
Explorer 41
Project Explorer
..........................................................................................................................................................
Sections 41
Navigating in ..........................................................................................................................................................
the Project Explorer 43
Tips & Tricks ..........................................................................................................................................................
in the Project Explorer 46
2 Converting old
...................................................................................................................................
projects 51
3 Creating projects
................................................................................................................................... 54
4 Importing data
................................................................................................................................... 55
5 Adding topics
................................................................................................................................... 56
6 Editing topics
................................................................................................................................... 58
7 Using styles................................................................................................................................... 61
8 Organizing the
...................................................................................................................................
TOC 63
9 Inserting graphics
................................................................................................................................... 67
10 Inserting tables
................................................................................................................................... 69
11 Creating hyperlinks
................................................................................................................................... 71
12 Publishing your
...................................................................................................................................
project 73
13 Template files
................................................................................................................................... 75
14 Tutorial Projects
................................................................................................................................... 77
DHTML examples
..........................................................................................................................................................
tutorial 77
Conditional output
..........................................................................................................................................................
tutorial 78
Modular help ..........................................................................................................................................................
systems tutorial 79
Pocket PC help
..........................................................................................................................................................
template 79
Non-scrolling..........................................................................................................................................................
header template 80
Help & Manual..........................................................................................................................................................
help project template 80
Help & Manual..........................................................................................................................................................
help source code 81
SDL Trados INI
..........................................................................................................................................................
file 81

© 1997 - 2009 by EC Software, all rights reserved

 Contents 3

Part IV Basic Working Procedures 83

1 Creating Projects
................................................................................................................................... 83
Creating an empty
..........................................................................................................................................................
new project 83
Choosing your..........................................................................................................................................................
save mode 85
Publishing formats
.......................................................................................................................................................... 87
Converting old
..........................................................................................................................................................
projects 87
2 Configuring ...................................................................................................................................
Your Project 91
Project Configuration
.......................................................................................................................................................... 91
Background colors
..........................................................................................................................................................
and help viewers 93
International languages
..........................................................................................................................................................
setup 94
3 Importing Data
................................................................................................................................... 99
New project with
..........................................................................................................................................................
imported data 99
Importing data
..........................................................................................................................................................
into existing projects 100
Importing & ..........................................................................................................................................................
copying topics and XML files 102
Settings for ..........................................................................................................................................................
importing data 105
Merging HTML ..........................................................................................................................................................
files into topics 107
4 Creating Topic
...................................................................................................................................
Files 108
About topics..........................................................................................................................................................
and the TOC 109
Creating new..........................................................................................................................................................
topics in the TOC 110
Creating new..........................................................................................................................................................
topics in Topic Files 112
Creating topics
..........................................................................................................................................................
from other sources 115
Editing the topic
..........................................................................................................................................................
caption and header 117
Topic headers.......................................................................................................................................................... 119
Using help windows
.......................................................................................................................................................... 121
Using HTML..........................................................................................................................................................
page templates 123
Creating popup
..........................................................................................................................................................
topics 125
Using JavaScript
..........................................................................................................................................................
popups 129
5 Editing Topic
...................................................................................................................................
Files 132
Writing and ..........................................................................................................................................................
formatting text 132
The paragraph..........................................................................................................................................................
end mark 135
Topic Headers.......................................................................................................................................................... 136
Selecting text
..........................................................................................................................................................
and content 138
Copying, cutting
..........................................................................................................................................................
and pasting 139
Searching for..........................................................................................................................................................
text, topics and referrers 141
Special characters,
..........................................................................................................................................................
lines and breaks 143
Using comments
..........................................................................................................................................................
and bookmarks 143
Spell checking
.......................................................................................................................................................... 145
Re-using content
..........................................................................................................................................................
with snippets 149
Printing topics
.......................................................................................................................................................... 153
Editing XML..........................................................................................................................................................
source code 154
6 Text Formatting
...................................................................................................................................
and Styles 155
Formatting text
..........................................................................................................................................................
manually 155
Quick guide ..........................................................................................................................................................
to using styles 157
Style display..........................................................................................................................................................
in the Toolbar 159
Defining styles
.......................................................................................................................................................... 161
Editing styles
.......................................................................................................................................................... 164
Formatting text
..........................................................................................................................................................
with styles 167
Turning formatting
..........................................................................................................................................................
into styles 169
Using indents.......................................................................................................................................................... 172
Help and print
..........................................................................................................................................................
styles 175

© 1997 - 2009 by EC Software, all rights reserved

4 Help & Manual 5 - User Help

Image caption..........................................................................................................................................................
and comment styles 176
Copying styles
..........................................................................................................................................................
from other projects 177
Table styles .......................................................................................................................................................... 178
Numbered and ..........................................................................................................................................................
Bulleted Lists 180
Bulleted.........................................................................................................................................................
lists 180
Numbered .........................................................................................................................................................
lists 183
Outline numbered
.........................................................................................................................................................
lists 187
Formatting
.........................................................................................................................................................
lists 193
HTML list.........................................................................................................................................................
output format 194
Formatting program
..........................................................................................................................................................
source code 195
Examples ......................................................................................................................................................... 197
7 Managing the
...................................................................................................................................
TOC & Topic Files 199
Moving, cutting
..........................................................................................................................................................
and pasting topics 199
Deleting TOC ..........................................................................................................................................................
entries and topics 201
Changing the ..........................................................................................................................................................
levels of topics 203
Exporting and..........................................................................................................................................................
importing topics 204
Topic IDs and..........................................................................................................................................................
context numbers 205
Multiple TOC..........................................................................................................................................................
entries for one topic 208
Topic icon, status
..........................................................................................................................................................
and timestamps 209
Topic files without
..........................................................................................................................................................
TOC entries 210
Managing topic
..........................................................................................................................................................
files in the Explorer 211
8 Links, Anchors,
...................................................................................................................................
Macros, Scripts and HTML 214
Supported hyperlink
..........................................................................................................................................................
types 214
Inserting topic
..........................................................................................................................................................
links 215
Inserting Internet
..........................................................................................................................................................
links 218
Inserting file..........................................................................................................................................................
links 220
Inserting script
..........................................................................................................................................................
and macro links 223
Editing and formatting
..........................................................................................................................................................
links 225
Anchors - jump..........................................................................................................................................................
targets 226
Linking to other
..........................................................................................................................................................
projects and help files 229
Links and secondary
..........................................................................................................................................................
windows 231
Inserting HTML..........................................................................................................................................................
code objects 231
Application links
..........................................................................................................................................................
to Webhelp 234
A-Links and ..........................................................................................................................................................
A-Keywords 236
9 Using Graphics
................................................................................................................................... 238
Supported graphics
..........................................................................................................................................................
formats 238
Inserting graphics
..........................................................................................................................................................
and screenshots 239
Positioning graphics
.......................................................................................................................................................... 241
Editing, resizing
..........................................................................................................................................................
and hi-res PDF printing 242
Using the Impict
..........................................................................................................................................................
graphics editor 244
Using the screen
..........................................................................................................................................................
capture function 244
Using graphics
..........................................................................................................................................................
as hyperlinks 245
Graphics with..........................................................................................................................................................
hotspots, macros and scripts 246
Finding and ..........................................................................................................................................................
replacing graphics 249
Managing your..........................................................................................................................................................
graphics 249
Shortcuts for..........................................................................................................................................................
graphics 251
10 Working with
...................................................................................................................................
Tables 253
About tables.......................................................................................................................................................... 253
Inserting tables
.......................................................................................................................................................... 254
Managing column
..........................................................................................................................................................
widths 256
Selecting and..........................................................................................................................................................
formatting cells and tables 258
Adding and deleting
..........................................................................................................................................................
rows and columns 259
Splitting, merging
..........................................................................................................................................................
and unmerging cells 260

© 1997 - 2009 by EC Software, all rights reserved

 Contents 5

Deleting the ..........................................................................................................................................................

contents of cells 261
Converting tables
..........................................................................................................................................................
to text 262
Indenting tables
.......................................................................................................................................................... 262
Table styles .......................................................................................................................................................... 263
Text/paragraph
..........................................................................................................................................................
styles in tables 265
Nested tables.......................................................................................................................................................... 266
Using background
..........................................................................................................................................................
graphics 267
Handling table
..........................................................................................................................................................
borders 268
11 Adding video
...................................................................................................................................
files 269
Inserting videos
.......................................................................................................................................................... 269
Editing the HTML
..........................................................................................................................................................
code 271
Support in output
..........................................................................................................................................................
formats 272
12 Keywords and
...................................................................................................................................
Indexes 273
Adding and editing
..........................................................................................................................................................
keywords 274
Editing the index
..........................................................................................................................................................
directly 275
Find and replace
..........................................................................................................................................................
keywords 280
Using keywords
..........................................................................................................................................................
with anchors 280
Using A-keywords
.......................................................................................................................................................... 281
Index section..........................................................................................................................................................
header separators 284

Part V Publishing 288

1 Testing Your
...................................................................................................................................
Project 288
Tools for finding
..........................................................................................................................................................
help bugs 288
Using the Report
..........................................................................................................................................................
Tool 289
Testing links..........................................................................................................................................................
and missing graphics 289
Searching for..........................................................................................................................................................
topics and referrers 290
Testing keywords
.......................................................................................................................................................... 292
2 Configuring
...................................................................................................................................
Your Output 292
Help Windows .......................................................................................................................................................... 292
HTML Help .......................................................................................................................................................... 294
Webhelp .......................................................................................................................................................... 296
Layout ......................................................................................................................................................... 298
Full Text.........................................................................................................................................................
Search tricks 300
Adobe PDF and..........................................................................................................................................................
printed manuals 301
Visual Studio..........................................................................................................................................................
Help 302
Winhelp .......................................................................................................................................................... 303
MS Word RTF .......................................................................................................................................................... 304
eBooks .......................................................................................................................................................... 304
Windows.........................................................................................................................................................
Exe eBooks 304
ePub eBooks
......................................................................................................................................................... 305
ePub resources
......................................................................................................................................................... 309
3 Publishing ...................................................................................................................................
Your Projects 311
Microsoft help
..........................................................................................................................................................
compilers 311
Publication checklist
.......................................................................................................................................................... 312
Publishing .......................................................................................................................................................... 313
Distribution ..........................................................................................................................................................
files 319
Transforming ..........................................................................................................................................................
your output with skins 321
4 PDF and Printed
...................................................................................................................................
Manuals 325
About PDF output
.......................................................................................................................................................... 325
Topic headings
..........................................................................................................................................................
in PDF 325
Publishing PDF
..........................................................................................................................................................
files 326

© 1997 - 2009 by EC Software, all rights reserved

 6 Help & Manual 5 - User Help

Printing user..........................................................................................................................................................
manuals 328
Using print manual
..........................................................................................................................................................
templates 330
Embedding files
..........................................................................................................................................................
in PDFs 332
CID mode for..........................................................................................................................................................
Unicode fonts 332

Part VI More Advanced Procedures 335

1 Using Version
...................................................................................................................................
Control Systems 335
Introduction.......................................................................................................................................................... 338
Setup and editing
.......................................................................................................................................................... 339
Auto & manual
..........................................................................................................................................................
check-out 346
Graphics and..........................................................................................................................................................
additional files 348
Backups and..........................................................................................................................................................
disaster recovery 349
2 Toggles: Expanding
...................................................................................................................................
Text and Images 350
About toggles.......................................................................................................................................................... 350
Expanding section
..........................................................................................................................................................
toggles 351
Expanding inline
..........................................................................................................................................................
text toggles 355
Expanding image
..........................................................................................................................................................
toggles 357
Toggle IDs .......................................................................................................................................................... 359
Editing and copying
..........................................................................................................................................................
toggles 360
Formatting toggles
..........................................................................................................................................................
with CSS 361
Expand All / ..........................................................................................................................................................
Collapse All 363
Toggle troubleshooting
.......................................................................................................................................................... 365
Updating old..........................................................................................................................................................
expanding sections 366
Printing topics
..........................................................................................................................................................
containing toggles 367
3 Using Context-Sensitive
...................................................................................................................................
Help 369
Context help..........................................................................................................................................................
support by output format 369
Creating context-sensitive
..........................................................................................................................................................
topics 370
Application calls
..........................................................................................................................................................
to context-sensitive topics 372
Application calls
..........................................................................................................................................................
to Webhelp 373
Auto-generating
..........................................................................................................................................................
topic files 375
4 Using Variables
................................................................................................................................... 376
Where you can..........................................................................................................................................................
use variables 377
User-defined..........................................................................................................................................................
variables 378
Global predefined
..........................................................................................................................................................
variables 381
Editing, formatting
..........................................................................................................................................................
and disabling variables 382
Inserting variables
..........................................................................................................................................................
in topics and headers 386
Inserting variables
..........................................................................................................................................................
in other project locations 388
Counter variables
..........................................................................................................................................................
for numbering 391
Find and replace
..........................................................................................................................................................
variables 392
Variables in ..........................................................................................................................................................
HTML templates 393
Redefining variables
.......................................................................................................................................................... 394
The power of..........................................................................................................................................................
editable variables 395
Variables in ..........................................................................................................................................................
PDF templates 399
5 Conditions...................................................................................................................................
and Customized Output 399
How conditional
..........................................................................................................................................................
output works 400
About include
..........................................................................................................................................................
options 400
Using conditional
..........................................................................................................................................................
output 402
Preventing dead
..........................................................................................................................................................
links 404
Defining include
..........................................................................................................................................................
options 406
Topic include
..........................................................................................................................................................
options 407
Conditional text
..........................................................................................................................................................
include options 410
Modular projects
..........................................................................................................................................................
include options 412

© 1997 - 2009 by EC Software, all rights reserved

 Contents 7

Redefining variables
.......................................................................................................................................................... 414
HTML template
..........................................................................................................................................................
conditions 415
6 Templates ...................................................................................................................................
in Help & Manual 416
Template types
.......................................................................................................................................................... 416
Templates for
..........................................................................................................................................................
projects 417
Skins .......................................................................................................................................................... 419
Content templates
..........................................................................................................................................................
for topics 423
PDF and print
..........................................................................................................................................................
manual templates 425
HTML templates
.......................................................................................................................................................... 427
Windows Exe ..........................................................................................................................................................
eBook templates 429
Using secondary
..........................................................................................................................................................
windows 429
7 Using HTML
...................................................................................................................................
Templates 430
Types of HTML..........................................................................................................................................................
templates 431
Editing HTML ..........................................................................................................................................................
templates 431
HTML topic page
..........................................................................................................................................................
Templates 433
The Layout template
..........................................................................................................................................................
for Webhelp 437
The TOC template
..........................................................................................................................................................
for Webhelp 437
The Search template
..........................................................................................................................................................
for Webhelp 438
The Index template
..........................................................................................................................................................
for Webhelp 438
Variables in ..........................................................................................................................................................
HTML templates 439
Conditional output
..........................................................................................................................................................
in HTML templates 441
Graphics references
..........................................................................................................................................................
in HTML templates 442
Referencing..........................................................................................................................................................
external files 444
Troubleshooting
.......................................................................................................................................................... 445
8 Working with
...................................................................................................................................
Modular Help Systems 446
Support in output
..........................................................................................................................................................
formats 447
Creating a modular
..........................................................................................................................................................
project 447
Merge methods..........................................................................................................................................................
for CHM & HLP 451
Managing modules
..........................................................................................................................................................
in the TOC 454
Managing graphics
..........................................................................................................................................................
in modules 456
Managing IDs ..........................................................................................................................................................
and context numbers 456
Creating links
..........................................................................................................................................................
between modules 459
Publishing modular
..........................................................................................................................................................
projects 461
Multiple Webhelp
..........................................................................................................................................................
projects 464
9 Command ...................................................................................................................................
Line Options 466
H&M command ..........................................................................................................................................................
line syntax 466
Project converter
..........................................................................................................................................................
syntax 471
Basic command..........................................................................................................................................................
line options 473
Using include..........................................................................................................................................................
options 475
Output to multiple
..........................................................................................................................................................
formats 476
Skins & redefining
..........................................................................................................................................................
variables 478
INI and batch..........................................................................................................................................................
files 480
Publishing from
..........................................................................................................................................................
your application 485
10 Using Baggage
...................................................................................................................................
Files 485
Uses for Baggage
..........................................................................................................................................................
Files 486
Adding and referencing
..........................................................................................................................................................
files 486
Removing, exporting
..........................................................................................................................................................
and importing 487
Baggage handling
.......................................................................................................................................................... 488
11 Visual Studio
...................................................................................................................................
Help (MS Help 2.0) 490
Requirements
..........................................................................................................................................................
and limitations 490
About compiling
..........................................................................................................................................................
VS Help 491

© 1997 - 2009 by EC Software, all rights reserved

 8 Help & Manual 5 - User Help

12 XML and XML

...................................................................................................................................
editing 493
13 Using OLE ...................................................................................................................................
Objects 494
Inserting OLE
..........................................................................................................................................................
objects 494
OLE examples.......................................................................................................................................................... 497
14 Replacing Formatting
...................................................................................................................................
and Styles 497
Introduction..........................................................................................................................................................
to style replacement 498
Font attributes
..........................................................................................................................................................
- styled text 500
Font attributes
..........................................................................................................................................................
- unstyled text 503
Paragraph attributes
..........................................................................................................................................................
- styled text 507
Paragraph attributes
..........................................................................................................................................................
- unstyled text 510
Styling imported
..........................................................................................................................................................
formatted text 513

Part VII Multi-User Editing & Translation 518

1 Multi-User ...................................................................................................................................
Editing 518
2 Translating...................................................................................................................................
Your Projects 521
About translation
..........................................................................................................................................................
support 522
Translating with
..........................................................................................................................................................
external editors 522
Translating in
..........................................................................................................................................................
Help & Manual 525
Translating texts
..........................................................................................................................................................
in images 528
Instructions ..........................................................................................................................................................
for translators and editors 528

Part VIII Tools included with Help & Manual 532

1 The Screen...................................................................................................................................
Capture Tool 532
2 The Project...................................................................................................................................
Reports Tool 534
3 The Impict ...................................................................................................................................
Screenshot Editor 536
4 The Print Manual
...................................................................................................................................
Designer 537
5 The Help Context
...................................................................................................................................
Tool 539
6 The Spell Checker
................................................................................................................................... 543
Creating and..........................................................................................................................................................
editing custom dictionaries 546
Using custom..........................................................................................................................................................
dictionaries 548
7 The Project...................................................................................................................................
Converter 550
8 The Project...................................................................................................................................
Synchronization Tool 556
About Project ..........................................................................................................................................................
Synchronization 556
Synchronization
..........................................................................................................................................................
Steps 557
Step 1: Create
.........................................................................................................................................................
a translation sibling 557
Step 2: Translate
.........................................................................................................................................................
the original project 559
Step 3: Update
.........................................................................................................................................................
the original project 560
Step 4: Synchronize
.........................................................................................................................................................
the new version 560
Step 5: Translate
.........................................................................................................................................................
the changes 562
Identifying changes
.......................................................................................................................................................... 563
Interim updates
.......................................................................................................................................................... 564
Synching existing
..........................................................................................................................................................
projects 565
Problems and ..........................................................................................................................................................
troubleshooting 565

Part IX Reference 568

1 FAQ for HM4
...................................................................................................................................
Upgraders 568
2 Ribbon Tabs
...................................................................................................................................
and Dialogs 573

© 1997 - 2009 by EC Software, all rights reserved

 Contents 9

The Workspace.......................................................................................................................................................... 574

Print Manual
......................................................................................................................................................... 575
Print Preview
......................................................................................................................................................... 577
Version .........................................................................................................................................................
Control System 578
The Project Tab
.......................................................................................................................................................... 579
Clipboard ......................................................................................................................................................... 579
Manage.........................................................................................................................................................
Topics 580
Add Topic/File ......................................................................................................................................... 581
Explore ......................................................................................................................................... 585
Change ......................................................................................................................................... 585
Find ......................................................................................................................................... 586
File ......................................................................................................................................... 588
Mini Toolbar ......................................................................................................................................... 589
Project ......................................................................................................................................................... 590
Publish ......................................................................................................................................... 590
Bookmark ......................................................................................................................................... 593
Options ......................................................................................................................................... 594
Tools ......................................................................................................................................................... 594
Spelling ......................................................................................................................................... 594
Screen Capture......................................................................................................................................... 595
Image Editor ......................................................................................................................................... 596
Report Tool ......................................................................................................................................... 596
Index Tool ......................................................................................................................................... 598
Manual Designer ......................................................................................................................................... 599
Context Tool ......................................................................................................................................... 600
Synchronize ......................................................................................................................................... 600
The Write Tab.......................................................................................................................................................... 600
Clipboard ......................................................................................................................................................... 601
Editing ......................................................................................................................................................... 601
Find & Replace.........................................................................................................................................
Text 602
Styles ......................................................................................................................................................... 603
Create Style from .........................................................................................................................................
Selection 603
Edit Styles ......................................................................................................................................... 604
Replace Styles......................................................................................................................................... 605
Font ......................................................................................................................................................... 605
Format Font ......................................................................................................................................... 606
Syntax Highlighting ......................................................................................................................................... 607
Paragraph ......................................................................................................................................................... 608
Format Paragraph ......................................................................................................................................... 609
Format Borders.........................................................................................................................................
and Background 611
Format Bullets .........................................................................................................................................
and Numbering 612
Insert / Insert
.........................................................................................................................................................
Object 615
Link ......................................................................................................................................... 617
Image ......................................................................................................................................... 622
Hotspot editor ......................................................................................................................................... 624
Movie ......................................................................................................................................... 625
Anchor ......................................................................................................................................... 627
Text Variable ......................................................................................................................................... 627
Conditional Text ......................................................................................................................................... 628
Toggle ......................................................................................................................................... 629
HTML Code Object ......................................................................................................................................... 632
Comment ......................................................................................................................................... 633
Snippets ......................................................................................................................................... 633
OLE Object ......................................................................................................................................... 635

© 1997 - 2009 by EC Software, all rights reserved

10 Help & Manual 5 - User Help

Special Characters ......................................................................................................................................... 637

The Table Tab
.......................................................................................................................................................... 638
Table Properties
......................................................................................................................................................... 638
The View Tab.......................................................................................................................................................... 642
Program.........................................................................................................................................................
Options 643
Program Options .........................................................................................................................................
- General 643
Program Options .........................................................................................................................................
- Ribbon 645
Program Options .........................................................................................................................................
- Shortcuts 646
Program Options .........................................................................................................................................
- Editor 647
Program Options .........................................................................................................................................
- Compilers 649
Program Options .........................................................................................................................................
- PDF Export 650
The Help Tab.......................................................................................................................................................... 652
3 Project Configuration
...................................................................................................................................
Settings 652
Common Properties
.......................................................................................................................................................... 653
Title & Copyright
......................................................................................................................................................... 654
Language .........................................................................................................................................................
Settings 654
Project Search
.........................................................................................................................................................
Path 656
Text Variables
......................................................................................................................................................... 657
Custom .........................................................................................................................................................
Builds 658
Topic Status
......................................................................................................................................................... 659
Help Windows
......................................................................................................................................................... 660
General Options ......................................................................................................................................... 660
HTML Help Options ......................................................................................................................................... 661
Winhelp Options .........................................................................................................................................
Tab 663
Miscellaneous
.........................................................................................................................................................
Options 665
HTML Page Templates
.......................................................................................................................................................... 666
Publishing Options
.......................................................................................................................................................... 667
HTML Help ......................................................................................................................................................... 667
Popup Topics ......................................................................................................................................... 667
Extended .HHP.........................................................................................................................................
Settings 670
HTML Export Options ......................................................................................................................................... 671
Webhelp......................................................................................................................................................... 674
Layout ......................................................................................................................................... 674
Navigation ......................................................................................................................................... 676
Table of Contents ......................................................................................................................................... 678
Keyword Index......................................................................................................................................... 679
Full Text Search ......................................................................................................................................... 680
Popup Topics ......................................................................................................................................... 682
HTML Export Options ......................................................................................................................................... 684
Adobe PDF ......................................................................................................................................................... 690
PDF Layout ......................................................................................................................................... 690
PDF Options ......................................................................................................................................... 691
Font Embedding ......................................................................................................................................... 692
Visual Studio
.........................................................................................................................................................
Help 694
Namespace & .........................................................................................................................................
Options 694
Popup Topics ......................................................................................................................................... 695
HTML Export Options ......................................................................................................................................... 697
Winhelp......................................................................................................................................................... 700
Miscellaneous .........................................................................................................................................
Settings 701
Modular Help Options ......................................................................................................................................... 702
Extended .HPJ.........................................................................................................................................
Settings 703
Microsoft.........................................................................................................................................................
Word RTF 705
Page Setup & Headings ......................................................................................................................................... 705
eBooks ......................................................................................................................................................... 706

© 1997 - 2009 by EC Software, all rights reserved

 Contents 11

Windows Exe eBooks

......................................................................................................................................... 706
Visual Appearance
................................................................................................................................... 706
Functionality &...................................................................................................................................
Security 708
Popups in eBooks................................................................................................................................... 709
ePub ebooks ......................................................................................................................................... 710
4 Styles, Formatting
...................................................................................................................................
and Tables 711
Why use dynamic
..........................................................................................................................................................
styles? 711
How do styles
..........................................................................................................................................................
work? 713
About inheritance
..........................................................................................................................................................
in styles 714
The standard..........................................................................................................................................................
styles 717
Paragraph, text
..........................................................................................................................................................
and table styles 718
Style organization
..........................................................................................................................................................
strategies 720
Tabs, indents
..........................................................................................................................................................
and HTML 722
About table and
..........................................................................................................................................................
column widths 723
5 Publishing ...................................................................................................................................
Formats 725
HTML Help .......................................................................................................................................................... 727
HTML Help
.........................................................................................................................................................
project files 728
Webhelp .......................................................................................................................................................... 730
Browser.........................................................................................................................................................
compatibility 731
eBooks .......................................................................................................................................................... 732
ePub eBooks
......................................................................................................................................................... 732
ePub resources
......................................................................................................................................................... 733
Windows.........................................................................................................................................................
Exe eBooks 735
Adobe PDF .......................................................................................................................................................... 737
Printed manuals
.......................................................................................................................................................... 738
Visual Studio
..........................................................................................................................................................
Help 738
MS Word RTF .......................................................................................................................................................... 739
Classic Winhelp
.......................................................................................................................................................... 740
Winhelp.........................................................................................................................................................
project files 742
Windows Vista
..........................................................................................................................................................
Help 743
6 Project Content
................................................................................................................................... 743
Accessibility.......................................................................................................................................................... 743
Snippets and..........................................................................................................................................................
multiple references 751
Graphics, Videos
..........................................................................................................................................................
and OLE Objects 753
Graphic .........................................................................................................................................................
formats and file size 753
Embedded .........................................................................................................................................................
graphics 755
About using
.........................................................................................................................................................
video files 756
About using
.........................................................................................................................................................
OLE objects 757
Scripts, HTML..........................................................................................................................................................
and Macros 758
About JavaScript
.........................................................................................................................................................
links 759
About Winhelp
.........................................................................................................................................................
macro links 761
About inline
.........................................................................................................................................................
HTML code 762
7 Modules, Conditional
...................................................................................................................................
Output & Variables 764
Modular Projects
.......................................................................................................................................................... 764
Runtime.........................................................................................................................................................
and publish time merging 767
Planning.........................................................................................................................................................
modular projects 770
Variables and..........................................................................................................................................................
Conditional Output 772
Where you.........................................................................................................................................................
can use variables 772
Global predefined
.........................................................................................................................................................
variables 774
Date & time
.........................................................................................................................................................
formatting in variables 776
HTML template
.........................................................................................................................................................
variables 778
HTML template
.........................................................................................................................................................
output conditions 782
PDF template
.........................................................................................................................................................
variables 784

© 1997 - 2009 by EC Software, all rights reserved

12 Help & Manual 5 - User Help

Conditional
.........................................................................................................................................................
output 785
Topic entry
.........................................................................................................................................................
and topic file include options 787
Context-Sensitive
..........................................................................................................................................................
Help & Popups 788
Context-sensitive
.........................................................................................................................................................
help technologies 789
About popup
.........................................................................................................................................................
topics 792
About field-level
.........................................................................................................................................................
popups 794
About implementing
.........................................................................................................................................................
context help 796
Popups .........................................................................................................................................................
in Winhelp and HTML Help 798
About map.........................................................................................................................................................
files 799
8 Project Structure
...................................................................................................................................
& Templates 801
Topic IDs, Context
..........................................................................................................................................................
Numbers and Keywords 801
About topic
.........................................................................................................................................................
IDs and anchors 801
About help
.........................................................................................................................................................
context numbers 803
About index
.........................................................................................................................................................
keywords 805
About A-Keywords
......................................................................................................................................................... 806
Help Windows .......................................................................................................................................................... 807
External.........................................................................................................................................................
windows 808
Help windows
.........................................................................................................................................................
in HTML Help 809
Help windows
.........................................................................................................................................................
in Winhelp 810
HTML Templates
.......................................................................................................................................................... 810
Graphics.........................................................................................................................................................
in HTML templates 811
HTML Template
.........................................................................................................................................................
Variables 813
HTML Template
.........................................................................................................................................................
Output Conditions 817
9 International
...................................................................................................................................
Languages and Unicode 819
About H&M's..........................................................................................................................................................
Unicode support 820
About project
..........................................................................................................................................................
language settings 822
Language settings
..........................................................................................................................................................
and PDF 824

Part X Frequently Asked Questions 826

1 General questions
................................................................................................................................... 826
2 Publishing ...................................................................................................................................
questions 826
3 Dynamic styles
...................................................................................................................................
questions 827
4 Editing questions
................................................................................................................................... 828
5 HTML and ...................................................................................................................................
HTML Help questions 829
6 PDF questions
................................................................................................................................... 832
7 Printing questions
................................................................................................................................... 834
8 Searching in
...................................................................................................................................
Webhelp 834
9 Spell check...................................................................................................................................
questions 835
10 Table questions
................................................................................................................................... 836
11 User interface
...................................................................................................................................
questions 836
12 Video questions
................................................................................................................................... 837
13 Winhelp questions
................................................................................................................................... 837

Index 840

© 1997 - 2009 by EC Software, all rights reserved

Part

I
 14 Help & Manual 5 - User Help

1 Welcome to Help & Manual 5

Help & Manual 5 is a single-source help authoring and technical
writing environment for both single and multi-author editing.
In the Professional version you can save your projects directly
as plain-text uncompressed XML files in a folder either on
your hard disk or in a version control repository.
This help is designed both as a course in using Help & Manual
and as an ongoing reference while you are working with the
program.

Getting started new users

· Study the Introduction 16 and Quick Start Tutorials 41 sections to familiarize yourself
with the basics of the program.
· Check out all the links in the Help tab plenty of help is available!

Getting started users upgrading from H&M 4

· See the Upgrade FAQ 568 for a quick summary of the major changes and where to find
the functions you are looking for.
· Even if you are an experienced Help & Manual user, please run through the
Introduction 16 and Quick Start Tutorials 41 sections quickly to get up to speed with what
has changed in the latest version of the program.

© 1997 - 2009 by EC Software, all rights reserved

Part

II
 16 Help & Manual 5 - User Help

2 Introduction
The topics in this section provide some basic information about Help & Manual, what it is for
and what you can do with it.

2.1 About Help & Manual

Help & Manual is a professional help authoring and documentation tool that is as easy to
use as a normal word processor. Originally, help authoring tools were developed to make it
easier to produce interactive help files for Windows applications in the standard Microsoft
formats Winhelp (HLP files)and HTML Help (CHM files).
Help & Manual can do this and much more. In addition to publishing your projects as
standard Windows help files you can also produce websites for access on the Internet,
Adobe PDF files, printed manuals and a number of other formats 725 .
This is why we refer to Help & Manual as a help authoring and documentation tool you can
use it for creating and managing documentation of all kinds: Software documentation,
production documentation, corporate information systems accessed on the Internet or your
intranet and much more.
Help & Manual is XML-based has full support for flexible single sourcing, team authoring and
conditional output.
· Single sourcing:
Publish multiple formats from the same project at any time.
· XML-based:
Help & Manual project files are pure XML for maximum flexibility. The Standard version
saves in a compressed format with all project files packed into a single file. The
Professional version can also save as a directory of plain-text XML file.
· Team authoring:
Multiple authors can work on the same project (requires the Professional version).
· Conditional output:
Generate different versions from the same project.
· Reuse content:
Create libraries of reusable topics and texts and insert them in your projects in Link or
Copy mode. In Link mode the texts update everywhere where they are used when the
original files are changed. In the Professional version you can also reuse topics from
other projects directly.

2.2 Why Help & Manual?

Create hyperlinks by dragging and dropping. Add graphics and multimedia elements in
seconds. Make screenshots of your application with the integrated screenshot tool and
enhance them quickly with the screenshot editing program. Compile your project to any
supported output format with a couple of clicks. Work in collaboration with a team of authors
all editing the same project at the same time. Produce help and documentation faster and
more efficiently and have fun in the process!

© 1997 - 2009 by EC Software, all rights reserved

 Introduction 17

Save time
Help & Manual helps you to create better documentation quicker. Despite its power
the user interface and workflow are amazingly intuitive The time required for
producing the help for a medium-sized software project can be measured in days or
weeks instead of months.
Save money
Online help is a key feature of your software and is just as important for success as
an application that does not crash. Professional, attractive and well-organized
documentation can significantly decrease your support costs. At the same time it will
also increase user satisfaction, generating a positive snowball effect.
Concentrate on your work
Explain your software to your users, not the help authoring tool to yourself. Help &
Manual's intuitive user interface is transparent and straightforward. All the technical
details are handled in the background by the program. What you see is what you get
and what you get is what you need.
Work in a team
With Help & Manual you and your co-authors can all work on the same project at the
same time. Just put your project on server where all team members can access it
and get to work. Help & Manual makes sure that no two team members can try to
change the same topic at the same time.
All standard help formats are supported
No matter whether you need to create modern HTML Help 727 , the obsolete Winhelp
740 format, or even Visual Studio Help 738 (also known as Help 2.0) for internal Visual

Studio .NET programming documentation, Help & Manual is the right tool for the job.
It compiles all standard help formats and it creates them all from the same single
source.
In addition to this Help & Manual also generates multi-browser friendly Webhelp 730 ,
Adobe PDF 737 , printed manuals 738 , single-file eBooks 735 (both the universal ePub
format a self-contained Windows Exe format that includes its own viewer) and Word
RTF 739 – also all from the same single source file, that you only need to edit once!
Reuse content
Create libraries of reusable topics and texts and insert them in your projects in Link
or Copy mode. In Link mode the texts update everywhere where they are used when
the original files are changed. In the Professional version you can also reuse topics
from other projects directly.
Localize your documentation
Help & Manual projects can be edited and translated directly by translators working
with professional tools like SDL Trados and Across. In addition to this, tools are also
included to help translators using Help & Manual itself as their translation editor.
Supply a user manual
You can output printed manuals on paper or as a PDF file that your users can view
on screen or print themselves. Here too, Help & Manual delivers where other help

© 1997 - 2009 by EC Software, all rights reserved

 18 Help & Manual 5 - User Help

authoring tools just make promises – it creates ready-to-ship user manuals directly
from your help project, including powerful facilities for controlling all the elements that
need to be different in printed and electronic output.
Forget about maintaining different versions for your online help and printed manuals!
Writing help can be fun
Don't believe it? Give it a try with Help & Manual...

2.3 FAQ for Upgraders from HM4

The user interface of Help & Manual 5 is very different from that in version 4 and earlier. In
addition to this a number of changes have been made to the way the program works. The
list below will help upgraders to find their way around in the new version.
Even if you are an experienced Help & Manual user we recommend that you work through
the Introduction 16 and Quick Start Tutorials 41 chapters of the new help briefly before you
start working with the new version. This will help you to familiarize yourself with the new
features.

User Interface – Where is Everything?!

What's the Project Explorer?
The Project Explorer is completely new and it allows you to access the contents of your
project just as you would browse the contents of your hard disk with Windows Explorer.
See the Introduction 16 and Quick Start Tutorials 41 sections for an introduction to the
Project Explorer.

Where are my Project Properties?

All the settings that used to be located in Project Properties are now accessed in the
Configuration 652 section in the Project Explorer.

Where's the File menu?

The File menu has now been replaced by the Application Button, which opens the
Application Menu. Look for all your basic file, input and output functions here.
Remember its name, this is one of the most important controls in the new interface and
it is referred to constantly in the help.

The Quick Access Toolbar next to the Application Button navigates in your editing
history like a browser and provides direct access to the most frequently-used functions.
Configure it with the drop-down menu at its right-hand end.
See The User Interface 23 for more details.

Where is Tools > Customize?

This is now called Program Options 643 you can access it both in the Application Menu

© 1997 - 2009 by EC Software, all rights reserved

 Introduction 19

and in the View tab.

Where are the Next/Previous project navigation buttons?

These are now in the Quick Access Toolbar next to the Application Button and they are
blue instead of green.

Where are all the other menus and the editor tabs?
The menus have been replaced by tabs. You will find your editing and text formatting
tools in the Write tab. The tools that used to be located in the Insert menu are also
located there.
The editor tabs are still there, they're now below the main editor window instead of
above it.

What happened to the Index tab behind the Table of Contents?

The Index tab has been replaced by the new Index Tool 275 , which you can access in
the Project menu.

Where is the Invisible Topics section?

This section no longer exists. Instead, you have the Table of Contents section with
all your TOC entries and the Project Files section where all your topic files are stored.
The TOC entries are only links to your topic files.
You can still create topics without TOC entries. To do this you just create a new topic in
the Topic Files section instead of in the Table of Contents section.

I can't find the "Compile" dialog!

We now refer to generating your output as "publishing". The old term "compile" is a
hangover from the time when Help & Manual only produced Winhelp and HTML Help
files, which are generated with the Microsoft help compilers. Help & Manual is now a
multi-format tool for technical writers and we felt that the term "publishing" was more
appropriate. We still refer to compiling occasionally, but only when we are really talking
about the Microsoft help compilers.

Where are my Baggage Files?

The Baggage Files 485 section is now located in Project Files > Baggage Files in the
Project Explorer.

How can I undock Help & Manual windows?

The mechanisms for undocking and redocking Help & Manual components have
changed. You can now undock and redock just by double-clicking on a window title bar.
You can't undock components of the Ribbon interface or the Editor window. However,
you can change the position of the tab by dragging it. See Explorer Tips 46 for more
details.
You can also undock and redock windows by dragging them to the borders of the
Editor window – you can dock components to any side of the editor: top, bottom, left or
right.

© 1997 - 2009 by EC Software, all rights reserved

20 Help & Manual 5 - User Help

I can't assign a help window in Topic Options!

Help windows are now only relevant for HTML Help (CHM) and Winhelp (HLP). It is no
longer possible or necessary to associate a help window definition with individual
topics. Help window definitions are now only used for defining the appearance and
behavior of the HTML Help and Winhelp help viewers and for displaying topics in
external windows with hyperlinks.
To configure the help viewers you just need to edit the definition of the Main help
window in Configuration > Common Properties > Help Windows.
Displaying topics in external windows is now achieved exclusively with hyperlinks. You
define an additional help window type and then select the help window type in the
Insert Hyperlink dialog when you create the hyperlink. It is no longer possible to define
a topic that automatically opens in an external window when it is selected in the TOC
(this never made sense anyway).

I can't find the settings for the background colors of the topic and header!
These are no longer defined by the help windows except for the obsolete Winhelp
format. Background colors for all HTML-based output formats are now defined in the
HTML page template which you can find in Configuration > HTML Topic Page
Templates.

What happened to the Repair and Recover tool?

This is no longer needed in Help & Manual 5 because there is no longer any internal
database that needs to be reorganized. If you save in the uncompressed XML format
everything is saved in plain-text files and there is nothing hidden that needs to be
repaired. The single-file HMXZ format is really just a ZIP archive and if it ever needs
repair you can fix it with any of a large number of ZIP repair and recovery tools just
change the file extension to .zip to perform the repair, then change it back to .hmxz to
be able to open it in Help & Manual.

New and Different – Major Changes

New terminology: Publishing and Webhelp
What used to be referred to as "compiling" is now known generically as "publishing".
This is more accurate because not all output formats are really run through compilers.
We still sometimes talk about compiling when referring specifically to the Microsoft help
compilers.
"Browser-based Help" is now known as "Webhelp", which as established itself as the
standard term for help viewed in a normal web browser. The old term was always a bit
of a mouthful and it was annoying to have to write the entire term whenever we wanted
to discuss it.

Two save formats – single-file compressed and uncompressed XML

If you have the Professional version you can now save in two different formats: A
single-file compressed format with the extension .hmxz and an uncompressed XML
format that saves your project in a directory of uncompressed XML files with a project
file with the extension .hmxp.

© 1997 - 2009 by EC Software, all rights reserved

 Introduction 21

The Standard version of Help & Manual can only read and write the single-file
compressed format.
Uncompressed XML is required for multi-user editing.

New additional eBook Format: ePub

The ePub eBook format is an open, universal eBook standard that is rapidly being
adopted all over the world. It is supported by many software readers on all computer
platforms and a growing number of hardware devices, including the Sony Reader and
the Apple iPhone and iPod Touch.
Please check the eBook sections in Configuring Your Output and Help Formats before
getting started with ePub eBooks. You will also need to install the free Adobe Digital
Editions reader software so that you can display your ePub eBooks.

Multi-project editing / Multi-user editing

You can load and edit multiple projects in the new Project Explorer, which supports
Copy & Paste and Drag & Drop between projects. You can also display split views of
projects or parts of projects with Explore > Split Explorer in Project > Manage
Topics.
If you have the Professional version multiple users can work on the same project at the
same time. All users must be using the Professional version and the project must be
saved in the uncompressed XML (HMXP) format.

Table styles are now available

Table styles are available in Write > Styles > Edit Styles. To apply them to a table
click in the table and then select Properties in the Table tab. Table styles are
dynamic, just like text styles – updating the style automatically updates all the tables
formatted with the styles.

Embedded topics are now called snippets and can do more

Embedded topics are now called snippets and are much more powerful. In addition to
topics in the current project you can also insert snippets from external XML files and
topics in other projects (provided they are saved in uncompressed XML). You can save
both selected text and entire topics to snippet files to create libraries of reusable
content.
See Re-using content with snippets 149 for more information and instructions.

Child modules must be inserted separately for runtime merging

When you are working with modular projects you now set the merge method (runtime
or compile-time) separately for each child module. This means that you can mix
runtime and compile-time (now referred to as "publish-time") merging. In addition to
this, child modules inserted in publish-time mode can be edited directly inside the
master project.
However, this also means that child modules inserted in runtime mode are only
exported to CHM and HLP because only these formats support runtime merging. If you
want to export the same modules to other formats you must now insert them a second
time and apply suitable build conditions to ensure that they are not exported when you

© 1997 - 2009 by EC Software, all rights reserved

22 Help & Manual 5 - User Help

publish to CHM or HLP.

See Exporting runtime modules to other formats in Merge methods for CHM & HLP 451
for details on how to do this.

Help Windows are much less important

Help windows are now only relevant for HTML Help (CHM) and Winhelp (HLP). They
no longer define background colors for any format except the obsolete Winhelp.
Background colors for all other formats are defined in the HTML Page Templates 666
(these colors are also displayed in the editor).
It is no longer possible or necessary to associate a help window definition with
individual topics. Help window definitions are now only used for defining the
appearance and behavior of the HTML Help and Winhelp help viewers and for
displaying topics in external windows with hyperlinks.
To configure the help viewers you just need to edit the definition of the Main help
window in Configuration > Common Properties > Help Windows.
Displaying topics in external windows is now achieved exclusively with hyperlinks. You
define an additional help window type and then select the help window type in the
Insert Hyperlink dialog when you create the hyperlink. It is no longer possible to define
a topic that automatically opens in an external window when it is selected in the TOC
(this never made sense anyway).

External windows in CHM and HLP are handled differently

Displaying topics in external windows is now achieved exclusively with hyperlinks. You
define an additional help window type and then select the help window type in the
Insert Hyperlink dialog when you create the hyperlink. It is no longer possible to define
a topic that automatically opens in an external window when it is selected in the TOC
(this never made sense anyway).

HTML page templates are defined separately

HTML page templates are now defined separately in the Project Explorer, in
Configuration > HTML Page Templates. They can be assigned to topics when you
create new topics and in .
Background colors for topics and headers are now defined in the HTML page
templates and displayed in the Help & Manual editor. The only exception is the
obsolete Winhelp format – the background colors for Winhelp are still set in the help
window definition in Configuration > Common Properties > Help Windows.

Project Synch works in the opposite direction

In the new Project Synchronizer tool you open the updated original project and then
select Synchronize in the Project tab to perform the conversion.

Popups are now defined with the new "Topic Class" attribute
Popup topics are now defined with the Topic Class attribute in or when you are creating
the topic file. Popup topics can only be created in the Topic Files section of the Project
Explorer.

© 1997 - 2009 by EC Software, all rights reserved

 Introduction 23

You cannot create a popup topic in the Table of Contents section and you cannot
switch the Topic Class to Popup in the Table of Contents section. (The Topic Class
attribute is currently only used for popups but it may be used for other new features in
later updates.)

Bookmarks and comments are now separate

In Help & Manual 4 bookmarks and comments were the same thing. In Help & Manual
5 they are now two separate functions.
Bookmarks are set and used with the Bookmark tool in the Project tab. You can only
set one bookmark per topic and they always link to the top of the topic. They are also
managed and accessed with the Bookmark tool. Bookmarked topics are identified in
the TOC by red "pin" icons.
Comments are inserted with the Comment tool in Write > Insert Object. You can
insert multiple comments in a topic but you cannot jump to comments like bookmarks.

Create sections and use external files in the Manual Designer

The print manual designer for PDF templates has been updated with some major new
functions:
· You can now create your own sections for additional pages. Just select Insert Page
in the new Pages menu. You can also move your custom pages around in the
manual template with the tools in this menu (the standard pages are fixed).
· You can insert topics from your current project and external Help & Manual XML
topic and snippet files into your template pages with the new Snippet tool.

2.4 The User Interface

The Help & Manual window is divided into three main areas: The Ribbon Toolbar, the Project
Explorer and the Editor Window.

© 1997 - 2009 by EC Software, all rights reserved

 24 Help & Manual 5 - User Help

The Ribbon Toolbar 24

Help & Manual's functions are accessed primarily through the Ribbon Toolbar (or Ribbon
for short). It is divided into tabs that group functions according to tasks.

The Project Explorer 25

The Project Explorer provides access to all the components of your project, including the
table of contents, your topic files, other project files and all the settings and templates
associated with your project.

The Editor 29
The editor is where you do all your editing work. You will spend most of your time here
editing topics, working as you do in a normal word processor. However, this is also where
your project options and settings are displayed when you select the Configuration
sections of your project in the Project Explorer.

2.4.1 Toolbars
This type of toolbar was first introduced by Microsoft in Office 2007, where it has radically
improved the usability of all Office programs. Instead of searching for functions in menus
they are all available directly.

The Ribbon Toolbar is context-sensitive, automatically displaying the functions relevant to

what you are doing at the moment. Functions that cannot be used in the current context are
grayed out.

The Application Menu and the Quick Access Toolbar

These two controls at the top left of the Help & Manual program window provide direct
access to the most frequently used functions.

The Application Button

Clicking the Application Button displays a menu of file functions for opening, closing,
saving, importing, publishing and printing your projects.
The Quick Access Toolbar
This mini-toolbar is for direct access to your most frequently-used functions.

© 1997 - 2009 by EC Software, all rights reserved

 Introduction 25

The Ribbon Toolbar

The Ribbon Toolbar or "Ribbon" for short is the main component of the toolbar. It is
divided into tabs where the tools used for different tasks and activities are grouped. The
tabs can be selected manually and they are also activated automatically depending on
what you are doing in the program.

Most of the tools are available directly in the "groups" within each tab for example
above you can see the Clipboard, Editing, Styles and Font groups. Some groups and
tools also provide access to dialogs with additional options.

Dialog icons and menu icons

Some groups in the Ribbon have little icons in the

bottom right corner. Clicking on these icons displays a
full dialog of options for that function group.

Other controls in the ribbon have menu icons that

display a normal menu of options when you click on
them. These menu options open dialogs for
example for editing styles

2.4.2 The Project Explorer

The Project Explorer on the left below the Ribbon provides direct access to all the
components of your projects.

© 1997 - 2009 by EC Software, all rights reserved

26 Help & Manual 5 - User Help

You can load multiple projects into the Explorer and work on them all at the same time for
example to copy and paste between projects and to work on the components of modular
help systems.
Just select an item in the Project Explorer to view it for editing in the Editor.

Productivity Tip
Select Split Explorer in the Project tab to
edit parts of your project in separate
Explorer windows. This also makes
copying and pasting in the Explorer easier.

The Welcome Section

The Welcome section of the Project Explorer displays general information, recently-
opened projects, tips for finding information in the help, live information on the latest
program updates and other details.

© 1997 - 2009 by EC Software, all rights reserved

 Introduction 27

The Table of Contents

The Table of Contents or "TOC" is used to organize the topics in your project in a
hierarchical structure. Every topic that has a TOC entry here will also have a
corresponding entry in the TOC of your published output.

You can create new topics by adding new entries to the

TOC, which automatically creates a matching topic file
for the TOC entry in the Project Files > Topic Files
section (see below).
You can change the structure of your project by moving
entries around in the TOC. This is quick and very easy.
You just drag TOC entries with the mouse or manipulate
them with the tools in Project > Manage Topics.
Each topic file has its own individual settings, which are
accessed in the tab in the editor.

© 1997 - 2009 by EC Software, all rights reserved

28 Help & Manual 5 - User Help

The Project Files Section

The Project Files section is used for managing and

viewing the files in your project. It is divided into two
groups, Topic Files and Baggage Files. The Topic Files
section contains all your topic files, both those that are
included in the TOC and those that are not (known as
"invisible files" in Help & Manual 4 and earlier).
Each topic file has its own individual settings, which are
accessed in the tab in the editor. This tab can also be
accessed in the Table of Contents section.

Topic Files
This section lists all the topic files in your project, including topic files that do not have
entries in the TOC for example topics containing the text for popup windows, for display
in external windows or for use as embedded topics.
To create a topic without a TOC entry you create it in the Topic Files section just click in
the Topic Files section where you want to insert the topic and create a new topic 56 . You
can always change the position of the topic later.
Baggage Files
You do not need to concern yourself with this section when you are just getting started
with Help & Manual. It is used for storing additional files you want to associate with your
project, such as additional graphics and script files that you want to reference in the code
of your HTML templates.
All the files included in the Baggage Files section are automatically exported to the
relevant output formats when you publish your project. See Using Baggage Files 485 for
more information.

© 1997 - 2009 by EC Software, all rights reserved

 Introduction 29

The Configuration Section

This section contains all your project's configuration

settings. This includes your project title, copyright notice,
your language settings for help in international
languages, special settings and editable layout templates
for your output formats, "skins" for changing the
appearance and formatting of your entire project, user-
defined variables and so on.
Program configuration settings
Note that the Configuration section in the Project Explorer
only contains settings for your individual projects (each
project has its own configuration settings). The general
configuration settings for Help & Manual are accessed in
View > Program Options in the Ribbon.

2.4.3 The Editor

This is the large area on the right below the Ribbon. When you select items in the Project
Explorer you edit their contents in the Editor.

You will spend most of your time editing the content of your topics here. The editor pane is
also used to display end edit project properties when you select them in the Configuration
section of the Project Explorer.

© 1997 - 2009 by EC Software, all rights reserved

30 Help & Manual 5 - User Help

The Page Editor tab

This is the main editor where you will spend most of your time. It shows a WYSIWYG
(what you see is what you get) view of your topic pages. To load a topic into the page
editor just select it in the Project Explorer. Then you can start editing as you would in a
normal text editor.

You can select topics both in the Table of Contents section and the Topic Files section of
the Project Explorer. The Topic Files section lists all the topic files in your project, the
Table of Contents section only shows those topic files that have entries in the Table of
Contents (TOC).

The Topic Options tab

This tab displays the editable settings of the current topic. Among other things you can
enter index keywords for the topic here. These keywords will then be included in the
index when you publish your project.

Apart from adding index keywords it is better not to change any of the settings displayed
here until you become more familiar with working with Help & Manual.

© 1997 - 2009 by EC Software, all rights reserved

 Introduction 31

The XML Source tab

This tab is for experts and is only displayed in the Professional version of Help & Manual.
It displays the XML source code of your topics and allows you to edit it.

If you don' t understand what you see here don't worry about it you don't need to know
anything about XML to use Help & Manual efficiently.
For details about XML in Help & Manual see XML and XML editing 493 .

2.4.4 Options & Keyboard Shortcuts

Help & Manual is extensively customizable. Most customization options are available in the
View section in the ribbon. Almost all functions can be controlled with keyboard shortcuts,
which you can configure with Customize in the View section of the ribbon. In addition to
this you can also undock the Project Explorer by double-clicking on it and add items to the
Quick Access Toolbar by right-clicking on them.

Customizing the user interface

· Select the View tab in the Ribbon to access the options for changing Help & Manual's
appearance and behavior.

· Select the drop-down gallery on the right of the Quick Access Toolbar to customize the
Quick Access Toolbar.
· Right-click on any item in the Ribbon to add it to the Quick Access Toolbar.

© 1997 - 2009 by EC Software, all rights reserved

32 Help & Manual 5 - User Help

Program customization options

· Select View > Program Options in the Ribbon to access the detailed program
configuration 643 dialog.

· You can configure the appearance of the program, the layout and contents of the
Ribbon Toolbar, the behavior of the editor, automatic update checking and many other
things.

Keyboard shortcuts and accelerators

Keyboard shortcuts:
You can assign keyboard shortcuts to most functions in Help & Manual, many functions
are already configured with keyboard shortcuts.
· Select View > Program Options in the Ribbon to view and edit keyboard shortcuts.

© 1997 - 2009 by EC Software, all rights reserved

 Introduction 33

· You can also assign keyboard shortcuts to styles. Select Write > Styles > Edit
Styles in the Ribbon to access the styles editing dialog.

Accelerator keys:
The Ribbon interface has an advanced accelerator keys interface which can also be used
by authors with vision handicaps.
1. Press the ALT key once briefly (you may have to press it twice if you have just clicked
on a control in the Ribbon). Small icons showing accelerator letters and codes will be
displayed on the Ribbon controls.

2. Type the accelerator letters on the keyboard to perform the corresponding actions. If
multiple letters are displayed type them one after another these are not key
combinations!
If Ribbon menus are displayed they will show more accelerator keys.

Undocking the Project Explorer

· Double-click on the Project Explorer title bar or drag it out of the program window to
display it as a separate window.

© 1997 - 2009 by EC Software, all rights reserved

34 Help & Manual 5 - User Help

· To re-dock the Project Explorer double-click on its title bar again.

Pinning the Project Explorer to the margin

· Click on the "pin" tool in the Explorer title bar to "pin" the Explorer to the left margin of
the window. The Explorer will then be hidden while you are editing and will only be
displayed when you mouseover the Explorer title in the left margin.

· To "unpin" just mouseover the Explorer title to display it and then click on the pin tool in
the title bar again.

Splitting the Project Explorer

You can "split" the Project Explorer to display projects or parts of projects in a separate
Explorer pane. This makes copying and pasting topic files and TOC branches easier,
both within projects and between different projects.
1. In the Project Explorer click on the project or the section of the TOC you want to split.

© 1997 - 2009 by EC Software, all rights reserved

 Introduction 35

2. Select Explore > Split Explorer in Project > Manage Topics.

Undocking, docking and pinning Explorer panes

· Click in the title bar and drag the new Explorer pane out to the left to display it in a
separate window.
· Drag it to the right onto the main Explorer pane to display it in a tab.
· Double-clicking on an Explorer pane title bar also docks and undocks.
· You can also "pin" individual Explorer panes to the left margin by clicking on the pin tool
in the pane's title bar (see above).

Repositioning the Topic Options tab:

You can't undock the tab but you can change its position and display it to the left or right
of the main editor pane. To do this just drag its tab:
Repositioning to the left and right:
Drag the tab to the left or right to change its position in relation to the other tabs. Release
the mouse button when the shaded outline shows the new position:

© 1997 - 2009 by EC Software, all rights reserved

36 Help & Manual 5 - User Help

Displaying next to the main Editor pane:

Drag the tab to the left or right margins of the Editor pane to display it next to the Editor.
To dock on the right of the editor release the mouse button when the shaded outline
shows the new position at the side and the mouse pointer is over the right margin (make
sure that the mouse pointer is over the margin when you release – if you move it too far it
won't work:

You can return the tab to its "tabbed" position by dragging its title bar back down onto the
other tabs:

© 1997 - 2009 by EC Software, all rights reserved

 Introduction 37

Pinning the window:

You can also "pin" the window to the margin so that it hides itself automatically and then
rolls out over the Editor when you mouseover the pinned tab:

This works best when you pin to the left side of the Editor. If you pin it on the right it will
roll out vertically rather than horizontally.

See also:
Using the Project Explorer 41

2.5 Getting help

There are a number of different sources of help in Help & Manual. In addition to this help file
you can also access tutorials, the online user forum and EC Software support.
To get started, your main source of information should be this help file. We have designed it
to provide all the information you will need for using and learning Help & Manual.
Before contacting support, please make sure that you really can't find the information you
need here or on the user forum. Thanks!

© 1997 - 2009 by EC Software, all rights reserved

38 Help & Manual 5 - User Help

Displaying the help

· The quickest way to display the help is to press F1. If context-sensitive help is available
it will be displayed automatically.
· Most dialogs have a Help button that displays relevant information.

· Select the Help tab in the Ribbon for additional help options.

Using the user forum

· The online Help & Manual user forum is a wonderful resource that contains a huge
amount of material. Register today (it's completely free) and get support from the EC
Software team and thousands of other experienced Help & Manual users.
· The forum is located at http://helpman.it-authoring.com/
· The forum portal page also has a list of links to other useful sites and user groups
where you can find more information about help authoring.

Contacting EC Software support

· Direct email support is available from the EC Software team at support@ec-software.
com. You can send a mail to this address automatically by clicking on the Customer
Support tool in the Help tab of the Ribbon.

Tutorials
· Check the Help tab in the Ribbon for links to a number of useful tutorials.

· You can also find a collection of tutorial projects in the Examples folder in the My
Documents\My HelpAndManual Projects directory.
· A selection of tutorials for programmers showing you how to integrate your help with
your application is available here on the EC Software website:

© 1997 - 2009 by EC Software, all rights reserved

 Introduction 39

http://www.ec-software.com/tutorial.htm

Getting a printed user manual

You can download a formatted PDF version of the entire documentation designed for
printing from our download page at:
http://www.ec-software.com/download.htm

2.6 How to buy Help & Manual

You can buy Help & Manual directly online worldwide with all major credit cards. As soon as
your transaction is completed you will be able to download and install the program and start
working right away.

Direct order link and EC Software homepage:

Order link:
http://www.ec-software.com/order.html
EC Software homepage:
http://www.ec-software.com

© 1997 - 2009 by EC Software, all rights reserved

Part

III
 Quick Start Tutorials 41

3 Quick Start Tutorials

The tutorials in this section provide a quick introduction to using Help & Manual. They are
intentionally kept brief so that you can actually start using the program as quickly as
possible. The objective is not to teach you every single detail but to familiarize you with the
basic principles and the way the program works.
For full details on the procedures described in the tutorials please refer to the Basic Working
Procedures 83 section.
Once you get used to working in the program you will also find plenty of more useful help
and support in the More Advanced Procedures 335 section.

3.1 Using the Project Explorer

The Project Explorer is the control center for your Help & Manual projects. It displays the
structure of your project with the Table of Contents (TOC), all your topic files (including
those not in the TOC), additional files associated with your project (Baggage Files) and all
the configuration settings saved with your project (Configuration).
You can open multiple projects at the same time each project has its own full entry in the
Project Explorer. Working in the Project Explorer you can copy and paste single and multiple
topics and chapters both within your project and between different projects. To make this
easier you can split the Explorer to display projects and sections of projects in their own
"panes", and you can undock the individual panes into separate windows.

3.1.1 Project Explorer Sections

When you load a project into the Project Explorer its contents are displayed in three
sections: Table of Contents, Project Files and Configuration. The Table of Contents or
"TOC" is a hierarchical tree of entries that define the structure of your project, organizing
your topics into chapters and sub-chapters. Most TOC entries have direct links to topic files
in the Project Files section. The Project Files section provides access to the actual files that
make up your project. The Configuration section stores all the settings associated with your
project.

Key Information
Topic entries in the TOC are actually links
pointing to matching topic files in the Topic
Files section. You can create topic files
without TOC entries by creating a new
topic file directly in Topic Files instead of in
the TOC.

© 1997 - 2009 by EC Software, all rights reserved

42 Help & Manual 5 - User Help

The Table of Contents section

This is the "structure" of your topic. It consists of TOC

"entries", most which are linked to topic files in the
Project Files section. Other TOC entries are "empty
chapters" without any content of their own, others link to
web pages or to other Help & Manual projects that you
want to merge into the current project.
The TOC section does not actually contain any topic
files. It is really just a list of TOC entries with links to the
actual topic files, which are stored in the Project Files/
Topic Files section of the Project Explorer.

You can create new topic files 108 by adding entries to the TOC. Doing this creates a TOC
entry and a topic file, and links the entry to the topic file. You can also create topic files
directly in the Topic Files section then the files do not have TOC entries.
You can change the structure of your TOC by moving the entries around in the TOC tree,
either with the mouse or with the blue arrow tools in Project > Manage Topics. Doing
this just moves around the entries in the TOC the topic files and other items to which
the TOC entries link remain unchanged.

The Project Files section

This section lists all the topic files in your project and
"Baggage Files", which are additional files associated with
your project.
The Topic Files subsection lists all your topic files,
including those that do not have entries in the TOC. For
example, these include popup topics and topics that are
only displayed when the user clicks on a hyperlink.
The Baggage Files subsection is the place where you
store small files that you want to export together with your
project when you publish it. These can include graphics
you want to use in your own HTML templates 427 ,
JavaScript files containing functions you want to use in
your HTML-based publishing formats and so on. If you are
just getting started with Help & Manual you don't need to
worry about the baggage files at the moment.

© 1997 - 2009 by EC Software, all rights reserved

 Quick Start Tutorials 43

The Configuration section

This section contains all your project's configuration

settings. This includes your project title, copyright notice,
your language settings for help in international
languages, special settings and editable layout templates
for your output formats, "skins" for changing the
appearance and formatting of your entire project, user-
defined variables and so on.
Program configuration settings
Note that the Configuration section in the Project Explorer
only contains settings for your individual projects (each
project has its own configuration settings). The general
configuration settings for Help & Manual are accessed in
View > Program Options in the Ribbon.

3.1.2 Navigating in the Project Explorer

If you are familiar with the Windows Explorer then you already have the basic skills you need
to find your way around the Project Explorer, they both function in pretty much the same
way.

The Project Explorer displays the contents of your projects in the same way as files in the
Windows Explorer file manager. Selecting topic files in the Table of Contents (TOC) or Topic
Files sections displays their contents in the Editor.
The Project Explorer display is exactly the same for both the compressed .hmxz format and
the uncompressed .hmxp format. The only difference between the two formats is the way

© 1997 - 2009 by EC Software, all rights reserved

44 Help & Manual 5 - User Help

they are saved – both contain exactly the same files and folders.

Loading projects in the Project Explorer

Loading projects:

To load a project click on the Application Button, select Open. and select a project to load
(or create a new project 54 ).
Loading multiple projects:

· You can load multiple projects in the Project Explorer.

· Each project has a Table of Contents, Project Files and Configuration section. When
you are getting started you only need to use the Table of Contents section.
· Select entries in the Table of Contents section to display and edit topics.

© 1997 - 2009 by EC Software, all rights reserved

 Quick Start Tutorials 45

Expanding and collapsing projects and sections

· The and buttons expand and collapse projects and the main sections of each
project.
· Inside the main sections the +/- nodes expand and collapse the subsections, just as
they do in the Windows Explorer.

Editing in the Project Explorer

· To edit a topic or topic file just click on an item in the Table of Contents or Project Files
sections of the Explorer. Topic contents are displayed in the editor and can be edited
directly. Work as you would in a word processor.
· To edit your project properties just select items in the Configuration section the
dialogs with the settings are displayed in the editor pane.

© 1997 - 2009 by EC Software, all rights reserved

 46 Help & Manual 5 - User Help

Copying and pasting in the Project Explorer

You can move, copy and paste topics in the Explorer. Drag with the mouse, right-click to
display editing options or use the Clipboard functions in the Project tab.
· Drag a topic between other topics to insert it before or after the other topics.
· Drag a topic onto another topic to make it a child (subtopic) of the other topic.

3.1.3 Tips & Tricks in the Project Explorer

You can edit multiple projects at the same time in the Project Explorer. In addition to this you
can also split off copies of parts of projects into separate Explorer panes to make editing,
copying and pasting easier. The Explorer has a number of features that make these
functions more useful.

Changing the Explorer position

If you don't like the Project Explorer position on the left of the editor pane you can change
it. Just click in the title bar of the Explorer and drag it onto one of the four borders of the
editor pane. You can position the Explorer above, below, on the left or on the right of the
editor pane.

© 1997 - 2009 by EC Software, all rights reserved

 Quick Start Tutorials 47

You can position the Project Explorer to the left, right, above or below the Editor Pane!

Undocking the Project Explorer

You can "undock" the entire Project Explorer to display it in a separate window. For
example, if you have a dual monitor system you may want to display the Explorer in a
separate monitor.

Undocking the Explorer:

· Double-click on the Explorer title bar. You can then drag the new window and resize it
as you like.
OR
· Click in the Explorer title bar and drag it out of the Help & Manual window.
Redocking the Explorer:
· Double-click on the title bar of the undocked Explorer window.

© 1997 - 2009 by EC Software, all rights reserved

48 Help & Manual 5 - User Help

OR
· Drag the Explorer title bar onto any of the margins of the editor pane. You can dock the
Explorer above, below, on the left or on the right of the editor pane.

Pinning the Project Explorer to the margin (auto-hide function)

Clicking on the "pin" tool in the Project Explorer title bar "pins" the Explorer into the left
margin of the Help & Manual window. The Explorer then collapses into the left margin,
showing only its title in a vertical tab. This can give you more room for editing on smaller
monitors.

· To display the pinned Explorer just move the mouse pointer over the vertical tab in the
left margin.
· To unpin the Explorer first display it, then click on the pin tool in its title bar.

Splitting the Project Explorer

You can "split" the Project Explorer to display individual projects or parts of projects in
separate panes. You can then undock these split panes or reposition them to make
editing, copying and pasting easier.

1. In the Project Explorer click on the section of your project you want to view separately,

© 1997 - 2009 by EC Software, all rights reserved

 Quick Start Tutorials 49

or on the title of a project (if you have more than one project open).
2. Select Explore > Split Explorer in Project > Manage Topics .

Productivity Tip
You can split any section of the Project
Explorer into a separate pane including
the Configuration sections and the Project
Files sections.

Undocking split Explorer panes

You can undock and redock split Explorer panes just like the main Explorer pane (see
above). Doing this can make it easier to copy and paste topics between different sections
of your project or between different projects.
"Tabbing" Explorer panes
· You can also display Explorer panes in tabs. To do this click in the pane's title bar and
drag it onto the main Explorer pane until you see the outline of a "tab" at the bottom of
the pane.
· To "untab" an Explorer pane click in the tab and drag to the left. Dragging onto the left
border of the Help & Manual window displays the tab next to the main Project Explorer
pane. Dragging out of the main window undocks the pane completely.
· Double-clicking on the tab of a tabbed pane also undocks the pane.
"Pinning" Explorer panes
You can also pin split Explorer panes to the left margin of the Help & Manual window in
the same way as the main Explorer pane. Just click on the pin tool in the title bar of the
pane (see above). You can then display the individual Explorer panes by moving the
mouse pointer over their vertical tabs in the left margin.

Repositioning the Topic Options tab:

You can't undock the tab but you can change its position and display it to the left or right
of the main editor pane. To do this just drag its tab:
Repositioning to the left and right:
Drag the tab to the left or right to change its position in relation to the other tabs. Release
the mouse button when the shaded outline shows the new position:

© 1997 - 2009 by EC Software, all rights reserved

50 Help & Manual 5 - User Help

Displaying next to the main Editor pane:

Drag the tab to the left or right margins of the Editor pane to display it next to the Editor.
To dock on the right of the editor release the mouse button when the shaded outline
shows the new position at the side and the mouse pointer is over the right margin (make
sure that the mouse pointer is over the margin when you release – if you move it too far it
won't work:

You can return the tab to its "tabbed" position by dragging its title bar back down onto the
other tabs:

© 1997 - 2009 by EC Software, all rights reserved

 Quick Start Tutorials 51

Pinning the window:

You can also "pin" the window to the margin so that it hides itself automatically and then
rolls out over the Editor when you mouseover the pinned tab:

This works best when you pin to the left side of the Editor. If you pin it on the right it will
roll out vertically rather than horizontally.

3.2 Converting old projects

Help & Manual automatically converts old project files from previous versions (H&M 3 and
H&M 4) when you open them. Alternatively, you can also use the stand-alone converter
program to convert old projects manually.
Help & Manual 4 projects are converted 1:1 and do not require any post-processing after
conversion. Older Help & Manual 3 projects did not have the styles and other features
introduced in the modern versions of the program and may require some reformatting after
importing.

© 1997 - 2009 by EC Software, all rights reserved

52 Help & Manual 5 - User Help

Converting old projects automatically

You can convert both Help & Manual 4 (.hmx) and Help & Manual 3 (.hm3) projects. In
addition to this you can also import data from a number of other formats using this option.
1. Click on the Application Button and select Open, then select the format of the project
you want to open in the Files of Type: field (or the drop-down menu next to the File
Name: field in Windows Vista).
2. Select the file you want to convert and click on Open to display the following dialog:

3. Select Convert and open to convert the old project.The new project file will be saved
in the same directory as the old project you are converting.
This method automatically converts the old project into a single compressed file with the
extension .hmxz containing all the project components except the graphics files. If you
are using the Standard version of Help & Manual this is the only project format you can
use.

Invisible topics from old Help & Manual projects

If your old HMX or HM3 project contains "invisible topics" they will be moved to a sub-
folder called Topics\Invisible in the Topic Files section in the Project Explorer.

© 1997 - 2009 by EC Software, all rights reserved

 Quick Start Tutorials 53

Automatic Converter:

When you use the automatic converter a folder called

(Former Invisible Topics) will also be created at the
bottom of the converted project's Table of Contents
(TOC) section.
These TOC entries are linked to the topic files of the
former invisible topics but they will still not be included in
your published output because their include options are
automatically set to "None".

You can delete the (Former

Invisible Topics) folder by
selecting it and pressing
DELETE. Before confirming,
deselect the option Also delete
referred topic files to keep the
actual topic files.

External Converter:
When you use the external converter program you can decide what you want to do with
your old invisible topics:

Add invisible topics to TOC creates the (Former Invisible Topics) folder described
above.
Keep organization structure creates sub-folders in the Topic Files section to match
your folder structure in your old project. You can create a maximum of 10 levels but the
converter will not create more levels than the original project contained.

© 1997 - 2009 by EC Software, all rights reserved

 54 Help & Manual 5 - User Help

Converting old projects with the external converter

You need to use the external converter to convert old projects to the uncompressed XML
format (Professional version only) and to select additional conversion options for Help &
Manual 3 projects.
Follow the instructions above and select Start external converter. For full details see
The Project Converter 550 .

Important: Images from old projects are not copied or moved

When you convert old projects the images they use are left in their original locations. The
images are accessed by adding links to the old locations to the Project Search Path in
the converted project. If you want to store the images with your new project you must
manually copy them to a new folder in your new project folder and then update the
Project Search Path of your new project so that it only references the new folder(s)
location.
See Managing your graphics 249 for more details on these subjects.

See also:
Choosing your save mode 85
The Project Converter 550

3.3 Creating projects

You can create a new Help & Manual project from scratch or import documentation from
another source and convert it into a new Help & Manual project. In both cases an interactive
on-screen wizard will guide you through the process.

Creating an empty new project

1. Click on the Application Button (the large button in the top left corner of the program)
and select New.
2. Select the option Create a new help project and then follow the instructions displayed
in the interactive wizard.
3. If you have Help & Manual Professional you can choose between two save formats:
· Uncompressed XML:
Saves your project as a collection of XML files. Must be saved in an empty folder.
This format is required for multi-user editing. The main project file has the extension
.hmxp.
· Compressed single-file format:

© 1997 - 2009 by EC Software, all rights reserved

 Quick Start Tutorials 55

Saves the same project files in a single compressed file with the extension .hmxz.
This is the only format supported by the Help & Manual Standard.

Creating a new project from imported data

1. Click on the Application Button and select New.

2. Select the option Import existing documentation from....
3. Select the documentation format, then follow the instructions displayed in the
interactive wizard.
You can also import some formats directly by clicking on the Application Button and
selecting Open. Then select the format type and open the file additional instructions
may be displayed.
See Importing data 55 for information on the different import formats.

3.4 Importing data

You can import existing documentation into your Help & Manual projects from a wide variety
of different formats. When you import data you can either create a new project or import the
data into an existing project. The procedure in both cases is almost identical.
When you import data an interactive wizard guides you through each step of the process.
However, each data format needs to be handled a little differently. You will find important
information on each format further below.

Importing data to new projects

1. Click on the Application Button and select New.

2. Select the option Import existing documentation from....
3. Select the documentation format, then follow the instructions displayed in the
interactive wizard.

© 1997 - 2009 by EC Software, all rights reserved

 56 Help & Manual 5 - User Help

Importing data into existing projects

1. Select the Table of Contents section in the Project Explorer and choose the position
in your project where you want to insert the imported data. The data will be inserted
after the selected topic.

2. Click on the Application Button and select Import.

3. Select the documentation format, then follow the instructions displayed in the
interactive wizard.
See Settings for importing data 105 for details on individual settings that you need to
consider for each import format.

See also:
Settings for importing data 105

3.5 Adding topics

The New Project wizard creates some topics for you automatically but normally you will
create topics yourself. Creating a topic in Help & Manual is very much like creating a new
document in a word processor.
You will normally create new topics in the Table of Contents (TOC), which automatically
creates both the topic file and an entry for the topic in the TOC, where you can move it
around 63 as you like. And you can also add text 58 and other content 67 to it, of course.
You can also create new topics in the Project Files/Topic Files section of the Project
Explorer, but when you do this the topics will not have TOC entries they will be "invisible".
Topics created in Topic Files can only be displayed with hyperlinks, they are used for popup
topics and for information you don't want to include in the TOC directly.

How to create a new topic

You can create topics in the project's Table of Contents (TOC) and the Topic Files

© 1997 - 2009 by EC Software, all rights reserved

 Quick Start Tutorials 57

sections in the Project Explorer. You will normally create topics in the TOC so that they
are included in the table of contents of your published project.
1. In the Project Explorer click in the position in the TOC where you want to insert a new
topic.

2. Select Add Topic in the Project tab of the Ribbon.

3. Choose where you want to insert your topic relative to the selected topic:

Insert Child inserts the new topic as a sub-topic of the selected topic, turning the
parent topic into a chapter (if it is not already a chapter).
4. This displays the Insert New Topic or Chapter dialog:

© 1997 - 2009 by EC Software, all rights reserved

 58 Help & Manual 5 - User Help

Select the Topic/Chapter option. Enter a heading (title) for the new topic. The Topic ID
is created automatically from the heading. You can edit this if you like. Leave the
HTML Template, Topic Class, Create in: and Topic Template: settings as they are.
5. After entering your settings click on OK to create the new topic and insert it in the
TOC.

6. Once you have created a topic you can edit it 58 and move it around 63 in the TOC.

See also:
Creating and Editing Topics 108

3.6 Editing topics

Entering and editing text in your topics in Help & Manual is very similar to working in a word
processor. To edit a topic select the topic in the Table of Contents or Project Files section of
the Project Explorer, then click inside the editing window to start editing.

© 1997 - 2009 by EC Software, all rights reserved

 Quick Start Tutorials 59

The Write tab in the Ribbon provides direct access to all the tools you need while you are
editing. The only group inside this section that may be unfamiliar to word processor users is
the Insert group, which contains special tools used in help authoring projects.

Editing overview
· You can type and enter text and copy and paste from other programs just as you would
in a normal word processor.
· Use the tools in the Font and Paragraph groups in the Write tab to format text. Select
text to apply new formatting, select a formatting option (Bold, Italic etc.) and type to
change formatting from the current cursor position.
· The Font and Paragraph groups have additional dialog modes that you can display by
clicking on the little icons in their bottom right corners.

· Hover the mouse pointer over the tools in the Write tab of the Ribbon for descriptions.
· You can save a lot of time and work by using styles. See the Using styles 61 tutorial.

Spell checking
Live spell checking:
1. Select Write > Spelling > Configure Spell Checker and select the dictionary for
the language you want to use in the Main Dictionaries section at the bottom of the
dialog. Select Download dictionaries to get additional dictionaries.
2. Activate the Check spelling as you type option. Misspelled words will then be
underlined in red as you type.
Manual spell checking:

· Select the top half of the Spelling tool in the Project tab to check the current topic or
text entry field or window. If text is selected only the selected text will be checked.
· Select the bottom half of the tool for the spell-check menu.

© 1997 - 2009 by EC Software, all rights reserved

60 Help & Manual 5 - User Help

Spell checking is supported almost everywhere in Help & Manual where you can enter
text. Just right-click to display the context menu or click on the upper half of the Spelling
tool in the Project tab to access.

Copying and pasting

· You can copy and paste text just as you would in a normal word processor. This works
within topics, between topics and between projects.
· You can open multiple projects and copy and paste between them, or you can open
Help & Manual a second time and copy and paste between the two windows.
· You can copy and paste formatted text from and to other programs, including Office
programs like MS Word and MS Excel.
Copying images from Word:
When you copy text with images from MS Word always right-click on the image
afterwards and convert the image into an external file. Otherwise the image will be
embedded in your topic file and will take up much too much space. If you have many
embedded images you may experience slow editing performance.

Split Project Explorer view for sections and projects

· You can split off individual chapters and topics into an individual Project Explorer
window for easier editing. Just select the project, chapter or topic you want to edit and
then select Explore > Split Explorer in Project > Manage Topics.
· The split view is just another "access point" to your topics and chapters. Closing the
new view window does not delete anything, it simply closes the new view window.

Preview mode for screen/print styles and font sizes

You can switch the editor display to show the styles definitions for screen output
(electronic help files) and print output (PDF, RTF and printed manuals). You can also
switch the editor's basic font sizes to emulate Windows' "large fonts" and "small fonts"
settings to check how your help will look on users' systems with these settings.
Note that different styles will only be displayed if you have actually defined different style
settings for screen and print output!
Display buttons in the status bar:

See Help and print styles 175 for more information on using different style sets for different

© 1997 - 2009 by EC Software, all rights reserved

 Quick Start Tutorials 61

output formats.

See also:
Use Styles 61 (Quick Start Tutorial)
Creating and Editing Topics 108
Text Formatting and Styles 155

3.7 Using styles

You can format all your text manually if you like but it's much more efficient to use Help &
Manual's dynamic styles. Styles are formatting definitions that you can apply to text and
paragraphs with a single click. The style definition is then linked to the formatted text and if
you change the definition everything formatted with the style is updated immediately.

How to apply a style

To apply a style to a paragraph just click anywhere in the paragraph and select the style
in the Style Selector in the Write tab:

If you included a keyboard shortcut in the style definition 164 you can use the keyboard
shortcut instead of the Style Selector.
If you select text before applying a style the style's font attributes will only be applied to
the selected text.

How to modify a style

1. Click in a paragraph in your project formatted with a style you want to change, then
select Styles > Edit Styles in the Write tab.
2. This displays the Edit Styles dialog. The style at the current cursor position is selected
automatically.

© 1997 - 2009 by EC Software, all rights reserved

62 Help & Manual 5 - User Help

3. Click on the Font Settings and Paragraph Settings buttons and adjust the font and
paragraph settings. If you want you can also apply Borders and Background settings.
4. Click on OK to close the dialog. The results are immediately visible in the editor and
will be applied to all the text in your entire project formatted with the edited style.
The same settings will also be applied to text formatted with styles based on the edited
style, for all attributes that have not been explicitly changed in the other styles.

How to change the font and paragraph settings for your entire project
There are a number of predefined standard styles. The most important one is Normal,
which is the default style for all normal body text paragraphs in your project. Most other
styles are based on Normal. This means that changing the settings of Normal will
automatically change all text in your entire project formatted with Normal or with any style
based on Normal.
Changing the definition of Normal changes the body text style for your entire project in a
couple of seconds.
The same settings will also be applied to text formatted with styles based on Normal, for
all attributes that have not been explicitly changed in the other styles.

How to define a new style

In addition to changing the Normal style you will also want to define your own styles so
that you can apply complex formatting quickly and change it whenever you want.
1. Select Styles > Edit Styles in the Write tab to display the Edit Styles dialog:

© 1997 - 2009 by EC Software, all rights reserved

 Quick Start Tutorials 63

2. Select Add Style to define a new style, then edit its default name in the Style Name:
field. You can change style names whenever you like!
3. Select Font Settings and Paragraph Settings to edit the settings for the style.
4. If you want you can also assign a shortcut key so that you can apply the style quickly.
5. Then click on OK to close the dialog.

Using table styles

You can define table styles in the Edit Styles dialog (see above) in the same way as you
define styles for paragraphs and text.
Applying a style to a table:
Click inside the table, select Properties in the Table tab and then select the style in the
Table Style: field.
Creating a table with a style:
Create a table with Table > Insert Table in the Write or Table tab and select the style in
the Table Style: field when entering the table configuration settings. Any additional
settings you enter in the Insert Table dialog will override the style settings for that table.

See also:
Text Formatting and Styles 155
Dynamic Styles 711 (Reference)

3.8 Organizing the TOC

One of the main differences between Help & Manual and a word processor is that in a word
processor you work in a single document. In contrast to this, each topic in a Help & Manual
project is a separate file that is like a word processor document. However, Help & Manual

© 1997 - 2009 by EC Software, all rights reserved

64 Help & Manual 5 - User Help

manages all these files as though they were a single document for example, you can
perform search and replace operations globally in all your topic files.
You can move topics around in the Table of Contents (TOC) section of the Project Explorer
with the keyboard and the mouse and you can also change the "level" topics in the TOC tree
hierarchy.

Table of Contents (TOC) Overview

Moving topics around in the TOC

· Use the arrow tools in Project > Manage Topics to move selected topics around in
the TOC:

· Drag a topic onto another topic to make it the child (sub-topic) of the target topic:

© 1997 - 2009 by EC Software, all rights reserved

 Quick Start Tutorials 65

· Drag a topic between two topics to insert it between them:

Using cut and paste in the TOC

You can also use normal cut and paste methods to move topics around in the TOC and
to copy and move topics between projects. There are two ways to do this:
· Open the second project in the current instance of Help & Manual. The second project
will be displayed as an additional item in the Project Explorer and you can then cut and
paste between the two projects in the Project Explorer.
· Open Help & Manual a second time, open the second project there and then cut and
paste between the projects.

Managing files in the Topic Files section

All the topic files in your TOC are also available in the Project Files > Topic Files
section of the Project Explorer. These are not second copies of your topic files, they are
the same files. The TOC shows the Table of Contents structure with links to the topic

© 1997 - 2009 by EC Software, all rights reserved

66 Help & Manual 5 - User Help

files, the Topic Files section only shows you the files.
In addition to your TOC topics, the Topic Files section can also contain topic files not
included in the TOC, for example topic files for popups and topics that are only accessible
by clicking on hyperlinks.
Folder display and file display in Topic Files:

The folders in the Project Files section are just like folders in Windows Explorer. You can
delete topic files and you can shift them from one folder to another if you have created
multiple folders. However, there is no "table of contents" structure here because you are
really just looking at disk folders containing lists of files.

© 1997 - 2009 by EC Software, all rights reserved

 Quick Start Tutorials 67

See also:
Managing Topics in the TOC 199

3.9 Inserting graphics

In addition to text you will also want to add graphics to illustrate your topics. This tutorial
shows you how to add ordinary graphic images to your topics from files and by cut and
paste.
You can also use Help & Manual's built-in screen capture utility 244 to capture images of
programs on your screen and insert them in your topics. In addition to graphics you can also
insert video files 269 and OLE objects 494 from other programs.
See Graphics formats and file size 753 for details on choosing graphics formats.

Inserting a graphic from a file

1. Click in the position where you want to insert a graphic, then select Image in Write >
Insert:

2. This displays the Open Image dialog. Select the image you want to insert, then click
on Open to insert the image in your document.

© 1997 - 2009 by EC Software, all rights reserved

68 Help & Manual 5 - User Help

Tooltip:Displays a tooltip when the user mouseovers the image in HTML formats.
Caption: A caption displayed below the image
Spacing: Space around the image (in pixels)
Zoom% / Autosize: Resize 242 the image or display in full size.
3. If the image is not in your project folder you will be asked whether you want to copy it
or add the path to the image location to your project.

Where to store your images

Help & Manual allows you to use images in any location. However, it is better to store
your images in a one or more graphics folders together with your project otherwise it is
very easy to lose track of your images.
You can easily move all your images 249 to different locations later if you need to.

Inserting images with cut and paste

1. Copy the image in your graphics program, then switch to Help & Manual and select
Write > Clipboard > Paste or press Ctrl+V. The Save Image dialog is displayed
with the following options:
· File name: Give the file a descriptive name!
· Save as type: You can save the image as a BMP, GIF, JPEG, PNG or Impict IPP
image. Use BMP for most purposes, Help & Manual converts and compresses
BMPs automatically when you publish your project.
2. Then just click on Save to save the graphics file. It will be inserted in the topic at the
current cursor position.
After inserting you can double-click on the image to display and edit the image properties.

Pasting graphics from MS Word

If you paste graphics from MS Word together with text they will be embedded directly in
your topic file. This uses up a huge amount of memory and computer resources (many
times the uncompressed size of the image itself) and is not recommended. Always
convert embedded images to external files after pasting them from Word or other office
programs.
1. Paste the image into your topic.
2. Right-click on the image and select Convert embedded picture.
3. Give the image file a descriptive name and save it in your graphics folder.

See also:
Using Graphics 238
Graphics, Videos and OLE Objects 753

© 1997 - 2009 by EC Software, all rights reserved

 Quick Start Tutorials 69

3.10 Inserting tables

Tables can be used both to arrange tabular data and as a formatting tool, in the same way
as in HTML pages. Help & Manual has full support for complex and nested tables. This
tutorial just shows you the basics of inserting tables for full details see the Working with
Tables 253 chapter.

How to insert a quick table

1. Click in the topic at the position where you want to insert the table.
2. Select Insert > Table in the Write tab or New > Table in the Table tab.
3. Move the mouse in the grid to highlight the number of columns and rows you want to
have, then click to insert the table,

How to insert a table with settings

1. Click in the topic at the position where you want to insert the table.
2. Select Insert > Table in the Write tab or New > Table in the Table tab, then select
Insert Table to display the Insert Table dialog.

© 1997 - 2009 by EC Software, all rights reserved

70 Help & Manual 5 - User Help

3. Select the number of rows and columns and choose the color and cell border settings.
For the moment leave all the other settings as they are you can always change them
later.
4. Click on OK to insert the table.
For full details of the settings see Table Properties 638 in the Reference section.

Manipulating tables
· Drag columns borders with the mouse to change column widths.
· Drag the right table margin to change the width of the table (whether you can do this
depends on the table width settings).
· Click in the table and select the Table tab to display the table tools most of these
are self-explanatory.
· Use the Lock Column tool to make column widths fixed or dynamic.
· Click in the table and select Table > Table > Properties to edit the table
properties.
· Click and drag to select cells, columns and rows, then select table properties and
apply settings in the Selected Cells tab (if you don't select anything the settings apply
to the current cell only).

Using table styles

You can define table styles in the Edit Styles 61 dialog in the same way as you define
styles for paragraphs and text.

© 1997 - 2009 by EC Software, all rights reserved

 Quick Start Tutorials 71

Applying a style to a table:

Click inside the table, select Properties in the Table tab and then select the style in the
Table Style: field.
Creating a table with a style:
Create a table with Table > Insert Table in the Write or Table tab and select the style in
the Table Style: field when entering the table configuration settings. Any additional
settings you enter in the Insert Table dialog will override the style settings for that table.

See also:
Working with Tables 253
How table sizing works 723

3.11 Creating hyperlinks

The Web without hyperlinks would be unthinkable and the same applies to interactive help
and documentation. Hyperlinks between topics are what makes your help really effective
and useful. You can create links to topics and specific places in topics. In addition to this you
can create links to pages on the Web and external files, and you can also create special
links that execute scripts and Winhelp macros.
This tutorial shows you the basics of creating hyperlinks to topics and specific positions in
topics. For full details on working with hyperlinks see Links, Anchors, Macros, Scripts and
HTML 214 .

Create a hyperlink with drag and drop

This is the fastest and easiest way to create a hyperlink and it is the method that you will
probably use most frequently when working on a project.
1. Select the text you want to turn into a hyperlink in the editor.

2. Drag the selected text to the Table of Contents (TOC) in the Project Explorer and drop
it on the topic you want to link to.
3. That's it, your hyperlink is finished. To edit it just double-click on it.

© 1997 - 2009 by EC Software, all rights reserved

72 Help & Manual 5 - User Help

Create a hyperlink manually

1. Select the text you want to use as the link. (This is optional with this method – you can
also create a link without selecting anything first.)
2. Select Inset > Link in the Write tab or press Ctrl+L to display the Edit Hyperlink
dialog. For the moment leave the default setting of Topic Link unchanged.

3. Select the Topic ID of the topic you want to link to from the list below the Target: field.
4. Choose a style for the link from the options on the left.
5. Click on OK to create the link.

Create a hyperlink to an anchor

Sometimes you will want to link to a specific location in the middle of a topic instead of
just displaying the top of the topic. This is achieved with anchors 226 , which are named
"link targets" that you can insert anywhere in a topic.
1. In the topic you want to link to, click in the position for the link target and select the
Insert Anchor tool in Write > Insert Object.
2. Type a name for the anchor (lower-case characters only) in the Anchor ID: field and
click on OK to insert the anchor. Don't worry about the other settings in the dialog at
the moment.
3. Manually create a hyperlink (see above) to the topic containing the anchor.
4. In the Insert Hyperlink dialog select the name of the anchor you want to link to from
the drop-down list next to the Target: field.

© 1997 - 2009 by EC Software, all rights reserved

 Quick Start Tutorials 73

You can also activate an anchor for an existing link by double-clicking on the link and
selecting the anchor from the list.

See also:
Links, Anchors, Macros, Scripts and HTML 214
Topic IDs, Context Numbers and Keywords 801

3.12 Publishing your project

Once you have completed a couple of topics you will want to publish your output to see what
your finished product is going to look like. You can output any of the formats 725 supported by
Help & Manual at any time you don't have to decide in advance what format you are
building your project for. The only thing you may need to do before you begin is install the
necessary Microsoft help compilers for Winhelp, HTML Help or Visual Studio Help (a.k.a.
Help 2.0).

How to publish your project

1. Save your project, then click on the Application Button and select Publish.

© 1997 - 2009 by EC Software, all rights reserved

74 Help & Manual 5 - User Help

2. Select the format you want to publish to in the list on the left.
3. Check the output file name and location in the Output File: field and change them if
you want.
4. Make sure that the Display file when finished checkbox is selected, leave all other
settings as they are.
5. Click on OK in a few moments you will be able to admire your finished product.
When you publish Webhelp 674 always use an empty folder because this format generates
a large number of output files. The program will suggest creating a folder called \HTML
inside your project directory, which is a good choice.
Before publishing ePub eBooks please check the eBook sections in Configuring Your
Output 305 and Publishing Formats 732 before getting started with ePub eBooks. You will
also need to install the free Adobe Digital Editions reader software so that you can
display your ePub eBooks.
The layout of your PDF output is controlled by separate template files. See Adobe PDF
301 for details.

Installing the Microsoft help compilers

Winhelp and HTML Help compilers:
Unless you have already done so you need to download and install the free Microsoft
compilers for HTML Help 727 and the obsolete Winhelp 740 if you are planning on using
these formats. You can find the latest versions of these compilers on the EC Software
website, here:
http://www.ec-software.com/reshelp.htm
After installing the compilers go to View > Program Options > Compilers and make
sure that Help & Manual knows where to find them. The Winhelp compiler executable is
called hcrtf.exe and the HTML Help compiler executable is called hhc.exe.

© 1997 - 2009 by EC Software, all rights reserved

 Quick Start Tutorials 75

Visual Studio Help compiler for .NET programmers:

You only need to compile to the Visual Studio Help/Help 2.0 format if you are a Visual
Studio .NET programmer. This help format is only used for documenting programming
components added to Visual Studio .NET. The compiler package can be downloaded
from the Microsoft website but it can only be used in combination with the Visual Studio .
NET package from Microsoft.
For details on using this format see the chapter on Visual Studio Help 490 in the More
Advanced Procedures section.

Quick-launching your project

The Quick Launch function compiles your output and displays it without displaying the
Compile Help File dialog. This function automatically uses the last settings you used
when you published to that format. It is thus advisable to publish to the selected format
manually (see above) at least once before using Quick Launch.
1. Click on the arrow symbol below the Publish button in the Project tab to display the
Quick Launch output options:

2. Then just select the output format you want to publish to. Your project will be
published and displayed automatically as soon as the process is finished.

See also:
Customize - Compilers 649
Testing Your Project 288
Configuring Your Output 292
Visual Studio Help 490

3.13 Template files

In addition to the other resources listed in this chapter the \Templates folder in the Help &
Manual program directory also contains a number of other useful templates and
configuration files:

Location of the files:

The files are stored in the \Templates folder in the Help & Manual program directory.

© 1997 - 2009 by EC Software, all rights reserved

76 Help & Manual 5 - User Help

Help & Manual skin files(*. \Templates\HTML skins

hmskin) These are special template files that store the
formatting, layout and design of an entire project
for HTML-based output formats. When you
compile a project you can then select a skin file
in the Publish 590 dialog to apply the design of a
different project to your output.
Some sample skins are provided in
\Templates\skins but if you have the
Professional version of Help & Manual you can
save any project as a skin with Save As in the
Application Menu. You can then edit the skin file
by opening it with Help & Manual, just like a
normal project.

Print manual templates (*.mnl \Templates\pdf

): These standard template files can be used as a
basis for creating and editing your own print
manual templates for PDF files and printed
manuals 325 .
Please copy these templates to your project
folder before editing them! (In Windows Vista
you will probably not be able to save your own
versions of the templates otherwise.)

Viewer templates (*.skin) and \Templates\ebooks

interface language files (*.lng The digital .skin templates allow you to change
) for Windows Exe eBooks: the appearance of the viewer used for Windows
Exe eBooks generated by Help & Manual. They
can be selected for your project in the Project
Explorer in Configuration > Publishing
Options> eBooks > Windows: Visual
Appearance.
The .lng language files contain the text for the
eBook user interface. They can be edited
manually in a normal text editor.

Full-text search language \Templates\Webhelp

files for Webhelp in multiple These files allow you to set the interface texts for
languages (*.zlang): the full-text search function in Webhelp to a
number of different languages. The language
files can be selected for your project in
Configuration > Publishing Options>
Webhelp > Full-text Search.

XML schema and stylesheet \Templates\xml

files (*.xsd and *.xsl):

© 1997 - 2009 by EC Software, all rights reserved

 Quick Start Tutorials 77

These are the source files for the XML Schema

definition and XSL stylesheets, if generated.
Do not make any changes to these files!

See also:
Templates in Help & Manual 416
Transforming your output with skins 321
PDF and Printed Manuals 325
Configuring your output for Webhelp 296
Configuring your output for eBooks 304

3.14 Tutorial Projects

In addition to the Quick Start Tutorials included in this help file, Help & Manual also comes
with a number of other useful tutorials and templates. All the tutorials are stored in Help &
Manual HMXZ project files that you can compile and edit yourself, so that you can
experiment with the procedures described directly.
This chapter provides brief descriptions of the subjects covered in these tutorials and
information on where you can find them.
· A template for creating help for Pocket PC (Pocket PC Help 79 )
· A non-scrolling header template that works both in HTML Help and Webhelp, including
full printing support with a Print button and generation of a printer-friendly version (
DHTML Examples 77 )
· The latest version of the project template for Help & Manual's own help and the entire
source code of Help & Manual's own help (H&M help project template 80 and Help &
Manual help source code 81 )
· Tutorials showing you how to create your own non-scrolling headers, navigation
buttons with mouseover effects, print links and buttons, CSS styles for hyperlinks, CSS
styles for the TOC in Webhelp, background images in the TOC and topics and more (
DHTML Examples 77 )
· A tutorial on how to use conditional output (Conditional Output 78 )
· A tutorial on how to work with modular help systems, including instructions for using A-
Links to link between modules (Modular Help Systems 79 )

See also:
Quick Start Tutorials 41
3.14.1 DHTML examples tutorial

Tutorial location and name:

Location: My Documents\My HelpAndManual
Projects\Examples\DHTML Examples
(in Windows Vista My Documents is called Documents)

© 1997 - 2009 by EC Software, all rights reserved

 78 Help & Manual 5 - User Help

Name: dhtml.hmxz

Subjects covered:
This tutorial shows you how to edit your project's HTML templates to create some more
advanced formatting and effects. All the code required is included in the tutorial project,
which you can also use as a template for your own projects. Once you have worked
through all the lessons you will be able to:
· Program your own expanding and collapsing sections (if you don't have the
Professional version of Help & Manual, which can do this for you automatically).
· Create non-scrolling headersA non-scrolling header stays visible while the user scrolls the text
of your topic. Help & Manual's own help uses these headers. for your HTML Help and
Webhelp output.
· Add graphical navigation buttons to your topic headers, with and without
mouseover effectsWhen the user positions the mouse over the button it changes and becomes
highlighted..
· Add a Print link or button to your topic headers.
· Use CSS styles to change the appearance and behavior of all the hyperlinks in
your project.
· Add customized icons to the TOC (table of contents) of your Webhelp projects.
· Add code to suppress underlined TOC entries in Webhelp in Firefox and Mozilla
browsers.
· Add a background to the TOC in Webhelp.
· Add background images to topics and headers.

See also:
Using HTML templates 430
3.14.2 Conditional output tutorial

Tutorial location and name:

Location: My Documents\My HelpAndManual
Projects\Examples\Conditional Output
(in Windows Vista My Documents is called Documents)
Name: CondOutput.hmxz

Subjects covered:
This tutorial project walks you through using the conditional output capabilities of Help &
Manual.
You will learn how to use build conditions to control the content included in your output.
When you have finished working through this tutorial you will be able to:
· Include and exclude topics, groups of topics and modules from your output on the
basis of output formats or your own defined build conditions.
· Include and exclude topic content (text, images etc.) on the basis of output formats
or user-defined build conditions.

© 1997 - 2009 by EC Software, all rights reserved

 Quick Start Tutorials 79

· Define your own build conditions to create multiple versions of the same project for
different purposes.
· Exclude all the topics of a chapter while including the chapter topic (this is a trick
that is not normally possible directly).

See also:
Conditions and Customized Output 399
3.14.3 Modular help systems tutorial

Tutorial location and name:

Location: My Documents\My HelpAndManual
Projects\Examples\Modular Help Systems
(in Windows Vista My Documents is called Documents)
Names: Master.hmxz, Module_A.hmxz, Module_B.hmxz

Subjects covered:
This tutorial project is an example of a simple modular help system. It guides you through
all the steps of creating and using modular help systems for a variety of different output
formats. When you have completed the tutorial you will be able to:
· Create and manage modular projects for all types of output formats.
· Add project files to your TOC as modules.
· Create genuine modular help systems for HTML Help and Winhelp formats. This
allows you to create different versions of your help without recompiling, just by
adding or removing help files from your distribution.
· Create dynamic conditional hyperlinks between modules using A-Links.

See also:
Working with Modular Help Systems 446
3.14.4 Pocket PC help template

Template location and name:

Location: My Documents\My HelpAndManual
Projects\Examples\Pocket PC Help
(in Windows Vista My Documents is called Documents)
Name: ppc.hmxz

About the template:

This is a project template for creating help for PDAs and smart phones running Pocket
PC. It can also be easily adapted for other devices with small screens and browsers with
limited capabilities. Full instructions and all the necessary graphics and styles are
included in the template project.

© 1997 - 2009 by EC Software, all rights reserved

 80 Help & Manual 5 - User Help

See also:
Templates for projects 417
3.14.5 Non-scrolling header template

Template location and name:

Location: My Documents\My HelpAndManual
Projects\Examples\DHTML Examples
(in Windows Vista My Documents is called Documents)
Name: dhtml.hmxz

About the template:

This HTML template is included in the DHTML tutorial project. It works both in HTML Help
and Webhelp. In addition to this it includes full printing support with a Print button and
generation of a printer-friendly version.

See also:
Using HTML templates 430
3.14.6 Help & Manual help project template

Location of the template:

Location: \My Documents\My HelpAndManual
Projects\Examples\Template for new Projects
(in Windows Vista My Documents is called Documents)
Name: HELPMAN.hmxz

About the template:

This project template enables you to style your own help like Help & Manual's own help.
Unlike a skin 321 , which is applied when you compile, a project template 417 is used as the
basis for a new project.
This template includes all the styles, graphics, HTML templates and other components
needed. It also includes non-scrolling header code for both HTML Help and Webhelp,
supporting non-scrolling headers with printing in both HTML and Webhelp.
Instructions for using the template for both new and existing projects are included.
Copy the template to your project folder before using it! Particularly in Windows Vista you
cannot edit the template while it is stored in the Program Files directory tree.

See also:
Templates for projects 417

© 1997 - 2009 by EC Software, all rights reserved

 Quick Start Tutorials 81

3.14.7 Help & Manual help source code

Location of the help project source code:

Location: My Documents\My HelpAndManual
Projects\Examples\HelpAndManual5
(in Windows Vista My Documents is called Documents)
Name: Helpman5.hmxz / Helpman5.hmxp

About the source code:

This is the complete source code of Help & Manual's own help as an example of a
relatively complex project. You are welcome to reverse-engineer the help and use its
components in any way you like but please don't use the actual text from the help in your
own projects.
The project template for this help project 80 for use in your own projects can be found in
the \My Documents\My HelpAndManual Projects\Examples\Template for new
Projects folder.

3.14.8 SDL Trados INI file

Location of the INI file:

Location: \Templates\Translation folder in the Help & Manual program
directory.
Name: SDL Trados Configuration.ini

About the file:

This is a customized INI file for use with the SDL Trados translation memory tool. It
allows proper display and editing of the uncompressed XML project files saved by Help &
Manual in SDL Trados.

See also:
Translating Your Projects 521

© 1997 - 2009 by EC Software, all rights reserved

Part

IV
 Basic Working Procedures 83

4 Basic Working Procedures

This section describes the most common basic tasks you will use when working with Help &
Manual. It is designed as a "How-To" guide. You can use the table of contents as an index.
Although it is organized roughly in the order that you would perform the tasks you don't need
to begin at the beginning and work your way through. Every topic contains comprehensive
links to background information and other relevant subjects so you can just pick out the task
you need to perform and begin.

More information
Once you have learned the basics in this section see More Advanced Procedures 335 to
learn what else you can do with Help & Manual.
The "How-To" topics are intentionally kept as brief as possible. The focus is on how to do
what you need to do. More detailed background information on many subjects is provided
in the Reference 568 section and in other areas.

See also:
Introduction 16
The User Interface 23
Quick Start Tutorials 41

4.1 Creating Projects

Creating a new project with Help & Manual is generally as easy as creating a new word
processing file you just click on the Application Button, select New and follow the
instructions.
In addition to creating an empty new project you can also create a project with data imported
from other sources, including Word RTF files, compiled HTML Help CHM files and HTML
pages. See Importing Data 99 for more details.

See also:
Importing Data 99
Help Formats 725
4.1.1 Creating an empty new project
When you create a new project Help & Manual automatically generates a table of contents
(TOC) with a small set of topics that you can use as a starting-point.

How to create an empty new project

1. Click on the Application Button and select New to display the Create New Help
Project wizard:

© 1997 - 2009 by EC Software, all rights reserved

84 Help & Manual 5 - User Help

Select the first option, Create a new help project, then click on Next.
2. In the next screen you choose the project save format and specify the project save
location, the project filename ,the project title and the language settings:

Save format:
The Standard version of the program can only save in Compressed ZIP Archive mode
(single .hmxz project file). If you have the Professional version you can deselect this
option to save in uncompressed XML format (an .hmxp project file and separate XML
files for all topics and settings, required for multi-user editing). You must save to an
empty folder when you choose the uncompressed format.
Enter a title for your help project and select your help project language and character
set. If your help project is in English or any ordinary western European language leave
these options set to English (United States) and ANSI_CHARSET. See International
languages setup 94 for details on settings for other languages. Then click on Next.
3. In the Table of Contents screen the wizard then displays a small set of standard
topics that you can now edit and add to:

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 85

You can edit, delete and add topics if you want to. Don't worry about getting everything
right now – you can change everything later very easily.
Click OK to create and open your new project. All the topics whose titles you entered
in the previous step will automatically be created.

Backing up your work - automatic backups

Your project represents a great deal of work, time and creativity and it is probably worth a
lot of money. We urgently advise you to make regular backups, preferably on an external
drive, and keep them in a safe place. Help & Manual is very secure and takes great care
to protect your data but Windows can crash, hard drives can fail, the power can go off
and viruses can strike, so it is better to be safe than sorry.
Automatic backups:
You can set Help & Manual to make automatic backups of your project file at regular
intervals. Go to View > Program Options > General and select the option
Automatically back up project every xx minutes. This will automatically create a backup
copy of your project with the extension .hmxz~~ in your project directory at the specified
intervals (to make these files readable just rename them to .hmxz removing the two tilde
characters).

See also:
Importing Data 99
4.1.2 Choosing your save mode
Help & Manual Help stores your projects as a collection of plain text files using a very
flexible format called XML. You don't need to know anything at all about XML to use the
program.
If you are using the Professional version of Help & Manual you can save your project in
single-file compressed mode or uncompressed XML mode. Single-file mode saves all your
project files in a single compressed file with the extension .hmxz. Uncompressed mode
saves your project as a collection of files and folders, which you must save in an empty
folder.

© 1997 - 2009 by EC Software, all rights reserved

86 Help & Manual 5 - User Help

Key Information
The uncompressed XML format (.hmxp) is
only supported in the Professional version
of Help & Manual. The Standard version
can only save in the compressed single-file
format (.hmxz).

How to choose and change save mode

You can only choose and change your save mode with Help & Manual Professional. The
Standard edition saves in compressed mode only.
· When creating a new project the default save mode is Single-File Compressed
(HMXZ). You can save in uncompressed XML (HMXP) by deselecting the option
Project file format is XML in a compressed ZIP archive in the Output file screen of the
New Project wizard.
· To switch to the other save format (compressed or uncompressed) click on the
Application Button and select Save as...
· Always save to an empty folder when saving in Uncompressed XML mode (Help &
Manual will not allow you to save to a folder with any content).

About single-file compressed mode

Help & Manual Standard only supports compressed mode.
· One compressed .hmxz file containing all project files.
· Contains exactly the same files and folders as uncompressed XML mode. The content
of both formats is identical.
· Compact and easily portable.
· Does not support multi-user editing, saving in versioning repositories, processing with
external tools or editing with external editors.

About uncompressed XML mode

Help & Manual Professional is required for this mode.
· Your project and all its topics, formatting and settings are stored in a collection of plain-
text XML files. The main project file has the extension .hmxp.
· Must be saved in an empty folder.
· Required for multi-user editing, saving in version control systems and editing with
external editors.
· Not quite as portable as .hmxz but data security is better because damage to a single
file will not compromise your entire project.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 87

4.1.3 Publishing formats

If you are familiar with other help authoring tools you may expect that you need to decide
what publishing format you are going to use when you create your project. This is not
necessary in Help & Manual. You can always publish your project to any of the supported
formats at any time. To change your publishing format you just need to select Publish 311 and
choose a different output format.

Available publishing formats

You can generate a total of eight different output formats (ten including printed
manuals), each of which has its advantages and disadvantages for specific purposes.
You can generate multiple formats from the same project, for example HTML Help for
your online help and PDF for your printable manual.
Supported publishing formats in Help & Manual:
· HTML Help (.chm)
· Classic Winhelp (.hlp, now obsolete)
· Webhelp (HTML, for display in normal web browsers)
· Adobe PDF (.pdf)
· Word RTF (.rtf)
· Windows Exe eBooks (.exe with integrated eBook viewer)
· Universal ePub eBooks (.epub)
· Visual Studio Help (.hxs, for Visual Studio .NET components only)
For details on these help formats and their individual features and uses see Help Formats
725 in the Reference section.

See also:
Help Formats 725
4.1.4 Converting old projects
Help & Manual automatically converts old project files from previous versions (H&M 3 and
H&M 4) when you open them. Alternatively, you can also use the stand-alone converter
program to convert old projects manually.
Help & Manual 4 projects are converted 1:1 and do not require any post-processing after
conversion. Older Help & Manual 3 projects did not have the styles and other features
introduced in the modern versions of the program and may require some reformatting after
importing.

Converting old projects automatically

You can convert both Help & Manual 4 (.hmx) and Help & Manual 3 (.hm3) projects. In
addition to this you can also import data from a number of other formats using this option.
1. Click on the Application Button and select Open, then select the format of the project
you want to open in the Files of Type: field (or the drop-down menu next to the File

© 1997 - 2009 by EC Software, all rights reserved

88 Help & Manual 5 - User Help

Name: field in Windows Vista).

2. Select the file you want to convert and click on Open to display the following dialog:

3. Select Convert and open to convert the old project.The new project file will be saved
in the same directory as the old project you are converting.
This method automatically converts the old project into a single compressed file with the
extension .hmxz containing all the project components except the graphics files. If you
are using the Standard version of Help & Manual this is the only project format you can
use.

Invisible topics from old Help & Manual projects

If your old HMX or HM3 project contains "invisible topics" they will be moved to a sub-
folder called Topics\Invisible in the Topic Files section in the Project Explorer.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 89

Automatic Converter:

When you use the automatic converter a folder called

(Former Invisible Topics) will also be created at the
bottom of the converted project's Table of Contents
(TOC) section.
These TOC entries are linked to the topic files of the
former invisible topics but they will still not be included in
your published output because their include options are
automatically set to "None".

You can delete the (Former

Invisible Topics) folder by
selecting it and pressing
DELETE. Before confirming,
deselect the option Also delete
referred topic files to keep the
actual topic files.

External Converter:
When you use the external converter program you can decide what you want to do with
your old invisible topics:

Add invisible topics to TOC creates the (Former Invisible Topics) folder described
above.
Keep organization structure creates sub-folders in the Topic Files section to match
your folder structure in your old project. You can create a maximum of 10 levels but the
converter will not create more levels than the original project contained.

© 1997 - 2009 by EC Software, all rights reserved

90 Help & Manual 5 - User Help

Converting old projects with the external converter

You need to use the external converter to convert old projects to the uncompressed XML
format (Professional version only) and to select additional conversion options for Help &
Manual 3 projects.
Follow the instructions above and select Start external converter. For full details see
The Project Converter 550 .

Important: Images from old projects are not copied or moved

When you convert old projects the images they use are left in their original locations. The
images are accessed by adding links to the old locations to the Project Search Path in
the converted project. If you want to store the images with your new project you must
manually copy them to a new folder in your new project folder and then update the
Project Search Path of your new project so that it only references the new folder(s)
location.
See Managing your graphics 249 for more details on these subjects.

Post-processing for Help & Manual 3 projects

There are three areas where you may need to make adjustments after converting and
importing old HM3 projects:
Settings for styles:
The settings for your styles may need to be edited a little because styles in Help &
Manual 3 projects did not have the same close association with text and paragraphs that
they have in Help & Manual 4 and 5. All the formatting of your text will be converted
correctly but you may find that some paragraphs are associated with the Normal style
instead of a newly-defined style matching the old formatting.
Imported and converted tables:
Some of the static tables from H&M3 projects may also need a little post-editing. Tables
in Help & Manual 3 were fixed-width only and they were often split into multiple tables to
handle page break problems in PDF and printed manuals. The Project Converter has
options 550 for dealing with both of these issues but because of the differences between
the two table formats you may need to make some manual corrections to your tables
after importing.
Custom code in HTML templates:
The HTML templates 427 used in <%TIGER%> have changed considerably, so it is not
possible to transfer custom code from your .hm3 projects when they are imported the
risk of damaging the resulting code would be too great.
If you have entered custom code in your templates you will need to re-enter it in the
templates of your converted Help & Manual project.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 91

See also:
The Project Converter 550
Text Formatting and Styles 155
Dynamic Styles 711
Working with Tables 253

4.2 Configuring Your Project

Once you have created a new project the first thing you want to do is to check through the
settings for the project in the Configuration section of the Project Explorer. There are a large
number of options that you will probably use once you are more experienced but the basic
settings are quick and intuitive. This chapter guides you through the most important ones
that you need to remember.

4.2.1 Project Configuration

After creating your project it's a good idea go through the Configuration 652 section of your
project in the Project Explorer and check all your basic settings, which are initially set to
default values by the program. You can change these settings at any time, but some are
easy to forget, like the help title, window titles and copyright information and so it's a good
idea to get into the habit of doing a check whenever you start a new project.
This topic lists the basic settings in Configuration that you should always check when you
create a new project. The other sections are also important but these generally contain
things that you will edit while working on or compiling your project. For full details see the
Project Configuration 652 chapter.

Setting your help title, copyright notice and version

The first thing you want to do is to enter the title of your project, the name of the author,
your copyright notice and so on.
· Select Title & Copyright in Configuration > Common Properties in the Project
Explorer.
· Enter your details. You can insert the version numbers and other information you store
here in your project topics with variables see here 774 for a list.
See Title & Copyright 654 in the Project Configuration chapter for details on the
settings.

Setting the default topic

The default topic in your help is the topic that is automatically displayed when the help is
opened in WinhelpNote that Windows Vista does not support Winhelp. If you want to be compatible with
Vista you must transition to a different help format., HTML Help, Webhelp, Visual Studio Help (MS
Help 2.0) and Windows Exe eBooks (this feature is not supported in ePub). If you don't
set a topic the help will open at the first topic containing text in your TOC.
1. Select Language Settings 654 in Configuration > Common Properties.

© 1997 - 2009 by EC Software, all rights reserved

92 Help & Manual 5 - User Help

2. Select the topic ID of the default topic in the Default ("Home") topic: field.

Setting your language settings

One of the most important things to check is your language settings. Help & Manual
supports almost all international languages but you need to make sure that your project is
configured correctly to handle the language you are using, even if it is English or a
common Western European language.
See International languages setup 94 for full details!

Setting the title of your help windows

You probably want the Help Title you enter in Title & Copyright section of Project
Configuration to be displayed in the title bar of your published help in HTML Help and
Winhelp. This is normally done with the <%TITLE%> variable but you can also enter a
different text manually if you like.
Important: This setting is only for HTML Help (CHM) and Winhelp (HLP) output files. All
other output formats where the title is relevant take the title directly from the Title &
Copyright section.
1. Select Help Windows in Configuration > Common Properties.
2. Click on the name of the help window whose title you want to change. If you have not
defined any additional help windows only the standard Main help window type will be
displayed. See Using secondary windows 429 for more information.
3. In the General tab, check that the <%TITLE%> variable is entered in the Title bar text:
field. If it is not just type it in manually. Alternatively you can type in a title manually but
this will not be updated automatically if you change your project title.
See Help Windows 807 and Help Windows Settings 660 in the Reference section
background information.

Checking your output format settings

All the output formats you can generate with Help & Manual can be customized with a
large number of options in your Project Configuration. You will only need to check and
adjust the settings for the formats you are actually going to use, of course.
See Configuring Your Output 292 and Project Configuration 652 chapter for details on all the
individual settings in these sections.

See also:
Project Configuration 652
Configuring your Output 292
Using help windows 121
Templates and Secondary Windows 416

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 93

4.2.2 Background colors and help viewers

If you are planning to publish your project to HTML Help (CHM) or the obsolete Winhelp
(HLP) format you will also want to configure the appearance and features of the Microsoft
help viewers used to display these formats. These settings are stored in what is known as a
"help window definition".
You can also define background colors for your topic pages and topic headers. These colors
are defined in the help window definition for Winhelp and in the HTML page templates for all
other electronic formats. You cannot define topic and header background colors for PDF,
RTF or printed manuals.
The settings in Help window definitions are only relevant for the Microsoft HTML Help and
Winhelp formats. For details see Help Windows 807 and Help Windows Settings 660 in the
Reference section and Choosing a help window 121 in the Creating Topic Files section.

Background colors of topics and headers

Background colors can only be set for the topics and headers in electronic help formats.
The background colors are ignored in PDF, RTF and printed manuals.
Background colors for HTML Help, Webhelp, eBooks and Visual Studio Help
In all these formats the background colors for the topic and header are set in the HTML
Page Template settings.
· In the Project Explorer, go to Configuration > HTML Page Templates > Default
and set the colors for the header and topic.
You can apply different background colors to different topics by creating additional HTML
page template definitions and choosing different templates for individual topics in the tab
behind the main editor window.
Background colors for Winhelp:
1. In the Project Explorer go to Configuration > Common Properties > Help
Windows and select the Main help window in the drop-down list at the top of the
dialog window.
2. Select the Winhelp Options tab and define the background colors.
You can apply different background colors to different topics by creating additional help
window definitions and choosing different help windows for individual topic in the tab
behind the main editor window.

How to edit the help viewer features

You can adjust the features of the Microsoft help viewers for HTML Help and the obsolete
Winhelp format by editing the settings of the Main help window in Configuration >
Common Properties > Help Windows.
There are separate sections for the HTML Help and Winhelp help viewers and there is
also a common section where you can define the text in the help window title bar and the
help window size and position.

© 1997 - 2009 by EC Software, all rights reserved

 94 Help & Manual 5 - User Help

Help viewer settings for HTML Help:

1. In the Project Explorer go to Configuration > Common Properties > Help
Windows and select the Main help window in the drop-down list at the top of the
dialog window.
2. Set the size and position of the help window in the General Options tab. In HTML Help
this setting will only be used the first time the user opens the help. After this Windows
will apply the last size and position used by the user.
3. The title bar text is displayed in the title bar of the help viewer. The standard setting <%
TITLE%> displays the title of your help project from your Title and Copyright settings.
4. Select the HTML Help Options tab and define the help viewer settings.

Help viewer settings for Winhelp:

1. In the Project Explorer go to Configuration > Common Properties > Help
Windows and select the Main help window in the drop-down list at the top of the
dialog window.
2. Set the size and position of the help window in the General Options tab.
3. The title bar text is displayed in the title bar of the help viewer. The standard setting <%
TITLE%> displays the title of your help project from your Title and Copyright settings.
4. Select the Winhelp Options tab and define the help viewer settings and the
background colors.

HTML Help window size and position

Note that if you want to control the size and position of the help viewer window in HTML
Help you must change two settings:
1. Set the window size and position in the Color and Position section.
2. Deselect the option Save user-defined positions after first use in the HTML Help
Options section.
If you don't do this your window settings will be ignored and Windows will save and use
the last window size and position set manually by the user. Most users prefer this and
dislike it when a program sets its own window size and position for the help!

See also:
Using help windows 121
Help Windows 807
Help Windows Settings 660
Templates and Secondary Windows 416
4.2.3 International languages setup
Help & Manual is fully Unicode-enabled and can edit and compile help files in virtually all
international languages except right-to left languages.
Working in Unicode languages requires both configuration settings for the language you are
using in your project and special Windows settings for the Microsoft help compilers, which

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 95

are not Unicode programs.

Even if you are working in English or any other Western European language it is important
to check that the language settings of your project are correct before starting work.
For more information see International Languages and Unicode 819 and Language Settings
654 in the Reference section.

Where to find the language settings

· Go to Configuration > Common Properties > Language Settings in the Project
Explorer to view and edit the language settings for your project.
· See Language Settings 654 in the Project Configuration section of the help for details.
· If you are plan to generate PDF files you also need to set CID Font Mode 332 to the
correct setting for the language you are using.

English and Western European languages

Windows version and configuration:
Projects in English and Western European languages can be published and viewed on all
versions of Windows without restrictions. The language of the help file does not have to
match the language of the Windows version on which the file is being viewed.
Configuration > Common Properties > Language Settings:
Language of The default setting is English (United States). This should not be
the help file: changed for English and Western European languages unless you
experience problems with sorting in the Keyword Index.
Because of a bug in the Microsoft HTML Help viewer it is best to set
English (United States) for all Western European languages if
possible otherwise "HTML Help" will be displayed in the title bar of
the help if the language setting does not match the language of the
user's Windows version.

Font character The default setting is ANSI_CHARSET. This should not be changed
set: for English and Western European languages.

Default font: This option only defines the font used in the TOC and dialog boxes by
HTML Help and the obsolete Winhelp.
Note that Winhelp and HTML Help are designed to work with the
default font and font size settings so please test thoroughly if you use
different fonts or sizes.
The default is MS Sans Serif,8,0. The value 8 defines the font size
and should generally not be changed. The last value defines the
character set and 0 tells Help & Manual to set the character set
automatically.

© 1997 - 2009 by EC Software, all rights reserved

96 Help & Manual 5 - User Help

CID Font Mode for PDF font embedding:

Go to Configuration > Publishing Options > Adobe PDF > Font Embedding 692 :
CID Font Mode is a special mode for embedding Unicode fonts in PDF files more
efficiently for Asian languages. It should generally be set to CID Off unless you are using
Asian languages. See CID mode for Unicode fonts 332 for more details.

Eastern European languages, Greek, Russian, Turkish etc.

Windows version and configuration:
Compiling projects:
· You can compile projects written in these languages to Webhelp, MS Word RTF, PDF,
eBooks and Visual Studio Help / MS Help 2.0 with any version of Windows 2000,
Windows XP or later with support installed for the language you are using.
· To compile projects in these languages to HTML Help or Winhelp you must also set the
"system locale" of your Windows configuration to match the language of your project.
Changing the system locale

Note that the system locale and the user locale are different! Simply setting the
display and/or data entry language does not change the system locale!
1. Log in to a user account with administrator privileges.
2. Open the Regional and Languages section in the Windows Control Panel.
· Windows 2000: Activate your language in the list of languages at the bottom of
the main tab and then select the same language as the locale at the top of the
same tab.
· Windows XP: Select your language as the default language for non-Unicode
programs in the Advanced tab (this tab is only displayed if you have
administrator rights).
· Windows Vista: Select the Change System Locale button in the Administrative
tab (this tab is only displayed if you have administrator rights.
3. Click on OK to apply the setting and then restart Windows.

Viewing compiled help:

Help & Manual's output files can be viewed on most versions of Windows on which
proper support for the specific languages is installed. Some features of Winhelp and
HTML Help (full-text search, Keyword Index sorting) will only work properly if the
language of the Windows version matches the language of the help file. This applies
particularly for Asian languages. For example, all functions of a Chinese HTML Help file
will only work correctly on a Chinese version of Windows.
See About H&M's Unicode support 821 for more details on this.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 97

Configuration > Common Properties > Language Settings:

Language of This setting must be set to the language in which your help is written.
the help file: This is important both for proper sorting in the Keyword Index and
proper identification of the language by the system.

Font character This setting must be set to the correct character set to display the
set: language used in your help file.

Default font: This is not the default font of your help project! This option only
defines the font used in the TOC and dialog boxes by HTML Help and
the obsolete Winhelp.
Note that Winhelp and HTML Help are designed to work with the
default font and font size settings so please test thoroughly if you use
different fonts or sizes. You may need to change the font to display all
characters correctly in your language.
The default is MS Sans Serif,8,0. The value 8 defines the font size
and should generally not be changed. The last value defines the
character set and 0 tells Help & Manual to set the character set
automatically.

CID Font Mode for PDF font embedding:

Go to Configuration > Publishing Options > Adobe PDF > Font Embedding 692 :
CID Font Mode is a special mode for embedding Unicode fonts in PDF files more
efficiently for Asian languages. It should generally be set to CID Off unless you are using
Asian languages. See CID mode for Unicode fonts 332 for more details.

Asian languages, all languages requiring Unicode

This group includes all languages that require Unicode, which means languages with
more than 255 characters requiring two bytes to store each character. For example, this
includes most Asian languages like Chinese, Japanese and Thai.
Windows version and configuration:
Editing projects:
Help & Manual projects written in Unicode-based languages can only be edited on
Windows 2000, Windows XP or later with support installed for the language you are
using.
Compiling projects:
· You can compile Unicode projects to Webhelp, MS Word RTF, eBooks and Visual
Studio Help / MS Help 2.0 with any version of Windows 2000, Windows XP or later with
support installed for the language you are using.
· To compile Unicode projects to Winhelp or HTML Help you must also set the "system
locale" of your Windows configuration to match the language of your project.
Changing the system locale

© 1997 - 2009 by EC Software, all rights reserved

98 Help & Manual 5 - User Help

Note that the system locale and the user locale are different! Simply setting the
display and/or data entry language does not change the system locale!
1. Log in to a user account with administrator privileges.
2. Open the Regional and Languages section in the Windows Control Panel.
· Windows 2000: Activate your language in the list of languages at the bottom of
the main tab and then select the same language as the locale at the top of the
same tab.
· Windows XP: Select your language as the default language for non-Unicode
programs in the Advanced tab (this tab is only displayed if you have
administrator rights).
· Windows Vista: Select the Change System Locale button in the Administrative
tab (this tab is only displayed if you have administrator rights.
3. Click on OK to apply the setting and then restart Windows.

Viewing compiled help:

Help & Manual's output files can be viewed on most versions of Windows on which
proper support for the specific languages is installed. Some features of Winhelp and
HTML Help (full-text search, Keyword Index sorting) will only work properly if the
language of the Windows version matches the language of the help file. This applies
particularly for Asian languages. For example, all functions of a Chinese HTML Help file
will only work correctly on a Chinese version of Windows.
See About H&M's Unicode support 821 for more details on this.
Configuration > Common Properties > Language Settings:
Language of This setting must be set to the language in which your help is written.
the help file: This is important both for proper sorting in the Keyword Index and
proper identification of the language by the system.

Font This setting must be set to the correct character set to display the
character set: language used in your help file. This too is particularly important for
proper handling of Unicode-based languages. You must have the
proper character set for your language installed for Help & Manual to
be able to process and compile the language correctly.

Default font: This is not the default font of your help project! This option only
defines the font used in the TOC and dialog boxes by Winhelp and
HTML Help.
The default is MS Sans Serif,8,0, which is the font and size that
Winhelp and HTML Help are designed for. In Asian languages and
other Unicode-based languages you may need to choose an
appropriate font for your language instead of MS Sans Serif.
The value 8 defines the font size and should generally not be
changed. The value 0 defines the character set. You do not need to
change the character set value – Help & Manual does this for you

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 99

automatically when you compile your project.

CID Font Mode for PDF font embedding:

Go to Configuration > Publishing Options > Adobe PDF > Font Embedding 692 :
CID Font Mode is a special mode for embedding Unicode fonts in PDF files more
efficiently for Asian languages. It should generally be set to CID Off unless you are using
Asian languages. See CID mode for Unicode fonts 332 for more details.

Test-publishing Asian languages on non-Asian Windows

Normally, you cannot publish help projects written Asian languages on non-Asian
versions of Windows because the necessary language settings don't match. However, if
you just want to do a quick test publish and don't have a Windows version in the
matching Asian language there is a configuration setting that will allow you to do this.
· Go to View > Program Options > Compilers and activate the option Tolerant
handling of Asian languages.
Some features may not work correctly in the resulting help file in Winhelp and HTML Help
if the languages of your Windows version and the help file don't match (Search, Keyword
Index) but you will be able to complete the compilation, which is sufficient for testing.

See also:
International Languages and Unicode 819 (Reference)
Language Settings 654 (Project Configuration)

4.3 Importing Data

There are a number of different ways to import data from other formats into Help & Manual.
You can "convert" the data you are importing into a new project, merge it into an existing
project or import individual documents into individual Help & Manual topics. You can also
copy and paste data directly into your topics from Office programs and other applications.
In addition to this you can also import data from other Help & Manual projects in a number of
different ways: You can copy and paste data and topics, "embed" topics from other projects
in your current project or import topics and projects.

4.3.1 New project with imported data

If you have existing documentation in other formats you can import it to Help & Manual and
create a new project in one easy process. An interactive wizard guides you through each
step of the process of importing the data.

Importing data to new projects

1. Click on the Application Button and select New.
2. Select the option "Import existing documentation from...".

© 1997 - 2009 by EC Software, all rights reserved

 100 Help & Manual 5 - User Help

3. Select the documentation format, then follow the instructions displayed in the
interactive wizard.
See Settings for importing data 105 for details on the optimum settings for each data
format.

General settings for all formats

See Settings for importing data 105 for full details. The following settings are the same for
all formats:
· Output file:
Name and location of the new project.
· Project file format:
Save in a single-file compressed format (.hmxz) or uncompressed XML (with .hmxp
project file, Professional version only)
· Project title:
The title of your project. This can be changed later.
· Project language and character set:
You can also change these settings later. See International languages setup 94 for
details.

See also:
Settings for importing data 105
4.3.2 Importing data into existing projects
In addition to creating new projects with imported data you can also import documentation
from other formats into existing Help & Manual projects. Here too, an interactive wizard
guides you through the steps of the import process, prompting you to enter the necessary
settings for importing the data.
The imported topics and chapters are inserted in the current position in the table of contents.
This means that you need to select the position in the TOC where you wish to insert the data

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 101

before you begin.

Productivity Tip
Also see the powerful Snippets 149 function
with which you can reuse topics and topic
content saved in external files.

Importing external data into existing projects

1. Select the Table of Contents section in the Project Explorer and choose the position in
your project where you want to insert the imported data. The data will be inserted after
the selected topic.
2. Click on the Application Button and select Import.

3. Select the documentation format, then follow the instructions displayed in the
interactive wizard.
See Settings for importing data 105 for details on settings for individual formats.

Importing external data into individual topics

You can also import external data directly into individual topics. Note that you should
always create a new topic to do this because importing the data overwrites the current
topic.
1. Create a new empty topic or select a topic that you want to overwrite.
2. Select File > Load Topic from File in Project > Manage Topics and select the file
you want to load. You can import HTML, RTF, RVF, TXT files and Help & Manual XML
topic files.
If you have the Professional version of Help & Manual you can load topics from other
projects directly provided the projects are saved in uncompressed XML format.
For full details on this function see Exporting and importing topics 204 in the Creating and
Editing Topics section.

© 1997 - 2009 by EC Software, all rights reserved

 102 Help & Manual 5 - User Help

Copying and pasting between projects:

You can also cut, copy and paste topics directly between projects in the Project Explorer.
Just open both projects in the explorer and then use the Clipboard functions in the
Ribbon to cut, copy and paste entire topics and chapters between the Table of Contents
sections of the projects. See Moving, cutting and pasting topics 199 for full details.

See also:
Re-using content with snippets 149
Moving, cutting and pasting topics 199
4.3.3 Importing & copying topics and XML files
You can import topics and XML topic files to the current topic from the current project, from
other Help & Manual projects and from libraries of Help & Manual XML files. You can either
overwrite the entire current topic with the external file using Load Topic from File or you can
insert the external file in the current topic with the Snippets tool.
You can also copy and paste topics and chapters from other projects in the same way as
within your current project.

Productivity Tip
Use Snippets to build up a collection of
pre-formatted text blocks and topics that
you and your team use frequently! Just
copy the XML topic files you want to use to
a folder for storage.

Importing topics and XML files as snippets

The Snippets tool insert topics and H&M XML files into your current topic at the cursor
position. These topics can be inserted in Copy mode or Link mode. In Link mode the
snippet content updates automatically when the source topic or XML file is edited.
The topics can be in your current project, another Help & Manual project (HMXP format,
Professional version only) or a directory of H&M XML files.
1. Click in your topic where you want to insert the snippet.
2. Select the Insert Snippet tool in Write > Insert Object.
3. Choose From Topic to insert a topic from the current project or From File to insert an
external H&M XML file or an XML topic file from another project.
· Copy & Paste inserts a copy of the file that you can then edit.
· Linked creates a live link to the file changes in the source file or topic are updated
automatically.
· You can also insert XML files from your current project instead of using the From
Topic mode (HMXP format, Professional version only).
4. Select the topic or file you want to insert and click on OK to insert it.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 103

"Use project search path to locate snippet"

This option adds the location of the snippet file to the project search path 656 if you
deselect it the path to the snippet is stored with the snippet.
Rather than using snippets from many locations it is better to store all your snippet files in
a common location. This will make them easier to manage, particularly if you ever need to
move your project or have it translated.

Managing and organizing snippets

You can insert snippets from any location. However, if you use linked snippets from many
locations the links will be dead if you move your project or send it to someone by email.
You can solve this problem by storing your snippet files together with your project in a
special directory.
1. Create a folder for your snippets in a location where you can easily transport it
together with your project folder.
2. Add the path to the snippets folder to your Project Search Path in your project's
Configuration > Common Properties settings.
3. When you insert a snippet select the Project Search Path option to tell Help & Manual
to look for the snippet files in the folders listed in the Project Search Path.
When you do this you can always move your snippets folders to any location you like. To
get Help & Manual to find the snippets you just need to add the new location to your
Project Search Path.

Exporting text and topics as snippet files

You can export selected text or the current topic to an external XML file, for example for
use as a snippet in a snippet directory.
Export the entire topic:
1. Select the topic you want to export in the Project Explorer (TOC or Topic Files).
2. Select File > Save Topic to File in Project > Manage Topics and choose the save
location.
Export selected text:
Select text in the editor the text can include anything that a topic can contain, i.e. also
images, tables, etc.
Select File > Save Snippet in Project > Manage Topics and choose a save location
and a filename.

Formatting and snippets

Formatting with styles:
If the text in snippets is formatted with styles the styles must be defined in the present

© 1997 - 2009 by EC Software, all rights reserved

104 Help & Manual 5 - User Help

project. If the styles are not defined the snippets text will be displayed unformatted. If you
use standard style names in all your projects your snippets will be reformatted
automatically to match the styles of the current project.
Manual formatting:
If the text in your snippets files is manually formatted it will be displayed normally in the
current project. It is generally better to use manual formatting if you want the formatting of
the snippets to look identical wherever they are used.

Loading entire topics from external files

You can load entire topics from external files. Unlike snippets, loading a topic from a file
replaces the entire current topic with the external file. You can load topics from RTF,
HTML, TXT and Help & Manual XML topic files.
1. Select the topic you want to overwrite in the Project Explorer (TOC or Topic Files).
2. Select File > Load Topic from File in Project > Manage Topics and select the file
you want to load. This will overwrite the current topic with the contents of the selected
file!
See Content templates for topics 423 for information on using Help & Manual XML topic
files as content templates for topics.

Merging external HTML files into topics

In HTML-based output formats you can also use the #MERGE command to merge the
contents of external HTML files into your topics when you compile your project. This
enables you to maintain external files for information that may change and insert the
latest version automatically every time you compile.
See Merging HTML files into topics 107 for full details and instructions.

Copying topics and chapters between projects

1. Open both projects in the Project Explorer.
2. Select the source and target positions in both projects so that you can see them
clearly. Use the Split Explorer tool in the Project tab to create additional views of all or
parts of the projects side by side.
3. Use the Copy, Cut and Paste tools in the Ribbon Toolbar to copy and paste topics or
chapters. These Clipboard tools are available in both the Write and Project tabs.
If the pasted topics have the same IDs as topics in the target project H&M will change
them automatically. It's advisable to open the tab and check the IDs of all pasted topics
after importing them.

See also:
Re-using content with snippets 149
Exporting and importing topics 204

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 105

Moving, cutting and pasting topics 199

4.3.4 Settings for importing data
Generally the interactive wizard displayed when you select Import in the Application Menu
provides most of the information you need. However, the information below will help you to
choose the settings that will produce the best results with the individual import formats.

HTML files and compiled HTML Help files (.chm)

The importer needs to know how to deal with the different parts of HTML topic pages.
You can improve the import performance with the settings in the HTML Import Options
page of the wizard.

Topic header:
Getting the header information from the <title> tag will usually work. If your topics have
a separate header block you may need to specify a different tag. If in doubt display the
CHM file, right-click on one of its pages and examine the source code with View Source.
Topic body:
Specify a <table> or <div> tag with a specific ID only if you know that is used to identify
your body content. Otherwise use the default setting.
Ignore internal folders:
Help & Manual does not use internal folders in CHM files, all files are stored on the same
level. If the CHM file contains internal folders the folder names will normally be prefixed to
the topic IDs of the imported topics to prevent name conflicts. You can turn this option off
if you are sure that there are no name conflicts caused by files with the same names
stored in different folders.
Single-column tables:
Some topic pages are enclosed in single-cell/single-column tables, which can cause
undesirable results when you import them. You can solve this problem with the option for
converting such tables to single paragraphs.
Popup topics file:
In CHM help popup topics are stored in a special plain-text file inside the CHM. Normally

© 1997 - 2009 by EC Software, all rights reserved

106 Help & Manual 5 - User Help

this has a standard name (CSHelp.txt) but if you know that the file you are importing
uses a different name you can enter it here.

Winhelp files (compiled and project files)

There are no special settings for importing Winhelp files.
You will get much better results if you import Winhelp project source files (.hpj project
file and other accompanying files). Compiled .hlp files do not contain all the information
needed for recreating Winhelp projects.

Word RTF files

There are no special settings in the import wizard for importing RTF files. However, you
do need to plan the content of your RTF files in order to get the best results.
Save RTF files with Word before importing
If you experience problems with RTF files not created with Word try loading them into
Word and then re-saving them before importing.
Automatic topic generation
The importer splits the contents of RTF files into topics automatically if possible, using
one of two methods:
Standard Word Heading1 - Heading 9 styles:
If your RTF file uses the standard Word Heading 1 ... Heading 9 styles each heading with
one of these styles will start a new topic. Subtopics will be created automatically on the
basis of the heading levels. Each heading must be followed by at least one paragraph of
text, otherwise it will be ignored.
Hard page breaks:
If your file does not use Heading 1 .. Heading 9 styles new topics are created at hard
page breaks. No subtopics are created with this method.
Graphics in RTF files
Graphics embedded in RTF files do not have names, they only have sequential numbers,
starting with 1 in every RTF file. This means that if you import two RTF files to separate
projects their graphics will have identical names. This will cause conflicts if you ever want
to use both projects in a modular project.
Solution 1: Import all RTF files to the same folder:
If you select the same output folder for all new projects created from RTF files the names
of the imported images will be incremented automatically. You must use the compressed
format (.hmxz) for saving your new projects when you use this method. A message will
be displayed warning you that the folder you are saving to is not empty – this is OK.
Solution 2: Import all RTF files to a single project:
After importing the first RTF file to a new project with New, click on the Application Button
and select Import for the next files. The topics will be inserted at the current position in
the TOC and the image file names will be incremented automatically.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 107

RoboHelp X5 projects
Here too, the importer needs to know how to deal with the different parts of the HTML
topic pages. You can improve the import performance with the settings in the HTML
Import Options page of the wizard.
Topic header:
Getting the header information from the <title> tag will usually work. If your topics have
a separate header block you may need to specify a different tag. If in doubt check the
HTML source code of the files in your RoboHelp project.
Single-column tables:
Some topic pages are enclosed in single-cell/single-column tables, which can cause
undesirable results when you import them. You can solve these problems with the option
for converting such tables to single paragraphs.
Graphics files:
The graphics files from the RoboHelp project are not imported to the new project
directory. Instead, Help & Manual adds the current location(s) of the graphics files to the
image folders list in the Configuration > Common Properties section of your project. You
can move the image files after importing if you want just change the folder entries in the
Image Folders list accordingly after doing so and Help & Manual will then be able to find
them.

Integrating imported formatting in your H&M stylesheet

Text imported from external sources is all tagged as "manually formatted" with inline
formatting, not with styles. You can integrate this formatting into your Help & Manual
stylesheet with the Create Style from Selection and Replace Styles functions.
For instructions see Replacing Formatting and Styles 497 .

4.3.5 Merging HTML files into topics

In addition to importing HTML and text files you can also use a command that enables you
to merge external HTML files into existing topics at publish time. This can be very useful if
you have material that changes frequently – you can maintain it in an external HTML file and
automatically merge the latest version into your project when you compile.

Key Information
This only works in HTML-based output
formats. Merged HTML files are not
included in Winhelp, PDF, printed manuals
and MS Word RTF output.

Preparing the external HTML files for merging

1. Open the external HTML file in an editor.
2. Locate the opening <body> tag and delete it and everything that comes before it.

© 1997 - 2009 by EC Software, all rights reserved

 108 Help & Manual 5 - User Help

3. Locate the closing </body> tag and delete it and everything that comes after it.
4. Save the file in the project folder with the .HTM or .HTML extension.
It is important to understand that the #MERGE command injects the entire external
HTML file into the position in the topic where you insert the command. This means that it
is advisable to remove everything in the external file outside the opening and closing
<body> and </body> tags before merging.
The topic page already has its own header section and <body> tags, and if you don't
remove this material from the external file you will have double header information. This
may work, but it is not recommended because it can and will cause problems in some
situations.

Inserting the #MERGE command

1. In the Help & Manual editor click in the position in the topic where you want to insert
the contents of the external HTML file. The topic can be empty but it does not have to
be. The #MERGE command inserts the contents of the file into the current topic
without deleting anything.
2. Select the Insert HTML Code Object tool in Write > Insert Object and type the
following code in the editing window:
#MERGE filename.htm
This assumes that the HTML file is in the project directory (i.e. the directory containing
your Help & Manual project). You must include the path to the file if it is stored
somewhere else. However, the files you import must be installed on your local file
system. You cannot import files from the Internet using http:// references with the
#MERGE command.

See also:
Inserting plain HTML code 231

4.4 Creating Topic Files

Topics are the main components of your project. Each topic is a separate file, which is like a
word processor document. These files are stored inside the main project file if you use the
single-file .hmxz format and in your project folder if you use the uncompressed .hmxp
format. (Help & Manual Standard uses the compressed format only.)

Topic files are managed in the Project Explorer

Topic files and your Table of Contents are managed in the Project Explorer. Before
starting with this chapter, please study the chapter Using the Project Explorer 41 it
contains important information that you need to be familiar with before you start working
with topic files.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 109

4.4.1 About topics and the TOC

The text and other content in your projects is organized in "topics". Each topic is stored in a
separate file in the Project Files section in the Project Explorer.

Key Information
Creating a new topic in the TOC creates a
TOC entry and an associated topic file in
the Project Files section. Creating a topic
in the Project Files section creates a topic
file without a TOC entry.

About topics, TOC entries and topic files

A topic is like a word processing file; it is a document dealing with one subject and it is
generally represented by one entry in your Table of Contents (TOC).
Each topic is stored in a separate file stored inside your project. The entries in the TOC
are actually separate from your topic files. The TOC entry is really just a link pointing to a
topic file.
Creating topics in the TOC:
When you create a topic in the TOC you automatically create a TOC entry and a topic file
in the Topic Files section of the Project Explorer. When you click on the TOC entry the
topic file is displayed for editing automatically.
Creating topics in the Topic Files section:
If you create a topic in the Topic Files section of your project it will not have a TOC entry.
Topics without TOC entries are used for popup topics, topics displayed only by hyperlinks
and topics used as snippets 102 (reusable content that you insert in other topics).
How topics are managed in your projects:
Although your topics are all separate files Help & Manual manages your project as
though it was one big file for some functions. For example, you can perform global search
and replace operations on all the topics in your project and your formatting styles also
apply to all your topics.

The Table of Contents (TOC)

The Table of Contents (TOC) in the Project Explorer is a representation of the structure
of the TOC in your finished documentation. The TOC is used to organize your project into
chapters and sub-chapters. In the Project Explorer it works like an outliner, allowing you
to move topics and chapters around and change your structure quickly and easily.
Topics included in the TOC are listed both in the Table of Contents section and in the
Project Files section of the Project Explorer. The Project Files section shows all the files
in your project, the TOC only shows those files that will actually appear in the table of
contents of your documentation.
See Managing Topic Files and the TOC 199 for information on working with topic files in
the Project Explorer.

© 1997 - 2009 by EC Software, all rights reserved

 110 Help & Manual 5 - User Help

See also:
Managing Topic Files and the TOC 199
4.4.2 Creating new topics in the TOC
You create a new topics in two places: In your project's Table of Contents (TOC) or the
Project Files section. Creating a new topic in the TOC creates a TOC entry and a topic file
and links the TOC entry to the topic file. Creating a new topic in Project Files creates a topic
file without a TOC entry.
The instructions below explain how to create topics with TOC entries. See Creating new
topics in Topic Files 112 for instructions on creating topics without TOC entries.

Key Information
If you save in compressed single-file mode
(.hmxz) all your topic files are stored inside
your compressed project file and can only
be viewed in the Project Explorer. The
Standard version of Help & Manual can
only save in compressed mode.

How to create a single new topic in the TOC

Normally, you will want your topic files to have entries in your Table of Contents (TOC).
Topic files that you create in the TOC section of the Project Explorer automatically have
TOC entries.
1. Click in the TOC in the Project Explorer at the position where you want to add your
new topic.
2. Select Project > Add Topic and choose an Add Topic option OR
Right-click to display the context menu and then select an Add Topic option
3. This displays the Insert New Topic 581 dialog:

· Select Topic/Chapter create a normal topic with content.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 111

· The Chapter without Text option creates a TOC entry that is only used as a chapter
heading for a group of sub-topics.
· Note that chapters with text are not supported in Winhelp. When you compile to
Winhelp a sub-topic with the same name as the chapter with text will be generated
containing the texts of the chapter.
4. Type your title in the Topic Heading: field (this is the title that appears in the TOC).
The Topic ID is generated automatically and is initially based on the caption you enter.
You can edit the automatically-generated topic ID if you like see Topic IDs and
context numbers 205 for more details.
See the Insert New Topic 581 for details of the settings displayed by More . Note that
you cannot select Popup as the Topic Class when you are adding topics to the TOC.
Popups should not have TOC entries so you must create popup topics in the Topic
Files 112 section.
5. Click on OK to create the topic.
Initially the header of the topic above the editing area will be identical to the caption. If
you edit the caption in the TOC the header will change with the caption. However, if you
edit the header this will turn off the "link" between the caption and the header. Any
changes made to the caption after this will no longer be reflected in the header.

Creating a topic by Drag & Drop

You can also create a new topic by dragging & dropping text to the Table of Contents
(TOC), in the same way that you create hyperlinks:
1. Select the text in a topic that you want to use for the topic caption.
2. Drag the text into the TOC between two topics, in the position where you want the new
topic to be inserted.
A blue line is displayed between the TOC entries in the position where the new topic
will be inserted.
3. Let go of the mouse button. A new topic will be created with the selected text as the
caption.

Creating multiple topics

1. Proceed as described above for creating a new topic.
2. In the Insert New Topic 581 dialog select the Multiple Topics option.
3. Enter captions in the Item Captions editing box. Use the indent tools on the right to
indent captions, which makes them sub-topics of the topic above them. The button
un-indents captions. You can also use the TAB key to indent entries to turn them into
sub-topics.

© 1997 - 2009 by EC Software, all rights reserved

 112 Help & Manual 5 - User Help

4. Click on OK to create the topics.

Note that when you use this method the topic IDs are all generated automatically from the
topic captions. You can edit the IDs 205 afterwards if you want.

Using templates for new topics

You can use content templates for topics to automatically insert a basic layout, including
any content (text, graphics, tables etc.) when you create a new topic. If you have already
created one or more topic content templates in your project directory you can select them
when you create the topic.
· Click on More in the Insert New Topic 581 dialog and select the template you want to
use in the Topic Template: field.
· Templates will only be defined if you have created them by saving topics in your project
directory as XML template files, using the naming syntax topicname.template.xml,
with the File > Save Topic to File in Project > Manage Topics.
See Content templates for topics 423 for full details on creating and using topic content
templates.

See also:
Insert New Topic 581 (Reference)
Topic IDs and context numbers 205
Content templates for topics 423
4.4.3 Creating new topics in Topic Files
When you create a new topic in your project's Project Files section you just create a topic
file, without an entry in the Table of Contents (TOC). Topics like these are used in electronic
help formats for information that is only displayed when the user clicks on a link for
example popup topics and topics displayed in external windows.
Topics without TOC entries are also used for content that you want to insert in multiple
locations in your project with Help & Manual's snippets 102 function.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 113

The instructions below explain how to create topics without TOC entries. See Creating new
topics in the TOC 110 for instructions on creating topics with TOC entries.

Key Information
If you save in single-file compressed mode
(.hmxz) all your topic files are stored inside
your compressed project file and can only
be viewed in the Project Explorer. The
Standard version of Help & Manual can
only save in compressed mode.

How to create topic files without TOC entries

By default, topics with TOC entries are created in the Topics folder in the Topic Files
section. It is advisable to create additional folders for topic files without TOC entries to
keep them separate. Follow the instructions below to create folders for your topic files.
1. Select Topic Files in the Project Files section of the Project Explorer, then select the
folder where you want to create your new topic file.

2. Select Add File > Add New File in Project > Manage Topics.
3. This displays the Insert New Topic 581 dialog in file mode:

4. You can create multiple topic files with this dialog. Type one or more names for the
topic files you want to create, one name per line.
5. Click on More for additional settings. See Insert New Topic 581 for details of these

© 1997 - 2009 by EC Software, all rights reserved

114 Help & Manual 5 - User Help

settings.
6. Click on OK to create the new topic file(s).
The file names and topic IDs for the new files will be generated automatically from the
names you enter. Spaces in your names will be converted to underscore characters.

How to create new folders for topic files

All your topic files are stored in the Topic Files section of your project, including the topic
files with TOC entries that you create in the TOC (which is really a list of links to the files).
By default, files with TOC entries are stored in a folder called Topics. It is advisable to
create additional folders for your files without TOC entries to keep them separate from
the TOC topic files.
1. Select Topic Files in the Project Files section of the Project Explorer.
2. Select Add File > Add New Folder in Project > Manage Topics.
3. Enter a name for the new folder and click on OK.
You can also access the Add File/Folder options by right-clicking in the Topic Files
section.

Using include options for topics without TOC entries

You can use conditional output include options for topic files in the same way that you
can for TOC entries to include or exclude the topic files from your output when you
compile. For more details on using include options see Conditions and Customized
Output 399 .
· Select the file you want to apply include options to in the Explorer and select Change >
Include in Builds in Project > Manage Topics, then select the options you want to
apply.
· Alternatively you can also right-click on the file to edit its include options.
Excluding the source files of snippets:
You should always exclude the source files for snippets 149 (both linked and pasted) from
your output using include options. Since the snippets are just copied from the source files
you don't want to include the source files themselves in your published output if you did
the user would be able to find them with search, which is not what you want.

How to add a TOC entry to a topic file

Sometimes you may decide that you would like to add a TOC entry to a topic file that
does not yet have one. To do this you just need to create a new entry in the TOC and
specify the Topic ID of the topic file.
1. Select the topic file you want to create a TOC item for and open the tab behind the
editor.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 115

2. Copy the Topic ID to the Windows clipboard.

3. Move to the Table of Contents section in the Project Explorer, click where you want to
insert the new TOC item and select Add Topic in Project > Manage Topics.
4. Select Topic/Chapter on the left and enter a heading for the topic.
5. Paste the topic ID you copied in step 2 In the Topic ID: field and then click on OK.
You will be asked if you want to create a new item for an existing topic. Confirm to create
the new TOC item.

How to delete a TOC entry without deleting the topic file

You can delete a topic's TOC entry without deleting the topic file. This turns a TOC topic
into a topic without a TOC entry.
1. Select the topic in the TOC (you can also use Ctrl+Click and Shift+Click to select
multiple topics).
2. Press DEL or right-click and select Delete Topic.
3. In the dialog displayed deselect the Also delete referred topic files option and click on
Delete Topics.

Auto-generating topic files

If your programmer can generate a "map" file containing a list of the topic IDs and context
numbers you can automatically generate any missing topics with the Context Tool in the
Project tab. See Auto-generating topic files 375 for details.

See also:
Insert New Topic 581 (Reference)
Creating popup topics 125
Organizing invisible topics 210
Using Context-Sensitive Help 369
4.4.4 Creating topics from other sources
In addition to creating new topics into which you enter new content you can also create TOC
entries that display content from other sources when the user clicks on the TOC entry.
You can create TOC entries that link to web pages or to topics in other help files that are
available when the user views the help.
You can also insert entire Help & Manual projects in your TOC. When you publish your
project the external projects are merged with the main project.

Productivity Tip
You can also use Snippets 102 to insert
topics and XML files from other sources
into existing topics. Snippets can be
inserted as editable copies or linked to the

© 1997 - 2009 by EC Software, all rights reserved

116 Help & Manual 5 - User Help

source files so that they update

automatically when the sources are edited.

Linking a TOC entry to a topic in an external help file

This option does not create a topic file. Instead, it creates a TOC entry that links to a topic
in an external help file, which can be either a Winhelp .hlp file or a HTML Help .chm file.
This only works in Winhelp and HTML Help output! Such topics will be empty in other
output formats and should be excluded from those formats with conditional output 402
options.
1. Select an Add Topic option to create a new topic.
2. In the Insert New Topic 581 dialog select the Jump to External Help option.
3. Use the Browse button in the Help File: field to navigate to the external help file. You
can select topics Help & Manual projects or in compiled .chm or .hlp files. (Type *.
hlp or *.chm in the File name: field of the Open dialog to display these files.)
4. Then use the Browse button in the Topic ID: field to select the ID of the topic you
want to link to.
5. Then click on OK to create the new topic.
The .chm or .hlp help file containing the topic you link to must be present in the same
directory as the help file containing the link, otherwise the topic will not be displayed. You
can only link between the same types of help files you cannot link to a .hlp file from a
.chm file or vice-versa!

Linking a TOC entry to a web page

This method only works in HTML-based output formats. You cannot include web pages in
your help in Winhelp or PDF, for example.
1. Select an Add Topic option to create a new topic.
2. In the Insert New Topic 581 dialog select the Web Link option.
3. Enter the URL of the web page in the Target Address: field. See Insert New Topic 581
for details on the available settings.
You must enter a fully-qualified URL including the http:// protocol identifier. For
example, http://www.ec.software.com/ will work but www.ec-software.com will
not work.
4. Click on OK to create the new topic. The web page will only be displayed in your
published output and only when you have an active connection to the Internet.

Inserting an entire Help & Manual project

In addition to topics you can also insert entire Help & Manual projects in the TOC, thus
merging the two projects.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 117

1. Select an Add Topic option to create a new topic.

2. Select Include Help Project in the Insert New Topic 581 dialog and select the project you
want to insert.

Merge content on publishing: If you select this mode the external project's contents
will be displayed in the TOC of the current project and can be edited directly. Merged
projects are still stored externally and their topics are identified by small green icon in
the TOC.
Merge content at runtime: This is for HTML Help and Winhelp only and just inserts a
placeholder in the TOC. The projects must be edited and published separately and are
only merged when the user views them if the help files are all present in the same
folder.
Publishing merged projects:
In most output formats the projects will be merged into one large help system when you
publish your output. In HTML Help and Winhelp you can also create separate help files
that are displayed in a single Table of Contents when the user opens the main help file.
This makes it possible to create different versions of your help just by including or
excluding help files in your distribution package.
See Working with Modular Help Systems 446 for full details.

See also:
Working with Modular Help Systems 446
4.4.5 Editing the topic caption and header
The topic caption is the title of the topic displayed in the TOC, both in Help & Manual and in
your output. For example, captions are displayed as the TOC titles in the Contents pane of
the HTML Help viewer and the Winhelp viewer and the Contents page of a PDF file.
When you create a new topic the caption text is duplicated in the topic header, which is the
title displayed in the editing box above the topic itself. The header is also displayed in your
output, for example above the topics in the HTML Help and Winhelp viewers.

© 1997 - 2009 by EC Software, all rights reserved

118 Help & Manual 5 - User Help

How to edit the caption (title) of a topic in the TOC

1. Click on the topic in the TOC.
2. Press F2 or wait a second or two and click again ("slow" double-click) or click on the
Edit Caption button in Project > Manage Topics.

3. Edit the caption and then press Enter to finish

Editing the topic header separately

When you create a new topic its caption is automatically duplicated in the topic header. If
you only edit the caption the header is also updated automatically so that the caption and
the header remain identical. However, if you want you can also make the topic header
different for example so that you have a short caption for the TOC and a longer, more
descriptive header.
· Click in the header box above the Page Editor end edit the header text. When you do
this the header and the caption are no longer linked and can then both be edited
separately.

· To "re-link" the caption and the header again just make the text in both identical again.
Then the header will automatically be updated when you edit the caption in the TOC.

How to turn off the header

To turn off the header for a topic just deselect the Topic has a separate header checkbox
below the topic editor on the left. This will create a topic without a header in your
published output.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 119

Warning:Turning off the header deletes any additional content you have added to the
header box. If you turn the header on again the box will only contain the standard topic
title, taken from the topic's TOC entry. The content will not be lost while you are still
editing the current topic (you can restore it by reactivating the checkbox) but once you
leave the current topic it will be deleted permanently.

See also:
Topic headers 119
4.4.6 Topic headers
By default, new topics always have a
"header", displayed in a separate editing
box above the main topic editor. You can
turn the header off if you want, creating
topics without headers.
Initially, this header contains the title of the
topic, formatted with the standard Heading1
style and with the background color set in
the HTML topic page template. You can
also add other content, including graphics,
hyperlinks etc.
Header formatting, background colors and
additional content are only supported in
electronic help formats (HTML Help,
Webhelp, eBooks, Winhelp and Visual
Studio Help). ePub eBooks have limited or
no support for additional content. In print-
style formats (PDF, RTF, printed manuals)
only the plain text from the header is
exported when you publish and the
formatting is defined separately.

© 1997 - 2009 by EC Software, all rights reserved

120 Help & Manual 5 - User Help

How to format the header text and background

Formatting the header text:
By default the header text has the standard Heading1 style. The easiest way to format
your header text is to edit this style in Write > Styles > Edit Styles. Then all new
headers will automatically have the selected formatting. You can format headers
manually by selecting the text and using the formatting tools in the Write tab if you want,
but then you must do this separately for every single topic.
Setting the header background color:
In most electronic output formats the header background color is defined by the HTML
topic page template. In the Project Explorer go to Configuration > HTML Page
Templates and select the Default template. Then you can set the background colors for
the header and the topic body. The background colors you set in the template are
automatically displayed in the editor.
The obsolete Winhelp format stores its background colors in its Main help window
definition. To set the background colors for Winhelp go to Configuration > Common
Properties > Help Windows. Select the Main help window at the top of the dialog,
then select the Winhelp Options tab and set the background colors. The background
colors you set for Winhelp are only displayed in your published Winhelp files
See Background colors and help viewers 93 for more details on this.

How to turn off the header

To turn off the header for a topic just deselect the Topic has a separate header checkbox
below the topic editor on the left. This will create a topic without a header in your
published output.

Warning: Turning off the header deletes any additional content you have added to the
header box. If you turn the header on again the box will only contain the standard topic
title, taken from the topic's TOC entry. The content will not be lost while you are still
editing the current topic (you can restore it by reactivating the checkbox) but once you
leave the current topic it will be deleted permanently.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 121

Additional content in the header

You can insert any content in the topic header box that you would normally insert in the
main body of the topic, including graphics, hyperlinks and so on. This content will be
published with the header in electronic formats (HTML Help, Webhelp, eBooks, Winhelp
and Visual Studio Help) but not in print-style formats (PDF, RTF, printed manuals).
Note that content added to the header will only be displayed in the current topic. If you
want to include the same content in every topic (for example a logo) you need to edit the
HTML topic page template and add the content to the header section of the template.
See Using HTML Templates 430 for more details.
If you want to include additional with your headers in PDF and printed manuals you need
to add it to the header definitions in the print manual template see PDF & Printed
Manuals 325 for details.

Topic headers in PDF, RTF and printed manuals

The topic header and its formatting and background color are not exported or used in
PDF, RTF and printed manuals. In these formats only the plain text topic title is exported,
the formatting is applied with the print manual template for PDF and printed manuals and
with the options in Configuration > Publishing Options > Word RTF for RTF.
In RTF only the header text from the TOC topic title is used. In PDF you can use either
the TOC topic title or the text from the topic header (if it is different). This is done by
selecting either the <%HEADINGx%> variables in the template for the TOC topic title or the
<%HEADINGLONGx%> variables for the text from the header box.
See PDF & Printed Manuals 325 for details on accessing and editing print manual
templates for PDF.

See also:
Background colors and help viewers 93
Using HTML Templates 430
PDF & Printed Manuals 325
4.4.7 Using help windows
The Microsoft HTML Help (CHM) and Winhelp (HLP) formats use sets of definitions called
"help windows" to configure the appearance, size and behavior of the Windows help viewers
used to display these formats. In addition to this they can also be used to display individual
topics in external windows.
Changing the definition of the default help window, which is called Main, adjusts the help
viewer features. You can also define additional "secondary" help window types, which can
have different features. These help windows are used for opening specific topics in external
windows when you link to them. You do this by specifying a different help window type when
you define the hyperlink.

Key Information

© 1997 - 2009 by EC Software, all rights reserved

122 Help & Manual 5 - User Help

Help window settings are only relevant for

HTML Help and Winhelp output, where the
control the appearance and behavior of the
Microsoft help viewers for these formats.

How to change the features of the help viewers

The definition of the default Main help window type controls the size, appearance and
controls of the help viewers for HTML Help and Winhelp.
You can change these settings with the Main help window definition in Configuration >
Common Properties > Help Windows. The common settings define the position and
size of the help viewer, the Winhelp Options and HTML Help Options tabs define the
features and behavior of the help viewer in each format.
See Background colors and help viewers 93 for more details and Help Windows Settings
660 in the Reference section for information on the individual settings. .

How to create, delete and edit help window types

1. Select Configuration > Common Properties > Help Windows >
{WindowName}
2. Add creates a new secondary help window type, Remove deletes the current window
type (you cannot delete Main). For more information see Help Windows 807 and Help
Windows Settings 660 in the Reference section.
3. Edit the attributes to change the properties.

How to display topics in external windows

In HTML Help and Winhelp you can use additional help window definitions to display
topics in external windows when they are opened with hyperlinks. Topics can only be
displayed in external windows in these two formats and the help window settings have no
effect in other help formats.
Important: Help window types can only be used in hyperlinks.
You cannot directly associate a help window type with an individual topic and you cannot
set a topic in the TOC to open in an external window when you click on its TOC entry.
HTML Help:
1. In the Project Explorer go to Configuration > Common Properties > Help
Windows and create at least one secondary help window type definition with Add.
Adjust the settings of the window definition as you want the external window to appear
in addition to the size and position you may want to switch off navigation controls
etc. in the help window definition's HTML Help Options tab.
2. In the HTML Help Options tab activate the option Links to secondary help windows
open a new help window.
3. When you create a hyperlink to a topic specify the secondary help window type with

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 123

the Window: setting in the link definition.

When the user clicks on the hyperlink the target topic it will now be displayed in an
external window in HTML Help, with all the settings defined for the window type in step 1.
Winhelp:
No special settings are required for Winhelp because links to secondary windows always
open in external windows in Winhelp. Just specify a secondary window in the hyperlink
definition, then the hyperlink will open the target topic in an external window.

Topic and header background colors

The help window definition only controls the background color of the topics and headers
in Winhelp. In all other electronic output formats the background colors are controlled by
the HTML page template 123 (you cannot set page and header background colors for PDF,
RTF or printed manuals).
See Background colors and help viewers 93 for more information on how to set
background colors.

See also:
Help Windows 807
Help Windows Settings 660
Using secondary windows 429
HTML templates 427
4.4.8 Using HTML page templates
Each topic in your project is also associated with an HTML page template, which defines
everything in your topic pages outside of the main body of your topics in HTML-based output
formats (HTML Help, Webhelp, Windows Exe and ePub eBooks, Visual Studio Help). HTML
page templates are irrelevant for Winhelp, PDF, RTF and printed manuals.
New projects only have one HTML page template called Default, which is automatically
assigned to every new topic. You can create as many additional templates as you like and
assign them to individual topics in the tab behind the main editor window.

Key Information
HTML page templates are only relevant for
HTML-based output formats. They are
ignored in all other output formats.

Topic and header background colors

In all HTML-based output formats the background colors of the topic and topic header are
defined in the HTML page template. The colors you define in the template are also
automatically displayed in the Help & Manual editor.
· In the Project Explorer go to Configuration > HTML Page Templates > Default
and set the background colors for the topic and topic header.

© 1997 - 2009 by EC Software, all rights reserved

124 Help & Manual 5 - User Help

· If you edit the HTML code of the template manually you can also set the header and
background colors manually. The topic background color is set in the <body> tag, the
header background color is the background of the main table in the section defined by
the <IF_TOPIC_HEADER> condition.
The background colors in the obsolete Winhelp format are defined in the help window
settings 121 for Winhelp and are not displayed in the editor.

Navigation link texts or buttons

By default every topic in HTML-based output formats has Top, Previous and Next
navigation links. These links can be deactivated and edited in the HTML page template
and replaced with icons.
· In the Project Explorer go to Configuration > HTML Page Templates > Default
and edit the settings for the Top, Previous and Next Links in the Simple Template
Layout tab.
· If you edit the HTML code of the template directly you are completely free to make any
additions you like. For example you could create icon buttons with mouseover effects
and so on.
If you use icons for your navigation links it is a good idea to add the icon files to your
Baggage Files in the Project Files section of the Project Explorer. This will ensure that the
icons are exported correctly when you publish your output.

Adding headers and footers to your pages

You can also add "headers" and "footers" to your HTML page templates to display
standard text, icons, logos or links above or below the main body of your text on every
topic page.
Simple template layout tab:
1. In the Project Explorer go to Configuration > HTML Page Templates > Default
and select the Simple Template Layout tab.
2. Insert text for your header or footer in the Text Above Topic or Text Below Topic
boxes. You can also use HTML code, CSS formatting and JavaScript.
HTML source code tab:
If you have experience with editing HTML you can also edit the HTML code directly.
1. In the Project Explorer go to Configuration > HTML Page Templates > Default
and select the HTML Source Code tab.
2. The topic content from your project is inserted in the template with the <%TOPIC_TEXT%
> variable. Everything directly above this variable is a "header", everything below it is a
"footer".
See Using HTML Templates 430 for more details.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 125

Defining and using different HTML templates for individual topics

By default every topic you create is associated with the Default template. You can also
create additional HTML page templates with different settings and apply them to
individual topics for example to use different topic and header background colors or
different navigation buttons etc. in some topics.
Creating new HTML templates:
1. In the Project Explorer go to Configuration > HTML Page Templates > Default
and click on the Add button.
2. Enter a name for the template and click OK.
3. Edit the code of the template as you wish.

Applying HTML templates to individual topics:

1. In the Project Explorer select the topic you want to change.
2. Select the tab, then select the template in the HTML Page Template: field.

See also:
Help window settings 121
Using HTML templates 430
4.4.9 Creating popup topics
Popups are mini-topics used to display a small amount of information in a small "popup”
window, which is normally displayed when the user clicks on a link. Popups are used both in
the help text itself and in applications, where they are referred to as "field-level popups".
However, field-level popups are a special Microsoft technology that is only supported in
HTML Help and Winhelp.
Topics used as popups should be created in the Project Files section so that they do not
have TOC entries. For more details on field-level popups see Using Context-Sensitive Help
369 and Context-Sensitive Help and Popups 788 .

How to create a popup topic

1. Open the Project Files section In the Project Explorer and click on Topic Files, or a
subfolder if you have created one and want to use it (see Creating new topics in Topic
Files 112 for more details).
2. Click on Add File in the Project tab to create a new topic.
3. Click on More and select Popup In the Topic Class: field. Note that you cannot select
this class when creating topics in the TOC!
4. If you plan to use the popup topic as a plain-text popup in HTML Help you must give it
a help context number. This is required by the Microsoft HTML Help API and the topic
will not be exported correctly without it.
Topics with the Popup class will automatically open as popups when you link to them.

© 1997 - 2009 by EC Software, all rights reserved

126 Help & Manual 5 - User Help

The HTML Template setting is irrelevant for these topics because popups do not use
HTML templates.
When you create hyperlinks to popup topics 215 in your help they will automatically be
displayed as popups. See Using Context-Sensitive Help 369 for information on calling
popups directly from your application.

Configuring your output formats to use popups

How popup topics are handled depends on your output formats. Some formats support
more than one popup style, which must be specified in your Project Configuration
settings.
HTML Help:
In the Project Explorer select Configuration > Publishing Options > HTML Help and
click on Popup Topics.
· Text-only popups are the native HTML Help popup mode. They support plain text only
(no hyperlinks, no graphics, no tables, no text formatting). This is the only popup mode
that supports field-level popups in HTML Help. Popup topics used in this mode must
have help context numbers.
· JavaScript Popups are generated by Help & Manual. They support formatting, links
and graphics but they cannot be used as field-level popups. They can only be displayed
within your help file by other links in your help file.
· HTML encode topics are not popups at all. When this option is selected all popup
topics will be opened as normal topics in the main help viewer, using the HTML
template assigned to the popup topic.
Winhelp and eBooks:
Winhelp and Windows Exe eBooks have no special popup topics settings. Popups are
not supported in ePub eBooks.
Winhelp: There is only one popup mode in Winhelp, which supports both popups
displayed in the help and field-level popups. Winhelp popups support hyperlinks, graphics
and formatting. However, Winhelp is obsolete and is not supported by default in Windows
Vista.
Windows Exe eBooks: eBooks popups are similar to Winhelp popups and can only be
displayed inside the eBook viewer.
Webhelp:
In the Project Explorer select Configuration > Publishing Options > Webhelp and
click on Popup Topics.
· JavaScript Popups are generated by Help & Manual. They support formatting, links
and graphics but they cannot be used as field-level popups. They can only be displayed
within your help file by other links in your help file.
· HTML encoded topics are not popups at all. When this option is selected all popup
topics will be opened as normal topics in the main help viewer, using the HTML
template assigned to the popup topic.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 127

Controlling the width of popup topics

In both Winhelp and HTML Help the width of popup windows is controlled by the help
viewer on the basis of the amount of text in the popup and the user's screen width. Since
this system was designed a long time ago it does not allow for modern computers with
wide-format screens and multiple monitors. When normal popups are displayed on these
computers the popups can be much too wide, which looks terrible.
Controlling popup width in HTML Help:
· In HTML Help's plain text popup topics the only way you can control popup width is by
entering a hard line break (ENTER) at the end of each line.
Controlling popup width in Winhelp and JavaScript popups:
· In WinhelpNote that Windows Vista does not support Winhelp. If you want to be compatible with Vista
you must transition to a different help format. and JavaScript popups 129 you can control popup
width precisely by entering the entire text of the popup in a single-cell table with a fixed
width. (Note that this doesn't work in HTML Help's native plain text popups because the
table and its contents are stripped when you compile, resulting in an empty topic.)
· Note that you must set the width of the single-cell table you use for this to an absolute
value in pixels. Select Size Table Manually and enter the value in pixels. Don't use
percent for this, it won't work properly!
You can speed up the process by defining a topic content template for your popup topics.
See Content templates for topics 423 for details.

Linking to popup topics from other topics

Any link within a project to a topic defined with the Popup class will automatically be
displayed as a popup in any of the output formats where popups are supported (Winhelp,
HTML Help, Windows Exe eBooks and Webhelp with JavaScript popups activated). Just
create a normal link 215 to the topic. Popups are not supported in ePub eBooks.

Linking to a popup topic from your application

This is basically a job for the programmer, not the help author (you may be both, of
course). All the help output formats generated by Help & Manual are fully standard-
compliant so you can use the standard procedures for linking to and calling popups.
HTML Help's plain-text popups:
· When you export to HTML Help with native, plain-text popups Help & Manual stores the
popup text topics in an internal text file in the HTML Help CHM file. By default this file is
called CSHelp.txt, but you can change this file name in Configuration >
Publishing Options > HTML Help > Popup Topics.
· Plain text popup calls from your application must be made to this file within the CHM file
using the standard popup syntax of the HTML Help API.
· Plain text popup topics used in HTML Help must have context numbers! This is

© 1997 - 2009 by EC Software, all rights reserved

128 Help & Manual 5 - User Help

required by the Microsoft HTML Help API for popups and if your popup topics do not
have help context numbers they will not be exported to the internal popup text file in the
CHM.
Winhelp popups:
· WinhelpNote that Windows Vista does not support Winhelp. If you want to be compatible with Vista you
must transition to a different help format. popup topics are stored in the main Winhelp HLP
file.
· Popup calls from your application must be made directly to the HLP file using the
standard popup syntax of the Winhelp API.
Tutorials for interfacing between your help and your application in the most common
programming languages are available on the tutorials page at the EC Software
website. A free set of tools for interfacing to help and context-sensitive help Borland
Delphi and Borland C++ is also available at the website, on the Delphi resources page.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 129

Where popups are supported

Output Format Supported Popup Types Where Supported

HTML Help (. · Plain-text popups integrated in Plain-text popups are

CHM): the main help file. Context supported both in the help
numbers are required for these text and as field-level popups
popup topics! in applications.
· Formatted JavaScript popups 129 Formatted JavaScript popups
stored in the main help file. can only be used in the help
text. They are not supported
for context-sensitive help.
Winhelp (.HLP): · Fully-formatted Winhelp Winhelp popups are
popups stored in the main help supported both in the help
file. text and as field-level popups
in applications.
Browser-based · Fully-formatted JavaScript JavaScript popups can only
HTML popups 129 integrated in the be used in help topics. You
(.HTM): individual HTML files. cannot link to them from
your application.
Windows Exe · Fully-formatted popups with Only available within eBooks.
eBooks: graphics, fonts, emphasis eBooks do not support
(bold, italics etc.) and context calls of any kind.
hyperlinks (topic and Internet
links).
ePub eBooks: · Popups are not supported. N/A
Popup links are automatically
converted to plain text.
Adobe PDF and · Popups are not supported. N/A
printed user Popup links are automatically
manuals: converted to plain text.
Word RTF: · Popups are not supported. N/A
Popup links are automatically
converted to plain text.

See also:
Using JavaScript popups 129
Using Context-Sensitive Help 369
Context-Sensitive Help & Popups 788 (Reference)
4.4.10 Using JavaScript popups
JavaScript popups make it possible to create popups in Webhelp and in HTML Help you can
use them as an alternative to HTML Help's own native plain-text popups.
Advantages: JavaScript popups create fully-formatted popups that can contain
formatted text (bold, italic, different fonts etc.), graphics, hyperlinks
(both topic and Internet links) and even video and animation files. In

© 1997 - 2009 by EC Software, all rights reserved

130 Help & Manual 5 - User Help

addition to this they also support a range of cool graphical effects and
transitions (fade-in, transparency etc.) that are displayed in both
HTML Help and Webhelp. (In Webhelp these effects are only
displayed by Internet Explorer 5.5 and later.) In HTML Help
JavaScript popups are stored in the main help file so that you only
need to distribute one file.
Limitations: JavaScript popups cannot be used for field-level popups 794 called
from and displayed in applications. They can only be displayed within
the help file. Also, activating JavaScript popups is a global setting for
all the popup topics in your Invisible Topics section.

Using JavaScript popups in HTML Help

You can use JavaScript popups as an alternative to HTML Help's limited plain-text
popups. This gives you fully-formatted popups with support for hyperlinks, graphics and
even videos.
When you use this popup mode you cannot use the same project for your field-level
popups called by your application.
1. In the Project Explorer select Configuration > Publishing Options > HTML Help
and click on Popup Topics.
2. Select JavaScript Popups, then click on Customize JavaScript Popups to configure
your popups. See below for details.
3. Create your popup topic files 125 in the Topic Files section, selecting Popup as the
Topic Class. You can use all Help & Manual's formatting options, including tables,
hyperlinks, formatted text, fonts, graphics, videos and animations. Just don't go
overboard – if your popups are too large and contain too many features they will not
be very useful!
4. Create normal topic links to your popup topics in your topics. When you compile to
HTML Help the target topics will automatically be displayed as JavaScript popups.

Using JavaScript popups in Webhelp

Popups in Webhelp are only possible with JavaScript popups. This popup technology will
work in all current browsers and should not cause problems with popup blockers. In
addition to being blocker-transparent the popups are also activated by the user, which is
explicitly permitted by most blockers.
1. In the Project Explorer select Configuration > Publishing Options > Webhelp
and click on Popup Topics.
2. Select JavaScript Popups, then click on Customize JavaScript Popups to configure
your popups. See below for details.
3. Create your popup topic files 125 in the Topic Files section, selecting Popup as the
Topic Class. You can use all Help & Manual's formatting options, including tables,
hyperlinks, formatted text, fonts, graphics, videos and animations. Just don't go
overboard – if your popups are too large and contain too many features they will not
be very useful!

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 131

4. Create normal topic links to your popup topics in your topics. When you compile to
Webhelp the target topics will automatically be displayed as JavaScript popups.

Configuring JavaScript popup options

JavaScript popups are fully configurable. Note that all the configuration options are global
for the current project you can only use one JavaScript popup configuration for all the
popups in the project. However, you can store separate JavaScript popup configurations
for HTML Help and Webhelp.
1. Select the JavaScript Popups option for HTML Help or Webhelp in .Configuration >
Publishing Options.
2. Click on Customize JavaScript Popups to display the configuration dialog. This dialog
is exactly the same for both HTML Help and Webhelp:

Click/ Displays the popup on user click or mouseover (i.e. as soon as the user
mouseover: moves the mouse pointer over the link). Be careful with using the
mouseover option as many users find this intrusive and it may also
trigger popup blockers in some browsers.

Minimum Setting this to 0 makes the popup width automatic, on the basis of the
width: amount of text and/or other content.
Setting it to any other value (in pixels) explicitly defines the width of the
popup. If the popup only contains text it will have the width you specify.
If it contains other content (graphics, videos) it will be at least as wide
as the specified width and wider if required by the content.

Border width: Enter 0 for no border, any value above 0 (in pixels) to draw a border
around the popup box.

Border The distance between the popup content and the border or edge of the
padding: popup (if there is no border) in pixels.

Background: The background color of the popup box.

© 1997 - 2009 by EC Software, all rights reserved

 132 Help & Manual 5 - User Help

Border color: The color of the border, if there is one.

Visual These effects are only supported by MS Internet Explorer. This means
effects: that they are available in HTML Help (which uses MSIE) and in
Webhelp when the user is using Internet Explorer. They are ignored by
all other browsers.
These effects are easier to see than to describe. Experiment! (Note
that the transition effects are only for opening the popup box. The
popups always close in the same way, no matter what effect you
select.)

See also:
Creating popup topics 125

4.5 Editing Topic Files

Entering, editing and formatting text in topic files in Help & Manual is very similar to working
in a modern word processor like MS Word. If you already know how to use a word processor
you have most of the skills you need to edit topics in Help & Manual.

See also:
Text Formatting and Styles 155
Numbered and Bulleted Lists 180
Links and Anchors 214
4.5.1 Writing and formatting text
For more detailed information on formatting text see Text Formatting and Styles 155 .

The editor tabs and the header box

The editor tabs:
The Help & Manual editor has two or three tabs, depending on the version of Help &
Manual you are using:

· The Page Editor tab is where you edit the content of your topic files. This is basically
just like a normal word processor. You can enter text, copy and paste, apply styles,

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 133

insert images etc. You can also use special help authoring features that a word
processor does not have.
· The tab provides access to settings that are saved separately for each individual topic,
including index keywords assigned to topics.
· The XML Source tab (Professional version only) allows you to view and edit the XML
source code of your topic. If you don't understand what you see here just ignore it!
The topic header box:
The box above the main editor area contains the topic header. This corresponds to the
header of topics in help files and supplies the titles of topics for PDF and other printed
formats. By default the header box contains the same text as the topic caption in the
Table of Contents but you can add additional text if you like. You can also insert graphics,
hyperlinks etc.

Editing and formatting tools

The editing and formatting tools are grouped in the Write tab of the Ribbon. Many of
these tools can also be selected with keyboard shortcuts. Select Program Options in the
View tab of the Ribbon to view and change all available keyboard shortcuts.

Applying formatting and copying, cutting and pasting work in the same way as in any
modern word processor.
· To format existing text manually you must first select it and then apply the formatting,
using a formatting tool or a style.
· If you select a formatting tool without selecting text (font, bold, underline, color,
background color etc.) it will apply from the cursor position onwards if you continue
typing.
· To delete the word to the left of the editing cursor press Ctrl+Backspace.
· See Text Formatting and Styles 155 for detailed information on formatting text and using
styles.

Preview mode for screen/print styles and font sizes

You can switch the editor display to show the styles definitions for screen output
(electronic help files) and print output (PDF, RTF and printed manuals). You can also
switch the editor's basic font sizes to emulate Windows' "large fonts" and "small fonts"
settings to check how your help will look on users' systems with these settings.
Note that different styles will only be displayed if you have actually defined different style
settings for screen and print output!

© 1997 - 2009 by EC Software, all rights reserved

134 Help & Manual 5 - User Help

Display buttons in the status bar:

See Help and print styles 175 for more information on using different style sets for different
output formats.

How to protect text against editing

Sometimes you want to make sure that text will not be changed or translated, particularly
when you are working on a project in a team.
· Select the text you want to protect, then click on the Protect Text tool in Write >
Font.
The text will be displayed with shading in the editor to show that it is protected. In the
XML file it will also be tagged with a translate="false" attribute to inform the translator that
you do not want it to be translated.

Navigating in the editor

Go to hyperlink: Hold down Ctrl and click on the link (double-clicking on links
opens the link editing dialog).
Word left/right: Ctrl+Cursor Left/Right
Next/previous topic: Ctrl+Cursor Up/Down
Other nav. controls: PgUp, PgDown, Ctrl+Home, Ctrl+End
Edit history: The buttons in the Quick Access Toolbar navigate through
the sequence of topics you have edited in the current session.
Keyboard shortcuts: Select Program Options in the View tab for a full list of all
available keyboard shortcuts. You can change the shortcuts and
assign your own shortcuts to most of Help & Manual's functions.
Display paragraph Click on the tool in Write > Paragraph or select Program
marks: Options in the View tab and activate Display paragraph and text
marks in the Editor tab.
Preview Windows Click on the 96/120 DPI button in the status bar at the bottom of
large/small fonts the program window to emulate Windows' small and large font
settings: modes in the editor. This is useful for making sure that your
layouts will work correctly with both settings.
Show Screen/Print Click on the Screen/Print button in the status bar at the bottom of
styles in the editor: the program window to switch between the style definitions for
screen output (electronic help files) and print style output (PDF,

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 135

printed manuals, Word RTF). This will only show any changes if
you have actually defined different styles for screen and print
output.

The XML Source editor

This tab is only available in the Professional version of Help & Manual and it is designed
for advanced users only.
Please don't edit anything in this tab unless you have plenty of experience in XML editing
and understand all the code. XML syntax is very strict and unlike HTML not even a single
mistake in the code is permitted!
You can find a detailed reference to the Help & Manual XML syntax in the
Helpman_XML_ref.chm file in the Help & Manual program directory.

See also
Formatting text manually 155
Text Formatting and Styles 155
Editing XML source code 154
4.5.2 The paragraph end mark
If you're used to working with a word processor like MS Word you will find that editing in
Help & Manual is slightly different. It's just as powerful, but the way it stores text formatting is
different, and you need to understand this.

The paragraph end mark does not store any formatting!

Word processors like MS Word store paragraph styles and formatting in the paragraph
end mark. In word processors like this you can format a paragraph by selecting the end
mark and applying formatting. Also, if you delete the paragraph end mark in these word
processors the formatting of the entire paragraph can "disappear".

You cannot select or format the paragraph end mark!

Help & Manual's paragraph end marks don't store anything, they are just carriage returns
marking the end of the paragraph. Instead, the formatting is associated with the entire
paragraph. Since the paragraph end mark contains neither formatting nor any other
information you cannot select it or format it.

Formatting is associated with the text.

In Help & Manual formatting is associated directly with the text and the entire paragraph.
When you apply formatting to text it is associated with every letter of the text. When you
apply a style 61 to a paragraph in it is associated both with the entire paragraph and with
every letter of the text it contains.

When you copy text all its formatting goes with it!
You will see this, for example, if you copy a passage of text from one paragraph to
another. If you then put your cursor in the copied text and look in the style selector 159 in

© 1997 - 2009 by EC Software, all rights reserved

 136 Help & Manual 5 - User Help

the toolbar you will find that it still has the attributes of the source paragraph. (You can
prevent this behavior by using the Paste as Text 601 tool in Write > Clipboard or
Ctrl+Shift+V.)
Paragraph formatting is only copied if you copy an entire paragraph, including all the text
in the paragraph down to the beginning of the next paragraph.

It's a slightly different way of working.

Once you get used to it you'll find that it's quite intuitive and also has its advantages. For
example, unlike Word you can't accidentally delete the formatting of an entire paragraph
by pressing DEL or BACKSPACE. If you ever accidentally join two paragraphs you just
need to press ENTER to separate them again. You may need to adjust the paragraph
formatting or reapply a style 61 to adjust the paragraph formatting, but that's it.
When paragraphs are joined the program automatically uses the paragraph attributes of
the upper paragraph in the text, because a paragraph can't have two sets of paragraph
settings.

4.5.3 Topic Headers

By default, new topics always have a
"header", displayed in a separate editing
box above the main topic editor. You can
turn the header off if you want, creating
topics without headers.
Initially, this header contains the title of the
topic, formatted with the standard Heading1
style and with the background color set in
the HTML topic page template. You can
also add other content, including graphics,
hyperlinks etc.
Header formatting, background colors and
additional content are only supported in
electronic help formats (HTML Help,
Webhelp, eBooks, Winhelp and Visual
Studio Help). ePub eBooks have limited or
no support for additional content. In print-
style formats (PDF, RTF, printed manuals)
only the plain text from the header is
exported when you publish and the
formatting is defined separately.

How to format the header text and background

Formatting the header text:
By default the header text has the standard Heading1 style. The easiest way to format
your header text is to edit this style in Write > Styles > Edit Styles. Then all new
headers will automatically have the selected formatting. You can format headers

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 137

manually by selecting the text and using the formatting tools in the Write tab if you want,
but then you must do this separately for every single topic.
Setting the header background color:
In most electronic output formats the header background color is defined by the HTML
topic page template. In the Project Explorer go to Configuration > HTML Page
Templates and select the Default template. Then you can set the background colors for
the header and the topic body. The background colors you set in the template are
automatically displayed in the editor.
The obsolete Winhelp format stores its background colors in its Main help window
definition. To set the background colors for Winhelp go to Configuration > Common
Properties > Help Windows. Select the Main help window at the top of the dialog,
then select the Winhelp Options tab and set the background colors. The background
colors you set for Winhelp are only displayed in your published Winhelp files
See Background colors and help viewers 93 for more details on this.

How to turn off the header

To turn off the header for a topic just deselect the Topic has a separate header checkbox
below the topic editor on the left. This will create a topic without a header in your
published output.

Warning: Turning off the header deletes any additional content you have added to the
header box. If you turn the header on again the box will only contain the standard topic
title, taken from the topic's TOC entry. The content will not be lost while you are still
editing the current topic (you can restore it by reactivating the checkbox) but once you
leave the current topic it will be deleted permanently.

Additional content in the header

You can insert any content in the topic header box that you would normally insert in the
main body of the topic, including graphics, hyperlinks and so on. This content will be
published with the header in electronic formats (HTML Help, Webhelp, eBooks, Winhelp
and Visual Studio Help) but not in print-style formats (PDF, RTF, printed manuals).

© 1997 - 2009 by EC Software, all rights reserved

 138 Help & Manual 5 - User Help

Note that content added to the header will only be displayed in the current topic. If you
want to include the same content in every topic (for example a logo) you need to edit the
HTML topic page template and add the content to the header section of the template.
See Using HTML Templates 430 for more details.
If you want to include additional with your headers in PDF and printed manuals you need
to add it to the header definitions in the print manual template see PDF & Printed
Manuals 325 for details.

Topic headers in PDF, RTF and printed manuals

The topic header and its formatting and background color are not exported or used in
PDF, RTF and printed manuals. In these formats only the plain text topic title is exported,
the formatting is applied with the print manual template for PDF and printed manuals and
with the options in Configuration > Publishing Options > Word RTF for RTF.
In RTF only the header text from the TOC topic title is used. In PDF you can use either
the TOC topic title or the text from the topic header (if it is different). This is done by
selecting either the <%HEADINGx%> variables in the template for the TOC topic title or the
<%HEADINGLONGx%> variables for the text from the header box.
See PDF & Printed Manuals 325 for details on accessing and editing print manual
templates for PDF.

See also:
Background colors and help viewers 93
Using HTML Templates 430
PDF & Printed Manuals 325
4.5.4 Selecting text and content
This topic outlines the different ways you can select text and content in the Help & Manual
editor. You can use both the mouse and key combinations.

Selecting with the mouse

Select a block Click and drag. Or click in the editor, hold down Shift and then click at
of text: the end of the text you want to select.

Select a single Click and drag or double-click on the word.

word:

Select a single Click to the left of the line in the margin of the editor.
line:

Select a Click and drag from the beginning of the paragraph to the end.
paragraph:

Selecting Click once on the graphic.

graphics:

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 139

Hyperlinks: Click once to select and edit link text, double-click to edit link properties
(Ctrl+Click navigates to the link target topic).

Selecting a Position the mouse pointer just to the left of the table and left-click. For
table: more details see Selecting and formatting cells and tables 258 .

Selecting with key combinations

Select by Hold down Shift+Ctrl and press right or left cursor arrow.
word:

Select by Hold down Shift and press PgUp or PgDown.

screen:

Select Press Ctrl+A or select Edit > Select All.

everything:

Keyboard Click on View > Program Options and then select the Shortcuts tab
shortcuts: to view and edit all the keyboard shortcuts available in the program.

See also:
Selecting and formatting table cells and tables 258
4.5.5 Copying, cutting and pasting
Copying, cutting and pasting text and other content in Help & Manual is exactly the same as
in a modern word processor. Just select what you want to copy and then use the standard
cut/copy and paste commands.
See Moving, cutting and pasting topics 199 for details on working with entire topics.

How to cut, copy and paste text and content

First select the text or content you want to copy. You then have two options:
Dragging:
· To move the selected text just drag without pressing any keys.
· To copy the selected text hold down Ctrl and drag.
You can use Drag & Drop within topics but not from one topic to another within the same
project. This is because dragging selected text onto a topic entry in the TOC creates a
link 215 to that entry! To use Drag & Drop between two separate projects you must open
the second project in a second instance of Help & Manual.
Using the Copy, Cut and Paste commands:
The Copy, Cut and Paste commands work just as they do in any normal word processor.
They are available in several places:
· Keyboard shortcuts: Ctrl+C (copy), Ctrl+X (cut), Ctrl+V (paste)

© 1997 - 2009 by EC Software, all rights reserved

140 Help & Manual 5 - User Help

· Write and Project tabs in the Ribbon (Clipboard group)

· Context menu: (right-click)
Copy as plain text
Select the Paste as Text tool in Write > Clipboard or press Shift+Ctrl+V to copy the
contents of the clipboard as text only, without any formatting or styles.
This is useful when you are copying text between paragraphs with different styles or from
another application like MS Word.

Copying from MS Word and other Office applications

Copying from and to MS Word:
You can copy and paste fully-formatted text both from and back to MS Word. Virtually all
formatting is supported, including tables (but not text boxes).
Copying tables from and to MS Excel:
You can also copy tables directly from and to MS Excel. In some cases you may find that
you get better results if you copy via MS Word i.e. first copy the table from Excel to
Word, and then from Word to Help & Manual. Similarly, to copy a table from Help &
Manual to Excel, copy it to Word first and then to Excel.
Copy as plain text
Select the Paste as Text tool in Write > Clipboard or press Shift+Ctrl+V to copy the
contents of the clipboard as text only, without any formatting or styles. .

Copying between projects

You can copy, cut and paste text between projects in exactly the same way as within a
project. Just open the second project and copy and paste between the two projects. See
Using the Project Explorer 41 for help with working in the Project Explorer.
You can't use Drag & Drop to copy text from topics between different projects if the
projects are both open in the same instance of Help & Manual. However, if you open Help
& Manual a second time you can use Drag & Drop between two projects.

Copying project settings between projects:

You can copy Project Configuration 652 settings from from one project to another. You can
copy individual groups of settings or entire settings sections. Note that this will overwrite
your current project settings with the new settings!
1. Open the project you want to copy settings to.
2. In the Project Explorer select the Configuration section and click inside the section
containing the settings you want to copy from another project – for example Title &
Copyright in Common Properties:
3. Click on Copy Properties From... at the bottom of the dialog and select the .hmxz or .

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 141

hmxp project file containing the settings you want to copy.

Warning: This will overwrite your current project settings with the settings that you copy!
4. In the dialog that appears choose This Page Only to copy only the settings of the
selected page or Copy Section to copy all the settings in the current section.

See also:
Moving, cutting and pasting topics 199
Project Configuration 652
4.5.6 Searching for text, topics and referrers
The functions for finding and replacing text in Help & Manual are very similar to the
comparable functions in word processors, with some additional options for the special
requirements of help projects.
In addition to this the program also has powerful functions for locating individual topics by
their topic IDs and their context numbers, and for locating "referrers", i.e. topics containing
links to the current topic or topics.

Productivity Tip
The Search function is also available in the
XML Source editor tab (Professional
version only) all HTML editor windows for
HTML templates and other editing
windows. Just right-click in these editor
windows to access.

How to find and replace text

1. Select Write > Editing > Find & Replace… or press Ctrl+F.
2. Enter your search text and choose your options. These are self-explanatory and are
very similar to all search and replace functions in all modern word processors.
Find where:
Topic Keywords searches for index keywords you have associated with your topics.
Image File Names changes the filenames of graphics file references in your projects so
that they refer to files with different names. See below for details.
Captions searches in TOC captions (the Topic Title field in the tab). Note that replacing
this text does not change the name of the topic in the TOC or the header in the header
box above the editor. Instead, it "uncouples" the topic title attribute from the other two
texts, giving it a different value.
Table of Contents searches in the TOC in the Project Explorer (search only, no replace).

© 1997 - 2009 by EC Software, all rights reserved

142 Help & Manual 5 - User Help

How to find and replace images

Images are referenced with their filenames only so you can "replace" them with other
images by replacing their filenames in your topics. Help & Manual finds the image files by
searching through all the folders in your Project Search Path 249 so if the filename you use
is in one of those folders Help & Manual will be able to find it.
1. Select Write > Editing > Find & Replace… or press Ctrl+F.
2. Select Image File Names in the Find Where section.
3. Enter the exact name of the image file as the search and replacement texts, including
the file extension, for example: main_screen.bmp.
4. Choose your other options. These are self-explanatory and are very similar to all
search and replace functions in all modern word processors.

How to find topics by ID or context number

1. Select Project > Manage Topics > Find > Find Topic
2. Select Topic ID or Help Context Number.

Find topics that link to the current topic

You can find links to the current topic with the Find Referrers function, which also shows
which topics the current topics links to.
Links to and from the current topic:
· Select Topics > Manage Topics > Find > Find Referrers
OR
· Right-click on a topic in the TOC and select Find Referrers in the context menu.
Selecting Find Referrers for a chapter in the TOC will display the referrers for all the
topics in the chapter. You can also use this function for multiple topics. Just select two or
more topics in the TOC before selecting the function. Note that this function will only find
links to the current topic or topics in the current project! You cannot use this function to
locate links to the topic in other projects or help files.
Finding links in all topics:
· Select Project > Tools > Report Tool and select either Long Report or Full Report
mode.
The report will include lists of all outgoing and ingoing links in all topics in your project.

See also:
Find & Replace 602 (Reference)
Find Referrers 586 (Reference)
The Project Reports Tool 534

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 143

4.5.7 Special characters, lines and breaks

Like most modern word processors Help & Manual can also insert special characters not
available on the keyboard, horizontal lines and hard page breaks.
Please note that special characters and hard page breaks need to be used with
consideration for the limitations of your chosen output format: If the fonts required for the
characters are not available on the user's computer the characters will not be displayed.
Page breaks will only have any effect in output formats that have "pages" PDF, printed
manuals and Word RTF.

How to insert special characters

Note that It doesn't make much sense to use characters from a rare font in your Webhelp
or HTML Help output, because most users won't have that font installed on their
computers. If you use rare fonts in PDF you can embed the font in your output, but this
will significantly increase the size of your PDF file. (Configuration > Publishing
Options > Adobe PDF > Font Embedding.)
1. Click in the editor in the position where you want to insert the special character.
2. Select Write > Insert Object >
3. Common special characters can be selected directly in the menu -- or select More
Symbols... to display more characters and all available fonts.

How to insert horizontal lines

Horizontal lines are inserted in their own paragraph and they are not formattable. They
always occupy the entire width of the page or table cell in which they are inserted.
1. Click in the editor in the position where you want to insert the horizontal line.
2. Select Write > Insert Object > to insert the line. A dialog will be displayed
allowing you to choose the line thickness and color.

How to insert hard page breaks

Hard page breaks are only used in PDF, printed manuals and Word RTF. They are
ignored in all other formats.
1. Click in the editor in the position where you want to insert the hard page break.
2. Select Write > Insert Object >

See also:
Insert Special Character 637 (Reference)
4.5.8 Using comments and bookmarks
Comments and bookmarks enable you to annotate your text and create jump markers so
that you can quickly access topics or chapters that you access frequently. Comments and

© 1997 - 2009 by EC Software, all rights reserved

144 Help & Manual 5 - User Help

bookmarks are separate you cannot jump to comments and you cannot add text to
bookmarks, other than the label that is the bookmark name.

Key Information
Comments and bookmarks are only an
editing tool to make working on your
project easier. They are not exported when
you publish your project.

How to insert a comment

You can insert multiple comments in a single topic.
1. Click in the position in the editor where you want to insert your comment. (You can
insert comments both in the topics themselves and in the header.)
2. Select Write > Insert Object > in the Ribbon.
3. Enter your comment text.
4. Select Show comment as icon only if you want to hide its content inside the topic.

How to insert and delete bookmark

Bookmarks can only be assigned to entire topics and you can only assign one bookmark
to any topic. Bookmarked topics are identified with a red "pin" icon in the Table of
Contents.
Inserting bookmarks:
1. Select the topic you want to bookmark.
2. Select Bookmark > Bookmark Current Topic in Project > Project.
3. Enter a descriptive name for the bookmark and click OK.

Deleting bookmarks:
Select Bookmark > Remove Bookmarks in Project > Project, then click on the
bookmarks you want to remove.

How to jump to bookmarks

· Select Project > Project > Bookmark and select the bookmark want to jump to
from the list.
Note that when you jump to a comment or bookmark you are always jumping to the topic
containing the bookmark. You cannot jump to the position of a comment within the topic.

How to edit comments

· Double-click on the comment in the editor. If only the pin icon is displayed you must

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 145

double-click on the lower half of the icon.

OR:
· Right-click on the comment in the editor and select Edit. Again, note that the clickable
area is in the lower half of the pin icon.
Changing the comment's text style:
The appearance of the text in the comment controlled by the standard Comment style,
which you can edit by selecting Write > Styles > Edit Styles. This is a special style
that has quite limited features compared to most other styles. See Caption and comment
styles 176 for details on this.

Storing text in comments

You can insert the text from comment a into your topic by right-clicking on it in the editor
and selecting Convert to plain text. You can "abuse" this feature to use comments as a
store for text that you may or may not want to include in your topics – for example for text
that is not yet finalized. When you want to insert it just convert the comment to plain text.

See also:
Graphic caption and comment styles 176
4.5.9 Spell checking
In addition to manual spell checking for individual topics, selected text and your entire
project you can also use live spell checking (misspelled words are highlighted as you type).
You can also create your own user dictionaries with lists of special terms for your own
projects, auto-correct entries and terms that you want to identify as incorrect even though
they are in the main dictionary. User dictionaries can be global for all projects or local for just
one project and can be stored anywhere you like.
See The Spell Checker 543 in the Tools Included with Help & Manual chapter for full details on
configuring the spell checker.

Productivity Tip
Spell checking is supported almost
everywhere in Help & Manual where you
can enter text. Just right-click to display the
context menu or click on the upper half of
the Spelling tool in the Project tab to
access.

Selecting the language and user dictionaries

Select the language:
Go to Project > Tools > Spelling > Configure Spell Checker > Dictionaries and
select the correct dictionary for the language you want to check in the Main Dictionaries
section:

© 1997 - 2009 by EC Software, all rights reserved

146 Help & Manual 5 - User Help

You can spell check documents that contain multiple languages by selecting more than
one main dictionary. Click on Download dictionaries... to download free dictionaries for
additional languages. These dictionaries must be stored in the Dictionaries folder in your
Help & Manual program directory.
Select the user dictionaries:
All user dictionaries listed in the Custom Dictionaries section will also be used for spell
checks. You can store these dictionaries anywhere you want, also on network drives, and
multiple users can access the same dictionary at the same time.
Select When adding words, use this dictionary: to choose the user dictionary you want to
use to store new words.
See The Spell Checker 543 for full details on configuring the spell checker.

How to use live spell checking

Go to Tools > Spelling > Configure Spell Checker and activate the Check spelling
as you type option.
Unknown words are highlighted with a wavy red underline. Right-click on a highlighted
word (or click on it and press the context menu key on your keyboard if you have one) to
display alternatives.
Select Spelling in the context menu to open a full manual spell checker window.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 147

Note that the live spell checker does not mark repeated words as errors. This is only
marked by the manual spell checker.

How to use manual spell checking

Selected text, current topic or current text entry field or window:

Select text in the editor and click on the top part of the Spelling tool in Project > Tools.
Current topic, all topics, table of contents:
Click on the bottom part of the Spelling tool and select Current Topic, All Topics or Table
of Contents.
When an unknown word is found the following dialog is displayed:

© 1997 - 2009 by EC Software, all rights reserved

148 Help & Manual 5 - User Help

Skips this occurrence of the unknown word without correcting it and

continues the spell check.
Skips the unknown word and all future occurrences of the word. Applies for
the current spell check session only.
Changes this occurrence of the unknown word and continues with the spell
check. You can type a word manually in the Replace with: field or click on
a word in the Suggestions: list.
Changes both this occurrence and all future occurrences of the unknown
word without prompting for confirmation. Applies for the current spell check
session only.
Adds the unknown word to the current custom dictionary (see below).
Adds the unknown word and its replacement to the Auto-Correct list in the
current custom user dictionary. When this unknown word is encountered in
future manual spell checks it will be corrected automatically without
prompting for confirmation.

Selecting and adding custom (user) dictionaries

The main dictionaries are not editable. However, you can create custom user dictionaries
to store your own additional terms. These dictionaries can also store auto-correct word
pairs and "excluded" words that you want to always identify as incorrect even if they are
in the main dictionary.
See Using custom dictionaries 548 and Creating and editing custom dictionaries 546 for full
details on this subject.

· The standard user dictionary is stored in your My Documents folder (called Documents
in Windows Vista). To use this just select it in the When adding words, use this
dictionary list at the bottom of the dialog.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 149

· Click on Add/New to create a new user dictionary or to select an existing dictionary.

You can store your dictionary anywhere you like.
· If you only want to use the selected dictionaries for the current project activate Selected
dictionaries are used for this help project only. Otherwise your selections will be stored
for all projects.

Using Auto-Correct to replace words and abbreviations

The spell checker has an Auto-Correct feature that can be used to automatically replace
words with other words when they are encountered in manual spell checks.
1. Set up your user dictionary and enter words you want to correct in the Auto-Correct
Pairs (see Creating and editing custom dictionaries 546 for details).
2. To add new Auto-Correct Pairs during manual spell checks enter the correct word you
want to use, then click on Auto-Correct to add the pair to the current user dictionary.

This word pair will be corrected automatically from now on when you use this dictionary
(also in the current session).

See also:
The Spell Checker 543
4.5.10 Re-using content with snippets
The Insert Snippet tool in Write > Insert Object enables you to insert the contents of
another topic or a Help & Manual XML file at the cursor position. You can insert topics and
files from the current project, from other Help & Manual projects (some restrictions in the
Standard version of H&M) and from collections of Help & Manual XML files. This means that
you can build up a library of reusable content that you can access very easily.
You can insert snippets in two different modes, Copy and Link. Copy mode is like normal
copy & paste it pastes the contents of the topic or file at the cursor position and you can
then edit it. Link mode creates a live link to the snippet file. To edit the snippet you must then
edit the original topic or file, but then it updates automatically in all the places where you
have inserted it, even if you are using it in multiple projects.

Productivity Tip
If you send your project for translation
remember to include any external snippet

© 1997 - 2009 by EC Software, all rights reserved

150 Help & Manual 5 - User Help

files you have referenced, otherwise the

translator won't see them!

Inserting topics and XML files as snippets

You can insert topics and XML files into your current topic at the cursor position. These
topics can be inserted in Copy mode or Link mode. In Link mode the snippet content
updates automatically when the source topic or XML file is edited.
The topics can be in your current project, another Help & Manual project or a directory of
H&M XML files.
1. Click in your topic where you want to insert the snippet.
2. Select the Insert Snippet tool in Write > Insert Object.
3. Choose From Topic to insert a topic from the current project or From File to insert an
external H&M XML file or a topic from another project. (You can also insert XML topic
files from the current project if you want.)

· Copy & Paste inserts a copy of the file that you can then edit.
· Linked creates a live link to the file changes in the source file or topic are updated
automatically.
· You can also insert XML files from your current project instead of using the From
Topic mode. This is only possible when your topic is saved as uncompressed XML
(Professional version only).
4. Select the topic or file you want to insert and click on OK to insert it.
"Use project search path to locate snippet"
This option adds the location of the snippet file to the project search path 656 if you
deselect it the path to the snippet is stored with the snippet.
Rather than using snippets from many locations it is better to store all your snippet files in
a common location. This will make them easier to manage, particularly if you ever need to
move your project or have it translated.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 151

Exporting selected text and topics as snippet files

You can export selected text or the current topic to an external XML file, for example for
use as a snippet in a snippet directory.
Export the entire topic:
1. Select the topic you want to export in the Project Explorer (TOC or Topic Files).
2. Select File > Save Topic to File in Project > Manage Topics and choose the save
location.
Export selected text:
1. Select text in the editor the text can include anything that a topic can contain, i.e.
also images, tables, etc.
2. Select File > Save Snippet in Project > Manage Topics and choose a save location
and a filename.
If you save in the uncompressed XML format you can also copy the XML files directly
from your project directory to other locations in Windows Explorer (Professional version
only).

Managing and organizing snippets

You can insert snippets from any location. However, if you use snippets from many
locations your linked snippets will not be displayed if you move your project or send it to
someone by email. You can solve this problem by storing your snippet files together with
your project in a special directory.
1. Create a folder for your snippets in a location where you can easily transport it
together with your project folder.
2. Add the path to the snippets folder to your Project Search Path in your project's
Configuration > Common Properties settings.
3. When you insert a snippet select the Use project search path to locate snippet option
to tell Help & Manual to look for the snippet files in the folders listed in the Project
Search Path.
When you do this you can always move your snippets folders to any location you like. To
get Help & Manual to find the snippets you just need to add the new location to your
project search path 656 .

Excluding the snippets source files from your published output

When you use topic files from your current project as snippets you will generally want to
exclude the source files from your published output. If you don't do this these files will be
published and the user will able to find them with Search in formats like HTML Help and
Webhelp.
1. Select the entry of the topic file in the Project Files section of the Project Explorer.

© 1997 - 2009 by EC Software, all rights reserved

152 Help & Manual 5 - User Help

2. In Project > Manage Topics select Change > Include in Builds and deselect all build
options. This will ensure that these topics will never be included when you publish your
project.
This is not necessary for snippets inserted from other projects or external XML files, of
course!

Editing the contents of snippet files

There are two ways to edit the content of a snippet file in Help & Manual. Which you use
depends on whether the snippet contains a small or large amount of text.
Editing small snippets:
1. Press ENTER a couple of times to create some space in the current topic.
2. Insert the snippet file you want to edit in Copy & Paste mode (see above) and make
the necessary changes.
3. Select the edited text and export it as a snippet, overwriting the original snippet file
(see above).
Editing larger snippets:
1. Create an empty dummy topic in the TOC.
2. Select File > Load Topic from File in Project > Manage Topics and load the snippet
file.
3. Edit the content and then select File > Save Topic to File and overwrite the original
snippet file.

Hyperlinks to anchors in linked snippets

If a linked snippet contains an anchor (jump target) you can link to it from other topics.
However, since the snippet file is not really inserted in the current topic you cannot select
the anchor from the drop-down list next to the Target: field in the Insert Hyperlink 617
dialog. You need to enter the anchor name manually.
1. Make a note of the name of the anchor you want to link to.
2. Create a normal hyperlink to the topic containing the linked snippet.
3. Double-click on the hyperlink to edit it and type in the name of the anchor in the drop-
down list box next to the Target: field.
4. Publish your project and test the link to make sure that it works.
You won't have this problem with snippets inserted in Copy mode because the text
containing the anchor is inserted in the topic directly.

Checking where a snippet topic is used

You can use the Find Referrers function to check where a topic file is being used as a

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 153

linked snippet. You can also use the same function to find the location of the linked
snippet topic files inserted in the current topic.
This only works for topic files used as snippets in the current project. It won't work across
multiple projects or for XML files that are not part of projects.
1. In the Project Explorer select the topic file either a file containing a linked snippet or
a file that you think is being used as a linked snippet.
2. Select Find > Find Referrers in Project > Manage Topics (or just right-click and
select Find Referrers).
3. The sources of linked snippets in the topic are shown as incoming links. Topics in
which the topic is used as a linked snippet are shown as outgoing links.

Keywords in snippets
If snippet files are H&M topic files containing index keywords the keywords are imported
when you use Link mode. A-keywords are not supported in snippets, however.
Keywords are not imported with snippets in Copy & Paste mode.

See also:
Multiple TOC entries for one topic 208
Snippets and multiple TOC references 751
Topic include options 407
Anchors - jump targets 226
4.5.11 Printing topics
You can print individual topics with the Print Topic tool in Project > Manage Topics. The
advantage of this over Print User Manual function (Application Button menu) is that this
function only prints the selected topic or topics. Print User Manual uses a PDF print manual
template, which always includes additional elements like the cover and back page, table of
contents, index and so on, even when you only print one or more selected topics.
See PDF and Printed Manuals 325 for more details on using these other functions.

How to print the current topic

1. Select the topic you want to print by clicking on it in the TOC.
2. Select the Print Topic tool in Project > Manage Topics.
3. Select your printer and other settings in the print menu, then select OK to print.

How to print multiple topics

To print multiple topics you need to use the Print User Manual function (Application
Button menu). If you frequently want to print multiple topics you can set up a special print
manual template 330 for this with all the sections except the Topics section disabled. Then

© 1997 - 2009 by EC Software, all rights reserved

 154 Help & Manual 5 - User Help

you just select this template in the Print User Manual dialog before printing.
1. Select the topics you want to print by clicking on them in the TOC, using Ctrl+Click to
select topics out of order and SHIFT+Click to select continuous blocks of topics.
2. Click on the Application Button and select Print User Manual.
3. Select the Selected topics option in the Include Options: box.
4. Select your printer and other settings in the print menu, then select OK to print.
See Printing user manuals 328 for full details on using the Print User Manual function.

See also:
PDF and Printed Manuals 325
Printing user manuals 328
4.5.12 Editing XML source code
As a normal documentation author you do not need to know anything about XML to get all
the benefits from using Help & Manual. Familiarity with XML is really only needed for users
who want to generate their topic files from their own applications automatically in XML
format and for performing complex search and replace operations directly on your project
files with an external editor.

Key Information
XML editing is for experts only. Although
XML looks a little like HTML it is actually
very different and does not tolerate even
the smallest syntax error.

Editing in the XML Source tab

The XML Source tab is a text editor with syntax highlighting. You can copy, cut and paste
and both search and spell-checking are supported (right-click in the XML editor window
for options).
If you want you can also copy the entire contents of the XML Source to a separate file –
this is effectively the same as exporting the topic to an external XML file with Topics >
Save Topic to File 204 .
You can only edit individual topics in the XML Source tab. To perform global search and
replace operations you must edit the source files of your project directly with an external
editor capable of performing search and replace operations on multiple files. If you select
another topic directly while the XML Source tab is active you will be returned to the Page
Editor tab automatically.
Help & Manual's XML format is open and fully documented. Full documentation is
available in the file Helpman_XML_ref.chm which you can find in the Help & Manual
program directory.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 155

Editing the XML project files directly

If you use Help & Manual Professional you can save your projects in as uncompressed
XML files with an .hmxp file as the main project file (this file is also an XML file).
If you observe the syntax rules of the Help & Manual XML Language you can edit these
files directly, either with a normal text editor or with a specialized XML editor. If you have
an editor that supports multiple-file search and replace you can also perform search and
replace operations on your entire project that are not possible directly in Help & Manual
itself. For example, you can use an editor that supports regular expressions to perform
very complex manipulations on the text and the source code.
WARNING: Caution when editing XML files in MS Word
Recent versions of MS Word can edit XML but you need to exercise extreme caution.
When you save XML files some versions of Word will change the source code and add
Microsoft's own version of XML, making the files unusable in Help & Manual. Please
perform tests to make sure that this is not happening before doing any XML editing with
Word.

Supported XML formats

Help & Manual can only process XML files conforming to the Help & Manual XML
Language. These can be produced by Help & Manual itself or generated by other
programs that conform to the language schema specifications. Documentation of the
updated version of the Help & Manual XML Language used in Help & Manual 5 is going
to be released as soon as possible.

See also:
XML and XML editing 493

4.6 Text Formatting and Styles

Text formatting in Help & Manual works in the same way as in a modern word processor,
supporting both manual formatting and formatting with styles. Styles give you full control
over your formatting changing your style definitions reformats all text formatted with your
styles.
If you are not familiar with styles please study the chapter Dynamic Styles 711 in the
Reference section before getting started.

See also:
Dynamic Styles 711 (Reference)
4.6.1 Formatting text manually
Manual formatting in Help & Manual works exactly as it does in a modern word processor.
You apply formatting to text manually with the tools in the Write tab of the Ribbon, where
you can select formatting options for Font, Paragraph and Borders and Background.
Generally, however, you should use styles for formatting your text. Styles are more efficient,

© 1997 - 2009 by EC Software, all rights reserved

156 Help & Manual 5 - User Help

create uniform-looking documents and enable you to reformat your entire project quickly just
by changing your style definitions. When you are working on a project in a team styles are
essential for uniformly-formatted documents

Productivity Tip
You can assign keyboard shortcuts to most
manual formatting tools. Select View >
Program Options > Keyboard Shortcuts to
access the settings.

How to apply manual formatting to text in the editor

There are two ways to apply formatting manually: Select a formatting option and start
typing, or select text and then apply a formatting option.
Select a formatting option and start typing:
If you select a formatting option without selecting text first the formatting options you
select will apply to all the text you type from that point onwards (unless you move the
cursor again). If you press Enter to create a new paragraph after applying formatting like
this the new paragraph will also have all the formatting attributes you have just applied.
Select text and then apply a formatting option:
If you select text in the editor and then select formatting options the options will be
applied to the selected text and paragraphs. If you then place the cursor directly after the
formatted text any new text you type in that position will also have the formatting.

Manual formatting tools

To see what a formatting tool does just position the mouse over it for a second or two and
a description will be displayed.
The Font and Paragraph tools:

The tools in the Font and Paragraph groups of the Write tab all apply formatting
manually in the current position. If text is selected the options are applied to the selected
text. If no text is selected the options apply from the cursor position onwards when you
start typing.
For more detailed formatting settings you can display the Font 606 , Paragraph 609 and
Borders and Background 611 dialogs. To display them just click on the little arrow icons at
the bottom right of the Font and Paragraph groups.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 157

The Borders and Background tool:

This tool is included in the Paragraph group in the Write tab. You can display a full
dialog of options by clicking on the little arrow next to the Border Tool.

Restrictions in Winhelp output

Please note that the obsolete Winhelp format that lacks support for a number of modern
formatting options. These include table borders, nested tables, text and paragraph
borders, background colors, superscript and subscript. It is advisable not to use these
features if you are still using Winhelp.
For details please see Classic Winhelp 740 in the Help Formats chapter in the Reference
section.

See also:
Formatting text with styles 167
The Format Menu 608 (Reference)
Syntax highlighting for program code 195
4.6.2 Quick guide to using styles
If you are new to using styles you should take a little time to learn how to use them. Used
properly, dynamic styles give you full control over your project's formatting, enabling you to
change the appearance and layout in seconds at any time.
You should define a style for each paragraph type and text format that you plan to use
frequently. You can do this as you work and you can change and reorganize your styles
whenever you like.
For maximum efficiency only use manual formatting for formats that you are not going to use
again. If you later find you want to use the formatting as a style you can always turn it into a
style later.

Productivity Tip
You can quickly turn manual formatting into a style by clicking in the formatted text and
then selecting Write > Styles > Create Style from Selection. For maximum efficiency
only use manual formatting for formats that you are not going to use again. If you later
find you want to use the formatting as a style you can always turn it into a style later.

Applying styles
· To apply a style to a full paragraph just click in the paragraph and select the style in the
style selector.

© 1997 - 2009 by EC Software, all rights reserved

158 Help & Manual 5 - User Help

· To apply a style to text select the text and then select the style in the style selector.
· If you have imported formatted text from other sources you must select it to be able
apply styles to it, otherwise the imported formatting has priority it is treated as manual
formatting. After applying a style you just need to click in the paragraph and select a
different style to change the style.

Changing an existing style

1. Click in a paragraph or in text formatted with the style you want to change (the style
name will be displayed in the style selector in Write > Font).
2. Select Styles > Edit Style in the Write tab. The style at the cursor is selected for
editing automatically.

3. Select Font Settings, Paragraph Settings and Borders and Background to change the
style attributes.
4. Define different settings for Print View (PDF, RTF, printed manuals) and Help View
(electronic formats).
5. Define keyboard shortcuts for styles you want to use frequently.
All text formatted with the styles you edit will be changed immediately.
Note that you can set different attributes for electronic help formats (Help View tab) and
print-style help formats (Print View tab). You can also switch between print and help view
in the Help & Manual editor by clicking on the Screen/Print switch in the status bar below
the editor. See Help and print styles 175 for details.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 159

Defining a new style

1. Select Styles > Edit Style in the Write tab, then select Add Style to define a new style.

2. Enter a name for the style and then set its paragraph and font attributes.
3. Don't forget to define a keyboard shortcut for styles that you want to use frequently.
This will speed up your work a lot!
Note that you can set different attributes for electronic help formats (Help View tab) and
print-style help formats (Print View tab). You can also switch between print and help view
in the Help & Manual editor by clicking on the Screen/Print switch in the status bar below
the editor. See Help and print styles 175 for details.

Changing the formatting in your entire project

If you use styles you can change the formatting in your entire project just by changing the
definitions of your styles. This is particularly powerful with the Normal style, which is
usually the main style used for all body text paragraphs. In addition to this, you will
usually base all your other styles on Normal, including your heading styles. If you
organize your styles like this you can change the font and formatting in your entire project
just by editing Normal.
· Follow the instructions above to edit the Normal style.
· If you change the font of Normal the font will change in all text formatted with Normal
and with styles based on Normal, including heading styles. The font will only not
change in those styles in which the font has been changed so that it is not the same as
Normal.
· All the paragraph, background and border attributes of Normal are also "inherited" in
the same way by all the other styles based on Normal.

See also:
Dynamic Styles 711 (Reference)
4.6.3 Style display in the Toolbar
The style selector in the Ribbon Toolbar functions as an indicator to identify the style of the
current text or paragraph. It displays the paragraph and/or text style at the current cursor
position or of the currently selected text. For example, in the screenshot below the cursor is
in a paragraph formatted with a style called Body Text:

© 1997 - 2009 by EC Software, all rights reserved

160 Help & Manual 5 - User Help

Display for manually-formatted text and text styles

If the cursor or selection is at a position containing manually-applied formatting the style
selector shows the name of the style in bold with a + sign after it, to indicate additional
formatting. For example, here the cursor is in text formatted in bold in a paragraph
formatted with the Normal style:

Here the cursor is positioned in text

formatted in bold.

The style name is shown as "Normal+" when the cursor is in manually-formatted text . In
the rest of the text of the paragraph the style selector display will be "Normal", without the
bold highlight and the + sign.
The bold Stylename+ display is also shown when the cursor is in text within a paragraph
formatted with a text style, because this also counts as additional formatting:

Here the cursor is in text formatted

with a text style.

Display for no style and imported styles

No style:
If the current paragraph has no style the style selector display will be empty:

The style selector is empty when

the current text has no style.
The style display is also empty when you paste text from Word or another word processor
that uses styles. The formatting of the text is imported but the styles with which the text is
tagged are not.
Imported styles:
If you paste text from another Help & Manual project containing styles that are not
defined in your current project the unknown style will be displayed in red in the style
selector.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 161

· See Turning formatting into styles 169 for instructions on how to turn imported styles like
these into styles you can use in your project.

See also:
Dynamic Styles 711 (Reference)
Formatting text with styles 167
Defining styles 161
4.6.4 Defining styles
Help & Manual's dynamic styles are defined and edited by selecting Styles > Edit Styles in
the Write tab. The style at the cursor position is automatically selected for editing.
If you have not used dynamic styles in a word processor before please study the chapter on
Dynamic Styles 711 in the Reference section before proceeding. This will make using styles
much easier for you.

Paragraph styles and text styles

By default style definitions are "paragraph styles" and always include both text and
paragraph attributes (borders and backgrounds are included in the paragraph attributes).
You can also define text-only styles for formatting text within paragraphs. See Defining a
new text style below for details.

Defining a new paragraph style

1. Select Styles > Edit Styles in the Write tab to display the Edit Styles dialog.

© 1997 - 2009 by EC Software, all rights reserved

162 Help & Manual 5 - User Help

2. Select Add Style and enter a name for your new style.
3. In the Based on Style: field select the style you want to base the new style on. The
style will inherit all the attributes of this style. Base paragraph styles on paragraph
styles, text styles on text styles. Alternatively, select (None) to create a style without a
parent.
4. Set the attributes of the style with the Font Settings, Paragraph Settings and Borders
and Backgrounds buttons.
5. If you want to create a hotkey combination for selecting the style click in the
Shortcut: field and press the key combination you want to use. You will be warned if
the key combination is already in use.
6. Click on OK to save the new style. It is then available immediately in all the style lists.

Defining a new text style

A text style is a style that only contains font attributes. See Formatting text with styles 167
for details on how to use text styles.
Note that you cannot create a text style based on a paragraph style. This also means that
you cannot create text styles based on the Normal style because Normal always has
paragraph attributes.
1. Select Styles > Edit Styles in the Write tab.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 163

2. Select Add Style and enter a name for your new style.
It's a good idea to use a prefix in the name of your text styles to identify them clearly.
For example, you could use T_, so that your text styles would have names like
T_Emphasized, or T_ProductNames.
3. In the Based on Style: field select another text style if you want to base the new style
on another style. The style will inherit all the attributes of this style. Alternatively,
select (None) to create a new text style without a parent..
4. Click on Reset Style to make absolutely sure that all the non-text attributes of the style
are canceled.
5. Click on Font Settings and set the attributes of the style.
Don't select the Paragraph or Borders buttons if you do the style will become a
paragraph style.
If you want to create a hotkey shortcut for selecting the style click in the Shortcut: field
and press the key combination you want to use. You will be warned if the key
combination is already in use.
6. Click on OK to save the new style. It is then available immediately in all the style lists
(see Formatting text with styles 167 for details).

Importing styles from another project

This function replaces all the styles of the current project with styles imported from
another project. Only use it if you really want to use the styles defined in another project
instead of the current project's styles.
1. Select Styles > Edit Styles in the Write tab.

© 1997 - 2009 by EC Software, all rights reserved

 164 Help & Manual 5 - User Help

2. Click on Copy Styles From... in the Edit Styles dialog and select the project
containing the styles you want to copy.
See Copying styles from other projects 177 for full details on this function.

See also:
Formatting text with styles 167
Editing styles 164
Dynamic Styles 711 (Reference)
4.6.5 Editing styles
Whenever you edit a style all the text in your project formatted with the style is updated
automatically and immediately. In addition to this any changes you make to styles will
automatically be inherited by any other styles based on that style. This makes it possible to
make changes to entire families of styles very quickly and easily by editing the parent styles.
For example, you can normally change the base font in your entire document by changing
the font of the Normal style.

Defining a new style

1. Select Styles > Edit Styles in the Write tab, then select Add Style to define a new
style.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 165

2. Enter a name for the style and then select Font Settings, Paragraph Settings and
Borders and Background to change the style attributes. See The Write Tab 600 for
details in the settings in these dialogs.
3. Don't forget to define a keyboard shortcut for styles that you want to use frequently.
This will speed up your work a lot!

Editing an existing style

1. Click in a paragraph or in text formatted with the style you want to change (the style
name will be displayed in the style selector in Write > Font).

2. Select Styles > Edit Styles in the Write tab. The style at the cursor is selected for
editing automatically.

© 1997 - 2009 by EC Software, all rights reserved

166 Help & Manual 5 - User Help

3. Select Font Settings, Paragraph Settings and Borders and Background to change the
style attributes. See The Write Tab 600 for details in the settings in these dialogs.
4. Define different settings for Print View (PDF, RTF, printed manuals) and Help View
(electronic formats). See Help and print styles 175 for more details on these two sets of
settings.
5. Define keyboard shortcuts for styles you want to use frequently.
All text formatted with the styles you edit will be changed immediately.
Select Reset Style to completely reset all of the style's attributes to the settings of its
parent style (the style listed in the Based on Style: field). If the style has no parent it will
be set to the Help & Manual defaults.

Moving and renaming styles

Change the style's parent:
To change a style's parent select a different parent style in the Based on Style: field. Any
style attributes that were set explicitly in the style will remain unchanged. All other style
attributes will be changed to those of the new parent style.
Eliminate the style's parent:
To eliminate the style's parent just select (None) in the Based on Style: field. This will
prevent the style from inheriting any attributes from any other styles. It will also make the
style the first parent in a new style tree. This can be useful under some circumstances.
See Style organization strategies 720 for details.
Rename a style:
Just select the style in the Edit Styles dialog and edit the name. You can change the
name of a style whenever you like, it will be updated automatically throughout your
project.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 167

Modifying an existing style on the basis of a selection in the editor

You can also modify a style on the basis of a modified paragraph or text formatted with
the style. This is often the easiest way to edit a style because it is much easier to see
your formatting in the editor.
1. Use the manual formatting tools to format a paragraph or some text formatted with the
style you want to change.
2. Make sure that the cursor is inside the formatted text, then select Styles > Create
Style from Selection in the Write tab.
You don't need to select any text, the cursor must only be inside the formatted text you
want to use as a model. If you do select text it should all be formatted in the same way
don't try to create a style based on text with some words formatted in one way and
some in another!
3. Select the Change existing style option in the dialog displayed. The style at the cursor
should be selected automatically. If it isn't close the dialog and check the position of
the cursor in the editor.

The Assign paragraph attributes option will be selected automatically for paragraph
styles and deselected for text styles. Only change this if you want to change the style
type. (See Paragraph and text styles 718 for details on changing the style type.)
4. Click on OK to apply the changes to the selected style.
See Defining styles 161 for details on using this function to create a new styles.

See also:
Paragraph and text styles 718
4.6.6 Formatting text with styles
Formatting text with styles couldn't be simpler: You just select your text and select a style,
and all the attributes of that style are applied to the text in one quick operation.
Help & Manual comes with a basic set of standard styles already predefined, so you can
start using styles right away, even without defining your own styles. Normally, however, you
will want to modify these styles and add styles of your own to create a customized layout
and appearance for your project.
See Defining styles 161 for information on defining and editing styles. If you are not yet
familiar with styles please study the chapter on Dynamic Styles 711 in the Reference section.

© 1997 - 2009 by EC Software, all rights reserved

168 Help & Manual 5 - User Help

Applying styles
· To apply a style to a full paragraph just click in the paragraph and select the style in the
style selector. You can also select multiple paragraphs and apply styles to all of them.
You must select all the text in all the paragraphs to do this only font attributes are
applied to partially-selected paragraphs.

· To apply a style to text select the text and then select the style in the style selector.
· If you have imported formatted text from other sources you must select it to be able
apply styles to it, otherwise the imported formatting has priority it is treated as manual
formatting. After applying a style you just need to click in the paragraph and select a
different style to change the style.

Paragraph styles and text styles

By default style definitions are paragraph styles and include both text and paragraph
attributes (borders and backgrounds are included in the paragraph attributes).
You can also define text-only styles for formatting text within paragraphs. See Defining
styles 161 for details, and see below for instructions on how to use text-only styles.

Applying text-only styles

You can also define text-only styles 161 that only set font attributes. Applying these styles
is very similar to formatting text manually.
To apply the text style to existing text:
Select the text and then select the style.
To apply the text style to an entire paragraph:
Click anywhere in the paragraph and select the style. The text style attributes will be
applied to all the text in the paragraph except manually-formatted text, imported
formatted text and text already formatted with other styles.
To type new text with a text style:
First press Enter to create a new paragraph. Then select the style and start typing.

How text selection interacts with applying styles

Nothing selected (click in paragraph):
When nothing is selected the style is applied to the entire paragraph with all its attributes
(text, paragraph, borders/background).

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 169

If the style is a text-only style the text attributes are applied to the entire paragraph.
Manually-formatted text, imported formatted text and text within paragraphs formatted
with other styles are all "protected" they will only be reset if they are selected before
applying the style.
Everything selected (all the text in one or more paragraphs):
When everything is selected the style and all its attributes (text, paragraph, borders/
background) are applied to all selected paragraphs. All formatting is reset to the style
attributes, including manually-formatted text, imported formatted text and text within
paragraphs formatted with other styles.
If any paragraph is only partially selected then only text attributes will be applied to that
paragraph.
Text within a paragraph selected (partial selection):
If you select text within a paragraph then only font attributes of styles will be applied to
that text, even if the style also has paragraph attributes.

The standard styles

There are several standard styles that are used automatically for various purposes. For
example, when you create a new topic the first paragraph always has the Normal style,
the topic header above the editing area always has the Heading1 style and graphics
captions always have the Image Caption style.
There are a number of other standard styles. They are all identified and displayed in bold
in the style editing dialog 604 . You can edit these styles but you cannot delete them or
change their names. See The standard styles 717 for details.

See also:
Defining styles 161
4.6.7 Turning formatting into styles
The easiest way to define a new style is to use some manually-formatted text in the editor as
a model. This allows you to see what you are doing much more clearly than when you are
setting attributes in the formatting dialogs.

Defining a new paragraph style from a selection

1. Use manual formatting options to format a paragraph so that it looks exactly as you
want your style to look.
2. Click in your model paragraph, then select Styles > Create Style from Selection in the
Write tab.

© 1997 - 2009 by EC Software, all rights reserved

170 Help & Manual 5 - User Help

3. Select the Create a new style option and enter a name for the new style.
4. If you want the style to have a parent select a style in the Based on Style: list. The new
style will then inherit all the attributes of the parent style that are not different from the
current paragraph in the editor. If you do not want the style to have a parent scroll to
the top of the list and select (None).
5. Make sure that the Assign paragraph attributes option is checked, then click on OK to
create the new style.

Defining a new text style from a selection

You can also create new text styles based on text in the editor. The procedure is almost
the same as for a paragraph style.
1. Format some text so that it looks exactly as you want your style to look.
2. Click in the formatted text, then select Styles > Create Style from Selection in the
Write tab.

3. Select the Create a New Style and enter a name for the new style. It is a good idea to
enter a prefix to identify it as a text style, for example "T_".
4. If you want the style to have a parent select a text style in the Based on Style: list. If
you use this option the parent style must be another text style. The new style will then
inherit all the attributes of the parent style that are not different from the current
paragraph in the editor. If you do not want the style to have a parent scroll to the top of
the list and select (None).
5. Deselect the Assign paragraph attributes option, then click on OK to create the new
style.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 171

Modifying an existing style on the basis of a selection in the editor

You can also modify a style on the basis of a modified paragraph or text formatted with
the style. This is often the easiest way to edit a style because it is much easier to see
your formatting in the editor.
1. Use the manual formatting tools to format a paragraph or some text formatted with the
style you want to change.
2. Make sure that the cursor is inside the formatted text, then select Styles > Create
Style from Selection in the Write tab.
You don't need to select any text, the cursor must only be inside the formatted text you
want to use as a model. If you do select text it should all be formatted in the same way
don't try to create a style based on text with some words formatted in one way and
some in another!
3. Select the Change existing style option in the dialog displayed. The style at the cursor
should be selected automatically. If it isn't close the dialog and check the position of
the cursor in the editor.

The Assign paragraph attributes option will be selected automatically for paragraph
styles and deselected for text styles. Only change this if you want to change the style
type. (See Paragraph and text styles 718 for details on changing the style type.)
4. Click on OK to apply the changes to the selected style.
See Defining styles 161 for details on using this function to create a new styles.

Adding imported styles to the current document

If you paste text from another Help & Manual project containing styles that are not
defined in your current project the unknown style will be displayed in red in the style
selector. You can convert this to a "known" style with Create Style from Selection.

Unknown styles are displayed in red

1. Place the cursor inside the pasted text so that the red style name is shown in the style
selector.

© 1997 - 2009 by EC Software, all rights reserved

 172 Help & Manual 5 - User Help

2. Select Styles > Create Style from Selection in the Write tab.

3. Select the Create New Style option and type the name of the unknown style exactly as
it appears in the style selector (the red text)
4. If you want to make the style the child of an existing style select the name of the
parent style you want to use in the Based On Style: list. The new style will then inherit
all common attributes from the parent style.

See also:
Defining styles 161
Editing styles 164
4.6.8 Using indents
Creating indents in a word processor is a trivial task that you hardly even need to think
about. In HTML-based formats indents are not quite so straightforward. HTML does not
support either tab stops or multiple spaces, so you cannot use them to created indented
paragraphs or to format tabular data. (Tabs and multiple spaces wouldn't work in HTML
because the page width is dynamic.)
You can use indented paragraphs – Help & Manual will convert them to stable HTML
structures when you compile to HTML-based formats. However, you should avoid using tab
stops and spaces on their own to create indented effects, because these will not work in
HTML-based outputs. You should always use the paragraph indenting functions described
below.
For some more background information see Tabs, indents and HTML 722 in the Reference
section.

Key Information
You cannot use the indent tools on single-
level bulleted and numbered lists. To
change the indent in a list you must first
switch off the list with the list tool. In outline
numbered lists the indent tools change the
list level.

How to indent paragraphs

· Use the indent tools in Write > Paragraph to increase and decrease indents.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 173

OR:
· Press Shift+Ctrl and the + or - key to increase and decrease indents.
OR:
· Drag the Indent tool in the ruler above the editor. The tool has three parts, which can all
be dragged separately: The upper triangle adjusts the first-line indent, the lower triangle
adjusts the main paragraph indent and the square box at the bottom adjusts the first
line and the paragraph indent together.

OR:
· Select the paragraph dialog icon in Write > Paragraph and set the indent values
manually.

How to create a paragraph with a hanging indent

Hanging indents work in all publishing formats, including HTML-based formats where
they are converted to stable table structures. Hanging indents are formatted in the editor
with a single tab stop between the "hanging" portion and the main paragraph. This is the
only place where you should use a tab stop for HTML-based output. Use only one tab
and don't add any spaces, otherwise you will get errors in HTML output.
· Use the Indent tool in the Toolbar to define the hanging indent:

OR:
· Select Format > Paragraph and set the indent values in the Indentation section.
See Tabs, indents and HTML 722 in the Reference section for more information on hanging
indents and how they are converted in HTML-based output.

© 1997 - 2009 by EC Software, all rights reserved

174 Help & Manual 5 - User Help

Indenting with leading spaces/blanks

In normal text:
Generally you should never indent text with leading spaces, it is much better to use real
paragraph indents. In HTML multiple spaces are normally always interpreted as a single
space Help & Manual gets around this by converting multiple spaces to alternating soft
and hard space characters. However, this still may not produce the results you need
because different browsers can interpret the widths of these different space characters in
different ways.
In program code:
Program code is often automatically indented with leading spaces. To get this to display
correctly you just need to turn word wrap off in the paragraph settings of your code
examples, either manually or with a style. Then all the spaces will be converted to &nbsp;
hard space entities which will render correctly in all browsers. Paragraphs will not wrap,
but you don't want paragraphs to wrap in program code. See Formatting program source
code 195 for more details.

Tip: Hanging indents in HTML publishing formats

In HTML hanging indents are turned into tables. This means that the left part of the
hanging indent will wrap inside the table cell if it is too long to fit. If you are only outputting
to HTML-based publishing formats this means you can make the left part of the indent as
long as you like because it will wrap in your output.
The indent in the editor:

This shows the paragraph with the

overlong text in the editor.

Result in HTML output format:

This shows the output in HTML

Help or Webhelp.
You can't use this trick if you are also outputting to PDF, printed manuals or Word RTF.
It only works in HTML-based output!

See also:
Tabs, indents and HTML 722

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 175

4.6.9 Help and print styles

You can define two different sets of attributes for every style: One for electronic help formats
(Winhelp, HTML Help, Webhelp, Visual Studio Help / MS Help 2.0, and eBooks) and one for
print-style output (PDF, printed manuals and Word RTF).

How to use different fonts for electronic and print output

1. Select Styles > Edit Styles in the Write tab.
2. Select Normal, as most other styles are usually based on this style. You will need to
edit any styles not based on Normal separately).
3. Change the font settings in the Print View and Help View tabs. Deselect Same options
as help view in the Print View tab to edit the print style settings.
4. Repeat for any styles not based on Normal these are styles that are not shown as
"sub-branches" of Normal in the style tree.

Completely different style attributes for electronic and print output

You can also create completely different layouts for electronic and print output, with a
completely different appearance for all your styles in each format. However remember
that you can only redefine the attributes of existing styles for each output format. You
cannot have different styles for each format because the styles are attached to your text
by name. There is only one list of styles, but each style can have two different definitions.
· Proceed as described above and edit all the style attributes you want to change for
each output format – you can define separate font, paragraph, border and background
settings for each view.

Preview mode for screen/print styles and font sizes

You can switch the editor display to show the styles definitions for screen output
(electronic help files) and print output (PDF, RTF and printed manuals). You can also
switch the editor's basic font sizes to emulate Windows' "large fonts" and "small fonts"
settings to check how your help will look on users' systems with these settings.
Note that different styles will only be displayed if you have actually defined different style
settings for screen and print output!
Display buttons in the status bar:

See Help and print styles 175 for more information on using different style sets for different
output formats.

© 1997 - 2009 by EC Software, all rights reserved

 176 Help & Manual 5 - User Help

See also:
About inheritance in styles 714
Defining styles 161
Editing styles 164
The Format Menu 608 (Reference)
4.6.10 Image caption and comment styles
Image captions and comments/bookmarks are formatted with two standard styles called
Image Caption and Comment. These styles are applied automatically to all image captions
and comments and they are the only styles that these elements can use.
This means that all image captions and all comments/bookmarks in your project will have
the same style. You can override these styles and change the formatting of individual
captions and comments by applying manual formatting.

Restrictions
· The Image Caption and Comment styles only have font attributes. If you set paragraph
attributes in the style definition they will be ignored.
· All the text in captions and comments has same font attributes. You cannot format
individual words differently from the rest of the text.
· Image captions are always centered, comments are always left-aligned. Since the
styles do not have paragraph attributes you cannot change these settings.

Editing the caption and comment styles

Select Styles > Edit Styles in the Write tab, then select the Comment or Image Caption
style in the list and edit its font attributes. (Don't bother editing the paragraph, border or
background attributes because these are ignored for these styles.
· See Editing styles 164 for more information.

Formatting caption and comment texts manually

You can also change the formatting of individual captions and comments manually:
· Just click on the graphic or comment in the editor to select it, then select the font
attribute you want to apply (bold, underlined, font etc).
All formatting will be applied to the entire comment or caption text. You cannot apply
different formatting to parts of the text. Also remember that you cannot apply paragraph
attributes to these texts, they will simply be ignored.

See also:
Editing styles 164
Inserting graphics and screenshots 239
Comments and bookmarks 143

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 177

4.6.11 Copying styles from other projects

Once you have created styles in one project you don't need to redefine them when you
create a new project. You can copy styles between projects, both individually and as
complete collections, which are referred to as "stylesheets".
Note that unlike many word processors Help & Manual does not store its project stylesheets
in separate files. Instead, they are stored in the project files along with all the other project
settings. This is why it is necessary to import them from the project file when you want to
copy them, instead of selecting a different stylesheet.

Copying a project stylesheet to an existing project

Note that importing a stylesheet completely replaces the stylesheet of the current project!
This is not a merge process: All the styles in the current project will be deleted, even if
they do not have the same names as the styles in the source file.
1. Make a backup of your current project and store it in a safe place. (In case you
change your mind about deleting the styles in your current project.)
2. Select Write > Styles > Edit Styles and select Copy Styles From....
3. Select the Help & Manual project you want to copy the stylesheet from and click on OK
to import and overwrite your stylesheet.

Copying a project stylesheet to a new project

If you are creating a new project the easiest way to copy the stylesheet from an existing
project is to use the existing project as a "template" for the new project. Then all the
styles of the existing project will be included in the new project automatically, along with
all of the project's other settings.
1. Open the project, click on the Application Button and make a copy of it using Save
As...
2. Delete all the topic files that you don't want to use in the new project.
3. Check your project settings in the Configuration section in the Project Explorer and
update anything that needs to be changed for the new project (project title, copyright
dates etc).
This is by far the quickest way to set up a new project if you wish to continue using the
same basic style, appearance and layout.
· See Templates for projects 417 for details.

Copying individual styles from one project to another

You cannot copy individual styles from other projects directly but it is still possible with
this little trick:
1. Open the project you want to copy the style to. We will call this Project A.

© 1997 - 2009 by EC Software, all rights reserved

 178 Help & Manual 5 - User Help

2. Open the project you want to copy the style from. We will call this Project B.
3. In Project B find a paragraph (for paragraph styles) or a piece of text (for text styles)
formatted with the style you want to copy. Use copy and paste to copy this paragraph
or text to a topic in Project A. If you now click in this text the name of its style will be
displayed in red in the style selector, like this:

4. Click anywhere in the copied text and select Write > Styles > Create Style from
Selection.
See Turning formatting into styles 169 for full instructions.

Redefining your styles with skins

In HTML-based output formats you can redefine all the styles in your entire project when
you publish by applying a "skin" containing different definitions for the styles. Basically
you create a version of your project with alternative definitions of your styles as a "skin
file" and then select this file when you publish in the Publish 590 dialog.
See Transforming your output with skins 321 for full details on using this powerful feature.
Note that you can only create your own skins with the Professional version of Help &
Manual.

See also:
Templates for projects 417
Defining styles 161
Transforming your output with skins 321
4.6.12 Table styles
Table styles define the formatting of the table itself the table width and width mode,
borders and border style, background colors and so on. They do not define the formatting of
the text inside the tables that must be formatted with styles or the manual formatting tools.

How to align a table with a paragraph style

You can control the alignment of a table by applying a style to the paragraph containing
the table for example to center a fixed-width table or to indent the left and right sides of
the table from the margins of the page. Only the paragraph attributes will have an effect,
text attributes will be ignored.
1. Click on in Write > Paragraph to display paragraph marks (this makes it easier to
see what you are doing).

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 179

2. Click to the right of the table between the table and its paragraph mark so that you can
see the blinking editing cursor between the right margin of the table and the paragraph
mark.
3. Select the style you want to apply in the drop-down style list in the Toolbar.

How to apply styles to the contents of tables

If you select all or part of a table and apply text or paragraph styles the styles will be
applied to the text in the selected cells inside the table.
· Select text and paragraphs in the table cells and apply styles just as you would in the
normal editor. You can also apply styles to multiple paragraphs in multiple cells by
selecting the cells and then applying the style.
Note that if you want to apply a style to all the paragraphs in a table you must select the
entire table by clicking and dragging inside the table. If you click in the left margin to
select the table you will not be able to apply styles because then the table is selected and
not its contents.

How to apply a table style to a table

1. Click in the table you want to format.
2. Select Properties in the Table tab and then select the table style you want to use and
click on OK.
See Working with Tables > Table styles 263 for full details.

How to define a table style

1. Select Styles > Edit Styles in the Write tab.
2. Click in the Table Styles section at the top, then select Add Style.
3. Enter a name for the style in the Style Name: field.
4. If you want to base the style on another style select the parent style in the Based on
Style: field.
5. Click on Modify Layout to define the attributes of the style. The settings are just the
same as the normal table settings 638 , although there are a couple of table settings that
cannot be included in table styles.

See also:
Working with Tables 253

© 1997 - 2009 by EC Software, all rights reserved

 180 Help & Manual 5 - User Help

4.6.13 Numbered and Bulleted Lists

The formatting definitions for numbered and bulleted lists are separate from the dynamic
styles. You can control text and paragraph formatting of your lists with normal text and
paragraph styles but the bullets, numbering of single-level lists and the levels of multi-level
lists are controlled by separate list definitions.
This chapter describes how to use numbered and bulleted lists and how to change their
appearance.

See also:
Formatting text with styles 167
4.6.13.1 Bulleted lists

To create simple bulleted lists you basically just need to select the tool in the Write tab
and start typing or just select the paragraphs you want to turn into a list and then select the
tool.
To change the text and paragraph formatting of the list contents you need to apply a style or
format the paragraph and text manually. See Formatting lists 193 for details.

How to make a quick bulleted list

Making a new list:
1. Click in the paragraph where you want to start the list.
2. Select the Bullets tool in the Write tab. Clicking on the left of the tool will apply
the default bullet style. Clicking on the arrow on the right of the tool displays a quick
gallery of available bullet styles:

3. Select a style to use and start typing. Alternatively you can also select Bullets and
Numbering to display the full Bullets and Numbering dialog.
4. Select the Bullets tool again to turn the list off. Pressing Enter twice in a list without
typing any text also turns the list off.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 181

Turning existing paragraphs into a list:

1. Select the paragraphs you want to turn into a bulleted list.
2. Select the Bullets tool in the Write tab. Clicking on the left of the tool will apply
the default bullet style. Clicking on the arrow on the right of the tool displays a quick
gallery of available bullet styles:

3. Select the style you want to apply. Alternatively you can also select Bullets and
Numbering to display the full Bullets and Numbering dialog.
If you are adding a bullet to a single paragraph select the entire paragraph or place the
cursor to the left of the very first character of the paragraph before applying the bullet.
Otherwise paragraph formatting may not work properly (particularly indents).

Changing the bulleted list style

1. Click in the list entry (for a single entry) or select the entire list.
2. Display the quick gallery by clicking on the arrow next to the Bullets tool:

3. Select a different style from the options in the gallery.

© 1997 - 2009 by EC Software, all rights reserved

182 Help & Manual 5 - User Help

Customizing a bulleted list definition

In bulleted lists you can only change the bullet character with the list definition. All other
formatting is handled by the style of the paragraph used for the list. See Formatting lists
193 for details.

1. Click in the list entry (for a single entry) or select the entire list.
2. Display the quick gallery by clicking on the arrow next to the Bullets tool:

3. Select Bullets and Numbering below the gallery to display the Bullets and Numbering
612 formatting dialog:

4. Select the bullet style you want to change, then click on Customize to edit it:

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 183

5. Select one of the bullets displayed or click on Select Bullet to select a different bullet
character.
See Formatting lists 193 for information on changing the list indent.

See also:
Formatting lists 193
4.6.13.2 Numbered lists

To create simple numbered lists you basically just need to select the tool in the Write
Ribbon and start typing or just select the paragraphs you want to turn into a list and then
select the tool.
To change the text and paragraph formatting of the list contents you need to apply a style or
format the paragraph and text manually. For details see Formatting lists 193 .
The only thing that is a little tricky at first is inserting un-numbered items within list while
maintaining the automatic list numbering. It's easy once you know how see the instructions
below for details!

How to make a quick numbered list

Making a new list:
1. Click in the paragraph where you want to start the list.
2. Select the Numbered List tool in the Write tab. Clicking on the left of the tool will
apply the default numbering style. Clicking on the arrow on the right of the tool
displays a quick gallery of available numbering styles:

© 1997 - 2009 by EC Software, all rights reserved

184 Help & Manual 5 - User Help

3. Select a style to use and start typing. Alternatively you can also select Bullets and
Numbering to display the full Bullets and Numbering dialog.
4. Select the Numbered List tool again to turn the list off. Pressing Enter twice in a list
without typing any text also turns the list off.
Turning existing paragraphs into a list:
1. Select the paragraphs you want to turn into a numbered list.
2. Select the Numbered List tool in the Write tab. Clicking on the left of the tool will
apply the default bullet style. Clicking on the arrow on the right of the tool displays a
quick gallery of available numbering styles:

3. Select the style you want to apply. Alternatively you can also select Bullets and
Numbering to display the full Bullets and Numbering dialog.
If you are formatting a single paragraph select the entire paragraph or place the cursor to
the left of the very first character of the paragraph before applying the numbering tool.
Otherwise paragraph formatting may not work properly (particularly indents).

Changing the numbered list style

1. Click in the list entry (for a single entry) or select the entire list.
2. Display the quick gallery by clicking on the arrow next to the Numbered List tool:

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 185

3. Select a different style from the options in the gallery.

Restarting list numbering

Often you will want to reset the numbering of your lists, or set your lists to start with a
specific number.
1. Select the part of the list you want to renumber:
To renumber the entire list you must select the entire list. If you select a single entry
only that entry will be renumbered.
If you want to restart numbering in the middle of a list you must select from the point
where you want renumbering to start until the end of the list.
2. Display the quick gallery (see above) and then select Bullets and Numbering to display
the Bullets and Numbering 612 formatting dialog and select the Numbered tab:

3. Select Restart Numbering to reset the list numbering to start at 1 or Start at: to select
the number you want to start with.
Note that Restart Numbering creates a new list that begins at the point where the
numbering is restarted. If you restart numbering in the middle of a list you are splitting the
list into two lists with two numbering sequences.

© 1997 - 2009 by EC Software, all rights reserved

186 Help & Manual 5 - User Help

Inserting un-numbered paragraphs in a numbered list

Sometimes you want to insert a paragraph without numbering within a numbered list and
have the numbering continue normally after the paragraph. This method is easier than
resetting the numbering:
1. Create all the text entries of the list with numbering, including the paragraph you want
to be un-numbered.
2. Click in the paragraph you want to be un-numbered and select List Tool in
the Toolbar. This will turn off numbering for that paragraph and the entries beneath the
paragraph will be re-numbered correctly. You can also select multiple paragraphs and
turn numbering off for them.
3. Now you can type text or insert a graphic in the un-numbered paragraph.
You can also restart numbering for lists that contain un-numbered paragraphs. After
resetting the numbering (see above) the un-numbered paragraphs will be numbered
again. Just select them and click on the numbering tool to switch the numbering off again.

Customizing numbered lists

1. Click in the list entry (for a single entry) or select the entire list.
2. Display the quick gallery (see above) and then select Bullets and Numbering to display
the Bullets and Numbering 612 formatting dialog and select the Numbered tab:

3. Select one of the definitions and click on Customize to modify the definition.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 187

Levels and Start numbering at: only apply to Outline numbered lists 187 (the Start
numbering at setting is for sub-levels).
List indent:
The list indent is set automatically. To change it you must change the indent of the first
paragraph in the list. See Formatting lists 193 for details.
Number style:
Just select the style from the list, it will be displayed automatically in the preview on the
right.
Number format:
This field allows you to enter characters to be displayed to the left and the right of the
number. <L1> is the variable that enters the number in the list. Don't change or delete
this entry!
"L" stands for "level" and since there is only one level in a normal numbered list <L1> is
the only variable you can use in single-level lists. You can use other level variables (<L2>,
<L3> and so on) in Outline numbered lists 187 .
1. Enter the characters you want to display with the list number to the left and right of the
<L1> variable.
Examples:
(<L1>) will generate: (1), (2), (3)
[<L1>] will generate: [1], [2], [3]
<L1>. will generate: 1., 2., 3.
2. Click on OK to save your changed definition. This overwrites the existing definition.
The Reset button in the Gallery resets the predefined lists to the default values. See
Formatting lists 193 for information on changing the list indent.

See also:
Formatting lists 193
4.6.13.3 Outline numbered lists

Outline numbered lists are pretty much the same as normal numbered lists except that they
also support multiple numbering levels and each level can have a different style. This is
much easier to demonstrate than to describe:

© 1997 - 2009 by EC Software, all rights reserved

188 Help & Manual 5 - User Help

Example of an outline numbered list:

1. This is the first level of an outline numbered list.
a. The is the second level of the list.
b. This is another second-level list entry.
2. This is another first-level entry in an outline numbered list.
a. This is a second-level entry. In this list second-level entries are numbered with a,
b, c...
b. This is another second-level entry.
i) And this is a third-level entry. In this list third-level entries are numbered with i,
ii, iii...
ii)This is another third-level entry. You get the general idea...

How to make an outline numbered list

1. Click in a paragraph or select the paragraphs you want to turn into a list. Then select
the bullets and numbering tool in Write > Paragraph. Display the quick gallery, then
select Bullets and Numbering to display the bullets and numbering 612 formatting dialog.

2. Select the Outline Numbered tab and choose the outline list style you want to apply:

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 189

3. Click on OK to create the list.

All the items in the list will initially be top-level items. See below for instructions on
creating lower-level items.
Selecting in the Toolbar automatically creates a simple numbered list. You can
change a simple list to an outline list by selecting it and then selecting a style for it in the
Outline Numbered tab.

Changing item levels

1. Click in the list entry you want to make a lower-level item.
2. Use the Indent Tools in Write > Paragraph to increase or decrease the level of
the current item
See Formatting lists 193 for information on changing the list indents.

Restarting list numbering

Note that you can only reset the numbering for the top-level list entries using this
function, because each list level is actually a separate list with its own independent
numbering sequence. To reset the numbering of lower-level entries you need to
customize the list definition (see below 187 ).
1. Select the entire outline numbered list you want to renumber.
2. Select the bullets and numbering tool in Write > Paragraph. Display the quick
gallery, then select Bullets and Numbering to display the bullets and numbering 612
formatting dialog.

© 1997 - 2009 by EC Software, all rights reserved

190 Help & Manual 5 - User Help

3. Select the Outline Numbered tab, then select Restart Numbering to reset the list
numbering to start at 1 or Start at: to select the number you want to start with:

This will only reset the numbering of the top-level entries. See Customizing outline
numbered list definitions below for instructions on resetting the numbering of lower-level
entries.

Selecting different list styles

1. Click in the list entry (for a single entry) or select the entire list. (It does not actually
make much sense to change the appearance for a single list entry...)
2. Select Write > Bullets and Numbering. to open the Bullets and Numbering dialog
and select the Outline Numbered tab:

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 191

3. Select one of the predefined outline numbered lists from the Gallery and click on OK.
OR select one of the definitions and click on Customize to modify the definition.
The Reset button resets all the list definitions in the Gallery to the default values. It is
only active if you have edited a definition.
See Formatting lists 193 for more details.

Customizing outline numbered list definitions

1. Select a list definition in the Outline Numbered tab (see above) and select Customize
to modify the definition.

2. Edit the list definitions for each level of your list that you want to change by selecting
the level number in the Levels box on the left. The results for each level are displayed
in the Preview box on the right.
Note that there is a separate definition for each level of your outline numbered list! You
must edit all the values for every list level that you want to change.
3. Click on OK to save your new outline numbered list definition to the Gallery. This will
overwrite the current definition.
The Reset button in the Outline Numbered tab resets all the predefined lists to the default
values.
See Formatting lists 193 for more details.

© 1997 - 2009 by EC Software, all rights reserved

192 Help & Manual 5 - User Help

Number style:
You can choose a different numbering style for each level. Select the level from the list
on the left, then select the numbering style. The selected style will be displayed
automatically in the preview on the right.
Number format:
This field allows you to enter characters to be displayed to the left and the right of the
number for each level.
· <L1>, <L2>, <L3> and so on are the variables that enter the numbers in the list for
each level. Don't change or delete these entries! Also note that the number of each
variable must correspond to the level number. For example, <L1> is for level 1, <L6>
for level 6, and so on.
· For each level, enter the characters you want to display with the list number to the left
and right of the <Lx> variable.
Examples:
(<L1>) will generate: (1), (2), (3)
[<L1>] will generate: [1], [2], [3]
<L1>. will generate: 1., 2., 3.

Start numbering at:

This setting allows you to set the number at which numbering is to begin for the current
level. The setting is stored separately for each level and must be set for each level.
Legal numbering style:
Activates legal numbering style for outline numbered lists, with all the list numbers at the
left margin. Must be set separately for each level of an outline numbered list!

· You cannot have different indent sizes for individual levels in outline numbered lists.
Because of this the legal numbering style is preferable for lists with large numbers of
levels otherwise you would have a very large indent for the top level and smaller
indents for the lower levels, which does not look so harmonious.
Level reset:
When this is selected the numbering of sub-levels in outline numbered lists always re-
starts with 1 or the equivalent. Otherwise the numbering continues from one sub-level to
the next. Must be selected separately for each level of the outline numbered list!

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 193

Changing the number of levels:

By default outline numbered lists have 9 levels. You can increase or decrease this
number with the Count: setting. The maximum number of levels is 20. Even 9 is actually
far too many – lists should never have more than four or five levels at the maximum,
otherwise they are much too confusing for the reader.

See also:
Numbered lists 183
Formatting lists 193
4.6.13.4 Formatting lists

List definitions only define the bullet or numbering styles to be used, they do not allow you to
format indents or paragraph formatting. Paragraph formatting and indents can be applied
manually or with styles. In addition to this you can also change the appearance of the bullets
and numbers (color, bold, italic etc) by applying manual formatting in the list items.

Key Information
By default lists have their own hidden
indent for the numbers or bullets, which is
not displayed in the editor ruler. To use
your own indent you must apply a style or
format the paragraph manually.

How to change list indents

The paragraph settings of lists, including the indent for the bullets or numbers, are
controlled by the first item in the list. To change the indent or the paragraph formatting of
the entire list you just need to format the first item.
1. Click in the first item in the list. If the list has only one item you must click to the left of
the very first character in the first line of the list item.
2. Adjust the indent of the list with the paragraph tool in the ruler above the editor:

You can also adjust list indents by applying an indented paragraph style to the first item in
the list. Note that in outline numbered lists you can only set one indent for the entire list,
including the lower levels.

Formatting lists manually and with styles

· You can change the paragraph settings of an entire list by formatting the first item of
the list manually or with a paragraph style. If the list has only one item place the cursor
to the left of the first character in the first line before applying a style.

© 1997 - 2009 by EC Software, all rights reserved

 194 Help & Manual 5 - User Help

· If you also want to apply font settings you must apply styles to all the items in the list.

The indent tools don't work!

If you use the indent tools in single-level lists you will just get an error message.
This is because in lists the indent tool is used for changing the list level, but this only
works in multi-level outline numbered lists. In single-level lists you will get an error
message because the list only has one level and you cannot change it to a higher or
lower level.
· If you want to use the indent tools on single-level lists you must first select the entire list
and "turn off" the list by clicking on the bulleted or numbered list tool. After changing
the indent with the indent tool you can then turn the list on again.
· It is easier to change the list indent by formatting the first list item manually or applying
a style (see above).

How to make bold and colored numbering and bullets

The formatting of bullets and numbering in lists is controlled by the formatting of the last
character in the first item of the list.
· To make bold numbering add a space to the end of the first item in the list, select the
space and make it bold. The numbering will also be bold if the entire first item is bold,
of course.
· You can use the same method to change the color of the numbering or the bullets in
the list. Just format a space at the end of the first item with a color the space is
invisible so the color won't show.

See also:
Bulleted lists 180
Numbered lists 183
4.6.13.5 HTML list output format

By default Help & Manual outputs numbered and bulleted lists as tables in HTML-based
output formats (HTML Help, Webhelp, Windows Exe and ePub eBooks, Visual Studio Help).
This is necessary to obtain accurate formatting because the rendering of lists varies very
considerably from one browser to another.
Even HTML Help, which uses Internet Explorer for HTML rendering, will frequently produce
unsatisfactory list formatting if you do not use tables. This applies particularly to more
complex lists and the indents used in lists.

How to choose the HTML list output format

If you want you can configure your project to output lists as standard HTML <OL> and
<UL> tags with <LI> list elements. This will produce less attractive formatting and layout
in many cases and the appearance will vary greatly from browser to browser. However, it
may be necessary for some applications.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 195

· Go to Configuration > Publishing Options > Webhelp > HTML Export Options
684 and deselect the option Export lists as tables.

Note that the HTML Export Options settings are available in several different sections in
Configuration > Publishing Options. These are shared settings used by all HTML-based
output formats and it doesn't matter where you access them.

See also:
HTML Export Options 684
4.6.14 Formatting program source code
Examples of program source code are much easier to read if reserved words, comments,
identifiers and so on are highlighted as they are in a modern programming editor. Help &
Manual's Syntax Highlighting function does this for you. It understands the syntax of Pascal,
C++, C#, Visual Basic, ANSI SQL and Visual Objects. It knows the reserved words of these
languages and can distinguish between plain text, comments, strings, numbers and even
compiler directives, where they are supported. You can also add your own reserved words.

How to format program code

1. Paste your program code into your topic and select it.
2. Select the Syntax Highlighter tool in Write > Font then select the language
parser you want to use from the list displayed.
Once you have chosen a language parser it is set as the default until you select a
different language. You can then select it directly by clicking on the Syntax Highlighter
tool in the Ribbon.

Editing the syntax highlighting style

The syntax highlighter uses a standard style called Code Example for the font and
paragraph attributes. By default this style is set to Courier New, 8 points, no word wrap
and keep paragraph lines together.
You cannot delete or rename this style but you can edit it. Just position the cursor in a
piece of text formatted with the syntax highlighter and select Styles > Edit Styles in the
Write tab to open the style editing dialog with the Code Example style selected. See
Editing styles 164 for details.

Indenting with leading spaces/blanks

Program code is often automatically indented with leading spaces. To get this to display
correctly you just need to turn word wrap off in the paragraph settings of your code
examples, either manually or with a style. Then all the spaces will be converted to &nbsp;
hard space entities which will render correctly in all browsers. Paragraphs will not wrap,
but you don't want paragraphs to wrap in program code.
In paragraphs with word wrap turned on Help & Manual converts multiple spaces to
alternating soft and hard space characters otherwise browsers would interpret multiple

© 1997 - 2009 by EC Software, all rights reserved

196 Help & Manual 5 - User Help

spaces as a single space. However, this will often not render quite right because different
browsers interpret the width of these hard/soft space combinations in different ways.

Customizing the syntax highlighter

· Click on the drop-down arrow next to in Write > Font, then select Customize.

Font color and style:

You can define the font style and color for the supported elements for each language
parser. To change the standard syntax highlighting font face click on Edit Style and edit
the Code Example style that is used automatically by the syntax highlighter (see above 195
).
Loading your own reserved words:
You can add your own reserved words to the lists used by the syntax highlighter or
completely replace the highlighter's lists with your own lists:
1. Create a plain text file containing your reserved words, with one word on each line.
2. Select the button in the Load reserved words from file: field and select your reserved
words text file.
3. Select Add list to predefined reserved words to merge your list of words with the
syntax highlighter's list for the current programming language. Deselect this option to
replace the highlighter's list with your list.
Restoring the default settings:
Clicking on Reset Defaults restores all the syntax highlighter's settings for the current
language to Help & Manual's default values, including the list of reserved words.

See also:
Editing styles 164

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 197

4.6.14.1 Examples

Pascal code:

{ Syntax Highlighting }
procedure TForm1.Button1Click(Sender: TObject);
var
Number, I, X: Integer;
begin
{$IFDEF WIN32}
Number := 654321;
{$ELSE}
Number := 123456;
{$ENDIF}
Caption := 'The number is ' + IntToStr(Number);

for I := 0 to Number do
begin
Inc(X);
ListBox1.Items.Add(IntToStr(X));
end;

asm
MOV AX, 1234H
MOV Number, AX
end;
end;

C++ code:

// Syntax Highlighting
void __fastcall TForm1::Button1Click(TObject *Sender)
{
Caption = "The number is " + IntToStr(i);

int i = 123456;
double d = 123.45;
char c = 'a';

#ifdef FULLMOON

asm
{
ASM MOV AX, 0x1234
ASM MOV i, AX
}
#endif

Visual Basic code:

'******** Visual Basic syntax highlighting example ********

'**********************************************************
Option Explicit

© 1997 - 2009 by EC Software, all rights reserved

198 Help & Manual 5 - User Help

' User-defined type to store information about child forms

Type FormState
Deleted As Integer
Dirty As Integer
Color As Long
End Type

Public Document() As New frmNotePad

Public gFindString As String
Public Const ThisApp = "MDINote"

Function AnyPadsLeft() As Integer

Dim i As Integer ' Counter variable

' Cycle through the document array.

' Return true if there is at least one open document.
For i = 1 To UBound(Document)
If Not FState(i).Deleted Then
AnyPadsLeft = True
Exit Function
End If
Next
End Function

SQL code:

Select BUYERID, max(PRICE)

from ANTIQUES
group by BUYERID
having PRICE 1000;

Select BUYERID
from ANTIQUES
where PRICE > (Select avg(PRICE) + 100 from ANTIQUES);

alter table ANTIQUES

add (PRICE DECIMAL(8,2) Null);

insert into ANTIQUES (BUYERID, SELLERID, ITEM)

values (01, 21, 'Ottoman');

delete from ANTIQUES

where ITEM = 'Ottoman'
And BUYERID = 01
And SELLERID = 21;

update ANTIQUES
Set PRICE = 500.00
where ITEM = 'Chair';

create index OID_IDX On ANTIQUEOWNERS (OWNERID);

drop index OID_IDX;

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 199

4.7 Managing the TOC & Topic Files

The Table of Contents (TOC) and Project Files sections in the Project Explorer are much
more than just a place to display the contents of your project. They are also a powerful
editing tool for manipulating the structure of your project. In the TOC section you can move
topics around to change the structure and organization of your project whenever you want.
These sections are also where you create new topics 110 . You create topics in the Table of
Contents section to include them in your project's TOC. In addition to this, you can also
create topics that are not included in the TOC by creating new topic files directly in the
Project Files section
Once you have added topics to the TOC you can manipulate them in many ways. You can
move them around, change their names, status and icons, cut and paste them (also
between projects) and demote or promote them to change their positions and status in the
TOC tree hierarchy.
All these operations can be performed in seconds with the mouse and/or simple keyboard
and menu commands.

Managing the TOC & Topic Files

Ø Moving, cutting and pasting
topics 199
Ø Changing the levels of topics 203
Ø Exporting and importing topics
204

Ø Topic files without TOC entries

210

Ø Managing topic files in the

Explorer 211

4.7.1 Moving, cutting and pasting topics

To change the structure of your project you need to be able to move topics around in the
Table of Contents (TOC). You can do this by dragging topics with the mouse or by cutting
and pasting. You can also copy, cut and paste between different projects in the Project
Explorer.
Note that all these operations must be performed in the Table of Contents section of the
Project Explorer. Different rules apply for managing your topic files directly in the Topic Files
section see Managing topic files in the Explorer 211 for details.

Key Information
There is no UNDO in the Table of Contents
(TOC) all changes that you make here
are permanent! In addition to deleting TOC
entries this also applies to cutting, pasting

© 1997 - 2009 by EC Software, all rights reserved

200 Help & Manual 5 - User Help

and moving TOC entries. Use Explore >

Disable Drag & Drop in the Project tab to
prevent accidental changes to the TOC.

Moving and copying topics with Drag & Drop

Drag & Drop can only be used on single topics. To move or copy multiple topics you must
use Cut & Paste. You can perform these operations both within the same project and
between multiple projects open at the same time in the Project Explorer.
Move: Select and drag with the left mouse button
Copy:Select, hold down Ctrl and drag with the left mouse button

· Select a topic or chapter in the TOC and drag it onto another TOC entry (target topic is
highlighted) to make topic you are dragging the child (sub-topic) of the target topic.
· Select a topic or chapter and drag it between two other topics (a blue line is displayed
between the target topics) to insert the topic you are dragging before/after the target
topic. Position the mouse pointer to the right or left of the topic caption to display the
blue line.
Note: You can create a second TOC reference 208 to an existing topic by holding down
Shift+Ctrl and dragging a topic in the TOC!

Moving topics with the Ribbon tools

The Ribbon tools can only be used on single topics. To move multiple topics you must
use Cut & Paste (see below).

The Up and
Down arrows
move topics.
Select the topic you want to move, then select the blue Up or Down arrow in Project >
Manage Topics to move the selected topic up and down one step at a time.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 201

Moving and copying topics with Cut & Paste

You can use Cut & Paste to move and copy multiple topics and chapters at the same
time. To select multiple entries use Shift+Click to select continuous blocks of entries
and Ctrl+Click to select multiple individual entries in different locations.
1. Select a topic or chapter in the TOC or in Topic Files and then use one of the Copy or
Cut options:
Keyboard shortcuts: Ctrl+C (copy), Ctrl+X (cut)
Ribbon: Clipboard tools
Context menu (right-click in TOC): Copy, Cut
2. Click on the topic after which you wish to insert the topic and use one of the Paste
options:
Keyboard shortcuts: Ctrl+V
Ribbon: Clipboard tools
Context menu (right-click in TOC): Paste
When you copy topics "(COPY)" is added to the topic caption in the TOC and "_2" (or _3
etc.) is added to the Topic ID in the to prevent duplicates. See Multiple TOC entries for
one topic 208 for an alternative to copying.

Moving and copying topics between projects

You can also copy and move single and multiple topics and chapters between projects:
1. Open the second project in the Project Explorer. Use the Split Explorer tool in the
Write tab to make it easier to see both parts of both projects at the same time. See
Using the Project Explorer 41 for details.
2. Follow the instructions above to copy or move topics and chapters.

See also:
Promoting and demoting topics 203
Copying, cutting and pasting 139 (text and content)
Importing topics and merging projects 102
4.7.2 Deleting TOC entries and topics
Topics and their TOC entries are two different things. The topic content is actually stored in
the topic file, which is stored in the Project Files section of the Explorer. The TOC entry is
really just a hyperlink to the topic file, which is stored in the Table of Contents section of the
Explorer. When you click on a TOC entry the topic file is displayed in the editor for editing,
but this is just for convenience. there are not actually any topic files in the TOC, when you
click on a TOC entry and edit the topic you are actually editing the file stored in the Topic
Files section.

© 1997 - 2009 by EC Software, all rights reserved

202 Help & Manual 5 - User Help

How to delete TOC entries

1. Select one or more entries in the Table of Contents section in the Project Explorer.
You can select multiple entries with Ctrl+Click and Shift+Click.
2. Press the DEL key or right-click and select Delete Topic. The following dialog is
displayed:

If you deselect the Also delete referred topic files option only the TOC entry/entries will be
deleted. This will result in topics without TOC entries in the Topic Files section.

How to delete topic files

1. Select one or more entries in the Topic Files section in the Project Explorer. You can
select multiple entries with Ctrl+Click and Shift+Click.
2. Press the DEL key or right-click and select Delete File. The following dialog is
displayed:

If you deselect the Also remove TOC references option only topic files be deleted. This
will result in TOC entries without any links to topic files. This is not normally desirable but
you may sometimes want to do this to reassign an existing TOC entry to a different topic.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 203

4.7.3 Changing the levels of topics

The Table of Contents (TOC) in most projects is organized in chapters with sub-chapters.
You can change the structure by moving topics around 199 and by changing their levels.
Changing the topic level is referred to as "promoting" or "demoting" a topic promoting a
topic moves it to a higher level in the TOC, demoting it moves it to a lower level.
Topics with sub-topics are automatically displayed as "chapters", shown with a book icon in
the TOC.
You can also organize topic files in the Topic Files section in folders and sub-folders, but this
is for convenience only. It does not have any effect on the structure of your project.

How to promote and demote topics with the Ribbon tools

The topic tools in Project > Manage Topics can be used to move topics up and down in
the TOC (Up and Down arrows) and to promote and demote topics (Left and Right
arrows). These tools can only be used on single topics.

· The Promote button (left arrow) promotes the current topic to the next level by moving
it one step to the left.
· The Demote button (right arrow) demotes the current topic to the next level by moving
it one step to the right.

How to promote and demote topics with the mouse

· Just drag the topic to the new position in the TOC. If you drag onto another topic it will
become the child of the target topic. If you drag between two topics (position mouse to
left of topic icons) it will be inserted between the target topics.

· It is easier to use Cut & Paste 199 to promote and demote topics over large distances in
large, complex TOCs.

See also:
Moving, cutting and pasting topics 199

© 1997 - 2009 by EC Software, all rights reserved

 204 Help & Manual 5 - User Help

4.7.4 Exporting and importing topics

You can export and import individual topics with the functions in the functions in the File
menu in Project > Manage Topics. You can save topics and select parts of topics to Help
& Manual XML files and you can load topics from XML, HTML, RTF and RVF files.
These functions can be used to create a library of reusable content in Help & Manual XML
topic files, which can also be used in combination with the Snippets tool 149 and the topic
content templates 423 feature. In addition to XML files you can also load topics from HTML,
Word RTF and RVF files.

How to export a topic as an external XML file

This method saves the entire topic file along with its title and any keywords associated
with it. Note that you cannot export multiple topics using this method.
1. Select the topic you want to export in the Project Explorer.
2. Select File > Save Topic to File in Project > Manage Topics.
3. Select the directory where you want to save your topic file and save.
If you want to use the file as a topic content template 423 you must name the file as
follows, replacing "filename" with the name you want to use (the .template.xml
extension is required):
filename.template.xml

How to export a topic or selected text as a snippet

Topics and selected text can be exported as reusable snippets, which are also saved in
XML files. Saving an entire topic as a snippet is exactly the same as saving it with Save
Topic to File it also exports the topic title and all the keywords. Saving selected text as a
snippet only saves the selected text and does not include any keywords or the topic title.
1. Select the topic you want to export from in the Project Explorer.
2. Select text in the topic if you only want to export part of the topic. You can select any
kind of content, including graphics, hyperlinks, toggles etc. If you do not select
anything the entire topic will be exported.
3. Select File > Save Snippet in Project Manage Topics.
4. Select the directory where you want to save the snippet and save.
See Re-using content with snippets 149 for more details on working with snippets.

Supported XML formats

Help & Manual can only process XML files conforming to the Help & Manual XML
Language. These can be produced by Help & Manual itself or generated by other
programs that conform to the language schema specifications. Documentation of the
updated version of the Help & Manual XML Language used in Help & Manual 5 is going
to be released as soon as possible.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 205

How to import a topic from an external file

This method is for importing individual topics. For instructions on how to import multiple
topics from a single Word RTF file see Settings for Importing Data 105 .
Note that Importing a topic into an existing topic overwrites the entire contents of the
existing topic! If you just want to insert another topic into the current topic use the Snippet
Tool 149 instead.
1. Create a new, empty topic in the position in the TOC where you want to import the
topic. Click inside the editor window in the new topic.
2. Select File > Load Topic from File in Project > Manage Topics and select the topic
file you want to load. You can load XML, HTML, RTF and RVF files.
You can only import XML files created with Help & Manual or files created with other
programs using the Help & Manual XML Language schema. Other XML formats or
schemas are not supported. RTF files created by programs other than MS Word or
Help & Manual may contain incompatible features. If in doubt re-save the file in Word
before importing.
3. Select the topic file you want to load.

How to export topics to the Word RTF format

To do this you must compile your project using the "selected topics" option. Unlike Save
Topic to File you can also export multiple topics at the same time with this function.
However, remember that RTF does not support all of Help & Manual's formatting
features. If you want to re-import your topics later it is better to save as XML.
1. Select the topic or topics you want to export in the Project Explorer.
2. Select Publish in the Project tab and select MS Word as the output format.
3. Select Selected Topics in the section under the Include Options: heading.
4. Use the button in the Output path and file name: field to select the location and file
name for the export.
5. Click on OK to export the topic(s).

See also:
Importing Data 99
Content templates for topics 423
Compiling your Project 311
Importing topics and merging projects 102
4.7.5 Topic IDs and context numbers
The topic ID is the unique alphanumeric identifier of a topic. It must be unique because it is
used to reference the topic for hyperlinks and by programmers accessing the topic from
applications.
The help context number is an additional unique topic identifier. It is optional and it is only

© 1997 - 2009 by EC Software, all rights reserved

206 Help & Manual 5 - User Help

used in Microsoft HTML Help (CHM files) and the obsolete Microsoft Winhelp (HLP files)
format. Context numbers are only used as addresses for help calls made from applications.
Most programmers now use topic IDs and you only need to use help context numbers if your
programmers ask you to do so.
The topic IDs and help context numbers of each topic can be viewed and edited in the tab in
the editor. For more background information see IDs, Context Numbers and Keywords 801 in
the Reference section.

Key Information
Accented characters, special characters
and high-ASCII characters are not
permitted in IDs. For maximum
compatibility with all output formats only
use a..z, A..Z, 0..9 and _ in topic IDs. Topic
IDs are never seen by the user.

How to assign and edit topic IDs

Topic IDs are assigned automatically when you create a new topic but you can also edit
them at any time.
· When you create a new topic the ID is generated on the basis of the topic caption. You
can accept the program's suggestion or edit it. Use descriptive topic IDs, it will make
your project much easier to manage. IDs can be up to 255 characters long.
· To edit a topic's ID just select the tab under the editor and edit the ID in the Topic ID:
field.
All links and references within your project are updated automatically when you edit the
ID. However, you must update any references to the ID from your applications or other
help files yourself. You must also update any references in your own manually-written
code in HTML templates etc.

How to assign and edit context numbers

Context numbers are stored as an unsigned 4-byte integer, which means you can enter
values between 1 and 4294967295. This is nearly 4.3 billion, so it should provide you with
a reasonable number of context numbers for most normal-sized applications.
Assigning and editing context numbers manually:
· Select the tab and type a help context number in the Help Context: field. Edit context
numbers in the same way.
· You can assign multiple context numbers to a single topic. To do this just separate the
context numbers by commas (no spaces required). You can then reference the same
topic with different context numbers.
Assigning context numbers automatically:
· Help & Manual can assign context numbers to new topics automatically. Activate this
function for your project in the Project Explorer in Configuration > Common

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 207

Properties > Miscellaneous.

· If you are working on modular projects make sure that you assign number ranges that
will not overlap. Remember, all context numbers must be unique!
Assigning context numbers to entire projects:
· Select the Context Tool in Project > Tools and follow the instructions displayed. See
The Help Context Tool 539 for details.

Assigning help context numbers to anchors

You can also assign help context numbers to anchors 226 . This enables programmers to
make calls to a specific position within a topic.
· To apply a context number to a new anchor just select Write > Insert Object >
and enter a context number in the Help Context field in the Insert Anchor dialog.
· To apply context numbers to new anchors automatically activate the anchors option in
Configuration > Common Properties > Miscellaneous.

Descriptive and hierarchical Topic IDs

It's advisable to give topics descriptive IDs, this will make your projects much easier to
manage. In addition to this, using a "hierarchical" topic ID naming scheme will keep topics
belonging to the same chapters together in lists of topic IDs.
Suppose you have a project called Widget Editor with a chapter called The Editor that
contains the topics About the Editor, Editor Controls and Using the Editor.
Descriptive, hierarchical IDs for these topics could look something like this:
WE_Editor
WE_Editor_About
WE_Editor_Controls
WE_Editor_Using

Topic ID prefixes
Using a unique topic ID prefix for each project prevents ID conflicts in modular projects 446
. This allows you to use IDs like "introduction" in all your projects without creating
duplicates.
If there is even a small chance that you will ever want to combine multiple projects to a
single large project you should use ID prefixes. It is best to use a 2 or 3 character project
identification prefix separated from the rest of the ID by an underscore, for example:
WE_Editor
WE_Editor_About
WE_Editor_Controls
WE_Editor_Using
You can configure Help & Manual to generate a prefix of your choice automatically for
every new topic you create. Just enter the prefix you want to use in the Project Explorer

© 1997 - 2009 by EC Software, all rights reserved

 208 Help & Manual 5 - User Help

in Configuration > Common Properties > Miscellaneous.

See also:
IDs, Context Numbers and Keywords 801 (Reference)
4.7.6 Multiple TOC entries for one topic
Normally you only have one item in the Table of contents (TOC) for each topic file. However,
there may be some situations where you want to use exactly the same topic in more than
one place in the TOC.
You can do this by creating multiple references to an single topic in the TOC. The result is a
single TOC topic that can be accessed from multiple positions in the TOC. There is still only
one topic, but it is displayed in several different positions within the TOC – for example in
different chapters.
Sometimes it is better to create a copy or to use an embedded topic. See Snippets and
multiple TOC references 751 for more background information.

Key Information
Multiple TOC references are not copies of
topics. There is still just one topic file but
with two items pointing to it in the TOC. It is
like a single room with two doors.

Creating additional topic references with Add Topic

1. Click in the TOC in the position where you want to enter the new TOC item, then
select any of the options for creating a new topic 110 .
2. When the Insert Topic 581 dialog is displayed select Topic/Chapter edit the topic
caption. The second reference can have a different caption from the original topic, this
is the only difference allowed.
3. Click on the browse button in the Topic ID: field and select the ID of the topic you
want to create a second reference to.
4. Click on OK. A prompt will be displayed asking you to confirm that you want to create
a new reference to an existing topic.

Creating additional topic references with Drag & Drop

1. Click on the topic you want to make an additional reference to in the TOC to select it.
2. Hold down Shift+Ctrl and drag to the position where you want to create the second
reference. Dragging onto a topic makes the new reference a child (sub-topic) of the
target topic. Dragging between two topics (position mouse to left of topic icons)
inserts the reference between the target topics. (See Moving, cutting and pasting
topics 199 .)
Warning for Parallels users:

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 209

If you are running Windows in Parallels on an Apple Mac this will not work initially. This is
because by default Parallels maps the right mouse button to Shift+Ctrl+Left Click.
You need to re-map this key combination in the Parallels settings to be able to create
additional TOC references with Drag & Drop.

See also:
Using embedded topics 149
Moving, cutting and pasting topics 199
4.7.7 Topic icon, status and timestamps
You can change the standard topic icons displayed in the Table of Contents (TOC). You can
also apply a "status color" to topics in the TOC to identify topics that need more work. Every
topic file and every TOC entry has a "timestamp" which records when they were last edited.

Productivity Tip
You can insert the date on which the
topic was last edited in the topic with a
variable. See Global predefined
variables 774 for details.

How to change the topic icon and status color

1. Select one or more topics in the TOC. Use Ctrl+Click and Shift+Click to select
multiple topics.
2. Select Change > Change Icon / Topic Status... in Project > Manage Topics or right-
click in the TOC and select Change Icon / Topic Status...
Icon: Choose the new icon from the list displayed to select it. Select Automatic to
reset the default icon.
Status color: Select the status color from the list. The status color is only displayed in
the editor, it is not exported when you publish.
Winhelp does not support custom icons the standard icons will always be displayed.
HTML Help and Windows Exe Books only support the icons displayed in the Change
Icon list.
ePub eBooks do not support topic icons at all, they are not used in this format.
Webhelp allows you to use your own icons. In the Project Explorer go to Configuration
> Publishing Options > Webhelp > Navigation to select your own icon graphics.

Checking topic and TOC entry timestamps

Every topic file and every TOC entry stores the date and time it was last edited. These
timestamps are only changed when the topic or TOC entry is actually edited, they are not
changed when the project is saved.

© 1997 - 2009 by EC Software, all rights reserved

 210 Help & Manual 5 - User Help

Topic file timestamp:

Click on the topic entry in the TOC or Project Files list. The topic file timestamp is
displayed in the status bar below the editor.
TOC entry timestamp:
Hover the mouse pointer over the topic entry in the TOC or Project Files list for a second
or so. The timestamp is displayed in a popup tooltip along with other information.
(Mouseover hints must be activated in View > Program Options > General.)

4.7.8 Topic files without TOC entries

Most topics have entries in the Table of Contents (TOC). However, sometimes you also
need topics that are not included in the TOC. For example, topic files without TOC entries
are generally used for popup topics and for topics that are displayed in external windows in
HTML Help and Winhelp. You can also use them for topics that are only displayed when the
user clicks on a link.
To create a topic file without a TOC entry you just create the file in the Topic Files section of
the Project Explorer instead of in the Table of Contents section.

How to create a topic file without a TOC entry

1. In the Project Explorer open the Project Files > Topic Files section.
2. Select Add File > Add New File in Project > Manage Topics.
3. Enter the name of the topic you want to create. You can create multiple files by
entering multiple names, one on each line.
4. Click on More Options and select a folder in Create in: to create the topic file in a sub-
folder that you have created in the Topic Files section.
5. Select any other relevant settings for the topic.

Organizing topic files in folders

You can create sub-folders in the Topic Files section to organize your files. It is a good
idea to use separate folders for the various different types of topics files that are not
included in the TOC to keep them separate from your TOC topic files.
1. Open the Topic Files section in the Project Explorer and select the folder that you want
to add a new sub-folder to.
2. Select Add File > Add New Folder in Project > Manage Topics and enter a name
for the new folder.
When you create new topics you can then click on More Options and select Create in: to
create the topic file for the new topic in a specific folder.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 211

Using status options and include options topic files

You can apply both topic status and include options to topic files in the Project Files
section of the Project Explorer. Just right-click on the file in the Explorer and select the
options in the context menu, or select the options in the Change menu in Project >
Manage Topics.

How to add a TOC entry to a topic file

Sometimes you may decide that you would like to add a TOC entry to a topic file that
does not yet have one. To do this you just need to create a new entry in the TOC and
specify the Topic ID of the topic file.
1. Select the topic file you want to create a TOC item for and open the tab behind the
editor.
2. Copy the Topic ID to the Windows clipboard.
3. Move to the Table of Contents section in the Project Explorer, click where you want to
insert the new TOC item and select Add Topic in Project > Manage Topics.
4. Select Topic/Chapter on the left and enter a heading for the topic.
5. Paste the topic ID you copied in step 2 In the Topic ID: field and then click on OK.
You will be asked if you want to create a new item for an existing topic. Confirm to create
the new TOC item.

See also:
Creating new topics 110
Promoting and demoting topics 203
Conditions and Customized Output 399 .
4.7.9 Managing topic files in the Explorer
When you are working in the Project Files section the Project Explorer is also a file manager
for your topic files and the folders where they are stored. If you are working in
uncompressed XML format (Professional version only, .hmxp project file) the files and
folders are stored directly on your hard drive. In the compressed single-file .hmxz format the
files and folders are stored inside the compressed .hmxz file.

How to "filter" topics by build/include options

You can use include options to "filter" the display of your topics in the TOC and Topic
Files section of the Project Explorer. This makes it possible for you to see only the topics
that will be included in a specific build, so that you can preview the results of specific build
options without publishing your project.
1. Apply build options to one or more topics if you don't do this filtering will not have any
effect! See Conditions and Customized Output 399 for details.

© 1997 - 2009 by EC Software, all rights reserved

212 Help & Manual 5 - User Help

2. Select Explore > Filter in Project > Manage Topics and set the filter options you
want to apply. The filter settings are also available from the right-click menu in the
Project Explorer (Explore > Filter).
This works both in the TOC and in Topic Files. This only filters entire topics, it does not
filter conditional text tagged within your topics.
The current build settings of topics are shown in the Project Explorer. Topics and
chapters set to All Builds (the default) will always be included, of course you cannot
hide them.

How to view topic files and folders in the Explorer

Folders:
Select Topic Files in the Project Files section of the Project Explorer. This will initially
display a list of the folders in which your topic files are stored. How many folders are
displayed will depend on whether you have created sub-folders:

Files:
Select the Topics folder or any other folder in the Topic Files section:

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 213

How to sort and group files in the Project Explorer

You can sort and group files by several different criteria (name, mod status, mod date,
build option, topic status color). You can combine sorting and grouping: When the files
are grouped the sorting options are applied within each group.
Sorting the files:
Just left-click in the column header you want to sort by. Alternatively you can also right-
click in the column header and select the sort option in the context menu.
Grouping the files:
Right-click in the column header and select the group option in the context menu, or
select Ungroup to return to an ungrouped list.

Creating folders for organizing topic files

You can create additional folders in the Topic Files section to organize your files to make
them easier to manage. For example, it is a good idea to keep topic files without TOC
entries in separate folders.
1. Select the folder in which you want to create your new folder for example Topics.
2. Right-click and select Add New Folder in the context menu, or select Add File > Add
New Folder in Project > Manage Topics.
3. Enter the name for the new folder and select OK,

Moving, deleting and renaming topic files

Cutting and pasting is not possible with topic files in the Topic Files section because you
are actually dealing with physical files. If you want to move topics around in your TOC by
cutting and pasting you must do this in the TOC see Moving, cutting and pasting topics

© 1997 - 2009 by EC Software, all rights reserved

 214 Help & Manual 5 - User Help

199 for details. However you can move files between folders and delete files in the Topic

Files section.
Moving topic files and folders:
To move a topic file from one folder to another just drag it to the new folder with the
mouse. You can also move folders in the same way.
Deleting topic files:
Just select the topic file in the Explorer and press DEL or right-click and select Delete
File.
Renaming topic files:
You cannot rename topic files directly. To rename the topic file you need to edit the Topic
ID.
1. Select the topic file in the Explorer.
2. Select the tab in the editor pane, edit the Topic ID and save your project to update the
Topic Files display.

See also:
Moving cutting and pasting topics 199
Using the Project Explorer 41

4.8 Links, Anchors, Macros, Scripts and HTML

Links, more properly referred to as "hyperlinks", are what makes electronic help so much
more useful and flexible than printed documentation. Hyperlinks allow you to refer directly to
related information, creating a non-linear "web" of information that is much better at
describing complex programs and processes than linear documentation.
Another subject covered in this section is Help & Manual's function for editing and inserting
plain or "inline" HTML code in your help files. If you know how to code HTML you can use
this function to add features and formatting with scripts and blocks of code. Use sparingly
however, otherwise it can make your projects more difficult to manage!

4.8.1 Supported hyperlink types

Help & Manual can create several different types of hyperlinks, which are used for linking to
different items or providing additional functionality:
Topic links: These links create "jumps" to other help topics, which can be in the
current help project or in other help projects or help files.

Topic Anchors are not really links in their own right – they are "targets" for topic
anchors: links. They allow you to create a links that go to specific positions in a
topic instead of to the top of the topic.

Internet Links to HTML pages on the World Wide Web or email addresses.
links:

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 215

File links: Links to external files on the user's computer.

Script/ These are not really hyperlinks in the real sense of the word. Instead of
macro links: taking the user to another page or topic clicking on them executes
JavaScript code or a Winhelp macro (which may actually link to
something, but it doesn't have to).

4.8.2 Inserting topic links

The easiest way to create hyperlink to another topic in your current project is with Drag &
Drop just select text in the editor and drag it onto the topic you want to link to in the Table
of Contents.

Productivity Tip
You can navigate to the targets of your
links within your project by holding down
Ctrl and clicking on the link.

How to create a topic hyperlink with Drag & Drop

1. Select the text in your topic that you want to use as the link caption (you can edit this
later).

2. Drag the selected text onto the topic in the Table of Contents (TOC) that you want to
link to and release the mouse button.
3. To view and edit the hyperlink settings double-click on the link to display the Hyperlink
617 dialog box.

Links to anchors:
To quickly create a link to an anchor 226 in the current or another topic just create the link
with Drag & Drop and then double-click on the link to select the target anchor in the
dialog. Select the anchor from the drop-down list next to the Target: field (see below for
details).
Links to popup topics:
You do not need to do anything special to create a popup link. Links to popup topics 125 in
your project automatically open the target topics as popups.

© 1997 - 2009 by EC Software, all rights reserved

216 Help & Manual 5 - User Help

How to create a topic hyperlink manually

1. Select text in your document if you want to use it as the link. You can also skip this
step and enter the caption in the hyperlink dialog.
2. Open the Insert Hyperlink dialog box. There are two different ways to do this:
· Press Ctrl+L
· Select the Link tool in Write > Insert

3. Edit the Caption: if necessary and select the link Style:

4. Select the ID of the topic you want to link to from the Topic ID: list.
If the topic contains anchors 226 you can also select an anchor from the drop-down list
next to the Target: field. The link will then jump directly to the position of the anchor in
the topic instead of the top of the topic.
See The Hyperlink dialog 617 for details of the other settings in the dialog. See Linking to
other projects and help files 229 for details on creating external links.
Links to popup topics:
You do not need to do anything special to create a popup link. Links to popup topics 125 in
your project automatically open the target topics as popups.

How to create multiple topic links with Copy & Paste

This method works with both single and multiple links. If you copy multiple items in the
TOC and paste them in the editor the result will be a list of links to the selected topics.
1. Select one or more items in the TOC that you want to link to. Use Ctrl+Click and
Shift+Click to select multiple items.
2. Select Copy in the Clipboard tools in the Ribbon or press Ctrl+C.
3. Click in the editor where you want to insert the links.
4. Select Paste in the Clipboard tools the Ribbon or press Ctrl+V.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 217

This will insert a list of links to all the items you copied from the TOC.

Opening topics in external windows in CHM and HLP

In HTML Help (.chm) and the obsolete Winhelp (.hlp) format you can open topics in
external windows by specifying a secondary help window type in the link definition. Just
select the window type you want to link to in the Window: field in the Insert Hyperlink
dialog.
See Using help windows 121 for more details.

Linking to anchors in topics

If the target topic contains anchors 226 you can link to an anchor to take the user directly to
a point inside the target topic.
· Double-click on the link in the editor to display hyperlink dialog 617 and select the anchor
from the drop-down list next to the Target: field.

The procedure is the same when you are creating a new link. Just select the anchor you
want to link to from the drop-down list.
Anchors in embedded topics:
If you link to a topic containing an embedded topic any anchors in the embedded topic
will not be displayed in the drop-down anchor list. To link to an anchor in an embedded
topic make a note of the anchor ID and type it in the drop-down list box next to the
Target: field manually when you edit the hyperlink.

Topic link compatibility in publishing formats

Classic Fully functional
Winhelp:

HTML Help: Fully functional

© 1997 - 2009 by EC Software, all rights reserved

 218 Help & Manual 5 - User Help

Visual Studio Fully functional.

Help:

Webhelp: Fully functional

Adobe PDF: Functional if activated in

Configuration > Publishing
Options > Adobe PDF > PDF
Layout 690 .

Winows Exe Fully functional

and ePub
eBooks:

MS Word RTF: Fully functional (links in RTF are

activated with Ctrl+Click)

4.8.3 Inserting Internet links

This function inserts Internet URLs and email links in your help. Internet links are supported
in all published help formats. The easiest way to create an Internet link is to type the URL in
the editor Help & Manual will automatically recognize the URL and turn it into an active
hyperlink.

Key Information
When inserting Internet links always
include the http:// protocol prefix. Links
without this prefix will not always work in all
formats.

Creating Internet links automatically

· Type a web URL or an email address in your text. Help & Manual will automatically
recognize the URL and turn it into an active link. (This function can be deactivated.
See Program Options - Editor 647 for details.)
· Double-click on the link to edit it.
· If you edit the link caption you must replace the <%LINK_CAPTION%> variable with the
URL that you want to link to, otherwise the link will point to the text you enter in the
caption field, which will not work.
If you don't want the address to be a link just right-click on the link and select Convert to
plain text in the context menu.
You can turn automatic URL recognition off in View > Program Options > Editor.

How to insert an Internet link manually

1. Select text in your document if you want to use it as the link. You can also skip this

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 219

step and enter the caption in the hyperlink dialog.

2. Open the Insert Hyperlink dialog box. There are two ways to do this:
· Press Ctrl+L
· Select the Link tool in Write > Insert
3. Select the Internet Link tab:

4. Select the Email or Internet address option and enter the web page URL or the email
address. You must include the http:// prefix for URLs, otherwise they won't work.
See The Insert Hyperlink dialog 619 for full details on the settings in the dialog.

Internet link compatibility in output formats

Classic Fully functional
Winhelp:

HTML Help: Fully functional

Visual Studio Fully functional

Help:

Webhelp: Fully functional

Adobe PDF: Functional if activated in

Configuration > Publishing
Options > Adobe PDF > PDF
Layout 690

Windows Exe Fully functional

eBooks:

ePub eBooks: Supported in the format but

remember that hardware readers
may not have Internet access

© 1997 - 2009 by EC Software, all rights reserved

 220 Help & Manual 5 - User Help

MS Word RTF: Fully functional

4.8.4 Inserting file links

A file link is a link to an executable file (e.g. notepad.exe) or to a data file associated with an
application (e.g. DOC word processing files or PDF files). Clicking on the link in the help is
just like double-clicking on an executable or DOC or PDF file on your desktop or in Windows
Explorer. It either starts the executable file or opens the DOC, PDF or other file with the
associated application.
File links are not supported in all output formats! See the compatibility list below for details.

How to insert file links

If you plan to publish to Microsoft HTML Help the files you link to must be stored in the
same folder as the CHM help file. The Microsoft HTML Help viewer has a bug that makes
it unable to access files outside the help file folder.
1. Select text in your document if you want to use it as the link. You can also skip this
step and enter the caption in the hyperlink dialog.
2. Open the Insert Hyperlink dialog box. There are two ways to do this:
· Press Ctrl+L
· Select the Link tool in Write > Insert
3. Select the File Link tab:

4. Enter the filename with extension in the File Name: field.

5. Enter any execution parameters associated with the file in the Execution Parameters:
field, for example the file to be opened by the executable file or any necessary
parameters for a data file.
6. Click on Test to test the link (the file must be present in your project directory for this
to work).
See The Hyperlink dialog 617 for full details on the settings in the dialog.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 221

Linking to page numbers and named destinations in PDF documents

Links between PDF files can open the PDF at a specific page number or named
destinations inside the target PDF. However, linking to page numbers and named
destinations only works in links between one PDF file and another. The same links in
other formats will just open the PDF at the first page. This is a restriction of the PDF
viewer, not of Help & Manual.
Linking to a specific page number:
File links from one PDF file to another PDF file can include a page number. The link will
then open the PDF file and jump to the specified page. Note that the Adobe PDF format
counts pages starting with "0" internally, so you must always enter one number higher
than the page you actually want to jump to:
1. Follow the instructions for inserting a file link (see above) and enter the name of the
PDF file you want to link to.
2. Add a # character and the page number to the end of the file name, like this:
myfile.pdf#123 (jumps to page 122)
myfile.pdf#0 (jumps to page 1)
myfile.pdf#11 (jumps to page 10)
That's all there is to it. Just remember that the number you enter must always be one
higher than the page you want to jump to, because PDFs start counting at 0 internally.
Internal section numbers are ignored – you can only jump to the absolute page numbers
of the PDF document, which always start with 0 and continue sequentially through the
entire document.
Linking to a named destination in PDF documents:
Some programs like Adobe FrameMaker support the creation of jump targets in PDF
documents called "named destinations". You cannot enter named destinations in PDFs
created with Help & Manual but you can use file links to link from one PDF file to a named
destination in a PDF file created by a program like FrameMaker.
1. Follow the instructions for inserting a file link (see above) and enter the name of the
PDF file you want to link to.
2. Add a # character and the named destination to the end of the file name, like this:
myfile.pdf#intro_section
myfile.pdf#details
myfile.pdf#advanced_users

Embedding linked files in PDF documents

You can automatically embed files referenced with file links into the PDF file when you
export your project to PDF. This makes it possible to distribute additional files with your
PDF document without having to use multiple files.
When the user clicks on the link the file will be displayed with the application with which it
is associated in Windows. This works for most file types, including other PDF files,

© 1997 - 2009 by EC Software, all rights reserved

222 Help & Manual 5 - User Help

documents and images of all kinds and even executable EXE files.
1. In the Project Explorer go to Configuration > Publishing Options > Adobe PDF
> PDF Layout and activate the option File links - embed linked files with the following
extensions:.
2. Make sure that the files you want to link to are stored in one of the folders referenced
in your Image Folders 656 list in Project Properties. If you have many folder references
place the files in one of the first few folders in the list.
3. Create your file links using the normal procedure.
When you compile your project the files referenced with file links will be physically
embedded in the PDF file. You no longer need to distribute these files separately as they
are now part of the PDF. This will increase the size of the PDF accordingly, of course.

File link compatibility in output formats

Winhelp: Supported, both relative paths and execution parameters will generally
work (exported as the ExecFile() macro).

HTML Help: Supported with execution parameters but do not use paths. All external
files must be in the same directory as the HTML Help CHM file.
Also, note that links to some types of external files in HTML Help are
now restricted in Windows. This is a security feature implemented by
Microsoft so you should test all links on properly-configured XP
systems before distributing.
Even more severe restrictions apply to HTML Help files accessed
across network drives. Here file links will not work at all and HTML Help
itself is also severely restricted. See the EC Software website for
more details. It is possible to enable the display of CHM files on
networks but file links will not work in CHM files on network drives.

Webhelp: Exported, but behavior depends entirely on the user's browser a file
link in Webhelp is an URL to a file, with all that entails. Relative and
absolute paths are supported; relative paths must be relative to the
location of the help when it is accessed by the user. No execution
parameters (for example, "wordpad.exe" on its own is OK but "
wordpad.exe myfile.doc" will not work).

Windows Exe Supported, do not use paths, files must be in the same directory as the
eBooks: eBook. Simple file links only, no execution parameters.

ePub eBooks: File links are not supported.

Visual Studio Not supported. External file links are explicitly forbidden in Visual Studio
Help: Help / MS Help 2.0.

Adobe PDF: Links to PDFs can include page number references (see above). Links
from PDFs can be simple file links only, no execution parameters. Links

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 223

must be activated in Configuration > Publishing Options > Adobe

PDF > PDF Layout 690 .

Word RTF: Supported but not recommended – users are very likely to move Word
RTF documents around and the links will then be dead. No execution
parameters.

4.8.5 Inserting script and macro links

This function inserts a piece of JavaScript code or a Winhelp macro that is executed when
the user clicks on the link in your help file. Note that scripts and macros are not supported in
all output formats – see the compatibility list below for details.
See Scripts, HTML and Macros 758 in the Reference section for some more background
information on scripts and macros and how they are implemented and handled.

How to insert a script or macro link

1. Select text in your document if you want to use it as the link. You don't have to do this
you can enter a completely new caption in the Insert Hyperlink dialog box if you
want.
2. Open the Insert Hyperlink dialog box. There are two ways to do this:
· Press Ctrl+L
· Select the Link tool in Write > Insert
3. Select the Script Link tab:

4. Select HTML JavaScript or Winhelp Macro and enter your script or macro in the
editing field.
See The Hyperlink dialog 617 for full details on the settings in the dialog.

Script implementation
Help & Manual creates script links by inserting the code you type between <a href=" and

© 1997 - 2009 by EC Software, all rights reserved

224 Help & Manual 5 - User Help

" >. For example, if you type:

javascript:alert('Hello World!');
The resulting link created in your output will be:
<a href="javascript:alert('Hello World!');">Link text</a>
This is just a simple example of course, you can place as much code in the script as you
want. If you are familiar with JavaScript and HTML you can use this knowledge to create
quite complex scripts! You just have to remember that everything you write is inserted
between <a href=" and ">. See Scripts, HTML and Macros 758 in the Reference section for
more details.

Winhelp macro implementation and translation

Macros can be typed and used just as you would use them manually in Winhelp. Note
that Winhelp macros only work in Winhelp, except for the four macros that are translated
for HTML Help (see below). If you are also generating other formats you need to create
alternatives for the other formats using conditional output 399 . See the help included with
Microsoft Help Workshop (the Winhelp compiler package) for documentation of the
macro functions available in Winhelp.
Macros translated in HTML Help:
The following four standard Winhelp macros are automatically translated to their HTML
equivalents when you compile to HTML Help. This can be convenient as the syntax of
these Winhelp macros is simpler and easier to enter:
ALink() KLink()
TCard() Close()

· Note that only keywords are supported as arguments in the ALink and KLink macros
when they are used in HTML Help. All other arguments are ignored.
· You do not need the ExecFile() Winhelp macro. Use file links 220 instead they produce
the same result much more efficiently.
· See Scripts, HTML and Macros 758 in the Reference section for full details on how
scripts and macros are implemented and handled.

Macro/script link compatibility in output formats

Winhelp: All Winhelp macros, no scripts. Paths will generally work.

HTML Help: JavaScript is broadly supported in CHMs. See the MS HTML Help
Workshop documentation for details. Four standard Winhelp macros (
see above 223 ) are translated to their HTML Help equivalents. Do not
use paths.

Visual Studio Same as for HTML Help.

Help:

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 225

Webhelp: Scripts are supported but support depends to a great extent on the
user's browser, so use the same caution as when using scripting in any
HTML pages.

Windows Exe Script and macro links are not supported.

and ePub
eBooks:

Adobe PDF: Script and macro links are not supported.

Word RTF: Script and macro links are not supported.

See also:
Scripts, HTML and Macros 758
Inserting plain HTML code 231
Using HTML templates 430
Webhelp 674 (Project Configuration)
4.8.6 Editing and formatting links
You can edit link captions (the link text) directly just by clicking inside the links once and
typing. You also have great freedom to format the appearance of your links the link text
can be formatted like normal text provided that you use the same formatting for all the text in
the link.

Productivity Tips
Hold down Ctrl and click on a link to
navigate to the link target in your project.
Double-click on a link to display its editing
dialog.

How to edit link captions

You can edit link captions (the text of the link displayed in the editor) in exactly the same
way you would edit normal text. Just click once inside the link or move the cursor into the
link with the cursor keys and start typing.
However Sometimes it is easier to double-click on the link and edit its caption in the
Hyperlink dialog 617 .

Link captions at the beginning of a paragraph

If a link caption is at the beginning of a paragraph you can't insert any text before it; all
the text you type to the left of the link becomes part of the link. Here is how to solve this
problem:
1. Click to the left of the link and press Enter to create a new paragraph.
2. Move up to the empty new paragraph, press the space bar (this switches off the link
highlighting) then type some text.

© 1997 - 2009 by EC Software, all rights reserved

 226 Help & Manual 5 - User Help

3. Click to the right of the new text and press Delete to bring the link into the same
paragraph.

How to format the link caption

· Select the caption and format it in the same way you would format any other text.
Always select the entire caption applying different formatting to different parts of the
caption will split the link in two.
· Note that underlining and color cannot be changed for normal links because they are
always blue and underlined.
· For full control over link caption formatting choose the Text style in the Link Properties
617 dialog. You can then format the link manually or by applying a text style. (Double-

click on a link in the editor to display this dialog.)

· See the DHTML Examples tutorial project in My Documents\My HelpAndManual
Projects\Examples for instructions on how to style your links with CSS in HTML-based
output formats.

Turning links back into text, deleting links, [****] links

· Turn a link back into text right-click on the link and select Convert to plain text in the
context menu.
· To delete a link select the entire link and press Delete. It is best to select the spaces
before and after the link, otherwise you may only delete the link caption and create a
ghost link (a link without a caption).
· If you create a ghost link it will be displayed as [****] in the editor after saving or
refreshing the topic. To get rid of it just right-click on it and select Convert to plain text
in the context menu.

4.8.7 Anchors - jump targets

Normally, topic links execute jumps to the top of the target topic. However, often you will
also want to create jumps to some point inside a topic. This is done with
"anchors" (sometimes also referred to as "bookmarks" in books on help), which are named
"targets" that you insert at any position within a topic so that you can jump to them with a
link.

Key Information
Anchors in Help & Manual do not have
captions. They are identified by an anchor
icon in the editor.

How to insert an anchor

1. Click in the text at the point where you want to insert the anchor (i.e. the position you

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 227

want to be able to jump to with your links). Don't select any text, if you do it will be
overwritten by the anchor!
2. Open the Insert Anchor 627 dialog box. There are two ways to do this:
· Press Ctrl+H
OR
· Select the anchor tool in Write > Insert
Type in a descriptive ID for the anchor in the Anchor ID: field. This will be displayed in
the link dialog when you are creating links so it should be easy to identify. You cannot
use spaces or special characters.
3. If you want to use a help context number 205 you can type it in manually (this allows you
to make calls to anchors from applications). You can also set Help & Manual to assign
help context numbers to anchors automatically in Configuration > Common
Properties > Miscellaneous 665 .
4. Type in any keywords 273 you want to associate with the anchor (see below 226 for
details).
Like topic IDs, anchor IDs can be up to 255 characters long. However, since you need to
view anchor IDs in dialog boxes it is advisable to keep them relatively short.

How to create a hyperlink to an anchor

1. First proceed exactly as you would for creating a normal topic link.
2. Open the Edit Hyperlink 617 dialog box. Just double-click on the link to open the dialog if
it is not already open.
3. Select the anchor ID from the drop-down list to the right of the Target: field and click
on OK.

To quickly create a link to an anchor in the current or another topic just create the link
with Drag & Drop and then double-click on the link to select the target anchor in the
dialog.

© 1997 - 2009 by EC Software, all rights reserved

228 Help & Manual 5 - User Help

Linking to anchors in linked snippets

When you create a hyperlink to a topic containing a linked snippet 149 any anchors stored
in the snippet will not be displayed the drop-down anchor list next to the Target: field.
(This does not apply for snippets inserted in Copy mode, of course, which become part of
the current topic like normal pasted text.)
1. To link to an anchor in a linked snipped first view the source topic or snippet file and
make a note of the anchor IDs you want to link to.
2. Then create the link and type the ID of the anchor you want to link to manually in the
drop-down list box next to the Target: field.

Linking to anchors in Webhelp pages

You can also create URL links from your application or from other web pages to anchors
in Webhelp pages so that users are taken directly to a specific point in a topic when they
use your links. The syntax is exactly the same as the standard HTML syntax for URLs
containing anchor references:
index.html?topicname.htm#anchorname
The topic name is simply the Topic ID of the topic, plus the extension .htm. The entire
URL must be written in lower case because Help & Manual automatically converts all file
names to lower case in HTML output for compatibility with Unix and Linux servers.
See Context calls to Webhelp 373 for some more details on this.

Using keywords in anchors

You can also associate index keywords with anchors. Selecting these keywords in the
help index will then jump to the anchor instead of the top of the topic. See Keywords and
Indexes 273 more information on using keywords and Using keywords with anchors 280 for
more information on using keywords in combination with anchors.
· Type the keywords into the Keywords: field of the Insert Anchor 627 dialog. You can
enter both main keywords and sub-keywords. Use the TAB key to enter sub-keywords
(an indented keyword automatically becomes the sub-keyword of the keyword above
it).
· Typing a space or tab in front of a keyword automatically makes it a sub-keyword of the
entry directly above it. Only one level of sub-keywords is allowed.
It is possible to have the same keywords in both the topic's keyword list and in one or
more anchors in the same topic. However, if you want your index entries to enable jumps
to the anchor without confusing the user it is better to avoid this.

Editing anchor IDs, "dead" anchor links

You can edit an anchor and its ID by double-clicking on it. However, it is better not to

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 229

change anchor IDs after creating them. Unlike topic IDs, links to anchor IDs are not
updated if you edit them. This means that editing an anchor ID can create dead links and
links to "dead" anchors are not highlighted. The link to the page will still work, of course,
but the jump to the anchor will not.
How to locate and correct dead anchor links
Dead anchor links are not listed in your project reports 534 . However, you can locate them
by publishing to any HTML-based output format (HTML Help, Webhelp, eBooks, Visual
Studio Help). The compiler report will list all topics containing links to undefined anchors
with links to the topics so that you can edit them and correct the anchor reference.
Tip: If you have the Professional edition of Help & Manual the easiest way to locate an
anchor is to search for the anchor ID in the XML Source Code tab. You can then either
edit it directly there or switch back to the editor tab and edit it there.

See also:
Inserting topic links 215
Using embedded topics 149
4.8.8 Linking to other projects and help files
By default the target ID list in the Hyperlink dialog displays the IDs of the current project, but
you can also link to topics in other projects and in other help files. When you distribute your
help these files must be present in the same directory as the help file containing the link.

How to link to an external project or help file

1. Follow the basic instructions for inserting a normal topic link 215 .
2. In the Hyperlink dialog 617 click on the browse button in the Help File: field and
choose the project or help file containing the topic you want to link to.

+
3. If you choose a project (.hmxz or .hmxp) or HTML Help (.chm) file the topic IDs of the
target project or file will be displayed in the Topic ID list. Choose the topic (and anchor
226 if applicable) you want to link to and click on OK.

© 1997 - 2009 by EC Software, all rights reserved

230 Help & Manual 5 - User Help

Restrictions in Winhelp:
Links to Winhelp .hlp files only work from other Winhelp files. Also, you can only open
the external Winhelp file at its default topic with this method, you cannot access its topics
directly. To link to individual topics in an external Winhelp file you must link to the Help &
Manual project. Here too, only links between Winhelp files are possible, you cannot link
from other formats.
Links between modular projects:
When you are linking between modular projects you may need to think about what will
happen in situations when the project you are linking to is not present when the user
clicks on the link. See Modular Projects 764 for more information on this and solutions.

Linking to topics in other Webhelp (HTML) projects

The situation is a little different when you want to create links between different Webhelp
730 projects, which are by definition stored in different directories. These are effectively

just groups of HTML pages, like any other set of HTML pages on a website. Topic links
will not work here because this is really a website, not a help project – you have to use
Internet links instead.
1. Follow the instructions for inserting an Internet link 218 and choose the Links to an
Internet address option.
2. Enter the URL of the page in the other project in the Address: field. You can enter
either the absolute address or the relative address (the relative address will depend on
the relative positions of the directories on your website, of course):
Absolute address:
http://www.yourdomain.com/subdirectory/index.html?topicname.
htm#anchorname
Relative address:
../subdirectory/index.html?topicname.htm#anchorname
Here index.html is the index file of your project (this is the default, you can change it
in the Publish 590 dialog when you compile), topicname.htm is the name of the topic (
topic ID 205 plus .htm) and anchorname (optional) is an anchor 226 in the topic you want
to link to.
Choosing the window to open the link in:
If you want to display the TOC of the target project in the current browser window select
the Top Frame option in the Target window: field. If you don't do this the topic will
overwrite the TOC in a single browser window. Selecting New Window opens the topic in
a new browser window together with its TOC.
Direct links to topic files:
It is possible to link directly to the topic filename, for example with:
../subdirectory/topicname.htm
The entire help with the TOC wills still be displayed automatically when you do this.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 231

However, the Back and Next history buttons in the user's browser will not work properly
so it is better to use the full syntax including the index.html index file.

See also:
Working with Modular Help Systems 446
4.8.9 Links and secondary windows
Help windows define the features of the Microsoft help viewers for HTML Help and Winhelp
and are also used to display individual topics in external windows. In the obsolete Winhelp
format they also define the background colors of the topic body and header. Help windows
are a Microsoft technology that is only relevant for Winhelp and HTML Help output.
When you define a hyperlink to a topic you can include a setting that specifies a secondary
help window for opening the topic. This allows you to create links that open topics that
would normally open in the TOC in external windows. In the obsolete Winhelp format you
can also use this feature to apply different background colors to the topic you are linking to.
See Using help windows 121 for more details.

Opening the target topic in an external window

Preparation:
1. Define at least one secondary help window 121 type.
2. In the window's HTML Help Options 661 tab select the Links to secondary help windows
open a new help window option. (This allows external windows in HTML Help. In
Winhelp secondary windows are always external.)
3. You will probably also want to use the other options in the HTML Help Options and
Winhelp Options tabs to switch off the external windows' control buttons and
navigation panel as they can confuse the user in external windows.
Opening target topics in an external window:
Create a hyperlink to a topic, open the Hyperlink dialog 617 (double-click on the link) and
select the secondary window type in the Window: field, then click on OK.

See also:
Using help windows 121
Help Windows 660 (Project Configuration)
Help windows and external windows 429
Help Windows 807 (Reference)
4.8.10 Inserting HTML code objects
The Insert HTML Code Object tool in Write > Insert Object allows you to add special
features or formatting to your topic pages with HTML code. For example, you can write
dynamic HTML code with JavaScript to add features not available directly in Help & Manual.
This function "injects" HTML code into your topic at the point where you insert it. The code
is entirely your responsibility and is not checked or parsed by Help & Manual in any way, so

© 1997 - 2009 by EC Software, all rights reserved

232 Help & Manual 5 - User Help

you need to be familiar with HTML coding.

Productivity Tip
You can resize the HTML code objects in
your topics to make their contents visible.
You can also the code object editor for
editing larger blocks of code.

Where HTML code objects are supported

HTML code objects are supported in all HTML-based output formats. However, Windows
Exe eBooks only support plain HTML code and basic CSS, any scripts will be ignored
because the embedded eBook viewer does not support JavaScript. The ePub eBooks
standard includes scripting but most ePub readers do not so it should be avoided as it will
hardly ever work,
If you want to use this feature in projects that will also be compiled to formats where it is
not supported you need to use Help & Manual's conditional output 399 features to create
alternative text for those versions.
Note that the Insert HTML Code Object tool inserts the code directly in the body of your
topic. If you want to insert scripts in the <head> section of your topic page you must do so
in the HTML template, either directly or by reference. See below for more information on
this.

How to insert plain HTML code in a topic

1. Click in the editor at the point where you want to insert the plain HTML code and select
the HTML Code Object tool in Write > Insert Object.

2. Type your code in the editing window displayed. You can resize the window for easier
editing by dragging on the lower right corner.
The Load from File and Save to File functions allow you to save blocks of code in
external text files for reuse.

Referencing external files in plain HTML code

If you reference external files in your plain HTML code you are entirely responsible for
making sure that the files are included in your output. Help & Manual does not parse or

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 233

check the code and it will not do this for you. There are two ways to make sure that
referenced files are included in your project:
Method 1: Adding the files to the Baggage Files
This is the simplest solution. The Baggage Files function provides a quick and easy way
to integrate external files in your project and make sure that they are available to the
compiler and included in your output.
· See Using Baggage Files 485 for details on using this function.
· See Graphics references 442 for more details on referencing graphics files. Since
graphics files are often large it is not always a good idea to add them to the Baggage.
Method 2: Integrating the files in your output manually
This is not really necessary since it is much easier to add any referenced files to your
Baggage. The following instructions are just included for the sake of completeness.
· In Webhelp you must manually copy the files to your output directory if you have not
added them to the Baggage Files (see above).
· In HTML Help you need to tell the HTML Help compiler to add the files to the .chm file.
Proceed as follows:
1. Copy the external file(s) to your project folder (the folder containing your .hmxz or .
hmxp project file).
2. In the Project Explorer open Configuration > Publishing Options > HTML
Help > Extended HHP Settings.
3. In the editing box add the following entries, replacing the dummy filenames in the
examples with your own files (one file per line):
[FILES]
..\donald.js
..\mickey.asp
Don't add a second [FILES] header if one already exists. Enter each external
filename on its own line below the [FILES] header and precede it with the ..\ relative
path reference.
This example assumes the files are stored in your project directory. (This is
necessary because the project is compiled from a temporary subdirectory in the
project directory, so files in the project directory are one level up.) If your files are
located anywhere else you need to adjust the ..\ relative path reference accordingly.

Referencing code in the <head> section

If you reference JavaScript or other script code in your HTML code objects you may want
to insert scripts containing the functions to be executed in the <head> section of your
HTML topic page that you then reference and run from the code objects inserted in the
body of your topics. You can't do this directly in the topic page because this only inserts
the code between the <body> and </body> tags in the final HTML page.
The code for the sections of your HTML pages above and below the <body> and </body>
tags is provided by your HTML topic page templates, which you can access and edit in

© 1997 - 2009 by EC Software, all rights reserved

 234 Help & Manual 5 - User Help

the Project Explorer. You can add script code and references to external script files to
the <head> section of your pages by editing these templates. By default you have one
HTML topic page template called Default, which is used for all topics. However, you can
create as many different templates as you like and assign them to individual topics in the
tab behind the editor.
In addition to this you can use HTML variables that you can redefine in individual topics to
add different script and code to the <head> section of every single topic. To do this you
insert the variables in your template and then redefine their content for individual topics in
the tab behind the editor.
See Using HTML Templates 430 for general information on how to access and edit your
HTML topic page templates. See The power of editable variables 395 for details on how to
use HTML variables to insert individual code in your templates on a per-topic basis.

See also:
Inserting script and macro links 223
Using HTML templates 430
Scripts, HTML and Macros 758
Webhelp 674 (Project Configuration)
Using Baggage Files 485
Graphics References 442
Extended .HHP Settings 670
4.8.11 Application links to Webhelp
You can create context-sensitive calls to Webhelp 730 (web HTML) from your application or
web pages with normal URLs using the syntax explained below. These calls can be made
locally, across networks or across the Internet.
Field-level popups are not supported in Webhelp, they can only be implemented with HTML
Help (CHM) or Winhelp (HLP). The JavaScript popups 129 supported in Webhelp can only be
used within your help, you cannot make calls to them from your application or web pages.

How to make calls to Webhelp topics

Calls to Webhelp must be normal URLs, made in the same way as any other URL link
that opens a browser with a specific web location or local HTML file, using exactly the
same syntax:
Calling syntax:
index.html?topicname.htm#anchorname

Examples:
This example uses the standard file names and extensions and accesses an anchor in
the referenced topic:
index.html?introduction.htm#gettingstarted
The following example shows a call to a project that was compiled with both a non-
standard index file name and a non-standard extension for the topic files (see below).
There is no reference to an anchor in this example.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 235

help.html?new_features.html

Elements of the calls:

index.html This is the name of the index file of your Webhelp (this is the default, it
can be changed in the Publish 590 dialog when you compile). If you use
this on its own it will simply display the help system with the standard
home topic.

?topicname. This is the name of the topic you want to display. This is created by
htm combining the topic ID 205 with the extension .htm..
This is the default topic extension, you can change it in Project
Configuration > Publishing Options > Webhelp > HTML
Export Options 684 . (These settings are shared with the other HTML-
based output formats and can also be accessed in the HTML Help and
Visual Studio Help sections.)

#anchorname Optional. This is the name of an anchor 226 in the topic that you want to
jump to.

Calling Webhelp topics without the TOC

Normally, a link to a topic file will automatically display the entire help with the TOC even
if you don't include the index.html part of the URL. This is achieved with a redirect script
in every topic page. However, It is also possible to call just the topic without the TOC if
you want. You do this by adding a simple switch to your URL.
Calling syntax for topic only:
topicname.htm?toc=0#anchorname (with an anchor)
topicname.htm?toc=0 (without an anchor)

Avoid direct calls to the topic file

Theoretically you don't actually need to include the index.html file in the URL. If you
make a direct call with the format topicname.htm or topicname.htm#anchorname this
will automatically display the entire help system with the Table of Contents.
This is not a good idea, however: Under some circumstances it can confuse the browser
history, making it impossible for users to navigate with the Back and Next buttons.
It is thus always advisable to use the full call including the index file, using the standard
syntax:
index.html?introduction.htm#gettingstarted

See also:
Creating popup topics 125
Context-Sensitive Help & Popups 788
Topic files without TOC entries 210

© 1997 - 2009 by EC Software, all rights reserved

 236 Help & Manual 5 - User Help

4.8.12 A-Links and A-Keywords

A-keywords, also known as "A-link keywords", are quite similar to normal keywords but they
not displayed in the index, they are always "hidden". What use is a keyword that isn't
displayed in the index? There are two major uses for A-keywords: To create "See also" lists
of related topics and to create links between help files in modular help systems.
See About A-Keywords 806 for background information.

Key Information
Note that A-keywords are a Microsoft help
technology that is only supported in the
Microsoft Winhelp (HLP) and HTML Help
(CHM) formats. A-keywords are irrelevant
in all other output formats, including
Webhelp.

How to make an automated See Also list with A-keywords

This method creates links that display a list of related topics. It works in both HTML Help
and the obsolete Winhelp format. It will not work an any other output format.
Step 1: Enter the A-keywords
1. Select a topic and display its tab.
2. Enter one or more keywords in the A-Keywords: section, one keyword per line. Note
that sub-keywords are not supported with A-keywords!
3. Repeat for all topics you want to "associate" with one another, adding the same A-
keyword to each topic.
Step 2: Create the link
The link that displays the list of See also: topics is created using the Winhelp ALink
macro. The syntax of this macro is much simpler than its HTML Help equivalent and so
Help & Manual automatically translates it when you output to HTML Help.
1. Select Insert > Link in Write > Insert to create a hyperlink.
2. Select the Script/Macro option in the Insert Hyperlink dialog, then select Winhelp
macro as the type of hyperlink.
3. Enter Alink() in the Script: field and type the keywords you want to link to between the
parentheses. If you enter more than one keyword separate them with semicolon (;)
characters, like this:

This example will create a link that displays a list of all topics that contain the A-keywords
"troubleshooting" or "solutions".

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 237

Note that when you are working in HTML Help you can only enter keywords as the
argument for the Winhelp macro. You cannot enter the other parameters for the Winhelp
A-Link macro because they are not translated into HTML Help code!

How to link between help modules with A-keywords

Use this method to create links between the help files of modular help systems if there is
a possibility that the help files containing the target topics may not be present when the
help is viewed. This can happen when you use runtime merging and choose not to
include one or more of the help files in your distribution. It can also happen if you are
using conditional output to exclude modules from publish-time merged HTML Help and
Winhelp projects.
This technique works both in HTML Help and the obsolete Winhelp forma but not in any
other formats. Please study Working with Modular Help Systems 446 before trying to use
this method!
Step 1: Prepare the alternative topic in the master project
The alternative topic should be in the master project because this is the only help file that
is always present in a runtime-merged modular help system.
1. Open the master help project and choose or create the alternative topic that you want
the user to be able to view when the other help file module containing the target topic
is not available.
2. Select this alternative topic, select the tab and enter a unique A-keyword in the A-
Keywords: field. The A-Keyword must be unique it should not be used anywhere
else in your projects! If it is, all the topics where it is used will be displayed when the A-
Link hyperlink is clicked.
Step 2: Prepare the target topic in the child project
1. Open the child project and select the topic you want to link to.
2. Select the tab and enter the same unique A-keyword as above in the A-Keywords:
field.
Step 3: Create the link
1. Open the project module in which you want to create the link. This can be a master
module or another child module.
2. Select Insert > Link in Write > Insert to create a hyperlink.
3. Select the Script/Macro option in the Insert Hyperlink dialog, then select Winhelp
macro as the type of hyperlink.
4. Enter Alink() in the Script: field and type the keyword between the parentheses. If your
keyword is "about widgets" the dialog would look like this:

© 1997 - 2009 by EC Software, all rights reserved

 238 Help & Manual 5 - User Help

If the target help file is not present when the user clicks on the link the alternative topic
will be displayed automatically. If the target topic is present a dialog will be displayed in
which the user can select either the target topic or the alternative topic.
This is just a very simple example to show you how this solution works in principle. In
practice you can also make more complex solutions, using more alternative topics and
more keywords. If you use multiple keywords remember to separate them with
semicolons, like this:
Alink(about widgets;troubleshooting;widget solutions)
Note that when you are working in HTML Help you can only enter keywords as the
argument for the Winhelp macro. You cannot enter the other parameters for the Winhelp
A-Link macro because they are not translated into HTML Help code!

See also:
About A-Keywords 806 (Reference)
Keywords and Indexes 273

4.9 Using Graphics

Inserting graphics in your topics with Help & Manual couldn't be easier – just select the
Insert Image tool in Write > Insert and choose your graphic file. Graphics can also
include captions that are stored together with the graphic.
You can capture and insert screenshots with the integrated screen capture utility and add
hotspots to your images with hyperlinks to topics, files, scripts and macros.

See also:
About Graphics in Help & Manual 753
4.9.1 Supported graphics formats
You can use a large number of different graphics formats directly in Help & Manual. If the
format of a graphic you use in your project is not supported in your publishing format Help &
Manual converts the file automatically when you publish your project. For example, the
obsolete Winhelp format only supports BMP, so if you use other types of graphics files they
will be converted to BMP when you publish your project.

Key Information
For most purposes BMP is the best format.
Help & Manual automatically converts and
compresses images when you publish and
BMP is the best source format for this.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 239

Directly supported graphics formats

All the following graphics formats listed below be inserted in your projects directly with
the Insert Image 239 tool. Native HTML graphics formats (PNG, GIF, JPG) are published
unchanged when you compile to HTML-based output formats. Other formats are
converted to one of these formats on the basis of your HTML Export Options 671
conversion settings in your project configuration settings.
· Standard bitmaps (BMP)
· Compuserve Graphics Interchange Format (GIF)
· JPEG Graphics (JPG)
· Portable Network Graphics (PNG)
· Photoshop images (PSD)
· Paint Shop Pro images (PSP, single-layer only)
· TIFF images (TIF)
· Kodak PhotoCD images (PCD)
· Windows Metafiles (WMF, EMF)
· Impict graphics (IPP, the special format of Help & Manual's Impict graphics editor)
· Segmented Hyper Graphics (SHG, MRB the Winhelp hotspot graphics format, now
obsolete.)

Old SHG graphics containing hotspots

The obsolete.shg format for Winhelp graphics should no longer be used, support for it is
only included for backward compatibility. You no longer need to use SHG graphics to add
hotspots in your images because you can add hotspots 246 to all graphics formats directly
in the Help & Manual editor.
However, if you have old .shg files with hotspots you can use them in your projects
directly, provided the hotspots link to valid topic IDs in your project.

IPP graphics containing hotspots from HM3 projects

Hotspots in .ipp graphics created with Help & Manual 3 cannot be imported to new
projects on their own because they are linked to specific projects. The hotspots will only
be imported if the .ipp images are imported together with the .hm3 project for which they
were created.

4.9.2 Inserting graphics and screenshots

You can insert graphics in your projects from files stored on your hard disk or with cut &
paste. Drag & drop from the desktop or Windows Explorer is not supported.
Note that although cut & paste may be more convenient you may get slightly better image
quality when you insert graphics directly from files. This applies particularly to pasting from
MS Word, which generally resizes the image very slightly (just a couple of percent) when

© 1997 - 2009 by EC Software, all rights reserved

240 Help & Manual 5 - User Help

you copy it via the Windows clipboard.

Productivity Tip
When inserting a graphic in a paragraph
with text always type a space as the first
character after the graphic, this will prevent
the image caption style from being applied
to the text you type.

How to insert a graphic from a file

1. Click in the editor at the position where you want to insert the graphic.
2. Select Insert > Image in the Write tab. displays the Open Image 622 dialog:

· Alignment can make text wrap around the image (not displayed in editor, does not
work in PDF).
· Spacing adds empty space around the image (in pixels).
· Zoom resizes the image, Autosize returns it to the default size.
· Tooltip is a text displayed when the mouse pointer is over the image.
· Caption is displayed below the image (formatted with the Image Caption style) and
is included as the ALT attribute in HTML-based image formats.
You don't need to worry about setting the dimensions of your graphic as you would have
to do in an HTML editor. Help & Manual does this automatically.

How to insert a graphic with Cut & Paste

1. Copy the graphic to the Windows clipboard in the source program.
2. Click in the editor at the position where you want to insert the graphic and press
Ctrl+V or select Clipboard > Paste in the Write tab.
3. This opens the Windows Save dialog with clipxxxx.bmp as the default name for the
image.
4. Give the image a descriptive name and save it in your project's graphics folder
rather than the main project folder.
5. To edit the graphic insertion properties double-click on the graphic to reopen the Open
Image dialog 622 .

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 241

Pasting text and graphics from MS Word:

When you paste graphics and text together from MS Word the Save dialog for the
graphic is not displayed. Instead, the graphic is embedded in your topic file. This uses up
a huge amount of memory and computer resources and it is advisable to convert the
embedded graphic into an external file.
· Right-click on the embedded graphic and select the context menu option for converting
it to an external file.

How to format the image caption

· The formatting of the caption text is controlled by a standard style 176 called Image
Caption. You can change this for the entire project by editing the style 161 .
· You can also change the appearance of the caption text by applying font attributes
directly. To do this select the graphic in the editor, then select the font attribute you
want to apply (bold, underlined, font etc).
Note that you can only format the entire caption text. You cannot apply different font
attributes to individual parts of the text. For more details see Image caption and comment
styles 176 .

See also:
Graphics, Videos and OLE 753 (Reference)
4.9.3 Positioning graphics
By default a graphic inserted in Help & Manual is a handled as a single object in a
paragraph, essentially the same as a character. This means that if it is alone in its paragraph
it can be centered, left-justified and right-justified by adjusting the paragraph formatting
settings. In addition to this you can also make text wrap around it to the left or right with the
Alignment: settings in the Open Image 622 dialog.
For more complex control over the position of graphics on your page you need to place the
graphics in tables 253 , in the same way that you would in a HTML page.

How to align a graphic without wrapping text around it

You can center graphics on the page or place them on the left or right side of the page
with the settings for the paragraph containing the graphic.
1. Click in the paragraph containing the graphic. There shouldn't be any text in the
paragraph as the result would not look good in the output.
2. Format the paragraph to position the graphic. For example you can left-justify, center
or right-justify the paragraph or add space before and space after to separate the
graphic from the paragraphs above and below it. (You can also add space around the
graphic with the Spacing: setting in the Open Image dialog 622 .
Formatting options:
Use the Paragraph tools in the Write tab or select the paragraph dialog icon at the

© 1997 - 2009 by EC Software, all rights reserved

 242 Help & Manual 5 - User Help

bottom right corner of the Paragraph tools group to display the full Paragraph formatting
dialog.

How to wrap text to the left or right of the graphic

1. Double-click on the graphic to re-open the Open Image 622 dialog.

2. Select Left of text or Right of text in the Alignment: field.

3. Set the Spacing: value to increase the amount of free space around the image.
The wrapping is not displayed in the editor. You must publish your output to see the
effect. This feature is not supported in PDF because the PDF format does not have an
equivalent formatting function use tables to arrange text and images side by side if you
plan to publish to PDF.

See also:
About Graphics in Help & Manual 753
Working with Tables 253 Help & Manual 753
4.9.4 Editing, resizing and hi-res PDF printing
You can edit the properties of a graphic by double-clicking on it. You can also resize your
graphics directly in the editor by selecting it and dragging its corners with the mouse or by
double-clicking and entering a zoom factor. Although this function is primarily designed for
high-resolution printing with PDF files you can use it for all your output formats whenever
you need a quick resize. You may obtain slightly better quality if you resize in Impict 536 or
another graphics program, but this feature can be a great time-saver when you are in a
hurry.

Editing graphics properties and captions

· Just double-click on any graphic to display the Open Image 622 dialog where you can
edit the caption, alignment, spacing (empty space around the graphic) and hotspots 246
(clickable links in the graphic).
· You can adjust the size of graphics precisely with the Zoom % setting in the Open
Image dialog. This does not physically resize the image until you compile and in PDF
the full image resolution is used (see below).
· You can also edit the properties and hotspots by right-clicking on a graphic and

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 243

selecting from the Picture... options in the context menu.

Resizing graphics in the Help & Manual editor

Note that this resize function is really for PDF printing (see the instructions for hi-res
graphics and PDF below). If you have the time it is generally better to resize your images
physically in Impict or another graphics program.
· Quick resize: Just click once on the graphic to select it and resize it by dragging the
resize handles displayed at the edges. It doesn't matter which handle you drag
because the height and width of the graphic are always resized proportionally.
· Precise resizing: double-click on the graphic to display the Image dialog and enter a
zoom factor in percent.
· Undo resize: To return the graphic to its original size just double-click on it to display
the Open Image dialog and select the Autosize option.
This function does not change the graphic file. Nothing actually happens until you compile
your output. In all output formats except PDF (see below) the graphic is physically scaled
and resized when you compile.
Resizing may increase the size of your output file:
This quick resize option can only be performed on TrueColor (65m colors) graphics so
the files must be converted to TrueColor before being resized. If you resize screenshots
with 256 colors or less you may end up with bigger files than when you started.
See Formats, Compression and File Size 753 for important information on how file formats
affect (and don't affect) the file sizes of your help.

Using high-resolution graphics for PDF and printing

When you print PDF files or view them at above 100% graphics can look "blocky" and
"jaggy". You can solve this problem by using larger graphics and resizing them in the
Help & Manual editor. The full-sized original image is then embedded in the PDF and
resized dynamically when the PDF is used.
· To use a high-resolution graphic just insert a graphic that is large enough to print well
on a high-resolution printer and then resize it to the size you want to use in your
document as described above.
· This will increase the size of your PDF files because larger graphics are bigger. In other
output formats the graphics are physically resized when you compile.
· Physical resizing when you output to formats other than PDF is automatic. However, if
you want to create one PDF for printing and a compact version for on-screen viewing
you can do this by inserting two versions of the graphic: One small graphics file that
does not need to be resized and one large one that you resize. You can then use Help
& Manual's conditional text 410 feature to select which version you want to include when
you publish your project.

© 1997 - 2009 by EC Software, all rights reserved

 244 Help & Manual 5 - User Help

Resizing graphics physically with the Impict graphics editor

For the best possible resize quality you can also resize your graphics files physically with
Impict, the screenshot enhancement and graphics editor included with Help & Manual, or
with any other graphics editor.
· To edit a graphic in Impict just click on the graphic in the editor to select it and then
select Image Editor in Project > Tools.
· To resize the image in Impict right-click on it, select Edit Properties and then select
Quality Resize.
· After saving the new version in Impict (don't change the filename or location) just select
another topic briefly in Help & Manual and then return to the current topic to reload the
topic with the modified graphic.

See also:
About Graphics in Help & Manual 753
Conditions and Customized Output 399
4.9.5 Using the Impict graphics editor
Help & Manual comes with its own powerful graphics program called Impict for editing and
enhancing screenshots and other graphics. This editor has a wide range of powerful
features for making professional help graphics and screenshots.

How to open a graphic in Impict

· Click once on the graphic in the Help & Manual editor screen to select it, then select
Tools > Image Editor in the Project tab.
Impict comes with its own comprehensive help and documentation. Please refer to this
for full details on using the program.

Editable objects and texts in Impict images

The great advantage of Impict is that all effects and objects you add to your images are
non-destructive. You can always go back and edit your screenshots later if you need to
make changes you don't need to rebuild the entire screenshot.
Texts in Impict images can be exported to XML files for translation. See the Impict help
for details.
For all these features you must save working copies of your images in Impict's own IPP
format you can't save editable objects and texts in standard formats like BMP, GIF or
JPG.

4.9.6 Using the screen capture function

Help & Manual has an integrated screen capture function that includes most of the
functionality you need to make attractive screenshots quickly and efficiently. The function

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 245

will automatically select windows, controls and menus and you can also select freely-defined
rectangular regions of applications or the desktop and fixed size regions.
In addition to simple screenshots you can also make screenshots with a wide variety of
different shapes, add shadows and background colors and automatically resize your
screenshots with a choice of high-quality scaling filters.

Using the screen capture tool

· Select the Screen Capture tool in Project > Tools. The tool is pretty self-explanatory
but for full instructions see Screen Capture 532 in the Tools Included with Help &
Manual chapter.
For even more screenshot power try TNT, the combined screen capture and graphics
editor tool from EC Software:
TNT Screen Capture Program Page

Making screen captures with Impict

You may want make screen captures for editing, without inserting them in your topic
directly. To do this use the screen capture feature in Impict 536 , the specialized graphics
editor included with Help & Manual.
Impict's screenshot tool simply captures a plain screenshot without applying any
automatic effects. All the effects can be applied inside Impict. The advantage of this is
that Impict's effects and objects are non-destructive you can always go back and make
changes later if you save a working copy in Impict's own IPP format.
The texts stored in Impict IPP images can also be exported to XML files for translation.

See also:
Screen Capture 532
About Graphics in Help & Manual 753
The Impict Screenshot Editor 536
4.9.7 Using graphics as hyperlinks
In addition to standard text links you can also use graphics as hyperlinks 214 in your help
project, for all the different supported link types. You can use this feature to turn entire
illustrations into clickable links, or to use your own graphical buttons as links.
In addition to this you can also add "hotspots2 to your graphics, which are clickable regions
that can have all the properties that any other link in a Help & Manual can have. See
Graphics with hotspots, macros and scripts 246 for details.

How to use a graphic as a link

Note that you cannot turn an existing graphic in your text into a link, you have to edit a
link and select a graphic instead of a caption.
1. Create a new hyperlink or double-click on an existing link to edit it.

© 1997 - 2009 by EC Software, all rights reserved

 246 Help & Manual 5 - User Help

2. Select the Picture option in the Style: section of the Hyperlink dialog 617 . The title of the
entry field at the top changes to Picture:, where you can then specify the graphics file
you want to use.

3. Click on the browse button next to the entry field to select your graphic file.
4. Click on OK to close the dialog.

See also:
Inserting Hyperlinks 214
4.9.8 Graphics with hotspots, macros and scripts
Hotspots are active, clickable areas in graphics. Hotspot data is stored separately from the
graphics, which makes it possible to add hotspots to all graphics types, not just special
hotspot graphics. All the link types supported in the editor are also supported in hotspots
(topic links, Internet links, file links and script/macro links).
Since the link types are identical to those used in normal topics their settings are only
described briefly here. See Links, Anchors, Macros, Scripts and HTML 214 for more
information on hyperlinks.

Key Information
Hotspots in graphics are only supported in
electronic output formats (HTML Help,
Webhelp, Windows Exe eBooks, Visual
Studio Help / Help 2.0 and PDF with
hyperlinks activated). Hotspots are not in
the obsolete Winhelp format. Many ePub
readers do not support hotspots.

How to insert and edit a hotspot in a graphic

1. Insert the graphic in your topic (hotspots can only be added to graphics inserted in
topics).
2. Open the hotspot editor:
· Double-click on the graphic and then click on the Hotspots... button

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 247

OR
· Right-click on the graphic and select Picture > Edit Hotspots in the context menu.

3. Click on one of the Insert Hotspot tools (this will insert a new hotspot in the top left
corner of the graphic):
Topic link hotspot
Internet link hotspot
File link hotspot
Script link hotspot
4. Move and resize the hotspot with the mouse and select the hotspot style (Rectangle
or Ellipse). You can also enter the precise size and position of your hotspot as pixel
values.
5. Select and enter the hotspot details. These are exactly the same as for ordinary links
in topics.
Editing hotspots:
To edit a hotspot just double-click on the graphic and open the Hotspots editor again.

Linking to popup topics

You don't have to do anything special to create a link to a popup topic. A topic defined as
a popup will automatically display as a popup when you link to it, so you just need to
create a normal topic link and choose a popup topic as the target.
See Creating popup topics 125 for full instructions on how to create and use popup topics.
All the instructions here apply for links in hotspots, which are essentially exactly the same
as normal links.

How to align hotspots precisely

The Align buttons arrange all the selected hotspots in a row, aligning them to first hotspot
that you select:

© 1997 - 2009 by EC Software, all rights reserved

248 Help & Manual 5 - User Help

1. Use Shift+Click to select all the hotspots you want to align. The hotspots will be lined
up with the first hotspot you select.
2. Select one of the two Align tools to align the hotspots vertically or horizontally:
aligns the hotspots in a vertical row,
using the first hotspot selected as the
reference.
aligns the hotspots in a horizontal row,
using the first hotspot selected as the
reference.

Old IPP and SHG graphics with hotspots

In Help & Manual 3 and earlier hotspots were stored in Impict IPP graphics files and in
files in the standard Microsoft SHG format. If you convert HM3 projects containing these
graphics to the current Help & Manual format the hotspots will be converted correctly.
However if you insert old IPP or SHG graphics containing hotspots in a current Help &
Manual project the hotspots will not be available. If you want to use hotspots in these
graphics you must re-enter them using the hotspot editor following the instructions above.

Hotspot compatibility in publishing formats

Winhelp: Hotspots are no longer supported in the obsolete Winhelp
format

HTML Help: Supported (JavaScript and four standard Winhelp macros

223 )

Visual Studio Same as HTML Help but all external file links are explicitly
Help: forbidden in Visual Studio Help / MS Help 2.0.

Webhelp: Supported (JavaScript but no Winhelp macros, JavaScript

support also depends to a great extent on the user's
browser, so use with caution)

Windows Exe Hotspot topic links are supported, no support for script or
eBooks: macro links

ePub eBooks Hotspots are included in the ePub specification but most
ePub readers (both hardware and software) do not support
them

Adobe PDF: Hotspot topic links are supported, no support for script or
macro links

Word RTF: No support for graphics hotspots.

See also:
Links, Anchors, Macros, Scripts and HTML 214

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 249

IDs, Context Numbers and Keywords 801

4.9.9 Finding and replacing graphics
The Find & Replace function for text can also locate and replace graphics files in your entire
project. This can be very useful if a graphic that you have used over and over again in your
entire project needs to be replaced quickly!

Key Information
This function only replaces the file names
in the references to the graphics files in
your topics. It does not affect the actual
graphics files or their names in any way!

How to find and replace graphics with Find & Replace

1. Make a note of the exact names of the graphics files you want to find and replace.
2. Select Find & Replace in Write > Editing.
3. Select the In Image Filenames option in the Find Where section of the dialog.
4. Use the other options in the dialog to define the scope of your search. See Find &
Replace Text 602 in the Reference section for details.
This function only searches for entire graphics file names. Wildcard characters are not
supported. This means you must enter the entire name, including the dot and the file
extension.

A quicker way to replace graphics files

There is a quicker way to do this if the name of the graphics file you want to replace is not
important:
· Just overwrite the original graphics file in your project graphics directory with the
updated or different graphic, so that the new graphic is in the same location and has
the same name as the old graphic.
Help & Manual always checks the size of graphics when it loads them so this also works
with graphics that have different dimensions. The two graphics must both have the same
format, however! (You cannot use this method to replace a JPG with a GIF graphic, for
example.)

See also:
Searching for text, topics and referrers 141
Find & Replace Text 602
Find Topic 585
Find Referrers 586
4.9.10 Managing your graphics
When you add graphics to a project Help & Manual inserts a reference to the graphic file
that only contains the name of the file. It finds the graphics by looking in the Project Search

© 1997 - 2009 by EC Software, all rights reserved

250 Help & Manual 5 - User Help

Path, which is defined in the Configuration section of your project. The folders listed in the
path are searched in order and the first file with a matching name is used.
This strategy makes it very easy to organize and move your graphics files you just need to
change the settings in the Project Search Path to let Help & Manual know where to look for
the graphics.
It is generally advisable to store your image folders together with your project folder.

Key Information
If you use multiple graphics folders it is
very important to avoid duplicate filenames
in different image folders! If you have
duplicates Help & Manual will only find the
first version of the graphics file with a
matching name.

Editing the Project Search Path

Help & Manual locates graphics on the disk by searching in the directories listed in the
Project Search Path. You do not normally need to add image folders to the path
manually. The program does this for you when you insert images from a new folder.
· To edit the Image Folders list manually go to Configuration > Common Properties
> Program Search Path for your current project in the Project Explorer.
· See Project Search Path 656 for more details.

Moving image files and image folders

You are free to move your image files and image folders whenever you like. Since only
the image file names are stored in your project you just need to change the references in
the Project Search Path to tell Help & Manual where to look for the files.
1. Move and/or rename the image folders and their contents.
2. Edit the Project Search Path (see above) to remove the old directories and add the
new ones. Help & Manual will now find your images in the new location(s).
Splitting and consolidating image folders:
You can also reorganize your image files in any way you like for example move all your
image files to a single folder or to multiple folders in any locations. You just need to tell
Help & Manual where to look for the images in the Image Search Path settings.

Moving your projects to different locations

The references in the Project Search Path are actually relative, even though the full paths
of all the folders are shown for your information. This means that moving your project is
very easy.
· If you save both your project folder and your image folders in the same folder you can

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 251

move your project without needing to make any changes to the Project Search Path.
· If your image folders and your project folders are in different locations you will need to
update your Project Search Path after moving your project folder.

Managing graphics in modular projects

It's always important to avoid duplicate filenames for your graphics. This applies in
particular for modular projects, because you will often have separate graphics folders for
each project.
Duplicate names across project modules are OK in HTML Help and Winhelp projects
with runtime merging 767 because then each module is compiled individually and the
correct graphics will be used. However, you need to avoid duplicates in all other formats
and in modular projects with publish-time merging 767 in HTML Help and Winhelp as well.
Use filename prefixes for graphics files in modules
The simplest solution for this problem is to add a unique prefix to the filenames of
graphics files used in modules, in the same way that you use prefixes for the topic IDs 456
in modules. The prefix should be short – two letters and an underline character are
usually plenty – and should identify the module.

See also:
Image Folders 656
Importing graphics from RTF files 105
4.9.11 Shortcuts for graphics
You probably have some graphics that you use again and again in your project logos,
images of buttons and so on. Help & Manual's "Recent Images" and "Image Shortcuts"
functions make accessing images quick and easy. Recent Images shows thumbnails of all
the images you have used recently, so that you can click on them to insert them again.
Image Shortcuts is a configurable list of graphics that you can select and insert in your
projects with a single click.

How to access Recent Images and Image Shortcuts

To display the Image Shortcuts list select the menu icon below the Insert Picture tool in
Write > Insert. The Recent Images selection appears automatically as soon as you
have inserted some images in your projects. You must add images to the Image
Shortcuts list yourself by selecting Configure Image Shortcuts.

© 1997 - 2009 by EC Software, all rights reserved

252 Help & Manual 5 - User Help

Recent Images only appears when you have inserted images

How to use the Image Shortcuts list

Image Shortcuts graphics are not embedded in your project. They are simply links for
quick access to frequently-used graphics. This means that you can also use shortcuts for
larger images.
Adding images to the list:
1. Click on the dialog icon below the Image tool in Write > Insert and select Configure
Image Shortcuts:

2. Select Add Picture in the dialog displayed to add a new image to the list.

Inserting images:
Click in the editor in the position where you want to insert the image, then click on the
thumbnail image you want to insert in the Picture Shortcuts menu.
Organizing the list:
Use Add Category to organize your images in categories, which are also displayed in the
menus. Use Move Up and Move Down to arrange your images and categories in the list.

See also:
Graphics References 442

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 253

4.10 Working with Tables

Tables in Help & Manual are a little different from what you may be used to if you have only
worked with a word processor like MS Word up to now. This is necessary because most of
the main output formats supported by Help & Manual are more like dynamic HTML pages
than the static print-style pages produced by word processors.
In HTML and similar formats tables can shrink and grow as the user changes the size of the
browser or viewer window. This means that you need to be able to define both tables and
table columns with dynamic widths that can change interactively, and you also need to plan
the layout of your table content to accommodate this behavior.

4.10.1 About tables

Help & Manual supports fully-formatted complex tables. Your tables can have styles,
borders, background colors, background images, alternating colors in alternating rows and
much more. Tables break automatically at page boundaries in PDF and other print-style
output formats, both between rows and within rows.
You can also define styles for tables in the same way as for paragraphs. This allows you to
format complex tables in seconds and when you change the style definition all tables
formatted with the table style will be updated automatically.

Table tools in the Table tab

You can insert tables with the Table tool in Write > Insert but all the main tools for
manipulating tables are in the Table tab of the ribbon. Most of the tools here are self-
explanatory just make selections in your table and select the tools.

Table styles
· Table styles are defined and managed together with paragraph and text styles. To
create and edit table styles select Styles > Edit Styles in the Write tab.
· To apply a style to a table just click in the table and then select Table > Properties
and select the style you want to use.
· You can also select a style when you are defining a new table.
See Table styles 263 for more details.

Tables occupy an entire paragraph

A table is inserted as a single paragraph containing a single object (the table). It is not
possible to add any more objects to this paragraph. For example, if you type a character
in the paragraph before or after the table this will automatically insert a new paragraph.
This has two important consequences:
· You can delete an entire table by pressing the Delete or Backspace key once.

© 1997 - 2009 by EC Software, all rights reserved

 254 Help & Manual 5 - User Help

· You can indent and center tables by applying paragraph formatting to the paragraph
containing the table.

Table editing restrictions

Copying, cutting and pasting is restricted to single cells and entire tables. You can copy,
cut and paste entire tables and the contents of single cells. You cannot copy either the
contents of multiple cells, or columns, rows or ranges of cells.

Restrictions in Winhelp output

Microsoft Winhelp is an obsolete format that lacks support for a number of modern
formatting options. These include table borders, nested tables, borders, background
colors, superscript and subscript. It is advisable not to use these features for Winhelp. If
you want to output to both Winhelp and other formats you can create alternative versions
using conditional output 399 .

See also:
Classic Winhelp 740
Table styles 263
4.10.2 Inserting tables
You can insert new tables with tools in the Write and Table tabs of the Ribbon. The Table
tab provides you with direct access to all the table editing tools.

Key Information
If you set a color for the heading row of a
table it will only be displayed if your table
has at least one heading row! Check this in
Table Properties if your heading row color
is not displaying.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 255

How to create a new table

1. Select the Table tool in Write > Insert.

2. For a quick table just highlight the number of rows and
columns in the table matrix and click to insert the table.
For more control click on Insert Table to display the
Insert Table dialog.
3. Enter the number of rows and columns and choose your
formatting options.
For full details see Table Properties 638 in the Reference
section.

Choosing the table width options

Column widths are not set when you create the table. Please see Managing column
widths 256 and About table and column widths 723 for details on setting and adjusting the
widths of your tables and their columns.
You can choose the following table width options when you insert a table:

Autosize: Creates a table that calculates its size on the basis of the contents of its
cells. The absolute width of the table in your output will depend on how you
adjust the width of the cells and the content you put in them.

Size table Creates a table that is permanently maximized to the width of the current
to fit on paragraph (if the paragraph has indents the table will be narrower than the
page: page). This is exactly the same as sizing manually and setting a width of
100%.

Size table Creates a table with a fixed width in percent or pixels. Percentage values
manually: are relative to the width of the current paragraph. Setting a value of 100%
is exactly the same as Size table to fit on page.

Setting up tables for printing

Tables can be set to split automatically at page boundaries for PDFs and manual
printouts. Note that this function is not supported by the Print Topic tool in the Topics tab,
which is a very simple print function.
· Select Table can split to next page in the Table Properties to ensure that page breaks
can be inserted when you output to PDFs and printed manuals.
· Select the Number of heading rows that you want repeat on each page as the ongoing

© 1997 - 2009 by EC Software, all rights reserved

 256 Help & Manual 5 - User Help

header of the table.

If you set a background color for your table header it will only be displayed if you define at
least one heading row!

See also:
Table Properties 638 (Reference)
Managing column widths 256
How table sizing works 723 (Reference)
4.10.3 Managing column widths
By default, the widths of all columns in tables are "dynamic" they expand to fit the width of
the content they contain and the defined width of the table. After you create a table you can
adjust the widths of columns by dragging their borders with the mouse and by setting their
widths to absolute or percentage values in the Table Properties dialog.
You can also "lock" the widths of columns. This can be necessary if you are using tables as
a layout tool and want to have column widths that do not change dynamically when the users
adjusts the size of the help viewer window.
How you define your column widths is crucial for how your tables behave in your published
output, in particular in formats like PDF and RTF where the tables must fit inside a fixed
page width.

Relationship of column width to table width

The table width is defined when you create the table and can be changed with the
Properties tool in the Table tab. The width can be dynamic or fixed.
In tables with dynamic widths (autosize, percentage widths and 100%/fit to page) you
must always have at least one column with a dynamic width that can resize to allow the
table to resize. If you do not Help & Manual will make all column widths dynamic in your
output and the results may be unexpected.

Setting and changing column widths

To adjust the width of a column you must make its width fixed, otherwise it will expand
automatically to fit its content. You do this by dragging the column dividers with the
mouse or by changing the settings in the Table Properties dialog.
· Drag column dividers with the mouse
This will lock the width of both affected columns. If you want one of the columns to be
dynamic click on the Lock Column tool (see below) in the Table tab to unlock it again
after resizing.
· Use Table Properties
Click in a column or click and drag to select 258 two or more columns. Then select the
Selected Cells tab in Table > Properties and enter a width value in percent or pixels.
· Use the Lock Column tool
When working with column widths use the Lock Column tool in the Table tab while you

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 257

are working to lock and unlock the widths of columns. It also shows you whether the
current column is locked or unlocked.
Column widths in complex tables:
If you merge and split cells in a table you will find that some widths cannot be changed
beyond a certain point because the rows and columns no longer extend across the entire
height and width of the table. In some cases you may have to use nested tables or
multiple tables to achieve the widths you need.

The Lock Column tool

The Lock Column tool in the Table tab sets the width of the selected column or columns
to a fixed value in pixels. In locked columns selecting the tool unlocks the column and
makes it dynamic again.
You can also access the same function by right-clicking in the column or by setting a
fixed width in pixels for Selected Cells in Table > Properties.

Possible and impossible column widths

The column widths you set will only be used if they are possible, otherwise you will have
problems in your output:
· If all column widths are in percent their total must be exactly 100%, otherwise they will
all be ignored.
· Avoid mixing columns with percentage widths and pixel widths in fixed-width tables.
Browsers, particularly the famously competent Microsoft Internet Explorer, will often
interpret these "mixed widths" incorrectly.
· If the table width is dynamic ("autosize" or "percent") you must always have at least one
dynamic column.
If your column width settings are contradictory or impossible all columns will be made
dynamic in your output and the results may be unexpected!

Column widths and PDF/RTF output

PDF and RTF files have fixed margins and fixed page widths. This means that your
tables and their content must fit inside the margins of your pages in these formats. If they
do not fit with the defined column widths Help & Manual will make all the column widths
dynamic to force the table to fit. The results may be unexpected!
You should always have at least one dynamic column in your tables to allow the table
width to be adjusted to fit on the PDF or RTF page. Adjustable columns should only
contain wrapping text, fixed-width content like graphics or paragraphs with word wrap
turned off (for example program code examples) will prevent column width adjustment.

See also:
Table Properties 638 (Reference)
How table sizing works 723 (Reference)

© 1997 - 2009 by EC Software, all rights reserved

 258 Help & Manual 5 - User Help

4.10.4 Selecting and formatting cells and tables

In general you can select and format tables and cells just as you would in a normal word
processor. However, there are a couple of differences. Also, you need to remember that
tables in Help & Manual behave more like dynamic HTML tables than the static tables you
may be used to if you have only worked with word processors up to now.

Key Information
Changing the widths of table columns with
the mouse always locks the width of both
affected columns. Always use the Lock
Column tool after changing widths to make
columns dynamic again!

Selecting and resizing tables with the mouse

Select entire Position the mouse just to left of table and click, or click and drag
table: through the entire table.
OR
Click in a cell and press Ctrl+A. Pressing once selects the current cell,
pressing again selects the entire table.

Select single Just click in the cell. Even though it is not highlighted it is selected for
cell: formatting the cell properties (see below). This does not select any text
that the cell contains, however – this must be selected, formatted and
edited just like text in the editor.

Select Click and drag.

multiple cells:

Select row: Position mouse over left border of table ( mouse pointer) and click. Or
click and drag through row. Using the click method takes a little
practice, the mouse pointer only appears in a very narrow area.

Select Position mouse over top border of table ( mouse pointer) and click. Or
column: click and drag through column. Using the click method takes a little
practice, the mouse pointer only appears in a very narrow area.
You cannot select a column if the cursor is currently in the top cell of
the column. Click in a cell to the left or right of the top cell before
selecting using this method!

Resize table: Drag the right and bottom borders of the table.
Note that this is not possible with some table width settings. For
example, you cannot resize a table with a width of 100%/fit to page.
You also cannot resize a fixed-width table or a table whose columns all
have fixed widths.

Resize cells: Drag the cell borders.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 259

Resizing tables and cells with Table Properties

Note that most of the settings you can enter are not absolute. All widths except pixel
values are relative to the output page, which can vary depending on how the user sizes
the viewer window (electronic formats) and the size of the printout page (PDF etc). You
can only set a minimum height for cells; the actual height is controlled by the cell
contents.
1. Select the table or the cells you want to resize (see above).
2. Select Table > Properties or right-click and select Table > Table Properties.
· To resize the entire table use the settings in the Table Layout tab.
· Select the Selected Cells tab to adjust the size settings for individual cells.
For details see Table Properties 638 in the Reference section.

Formatting entire tables and individual cells

Formatting Right-click in the table and select Table > Properties.
entire table:

Formatting Right-click in the cell and select Table > Properties, then click on the
single cells: Selected Cells tab.

Formatting Select the cells, right-click on the selection and select Table >
multiple cells: Properties, then click on the Selected Cells tab.

See also:
Table Properties 638 (Reference)
How table sizing works 723 (Reference)
4.10.5 Adding and deleting rows and columns
You can add and delete rows and columns in tables both with the Ribbon tools and by
changing the number of rows and columns in the table definition in Table Properties.

Key Information
In complex tables with split and merged
cells deleting rows and columns may have
unexpected results if the row or column
you are deleting overlaps merged or split
cells.

Adding rows and columns with the Ribbon tools

1. Click in the table at the point where you want to insert new rows or columns.
2. Use the Rows and Columns tools in the Table tab, or right-click and select the same

© 1997 - 2009 by EC Software, all rights reserved

 260 Help & Manual 5 - User Help

options from the context menu.

Deleting rows, columns and tables with the Ribbon tools

1. Select the rows or columns you want to delete or click in a cell to delete only the row
or column containing that cell.
2. Select Table > Rows and Columns > Delete or right-click and select Table >
Delete and then select what you want to delete (Rows, Columns or Table).
You can also delete an entire table by placing the cursor directly before or after the table
and pressing Delete or Backspace.

Adding and deleting rows and columns with Table Properties

1. Select Table > Properties or right-click and select Table > Properties in the context
menu.
2. Adjust the Rows and Columns settings to increase or delete.
Increasing and decreasing the number of rows and columns in the Table Properties
dialog adds or deletes rows or columns in the last positions (right and bottom) of the
table.

See also:
Table Properties 638 (Reference)
How table sizing works 723 (Reference)
4.10.6 Splitting, merging and unmerging cells
You can create complex tables by splitting and merging cells both vertically and horizontally.
In addition to this you can also nest tables 266 inside one another to create even more
complex structures. (To nest a table just insert a new table in the cell of an existing table.)

How to merge cells

1. Select the cells you want to merge (you must select at least two cells).
2. Use the Merge Cells tool in the Table tab or right-click and select Table > Merge
Cells in the context menu.
You may need to adjust the width of the table or individual columns after merging.
Remember to check your column lock settings with the Lock Column tool 256 in the Table
tab after adjusting widths.

How to split cells

1. Select the cells you want to split. If you just want to split a single cell click inside the
cell, it is then selected automatically even though it is not highlighted.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 261

2. Use the Split tool in the Table tab or right-click and select Table > Split Cells in the
context menu and choose Vertically or Horizontally to choose the direction of the split.
3. Enter the number of columns or rows you want to split into (the default is 2).

How to unmerge cells

This function restores the original number of rows and/or columns in the selected cells,
basing the number on the original definition of the entire table.
1. Select the cells you want to unmerge. If you just want to unmerge a single cell just
click inside the cell, it is then selected automatically even though it is not highlighted.
2. Use the Unmerge tool in the Table tab or right-click and select Table > Unmerge in
the context menu and then choose Rows, Columns or Rows and Columns.

See also:
Nested tables 266
Managing column widths 256
Table Properties 638 (Reference)
How table sizing works 723 (Reference)
4.10.7 Deleting the contents of cells
Selecting cells and pressing Delete just deletes the contents (i.e. text, graphics etc.) of the
cells, not the cells themselves. The only exception to this is when you select the entire table.
If you do this and press Delete it will delete both the contents and the entire table!

How to delete the contents of cells

1. Select the cells 258 whose contents you want to delete. (Don't select the entire table as
this will delete both the contents and the entire table.)
2. Press the Delete key.

Deleting both cells and their contents

This is only possible with entire rows and columns.
1. Select the cells, rows or columns you want to delete.
2. Select the Delete tool in the Table tab and choose Rows or Columns to delete all the
cells and their contents.

See also:
Table Properties 638 (Reference)
How table sizing works 723 (Reference)

© 1997 - 2009 by EC Software, all rights reserved

 262 Help & Manual 5 - User Help

4.10.8 Converting tables to text

At the moment it is not possible to convert text to tables in Help & Manual. However, if you
need to do this you can copy the text to MS Word, convert it to a table there and then paste
the table back to Help & Manual.
In the same way you can also copy a table from Help & Manual to Word, convert it to text
there and then copy the text back.
In addition to pasting you can also save Word documents as RTF files and then import them
to your project with File > Load Topic from File in Write > Manage Topics, or with Import
in the Application Button menu.

See also:
Selecting and formatting cells and tables 258
Exporting and importing topics 204
4.10.9 Indenting tables
A table is handled as a single object in a paragraph that is not allowed to contain any other
objects. The formatting of the table itself is handled by the table properties but the position
and alignment of the table on the page are controlled by the paragraph properties of the
paragraph containing the table.
This means that to indent a table you need to adjust the indent settings of the paragraph
containing the table. This can be done either with a style or by adjusting the paragraph
formatting manually.

How to select the table paragraph for indenting

To indent a table's paragraph you first need to place the cursor between the table and its
paragraph mark. Doing this can be a little tricky until you get the hang of it. To make it
easier it is better to turn on paragraph marks display in the editor with the tool in Write
> Paragraph. Then just click directly between the paragraph mark and the end of the
table.

Alternatively, you can just place the cursor at the end of the last cell in the table and then
press the right arrow cursor key on your keyboard once, or place the cursor at the
beginning of the next paragraph after the table and press the left arrow cursor key once.
Both these operations will also position the cursor between the table and its paragraph
mark.

Adjusting table indent settings

First position the cursor between the table and its paragraph marker (see above), then
adjust the indent settings with a style or manual formatting:

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 263

· To adjust the settings with a style:

Create a style (see Text Formatting and Styles 155 ) with the necessary indent settings,
then position the cursor and apply the style by selecting it in the style selector (or by
pressing the style's keyboard shortcut if you have defined one).

· To adjust the settings manually:

Position the cursor and then use the paragraph formatting tools to adjust the paragraph
settings.

See also:
Selecting and formatting cells and tables 258
Text/paragraph styles in tables 265
4.10.10 Table styles
Just as you can define styles for formatting text and paragraphs you can also define styles
for tables. Like text and paragraph styles, table styles are dynamic. This means that when
you change the style definition all tables in your project formatted with that style change
automatically.
Table styles also "inherit" properties from the styles they are based on and this is also
dynamic. The "child" style inherits all the properties of the "parent" style. If you change the
definition of the parent style all the matching attributes in the child styles will also change.
Only attributes that you have explicitly changed in the child styles will remain unchanged.

How to define a new table style

1. Select Styles > Edit Styles in the Write tab.
2. Click in the Table Styles section at the top, then select Add Style.

© 1997 - 2009 by EC Software, all rights reserved

264 Help & Manual 5 - User Help

3. Enter a name for the style in the Style Name: field.

4. If you want to base the style on another style select the parent style in the Based on
Style: field.
5. Click on Modify Layout to define the attributes of the style. The settings are just the
same as the normal table settings 638 , although there are a couple of table settings that
cannot be included in table styles.

Creating a new table with a style

1. Click on the Table tool in the Write or Table tab and select Insert Table.
2. Enter the number of rows and columns you want the table to have.
3. Select the style in the Table Style: field.
4. Make any manual changes (settings that you want to be different from the style
definitions)
5. Click on OK to insert the table.
Note that any properties settings you edit manually in a table formatted with a style will
remain unchanged if you change the definition of the table style later. Only attributes
controlled by the style will change when you change the style definition!

Applying a table style to an existing table

1. Click inside the table that you want to format.
2. Select Properties in the Table tab and select the style in the Table Style: field.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 265

3. If you want to make any individual changes you can also adjust the settings directly in
the Table Properties dialog before you close it.
Note that any properties settings you edit manually in a table formatted with a style will
remain unchanged if you change the definition of the table style later. Only attributes
controlled by the style will change when you change the style definition!

4.10.11 Text/paragraph styles in tables

Table styles define the formatting of the table itself the table width and width mode,
borders and border style, background colors and so on. They do not define the formatting of
the text inside the tables that must be formatted with styles or the manual formatting tools.

How to align a table with a paragraph style

You can control the alignment of a table by applying a style to the paragraph containing
the table for example to center a fixed-width table or to indent the left and right sides of
the table from the margins of the page. Only the paragraph attributes will have an effect,
text attributes will be ignored.
1. Click on in Write > Paragraph to display paragraph marks (this makes it easier to
see what you are doing).

2. Click to the right of the table between the table and its paragraph mark so that you can
see the blinking editing cursor between the right margin of the table and the paragraph
mark.
3. Select the style you want to apply in the drop-down style list in the Toolbar.

How to apply styles to the contents of tables

If you select all or part of a table and apply text or paragraph styles the styles will be
applied to the text in the selected cells inside the table.
· Select text and paragraphs in the table cells and apply styles just as you would in the
normal editor. You can also apply styles to multiple paragraphs in multiple cells by
selecting the cells and then applying the style.
Note that if you want to apply a style to all the paragraphs in a table you must select the
entire table by clicking and dragging inside the table. If you click in the left margin to
select the table you will not be able to apply styles because then the table is selected and
not its contents.

How to apply a table style to a table

1. Click in the table you want to format.

© 1997 - 2009 by EC Software, all rights reserved

 266 Help & Manual 5 - User Help

2. Select Properties in the Table tab and then select the table style you want to use and
click on OK.
See Working with Tables > Table styles 263 for full details.

How to define a table style

1. Select Styles > Edit Styles in the Write tab.
2. Click in the Table Styles section at the top, then select Add Style.
3. Enter a name for the style in the Style Name: field.
4. If you want to base the style on another style select the parent style in the Based on
Style: field.
5. Click on Modify Layout to define the attributes of the style. The settings are just the
same as the normal table settings 638 , although there are a couple of table settings that
cannot be included in table styles.

See also:
Table styles 263
Table Properties 638 (Reference)
How table sizing works 723 (Reference)
Text Formatting and Styles 155
4.10.12 Nested tables
Help & Manual's table formatting functions are powerful but they do have some limitations.
For example, you can't set cell borders (or different cell borders) for just a defined range of
cells, and you can only set a background picture for the entire table. Merging and splitting
cells in a single table can also place limitations on column width adjustments.
Some of these problems can be solved by using nested tables, i.e. by inserting a second
table inside the first table. Then you can apply different table properties to the second table,
which can be a single cell, row or column in the "parent" table.

Productivity Tip
Temporarily apply thick colored borders to
your nested tables so that you can see
where they are while you are working with
them. You can do this most easily by
defining a table style and applying it
temporarily while you are working.

How to insert a nested table

Inserting a nested table is just like inserting any other table. The only difference is where
you insert it:
1. Click inside the cell of the table where you want to insert another table.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 267

2. Use any of the standard methods for inserting a new table.

The nested table is a fully independent table in its own right. You can use all the normal
table formatting and editing functions on it, including applying a style to its "table
paragraph". You just need to keep track of where your nested tables are, which can be
tricky.

Warnings and limitations

Don't go overboard with nested tables. It's tempting to use them but it can get too
complicated very quickly!
Nested tables are not supported by Winhelp and will cause compiler errors if you try to
use them for Winhelp output.
Page breaks in PDF and RTF output and printed manuals may not work correctly inside
table rows containing nested tables, particularly if the tables contain merged cells.

See also:
Table Properties 638 (Reference)
How table sizing works 723 (Reference)
4.10.13 Using background graphics
In addition to defining background colors you can also add background graphics to your
tables. For example, you can insert a single large graphic behind a table like a "watermark",
or you can tile a small graphic to create a repeating pattern or texture as a background for
the table.

Productivity Tip
You can apply a background graphic to a
single cell of a table by using a single-cell
nested table 266 (inserting one table inside
another) and applying the background
graphic to the nested table.

How to apply a background graphic to a table

1. Click in the table and select Properties in the Table tab or right-click and select Table
> Properties to display the Table Properties 638 dialog.
2. In the Table Layout tab select the Background Picture option.
3. Click on and select the graphics file you want to use.
4. Select Tile to repeat the graphic in a pattern or Center to display the graphic only
once, centering it on the center of the table.
Matching the size of graphics to your tables can be tricky with centered images. The most
practical solution is to use graphics that have an edge the same color as the page or
table background so that you don't have to line up precisely with the edge of the table.
Graphics are normally applied to the entire table. If you want to apply a graphic to a

© 1997 - 2009 by EC Software, all rights reserved

 268 Help & Manual 5 - User Help

single cell or range of cells you can do this by inserting a nested table 266 and applying the
background graphic to the nested table.

See also:
Table Properties 638 (Reference)
How table sizing works 723 (Reference)
4.10.14 Handling table borders
When you are defining borders around tables it is important to remember that there are two
different "objects" in tables for which you can define borders: The table itself and the cell.
Cell borders and table borders have separate settings.

Productivity Tip
If the thickness of your table borders looks
off in your PDF output try selecting the
screen device as the reference device for
PDF output in View > Program Options >
PDF.

The relationship between table borders and cell borders

The table border is outside the cell borders. If you set both cell and table borders the
resulting border around the table will have the width of the cell borders plus the width of
the table border.
· For example, if you set both the cell borders and the table border to a width of 3 pixels
the table border will have a width of 6 pixels, like this:

Table border width: 3 pixels

Cell borders width: 3 pixels

· If you want to create a table with borders that are the same as the cell borders just set
a width for the cell borders and leave the table border set to 0.

Table border width: 0 pixels

Cell borders width: 3 pixels

· The following example does the opposite. Here the table border width is set to 3 pixels
and the cell border width is set to 0 pixels. The grid lines are visible to show that it is the

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 269

same table:

Table border width: 3 pixels

Cell borders width: 0 pixels

Cells with different border colors

You cannot define different colors for cell and table borders in a single table. To create
one or more cells with different colored borders insert a second table inside the first table
and define different border color settings for the two tables. See Nested tables 266 for
details.

See also:
Nested tables 266
Table Properties 638 (Reference)
How table sizing works 723 (Reference)

4.11 Adding video files

Help & Manual takes all the manual labor out of adding videos to your help projects.
Basically you just click where you want to insert your movie and select the video file. Help &
Manual handles everything else for you, including choosing and inserting the correct code
for integrating the media files in the various output formats.
Please see About using video files 756 for important information on using video files in your
projects and support for video in the various publishing formats!

Adding Video Files

Ø Inserting videos 269
Ø Editing the HTML code 271
Ø Support in output formats 272

See also:
About using video files 756
4.11.1 Inserting videos
Inserting a video is just as easy as inserting a graphic. Basically you just click in the editor
where you want to insert the video, select the Insert Movie tool in Write > Insert Object
and select the video file you want to use.

© 1997 - 2009 by EC Software, all rights reserved

270 Help & Manual 5 - User Help

Please see About using video files 756 for important information on using video files in your
projects and support for video in the various publishing formats!

Productivity Tip
If you want to be sure that videos will play
properly then use the Flash Video format.
Other formats frequently cause problems
because of the varying support for different
video formats in different versions of
Windows and Windows Media Player.

How to insert a video in your project

1. Click in the editor at the point where you want to insert the video.
2. Select the Insert Movie tool in Write > Insert Object or right-click and select
Insert > Movie.

3. Click on the browse button in the File Name: field and select the movie file.
4. Select the Start options:
Start Starts the movie as soon as the topic
automaticall is displayed.
y:
Loop Repeats the movie indefinitely as long
playback: as the topic is displayed.
Show Displays playback control buttons
controls: together with the movie. Not available
for Flash Flash videos must have
their own embedded player controls.
5. Use Select Placeholder to select the placeholder graphic to be displayed in the topic
when the movie is not running. This graphic is also displayed in the Help & Manual
editor.
6. Check the Width: and Height: values and correct them if they do not correspond to the

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 271

original width and height of the movie (some players do not read these values
correctly).
7. Click on OK to insert the movie in your topic.
Important warning:
Don't try to use the Width: and Height: settings to scale your video, these options are only
for setting the correct original size! If you scale with these settings quality will be very
poor (i.e. really, really, really bad), particularly in Flash video and animation files.

How to insert a placeholder graphic

The "placeholder graphic" is a graphic that is displayed in your topic when the movie is
not running. This graphic is also displayed in the Help & Manual editor and in output
formats that do not support movies like PDF, printed user manuals and eBooks (Flash is
supported in Windows Exe eBooks, other video formats are not, ePub eBooks do not
support any video or multimedia formats).
1. If the Edit Movie dialog is not already displayed open it by double-clicking on the movie
placeholder in the editor.
2. Click on Select Placeholder, which displays a dialog with these options:
Run movie Allows you to make a screenshot from the
and take movie and insert it as a placeholder
snapshot: graphic.
Load image Loads a graphic image from a file and uses
from file: it as the placeholder graphic. The graphic is
automatically resized to the size of the
movie display so it should have the same
dimensions as the movie.
Copy Pastes an image from the Windows
image from clipboard. You must copy an image to the
clipboard: clipboard first, of course. Here too, the
image should have exactly the same
dimensions as the movie.

See also:
About using video files 756
4.11.2 Editing the HTML code
Help & Manual automatically generates the HTML code needed to embed and play media
files in HTML-based output formats (HTML Help and Webhelp). Normally you will not need
to touch this code but there may be special circumstances where you want to change or edit
the code for your own purposes.
eBooks: Note that although you can play Flash video and animation files in Windows Exe
eBooks (other video formats are not supported) this is handled by special internal routines.
Editing the HTML embedding code will not make any difference in your eBooks output.
Video is not supported at all in ePub eBooks.

© 1997 - 2009 by EC Software, all rights reserved

 272 Help & Manual 5 - User Help

How to edit the HTML embedding code

1. Insert a movie in your topic and double-click on it to display the Edit Movie dialog.
2. Click on the HTML Code tab and select the I want to enter the embedded HTML code
manually option.

3. This displays the code that would normally be entered automatically.

4. Edit the code and click on OK.
Note that you need to be familiar with writing HTML code and scripts to use this function.
Any changes you make are entirely your own responsibility, Help & Manual will not parse
or check your code in any way!
If you enter additional file or image references in your code the compiler will not know
about the files you are referring to and will not automatically include them in your output.
To solve this problem add these external files to the Baggage Section 485 – then they will
be included in your HTML output automatically.

See also:
About using video files 756
4.11.3 Support in output formats
Support for video files varies according to the output format you are using. This support is
dependent on the output formats themselves, not on the capabilities of Help & Manual.
The bottom line is that if you want to be relatively sure that your movie will play on the user's
computer then use Flash. This is the only real standard that will always play if support for it
is installed, and the great majority of users now have it. If support for Flash is not installed
the user will be prompted to download and install it automatically. Other formats may or may
not play, depending on the configuration of the user's computer.
Flash video can also be embedded in HTML Help CHM files. All other video formats must be
distributed in separate files.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 273

Support for video files in output formats

HTML Help: Flash and other video formats are supported. However, codecs for
playing the formats used must also be installed on the user's computer.
For example, if you use a DiVX video don't expect it to be playable on
all user machines!
Generally, however, only Flash video is recommended in HTML Help: If
Windows Media Player is required to play your video it will often fail to
play on some users' computers, depending on the version of Media
Player they have installed.
Flash is also the only format that is actually embedded in the HTML
Help CHM file, so you don't need to distribute any additional files with
your help.

Winhelp: Multimedia support in Winhelp is very limited. Only standard Windows

AVI videos are supported. Flash and other video formats are not
supported.

Webhelp: Flash and other video formats are supported. Here too, support for
playing the formats used must be installed on the user's computer.
Also, the degree and quality of the support also depends on the support
provided by the browser the user is using. So please test your output
on all relevant browsers before distributing!

Windows Exe Flash is supported if the necessary Flash plug-in is installed on the
eBooks: user's computer (the user will be prompted to download the plug-in if it
is not found). Other video formats are not supported.

ePub eBooks Neither Flash nor any other multimedia formats are supported in ePub
eBooks.

Adobe PDF: No multimedia support except as file links to external media files.

Word RTF: No multimedia support except as file links to external media files.

See also:
Help Formats 725 (Reference)

4.12 Keywords and Indexes

Every help file or manual needs a keyword index and Help & Manual makes creating and
maintaining a good index much easier than ever before. The Index Tool 275 displays the
finished index while you work and enables you to work in the entire index directly as well as
entering keywords for individual topics. .
Since you can see the results immediately it is very easy to avoid multiple entries that are
only slightly different from one another. In addition to this you can produce a much better
index because you can refer to the finished index while adding new entries, and you can
also navigate directly to the topics associated with index entries by clicking on the entries in

© 1997 - 2009 by EC Software, all rights reserved

 274 Help & Manual 5 - User Help

the Index Tool.

See also:
IDs, Context Numbers and Keywords 801 (Reference)
4.12.1 Adding and editing keywords
Each topic in your project can have its own list of "index keywords", each of which will create
an index entry in your output. You can add both simple keywords (master keywords) and
keywords with sub-entries (child keywords). Only one level of child keywords is supported
(this is a restriction imposed by the output formats, not by Help & Manual).
Index generation is automatic – an index will be generated when you compile as soon as
you have added one or more keywords to any topic in your project.

Productivity Tip
It is best not to use keywords in popup
topics and topics without TOC entries.
Clicking on Keyword Index entries will
display these topics in the main help
viewer and this may confuse the user.

How to add keywords from the topic editor

You can quickly add any word or series of words in the topic editor as a keyword:
· Just select the word or phrase you want to add and press Ctrl+K.
· This is the standard keyboard shortcut for this function. You can change it if you like in
View > Program Options > Shortcuts.

How to add and edit topic keywords

1. Select the topic you want to add a keyword to and select its tab below the editor
window.
2. Type your index entries in the Keywords: field in the tab. Enter one keyword per line
and press Enter after each keyword to create a new line.
Viewing and the topic at the same time:
Working with index keywords is easier if you can see and the topic content at the same
time. To do this drag the tab to the right border of the editor. Drag back down to the tab
bar to restore it to its original position. See Tips & Tricks in the Project Explorer 46 for
more details.
Using the Index tool:
If you have the Professional version of Help & Manual you can select the Index Tool 275 in
Project > Tools so that you can see the finished index while you are writing.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 275

How to add and edit topic sub-keywords

In the tab, indenting a keyword with the TAB key automatically makes it the sub-keyword
of the keyword above it.
1. Proceed as described above for adding keywords.
2. Enter child keywords in the line directly below their master keyword and indent them
with the TAB key. This will make it the sub-keyword of the keyword directly above it.
You can enter as many child keywords as you like for each master keyword – one per
line.
You can only enter one level of child keywords. Child keywords cannot have their own
child keywords.

Adding and editing keywords with the Index tool

If you have the Professional version of Help & Manual you can also edit the real-time
index directly with the Index tool. See Editing the index directly 275 for details.

See also:
Editing the index directly 275
IDs, Context Numbers and Keywords 801 (Reference)
4.12.2 Editing the index directly
If you have the Professional version of Help & Manual you can also edit the real-time index
directly with the Index Tool in Project > Tools. Note that this tool is only available in the
Professional version.
This tool enables you to edit keywords in all the topics where they occur simultaneously. You
can also add keywords to multiple topics and delete keywords from multiple topics at the
same time, in one quick operation.

Productivity Tips
Select Expanded View at the bottom of the
Index Tool window to display links to the
topics containing the index keywords.
Double-click on the Index Tool title bar to
undock or redock it.

Editing keywords in the Index window

This method allows you to edit keywords in all the topics where they occur
simultaneously. Any changes you make to the keyword in this editing dialog updates the
keyword in all the topics where it is used.
1. Select the Index Tool in Project > Tools, this displays the index window to the right
of the main editor pane.

© 1997 - 2009 by EC Software, all rights reserved

276 Help & Manual 5 - User Help

2. Select a keyword in the index and then click on the Edit Keyword tool in the Index
Tool toolbar. You can select a master keyword or a child keyword.

To add the keyword to more topics select the topics on the right and click on <<
3. Edit the keyword in the Keyword: field, then click on OK to save your changes. This
will save the modified keyword in all the topics whose IDs are listed in the Topic: list on
the left.

Viewing Topic Options and the topic at the same time:

Working with index keywords is easier if you can see and the topic content at the same
time. You can't undock the tab but you can display it next to the editor. To do this drag
the tab to the right or left border of the editor (choose the border not currently occupied
by the index tool). Drag back down to the tab bar to restore it to its original position.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 277

Drag the tab to the right or left editor margin to move it. Double-click on the Index
tool title bar to undock/redock it. Click on the "pin" icon in the Explorer title bar to pin/unpin
it.
Since this can make the editor a little narrow on smaller monitors it can be helpful to
undock the Index tool. To do this just double-click on the Index tool title bar. You can also
get more space when you are working in this mode by pinning the Project Explorer to the
left margin so that it collapses automatically when it is not needed.
See Tips & Tricks in the Project Explorer 46 for instructions and more details on these
features.

How to add new keywords in the Index window

New master keyword:
1. Select the Index Tool in Project > Tools to display the Index window, then select the
Add Keyword tool in the Index toolbar.

2. Select New Master Keyword and type the keyword in the Keyword: field of the dialog
displayed.

© 1997 - 2009 by EC Software, all rights reserved

278 Help & Manual 5 - User Help

3. In the Available Topics: list select the topic IDs of the topics you want to use the
keyword in. Use Ctrl+Click and Shift+Click to select multiple IDs.
4. Select to add the IDs to the Topics list, then click on OK to insert the new
keyword in all the selected topics. You can also double-click or drag to the left to add
topics to the list.
5. Click on Reload in the Index toolbar to redisplay the index.

New child keyword:

1. Select a master keyword in the Index window. The new child keyword will be added to
this keyword.
2. Select the Add Keyword tool in the Index toolbar and then select New Child
Keyword.

3. Enter the new child keyword in the dialog displayed and press on OK to confirm.
You can use the button to add the same child keyword to additional topics just
select the topics in the list on the right and add them to the topics list on the left. If the
master keyword is not stored in those topics it will be added too.

How to add keywords to additional topics

You can add selected keywords to additional topics or remove keywords from selected
topics with the Index window tools.
1. Select the Index Tool in Project > Tools to display the Index window, select a
keyword and open the editing dialog with the Edit Keyword tool.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 279

2. In the Available Topics: list select the topic IDs of the topics you want to use the
keyword in. Use Ctrl+Click and Shift+Click to select multiple IDs.
3. Select to add the IDs to the Topics list, then click on OK to insert the new
keyword in all the selected topics. You can also double-click or drag to the left to add
topics to the list.

Adding keywords to anchors

If topics contain anchors you can add keywords to the anchors instead of to the main
topic.
1. Use any of the methods described above to add or edit a keyword in the Index
window.
2. In the Edit Keyword dialog select the topic in the list on the left, then select the anchor
in the Anchors: drop-down list in the middle. The keyword will then be assigned to the
anchor for this topic instead of to the top of the topic.
Anchors will only be displayed for topics that actually contain anchors. See Anchors -
jump targets 226 for more details on how to enter and edit anchors.

Deleting keywords
Warning: Deleting keywords in the Index window deletes the keywords from all the
topics in which they occur! If you only want to remove keywords from individual topics use
the Edit Keyword tool or edit the keywords for the topics directly in the tab.
1. Select the Index Tool in Project > Tools to display the Index window.
2. Click on the Delete Keyword tool in the Index toolbar and confirm the prompt
displayed.

See also:
IDs, Context Numbers and Keywords 801 (Reference)
Anchors - jump targets 226

© 1997 - 2009 by EC Software, all rights reserved

 280 Help & Manual 5 - User Help

4.12.3 Find and replace keywords

You can also perform search and replace operations in all the keywords in your project. This
is a very useful Help & Manual function that is easy to overlook!

How to find and replace keywords

1. Select Editing > Find and Replace Text in the Write tab.
2. In Find Where select In topic keywords.
Note that Find and Replace does not work on keywords attached to anchors, but it does
work on A-keywords.

See also:
Searching for text, topics and referrers 141
IDs, Context Numbers and Keywords 801 (Reference)
Using keywords with anchors 280
Using A-keywords 281
4.12.4 Using keywords with anchors
Normally, clicking on an entry in the index of a help file executes a jump to the top of the
topic containing the keyword. However, you can also associate keywords with anchors,
which are jump targets in your topics. When an anchor keyword is clicked in the index the
user is taken directly to the anchor location in the topic.

How to add keywords to an anchor

1. Select the Insert Anchor tool in Write > Insert Object to insert a new anchor or
double-click on an anchor icon in your topic text to edit an existing anchor.

2. Type the keywords into the Keywords: field of the Anchor dialog. You can enter both
main keywords and sub-keywords. Use the TAB key to enter sub-keywords (an
indented keyword automatically becomes the sub-keyword of the keyword above it).
Same keywords in anchors and :
It is possible to have the same keywords in both the topic's and in one or more anchors in
the same topic. However, if you want your index entries to enable jumps to the anchor
without confusing the user it is better to avoid this.
Note that you can also add keywords to anchors by editing the keyword with the Index
Tool. See Editing the index directly 275 for details.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 281

Displaying anchor keywords in the Index Tool

Anchor keywords in the Index Tool:
Normally, anchor keywords look exactly the same as other keywords in the Index Tool in
Project > Tools. To make the anchor keywords visible select Expanded View at the
bottom of the Index Tool window. The anchors of anchor keywords will then be displayed
after their topic IDs, separated from the IDs by a # character, like this:
intro_part1#beginners
In the example above intro_part1 is the topic ID and beginners is the anchor name.
Anchor keywords in the Edit Keyword dialog:
Anchor keywords are always displayed in the topic_id#anchorname format in the Edit
Keyword dialog, which is display by selecting the Edit tool in the Index Tool toolbar.

Anchor keyword display in HTML Help

When the user clicks on a keyword found in multiple topics a dialog is displayed showing
the names of the topics in which the keywords are found together with the title of the help
project (this is only really relevant for modular projects containing multiple help files).
In HTML Help, however, the keyword text is displayed instead of the name of the topic.
This is a restriction of the HTML Help format and cannot be changed.

Both the entries found here refer to the keyword "Horticulture". The first keyword is an
anchor keyword, the second is a normal keyword in a topic.

See also:
Editing the Index directly 275
IDs, Context Numbers and Keywords 801 (Reference)
4.12.5 Using A-keywords
A-keywords, also known as "A-link keywords", are quite similar to normal keywords but they
not displayed in the index, they are always "hidden". What use is a keyword that isn't
displayed in the index? There are two major uses for A-keywords: To create "See also" lists
of related topics and to create links between help files in modular help systems.

© 1997 - 2009 by EC Software, all rights reserved

282 Help & Manual 5 - User Help

See About A-Keywords 806 for background information.

Key Information
Note that A-keywords are a Microsoft help
technology that is only supported in the
Microsoft Winhelp (HLP) and HTML Help
(CHM) formats. A-keywords are irrelevant
in all other output formats, including
Webhelp.

How to make an automated See Also list with A-keywords

This method creates links that display a list of related topics. It works in both HTML Help
and the obsolete Winhelp format. It will not work an any other output format.
Step 1: Enter the A-keywords
1. Select a topic and display its tab.
2. Enter one or more keywords in the A-Keywords: section, one keyword per line. Note
that sub-keywords are not supported with A-keywords!
3. Repeat for all topics you want to "associate" with one another, adding the same A-
keyword to each topic.
Step 2: Create the link
The link that displays the list of See also: topics is created using the Winhelp ALink
macro. The syntax of this macro is much simpler than its HTML Help equivalent and so
Help & Manual automatically translates it when you output to HTML Help.
1. Select Insert > Link in Write > Insert to create a hyperlink.
2. Select the Script/Macro option in the Insert Hyperlink dialog, then select Winhelp
macro as the type of hyperlink.
3. Enter Alink() in the Script: field and type the keywords you want to link to between the
parentheses. If you enter more than one keyword separate them with semicolon (;)
characters, like this:

This example will create a link that displays a list of all topics that contain the A-keywords
"troubleshooting" or "solutions".
Note that when you are working in HTML Help you can only enter keywords as the
argument for the Winhelp macro. You cannot enter the other parameters for the Winhelp
A-Link macro because they are not translated into HTML Help code!

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 283

How to link between help modules with A-keywords

Use this method to create links between the help files of modular help systems if there is
a possibility that the help files containing the target topics may not be present when the
help is viewed. This can happen when you use runtime merging and choose not to
include one or more of the help files in your distribution. It can also happen if you are
using conditional output to exclude modules from publish-time merged HTML Help and
Winhelp projects.
This technique works both in HTML Help and the obsolete Winhelp forma but not in any
other formats. Please study Working with Modular Help Systems 446 before trying to use
this method!
Step 1: Prepare the alternative topic in the master project
The alternative topic should be in the master project because this is the only help file that
is always present in a runtime-merged modular help system.
1. Open the master help project and choose or create the alternative topic that you want
the user to be able to view when the other help file module containing the target topic
is not available.
2. Select this alternative topic, select the tab and enter a unique A-keyword in the A-
Keywords: field. The A-Keyword must be unique it should not be used anywhere
else in your projects! If it is, all the topics where it is used will be displayed when the A-
Link hyperlink is clicked.
Step 2: Prepare the target topic in the child project
1. Open the child project and select the topic you want to link to.
2. Select the tab and enter the same unique A-keyword as above in the A-Keywords:
field.
Step 3: Create the link
1. Open the project module in which you want to create the link. This can be a master
module or another child module.
2. Select Insert > Link in Write > Insert to create a hyperlink.
3. Select the Script/Macro option in the Insert Hyperlink dialog, then select Winhelp
macro as the type of hyperlink.
4. Enter Alink() in the Script: field and type the keyword between the parentheses. If your
keyword is "about widgets" the dialog would look like this:

If the target help file is not present when the user clicks on the link the alternative topic
will be displayed automatically. If the target topic is present a dialog will be displayed in

© 1997 - 2009 by EC Software, all rights reserved

 284 Help & Manual 5 - User Help

which the user can select either the target topic or the alternative topic.
This is just a very simple example to show you how this solution works in principle. In
practice you can also make more complex solutions, using more alternative topics and
more keywords. If you use multiple keywords remember to separate them with
semicolons, like this:
Alink(about widgets;troubleshooting;widget solutions)
Note that when you are working in HTML Help you can only enter keywords as the
argument for the Winhelp macro. You cannot enter the other parameters for the Winhelp
A-Link macro because they are not translated into HTML Help code!

See also:
About A-Keywords 806 (Reference)
4.12.6 Index section header separators
When Help & Manual generates keyword indexes in Webhelp and PDF, it automatically
adds section headers corresponding to the letter of the alphabet. The keywords are then
organized beneath the section headers by letter, which makes them easier for the user to
find quickly:

Example of index section headers in Webhelp

You can edit the index section header separators if necessary, for example to add letters for
non-English languages.

© 1997 - 2009 by EC Software, all rights reserved

 Basic Working Procedures 285

How to edit the separators for Webhelp and PDF

1. Locate the separators setting for Webhelp or PDF:
Webhelp:
In the Project Explorer go to Configuration > Publishing Options > Webhelp >
Keyword Index.
PDF:
Open the print manual template 330 for your project in the Print Manual Designer and
select the Keyword Index section. Then select File > Page Options and choose the
Keyword Index Section tab.
2. Then edit the list of separators for your own requirements. For example, for German
you would enter:
A,Ä,B,C,D,E,F,G,H,I,J,K,L,M,N,O,Ö,P,Q,R,S,T,U,Ü,V,W,X,Y,Z
Note that you don't need to enter separators for non-alphabetic characters like "#" and
".". If there are keywords starting with characters like these the section headers for
them will be generated automatically and placed at the top of the list.

Adding "letter links" to the separators for Webhelp

It is practical to have "letter links" at top of the index that take you down to the
corresponding letter in the index when you click on them:

The "letter links" in the Index

You can create links like these for your own help by adding some code to the HTML
template for the Webhelp index. You need some experience with editing HTML manually
to do this.
1. In the Project Explorer go to Configuration > Publishing Options > Webhelp >
Keyword Index and select the HTML Source Code tab.

© 1997 - 2009 by EC Software, all rights reserved

286 Help & Manual 5 - User Help

2. Locate the <%KEYWORD_INDEX%> variable. This variable inserts the content of your
keyword index, so you want to insert your link list directly above it.
3. Insert one or two <br /> line break codes to create some space, then insert one link
for each letter in your link list, using the following syntax:
<a href="#A">A</a>
If you want links to keywords beginning with non-alphabetic characters you must also
enter lines for them yourself. The result will look something like this:

...
<a href="<%HREF_CONTENT_PAGE%>">Contents</a>
<IF_INDEX_PAGE> | <b>Index</b></IF_INDEX_PAGE>
<IF_SEARCH_PAGE> | <a href="<%HREF_SEARCH_PAGE%>">Search</
a></IF_SEARCH_PAGE>
</p><hr size="1" />
<br><a href="#A">A</a>
<a href="#B">B</a>
<a href="#C">C</a>
<a href="#D">D</a>
...
<a href="#X">X</a>
<a href="#Y">Y</a>
<a href="#Z">Z</a>
<!-- Placeholder for the keyword index - this variable is
REQUIRED! -->
<%KEYWORD_INDEX%>
...

See also:
Using HTML templates 430
About HTML templates 810

© 1997 - 2009 by EC Software, all rights reserved

Part

V
 288 Help & Manual 5 - User Help

5 Publishing
In Help & Manual you edit your text as you would in a word processor, but that is where the
similarity ends. After creating your texts you need to turn them into finished documents in
one of the supported output formats. We refer to this process as "publishing". This process
used to be called "compiling" but since Help & Manual now supports so many different
output formats we have decided to use a less technical term.
When you publish your output Help & Manual converts your project into your chosen output
format, for example a PDF document, a website (Webhelp), a Microsoft help file (HTML Help
or Winhelp) and so on. In some formats this is done directly, in others with the help of an
additional program like one of the Microsoft help compilers.

5.1 Testing Your Project

Testing your help project is just as important as testing your application. You should publish
your project 311 regularly, view the output, test its interaction with your application 369 and also
use Help & Manual's tools and features for checking your project for help bugs.
In addition to invalid macros and scripts 223 (which you are responsible for checking yourself)
help bugs can include dead and inappropriate links, missing graphics and inappropriate
index keywords.

5.1.1 Tools for finding help bugs

Help & Manual includes a number of tools and features that help you to find "help bugs" in
your project:
Project reports
The Report Tool 289 gives you a comprehensive overview of the current state of your
project, allowing you to check topics, links, graphics and other elements.
Testing links and missing graphics
You can test links 289 directly in the Help & Manual editor. Dead and invalid links are
highlighted automatically in the editor. Missing graphics are immediately visible,
highlighted as a big red X.
Searching for topics and referrers
There are a number of different ways to search for topics and referrers 290 by text, topic
IDs and help context numbers. Referrers are other topics that refer to the current topic,
and checking them can sometimes be useful.
Checking keywords
The Index Tool 275 is very useful for checking and managing the keywords in your project.
Among other things, it enables you to immediately see and eliminate duplicate keywords
with variant spellings and formats.

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 289

5.1.2 Using the Report Tool

The Project Reports tool can generate reports with varying degrees of detail on your entire
project, chapters or even individual topics. You can also generate reports on topics modified
between specific dates, topics associated with specific help window types 121 and topics with
a specified status 209 . For details see The Report Tool 534 .

Information you can get with the Report Tool

· Topic details of all topics, including titles, topic IDs, help context numbers, inclusion
options and date edited
· Keywords in all topics, listed by topic
· All hyperlinks, both to and from topics, listed by topic
· All topic anchors, listed by topic, including anchor keywords and context numbers
· All images used, listed by topic
· Unused images found in the project's image folders
· Detailed project statistics, including the number of topics with topic type, number of
keywords with keyword type, number of links and hotspots with types (including scripts
and macros) and the number of images with names and list of where they are
referenced.

See also:
The Report Tool 534
5.1.3 Testing links and missing graphics
All links and graphics inserted in your projects incorporate dynamic validity checking
features. Dead links are automatically highlighted in red and a popup explanation is
displayed when you position the mouse over them if the mouseover hints feature is enabled
in View > Program Options > General. Missing images are clearly indicated by a square
graphic with a red X in the middle.

How to test links in the editor

· Hold down Ctrl and click on the link to visit the topic to which the link points.
· In addition to topic links you can also use this feature to test Internet links and file links.

· Use the Back button in the Quick Access Toolbar and the History button between
the Back and Next buttons to return to the topic you were editing before testing
the link.

© 1997 - 2009 by EC Software, all rights reserved

 290 Help & Manual 5 - User Help

Dead links and graphics in the editor

Dead links and missing graphics are clearly identified in the editor, you can't miss them.
Dead links are highlighted in red, missing graphics files are shown as a square with a big
red X in the middle. Note that the mouseover popup information for dead links is only
displayed if this feature is activated in View > Program Options > General.

Locating dead links and graphics with the Report Tool

You can generate a full list of dead links and missing graphics in all or part of your project
with the Report Tool 534 , which is accessed in Project > Tools .

See also:
The Report Tool 534
5.1.4 Searching for topics and referrers
When you are testing your project you will often want to find topics and check links to and
from your topics. Help & Manual includes several tools that make this a quick and easy
process. In addition to the search functions described here you can also use the Report Tool
534 to generate detailed reports on your project with full lists of topics, links, graphics and

other details.
The functions for finding and replacing text in Help & Manual are very similar to the
comparable functions in word processors, with some additional options for the special
requirements of help projects.
In addition to this the program also has powerful functions for locating individual topics by
their topic IDs and their context numbers, and for locating "referrers", i.e. topics containing
links to the current topic or topics.

Productivity Tip
The Search function is also available in the
XML Source editor tab (Professional
version only) all HTML editor windows for
HTML templates and other editing
windows. Just right-click in these editor
windows to access.

How to find and replace text

1. Select Write > Editing > Find & Replace… or press Ctrl+F.
2. Enter your search text and choose your options. These are self-explanatory and are
very similar to all search and replace functions in all modern word processors.
Find where:
Topic Keywords searches for index keywords you have associated with your topics.

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 291

Image File Nameschanges the filenames of graphics file references in your projects so
that they refer to files with different names. See below for details.
Captions searches in TOC captions (the Topic Title field in the tab). Note that replacing
this text does not change the name of the topic in the TOC or the header in the header
box above the editor. Instead, it "uncouples" the topic title attribute from the other two
texts, giving it a different value.
Table of Contents searches in the TOC in the Project Explorer (search only, no replace).

How to find and replace images

Images are referenced with their filenames only so you can "replace" them with other
images by replacing their filenames in your topics. Help & Manual finds the image files by
searching through all the folders in your Project Search Path 249 so if the filename you use
is in one of those folders Help & Manual will be able to find it.
1. Select Write > Editing > Find & Replace… or press Ctrl+F.
2. Select Image File Names in the Find Where section.
3. Enter the exact name of the image file as the search and replacement texts, including
the file extension, for example: main_screen.bmp.
4. Choose your other options. These are self-explanatory and are very similar to all
search and replace functions in all modern word processors.

How to find topics by ID or context number

1. Select Project > Manage Topics > Find > Find Topic
2. Select Topic ID or Help Context Number.

Find topics that link to the current topic

You can find links to the current topic with the Find Referrers function, which also shows
which topics the current topics links to.
Links to and from the current topic:
· Select Topics > Manage Topics > Find > Find Referrers
OR
· Right-click on a topic in the TOC and select Find Referrers in the context menu.
Selecting Find Referrers for a chapter in the TOC will display the referrers for all the
topics in the chapter. You can also use this function for multiple topics. Just select two or
more topics in the TOC before selecting the function. Note that this function will only find
links to the current topic or topics in the current project! You cannot use this function to
locate links to the topic in other projects or help files.
Finding links in all topics:
· Select Project > Tools > Report Tool and select either Long Report or Full Report

© 1997 - 2009 by EC Software, all rights reserved

 292 Help & Manual 5 - User Help

mode.
The report will include lists of all outgoing and ingoing links in all topics in your project.

See also:
Find & Replace 602 (Reference)
Find Referrers 586 (Reference)
The Project Reports Tool 534
5.1.5 Testing keywords
The Index Tool provides a preview of your finished index and it is also fully editable, allowing
you to edit and correct keywords in all the topics where they occur at the same time.
The Find and Replace Text function in Write > Editing also works on keywords. You can
locate and replace keywords in your entire project in a just a few seconds.

See also:
Keywords and Indexes 273
Editing the index directly 275
Searching for text, topics and referrers 141

5.2 Configuring Your Output

When your project is finished you will want to output it to one of the output formats 725
supported by Help & Manual. You can generate all these formats from the same project
without any changes to your content, with the exception of a few formatting features 740 that
are not supported by the obsolete Winhelp format.

Configurable publishing options

The layout of the content of your topic pages is controlled by what you enter in the editor
but there are many other aspects of your output that you can configure individually for
different output formats. These options are configured with settings in the Configuration
652 section of your project in the Project Explorer.

The topics in this chapter provide an introduction to configuring the options for each
format with references to documentation of the individual settings available for each
format.
See Help Formats 725 for more information on the individual output formats.

See also:
Project Configuration Settings 652
Help Formats 725
5.2.1 Help Windows
In Microsoft HTML Help and the obsolete Microsoft Winhelp format the appearance and
functions of the help viewer are controlled by the help window definitions in Configuration
> Common Properties > Help Windows in the Project Explorer.
For details on the individual settings see Help Windows 660 in the Project Configuration
chapter. For more information on help windows and what they are for see Help Windows 807

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 293

in the Reference section.

Help windows no longer generally define colors and HTML templates

Background colors of topics and headers
As of Help & Manual 5 the background colors of topics and headers are no longer set in
the help window settings except in Winhelp, where they are actually an integral part of the
help window definition.
In all formats except Winhelp the topic and header background colors are now set in the
definition of the Default HTML page template in Configuration > HTML Page
Templates > Default.

HTML page templates:

The HTML templates for your topic pages are now completely separate from your help
window definitions. The standard HTML template is called Default, not Main, and creating
a new help window does not create a new HTML page template.
HTML page templates are now created and edited separately in Configuration > HTML
Page Templates the Project Explorer.

What the help window definitions define

· In HTML Help and the obsolete Winhelp format the help window settings define the
appearance and functions of the help viewer, including the controls displayed in the
viewer, the text displayed in the viewer title bar and how secondary and external
windows 429 are handled in HTML Help.
· In HTML Help and the obsolete Winhelp format the help window settings also define
the initial size and position of the help viewer and secondary windows displayed as
external windows (if you are using them).
· In Winhelp, and only in Winhelp, the help window settings also control the background
colors of topics and topic headers.

Default and user-defined help windows

By default only one default help window type called Main is defined. This is the standard
window type used for all topics. The settings for Main control the appearance and
behavior of the main help viewer in Winhelp and HTML Help.
Windows other than Main are only used to open topics in external windows 429 when you
link to them. This is done by specifying the secondary window type in the Window: field in
the Insert Hyperlink dialog.

See also:
Using help windows 121
Templates and Secondary Windows 416
Help Windows 660 (Project Configuration)
Help Windows 807 (Reference)

© 1997 - 2009 by EC Software, all rights reserved

 294 Help & Manual 5 - User Help

5.2.2 HTML Help

The appearance and functionality of HTML Help output is controlled by the settings in three
Project Configuration sections:
· Configuration > Common Properties > Help Windows
· Configuration > Publishing Options > HTML Help
· Configuration > HTML Page Templates

Settings in the Help Windows section

In addition to the settings in the HTML Help section the configuration and appearance of
your HTML Help output is also controlled by the settings in Configuration > Common
Properties > Help Windows. In particular, the HTML Help Options 661 tab configures
the features of the Microsoft help viewer used to display your HTML Help CHM file.
See Configuring Your Output - Help Windows 292 for some more information on this
subject.

Settings in the HTML Help section

The settings in Configuration > Publishing Options > HTML Help directly control
the appearance and functionality of your HTML Help output. The notes below explain
what the sections are for, which settings you need to check and where you can find more
information.
The most important section is HTML Export Options 671 you should always check the
settings in this section before compiling a new project for the first time.
See Publishing Options - HTML Help 667 for full details of all the individual settings.
Popup Topics:
The options in this section control how popup topics 125 are handled and exported in
HTML Help. These settings are important if you are using popups because the modes are
very different and they all have different advantages and disadvantages. For example, if
you use JavaScript popups you will have to create a separate project for field-level
popups called from your application.
For information on creating and using popup topics see Creating popup topics 125 and
Using JavaScript popups 129 in the Creating and Editing Topics chapter and Using
Context-Sensitive Help 369 in the More Advanced Procedures section.
Extended .HHP Settings:
Additional settings for the HHP file:
This section is for advanced users who have experience with the manual configuration
of HTML Help projects. If you are just getting started with Help & Manual you don't
need to worry about it at all. It enables you to add and modify settings in the HHP
project configuration file that is fed to the Microsoft HTML Help compiler together with
all the other project files.

Window styles of the table of contents:

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 295

These additional options adjust the appearance and behavior of the TOC in the
Microsoft HTML Help viewer:
Display plus/minus icons:
Activates or deactivates the +/- icons displayed to the left of closed/open chapter icons
("books") in the HTML Help viewer's TOC.
Draw lines between items:
When this is activated fine dotted lines are displayed between related items in the
TOC, making it easier see which topic belongs to which chapter in complex TOCs.
Track selection (mouseover effect):
When this is activated an underline is displayed below topic entries in the TOC when
the user moves the mouse over them. This makes it easier to be sure which topic you
are going to click on.
Only expand a single heading:
When the user selects a new chapter any other chapters on the same level in the TOC
that are open will be closed automatically. This is useful for complex help documents
with lots of chapters, because it is easier to navigate in the TOC if you do not have
multiple chapters open.

If this is a child file merged at run time:

This setting specifies what happens when the user opens the compiled help file directly
if it is part of a modular help system. See Working with Modular Help Systems 446 for
more information on this subject.

HTML Export Options:

This section contains some of the most important options for your HTML Help output.
They control how your project is converted to HTML code and you should always check
them before compiling a new project for the first time. Changes made here can cause
radical differences in the behavior and appearance of your HTML Help output.
For full details on all the settings in this section see HTML Export Options 671 in the HTML
Help section of the Project Configuration chapter.
This is a shared section! The options in HTML Export Options are used for all HTML-
based output formats (HTML Help, Webhelp, Windows Exe and ePub eBooks and Visual
Studio Help / MS Help 2.0). The settings of these options are the same for all these
formats. You cannot enter different settings for the individual output formats.

Settings in the HTML Page Templates section

This section provides access to the HTML templates used in all HTML-based output
formats. These templates define the layout of the HTML pages into which the text from
your topics is inserted.
Editing HTML templates directly requires experience with editing HTML code. If you are
just getting started with Help & Manual it is recommended that you only use the Simple
Template Layout tab. This allows you to use the default template while you are getting
used to using the program.
For full details on all the settings in this section see Topic Pages 666 in the HTML Help

© 1997 - 2009 by EC Software, all rights reserved

 296 Help & Manual 5 - User Help

section of the Project Configuration chapter.

For information on using and editing HTML templates see the Templates and Secondary
Windows 416 and Using HTML Templates 430 chapters in the Reference section.

See also:
Project Configuration - HTML Help 667
Output Formats - HTML Help 727
5.2.3 Webhelp
The appearance and functionality of Webhelp output is controlled by the options in two
sections in your Project Configuration:
· Configuration > Publishing Options > Webhelp
· Configuration > HTML Page Templates

Different appearance in different browsers

It is unavoidable that your Webhelp output will look slightly different depending on the
browser used to view it. HTML Help, Winhelp and Visual Studio Help / Help 2.0 are
controlled Microsoft outputs that use Microsoft help viewers to display them, and your
output in these formats will always closely resemble your source in the Help & Manual
editor.
This is not possible in Webhelp. The HTML code generated is the best possible
compromise between the many quirks of all the browsers now in use and compliance with
the W3C specifications for XHTML 1.1, HTML 4.01 and CSS1.
Unfortunately, no browser is really compliant with all the standards. In addition to this,
individual browsers often interpret the same rules and formatting tags differently.

Settings in the Webhelp section

The most important sections are Layout, Navigation and HTML Export Options.
Always at least check the settings in these sections before compiling a new project.
The Layout section:
The options in this section control the layout of your Webhelp.
No Frames, No Scripts:
This option is only for users who want to manage all their help topic files themselves. It
does not create an integrated help system. The TOC file and all the topic files are
separate HTML files.
Two Frames:
This is the default. It creates a standard help system with the same layout and
navigation as HTML Help.
Three Frames:
This is for integration in your own website. It adds a top frame in which you can insert
the header of your website or any other web page. When you choose a 3-frame layout

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 297

you can either load an existing page into the top frame or edit the code for the top
frame directly in the Layout section. If you load an external page you are responsible
for making sure that it is available at runtime. If you want to store it in the same
directory as your help you must copy it to the correct directory on your server, along
with any graphics files and other files that it uses.

The Navigation section:

The options in this section control how Help & Manual generates the navigation for
your Webhelp. Most of the options should be self-explanatory. For full details see
Navigation 676 in the Project Configuration chapter.
If you want a Keyword Index and Full-text Search tabs in your Webhelp you must
activate these features here!

The Table of Contents, Keyword Index and Full Text Search sections:
These sections configure the Contents, Index and Search tabs of your Webhelp output.
In addition to this you can also edit the HTML templates that are used for generating
these tabs. Editing HTML templates directly requires experience with editing HTML
code. If you are just getting started with Help & Manual it is recommended that you
only use the default settings in the Simple Template Layout tab.
Note that the Full-text Search feature for Webhelp is only available in the Professional
version of Help & Manual.
For full details on all the settings in these sections see Webhelp 674 in the Project
Properties chapter. For full details on using and editing HTML templates see Using
HTML Templates 430 and Templates and Secondary Windows 416 . See Publishing 313 for
an important note on compiling Webhelp with full-text search.

The Popup Topics section:

The options in this section control how popup topics 125 are handled and exported in
Webhelp.
For full details on all the settings in this section see Popup Topics 682 in the Webhelp
section of the Project Configuration chapter.
For information on creating and using popup topics see Creating popup topics 125 and
Using JavaScript popups 129 in the Creating and Editing Topics chapter and Using
Context-Sensitive Help 369 in the More Advanced Procedures section.

The HTML Export Options section:

This section contains some of the most important options for your Webhelp output.
They control how your project is converted to HTML code and you should always check
them before compiling a new project for the first time. Changes made here can cause
radical differences in the behavior and appearance of your HTML Help output.
For full details on all the settings in this section see HTML Export Options 671 in the
HTML Help section of the Project Configuration chapter.
This is a shared section! The options in HTML Export Options are used for all HTML-
based output formats (HTML Help, Webhelp, Windows Exe and ePub eBooks and
Visual Studio Help / MS Help 2.0). The settings of these options are the same for all

© 1997 - 2009 by EC Software, all rights reserved

 298 Help & Manual 5 - User Help

these formats. You cannot enter different settings for the individual output formats.

Settings in the HTML Page Templates section

This section provides access to the HTML templates used in all HTML-based output
formats. These templates define the layout of the HTML pages into which the text from
your topics is inserted.
Editing HTML templates directly requires experience with editing HTML code. If you are
just getting started with Help & Manual it is recommended that you only use the Simple
Template Layout tab. This allows you to use the default template while you are getting
used to using the program.
For full details on all the settings in this section see Topic Pages 666 in the HTML Help
section of the Project Configuration chapter.
For information on using and editing HTML templates see the Templates and Secondary
Windows 416 and Using HTML Templates 430 chapters in the Reference section.

See also:
Project Properties - Webhelp 674
Output Formats - Webhelp 730
5.2.3.1 Layout

The options in this section define the layout of your Webhelp. You can use a standard two-
pane layout that directly emulates the HTML Help viewer, a three-pane layout that allows
you to integrate your own website's header page in the top frame or a "no frames, no
scripts" option for manual integration.

Choosing your layout mode

There are three different layout modes to choose from. In addition to the no-frame and 2-
frame modes that are exactly the same as Simple and Dynamic layout options in earlier
versions, you can now also create a 3-frame mode for better integration in your own
websites.
No frames, no scripts: Choose for fully manual website integration
This completely turns off the dynamic TOC and outputs your help as
simple HTML pages without frames, without any scripting and with a
single separate TOC page containing all the links to your individual
topics.
Only choose this layout option if you want to integrate your individual
HTML pages in your website yourself manually after generating it. The
output generated with the Two frames and Three frames options will
also work with older browsers and browsers with JavaScript support
turned off – the dynamic features will simply be disabled automatically.

Two frames: Default, choose for stand-alone help

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 299

Two frames is the default layout. It creates a stand-alone help project

that is effectively a website in its own right. It is not integrated in
another web page. Navigation is dynamic with an expanding and
collapsing contents tree if the user's browser supports it and static if it
doesn't.

Three frames: Choose for integration in an existing website

This is the same as two frames but with an additional frame above for
integration in your website – you can use the top frame to insert your
standard website header components. Navigation is dynamic with an
expanding and collapsing contents tree if the user's browser supports
it and static if it doesn't.
You can edit the code for the top frame directly in the dialog or provide
a reference to your own external HTML file that you want to load into
the top frame.

Content of the head frame in 3-frame mode

When you choose 3-frame mode you have two options for inserting your own top frame:
You can either insert a reference to an existing web page that you want to load into the
top frame or you can enter the HTML code for the top frame directly in the Layout dialog.
Inserting a reference to an existing web page:
Choose the option Head frame loads external file: and enter the name of the
HTML file you want to load into the top frame.
Ø Help & Manual does not copy this file for you! You must make sure that the file and
all the files it references (graphics etc.) are copied to the correct location on your
server.
Ø The HTML file does not have to be stored in the same directory as your help. If it is
located somewhere else you must include the correct relative or absolute path to the
HTML file in the dialog together with the filename.

Entering your own code in the Layout dialog:

Select the Edit HTML Code tab and edit the code manually in the editor box that
activates when you choose this option. You should have experience with manual HTML
code editing to do this!
Ø When you use this option the head frame HTML file is generated automatically and
copied to your output folder together with the rest of your help.
Ø You can reference graphics files and other external files in your code in the same
way as you would in the other HTML template files. See Using HTML Templates 430
for details.

Special variables for the layout template

There are three special variables that you can use in the Layout page's HTML
template. See HTML template variables 782 for details.

© 1997 - 2009 by EC Software, all rights reserved

 300 Help & Manual 5 - User Help

See also:
Layout 674 (Reference)
HTML template variables 782 (Reference)
Using HTML Templates 430
Templates and Secondary Windows 416
5.2.3.2 Full Text Search tricks

There are a couple of manual settings and switches you can use to change the way that full-
text search works in Webhelp. These aren't absolutely essential but they can be useful for
advanced users to fine-tune search performance.
For full details on all the standard search configuration settings please refer to Full Text
Search 680 in the Project Properties section.

Excluding topics and files from the search index:

HTML files with names beginning with an underscore (_myfile.htm) are not indexed for
searching. You can use this knowledge to exclude both topics and other files from your
Browser Help search index (i.e. files not generated by Help & Manual).
· To exclude topics from the search: Add an underscore to the beginning of the topic's
topic ID in the tab. For example, to include a topic with the ID Introduction from the
search change the ID to _Introduction. (Note that you will then also have to change the
addresses of any existing calls to your topic from your application!)
· To exclude additional files from the search: Just add an underscore to the
beginning of the file name. For example, change myfile.html to _myfile.html.

Excluding page components from the search index:

Out of the box the full-text search feature in Webhelp indexes everything in the page,
including all the text in the header. When the user executes a search the header text gets
displayed at the beginning of the "excerpt" for each topic displayed in the list of search
results.
You can change this with two switches that turn indexing on and off in your HTML
templates. These can be used to exclude the both the header itself and the header
information from the index, which means that the excerpts will begin with the actual text
of your topics. Here's how to do it:
1. Go to Project > Project Properties > Webhelp > Topic Pages.
2. Select "Let me edit HTML code directly" and select the Main template. (You
must repeat this for the other templates if you have created any other custom
templates.)
3. Enter <!--ZOOMSTOP--> on a single line of its own directly before the beginning of the
header code, (directly before the <IF_TOPIC_HEADER> switch), like this:
<!--ZOOMSTOP-->
<IF_TOPIC_HEADER>

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 301

4. Enter <!--ZOOMRESTART--> on a single line of its own directly before the <%
TOPIC_TEXT%> variable, like this:
<!--ZOOMRESTART-->
<%TOPIC_TEXT%>
That's it. When you recompile everything in the header will be excluded from the index
and the excerpts. You can also exclude parts of individual topics from the search index.
To do this just use the Insert - HTML Code function to insert the stop and start switches
before and after the text you want to exclude.

See also:
The Search template for Browser Help 438 (Using HTML Templates)
Full Text Search 680 (Configuration Options)
5.2.4 Adobe PDF and printed manuals
The appearance and functionality of Adobe PDF output is controlled by the settings and
tools in the following locations:
· Project > Tools > Manual Designer (for editing Print Manual Templates)
· Configuration > Publishing Options > Adobe PDF
· View > Program Options > PDF Export

Settings for printed manuals

Manuals printed with Print Manual in the Application Menu are also generated with Adobe
PDF. However, the configuration options in the Configuration section of the Project
Explorer do not apply here. Printed manuals are configured entirely with Print Manual
Templates (see below) and the settings in the Print Manual dialog.
For more information see PDF and Printed Manuals 325 .

The Print Manual Designer

The appearance and layout of your PDF output is controlled by template files with the
extension .mnl called Print Manual Templates. These templates are edited with an editor
called the Print Manual Designer 537 , which is included with Help & Manual.
Print manual templates control much more than the appearance of your PDF page. They
can also be used to add cover pages, introductions, a keyword index and many other
features.
· To attach a print manual template to your project for PDF output go to Configuration
> Publishing Options > Adobe PDF > PDF Layout and select a template in the
Print Manual Template: field. You can then open the selected template directly for
editing by clicking on the Design button.
· The print manual template for printed manuals is selected directly in the dialog
displayed when you select Print Manual in the Application menu.
· For details see Print Manual Designer 537 and the separate help and documentation of

© 1997 - 2009 by EC Software, all rights reserved

 302 Help & Manual 5 - User Help

the Print Manual Designer program.

Settings in the Adobe PDF section

The three groups of options in Project > Project Properties > Adobe PDF 690 control
the basic functionality of your Adobe PDF output.
PDF Layout:
These options are critical for PDF output and should always be checked before
generating PDF from your project for the first time. This is where you select the print
manual template file that defines the entire appearance and content of your PDF
document. The Output Style setting specifies whether you want to create an interactive
PDF for on-screen viewing or a document-style PDF for printing.
See PDF Layout 690 and PDF and Printed Manuals 325 for details.
PDF Options:
These options 691 are not quite so crucial but they can make a big difference to how your
PDF document functions. They should always be checked before publishing a PDF or
distributing it to your users.
See PDF Options 691 for details.
Font Embedding:
The options in this section can significantly effect the size of your PDF output file, and
whether your users see your files with the same fonts that you chose when you produced
the document.
See Font Embedding 692 for details.

Printer driver for generating Adobe PDF

Help & Manual uses a printer driver to generate PDF documents. This will normally be
your screen device or your default printer. If your PDF output is OK you don't need to
change this but if you experience problems you may need to install an additional standard
printer driver for PDF conversion.
See Customize - PDF Export 650 for details.

See also:
Output Formats - Adobe PDF 737
Customize - PDF Export 650
The Print Manual Designer 537
5.2.5 Visual Studio Help
Visual Studio Help is also known as MS Help 2.0. Originally this help format was intended to
be the successor to HTML Help. However, Microsoft then postponed its release indefinitely
and it is now clear that it is never going to be released as a help format for normal user
applications.
Please note that this is a special help format that is only used for documenting third-party

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 303

programming components designed for integration into Visual Studio .NET. It is not suitable
for any other purpose and cannot be used for normal help projects for application programs!

About configuring Visual Studio Help output:

MS Help 2.0 is only relevant for programmers designing programming components for
Visual Studio .NET. If this does not apply to you please don't worry about this help
format. It cannot be used for any other purpose.
Please refer to the special Visual Studio Help 490 chapter in the More Advanced
Procedures section for details on working with Visual Studio Help in Help & Manual.

See also:
Visual Studio Help 694 (Advanced Procedures)
Visual Studio Help 694 (Configuration Options)
Visual Studio Help 738 (Reference)
5.2.6 Winhelp
The appearance and functionality of Winhelp output is controlled by the settings in two
sections in your Project Configuration:
· Configuration > Common Properties > Help Windows
· Configuration > Publishing Options > Winhelp

Settings in the Help Windows section

In addition to the settings in the Winhelp section the configuration and appearance of
your Winhelp output is also controlled by the settings in the Configuration > Common
Properties > Help Windows section.
See Configuring Your Output - Help Windows 292 for more information.

Settings in the Winhelp section

The settings in Configuration > Publishing Options > Winhelp directly control the
appearance and functionality of your Winhelp output. The notes below explain what the
sections are for, which settings you need to check and where you can find more
information.
Miscellaneous settings:
These options include settings for configuring Winhelp's full-text search function and
some other functions of the Winhelp format. The full-text search index is no longer
necessary on modern computers. It is generated automatically almost instantly on the
user's computer and it can be left out if you want to make your help more compact.
The only setting that is really important here is Limit images to 256 colors,which will
prevent the Winhelp viewer from crashing on computers with screen resolutions of less
than 256 colors.
Modular Help Options:
These options control how modular help projects are handled in Winhelp. See Working

© 1997 - 2009 by EC Software, all rights reserved

 304 Help & Manual 5 - User Help

with Modular Help Systems 446 for information on working with modular projects and
modular help systems .
Extended .HPJ Settings:
This section is for advanced users who have experience with the manual configuration of
Winhelp projects. It enables you to add and modify settings in the .HHP project
configuration file that is fed to the Microsoft Winhelp compiler together with all the other
project files.

See also:
Project Configuration - Winhelp 700
Help Formats - Winhelp 740
5.2.7 MS Word RTF
The appearance and layout of your MS Word RTF output is controlled entirely by the options
in the following location:
· Configuration > Publishing Options > MS Word RTF
All other settings are irrelevant for Word RTF output. Also, please note that Word RTF is a
deprecated and rather limited format that is only provided for backward compatibility. Adobe
PDF is always preferable unless you have a specific application for which RTF is an
absolute requirement.

See also:
Project Configuration - Word RTF 705
Output Formats - Word RTF 739
5.2.8 eBooks
Help & Manual supports two eBook formats: Windows Exe eBooks and ePub eBooks.
Windows Exe eBooks 304 are stored in a single .exe file that contains both the eBook and the
viewer. They can be viewed on any Windows computer without additional drivers or
software, all the way from Windows 95 to Windows Vista. To display one of these eBooks
the user just needs to double-click on the eBook file. They cannot be viewed on other
platforms, however.
ePub eBooks 305 are standard, generic and open eBook format that is supported by many
software readers on all computer platforms and harddware devices, including the Sony
Reader and the Apple iPhone (with the free Stanza application). ePub eBooks are cross-
platform and many thousands of eBooks are already available in this format.

See also:
Output Formats - eBooks 735 (information on pros and cons)
Publishing Options - eBooks 706 (project configuration settings)
5.2.8.1 Windows Exe eBooks

The appearance and functionality of Windows eBooks output are controlled by the settings
in the following locations:
· Configuration > Publishing Options > eBooks > Windows: Visual
Appearance

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 305

· Configuration > Publishing Options > eBooks > Windows: Functionality

In addition to this the shared HTML Export Options 684 settings in the Publishing Options
Settings for Webhelp are also used for both Windows Exe and ePub eBooks as well as for
all other HTML-based output formats.

Windows eBook settings in Publishing Options

Click on the Help button in each screen for detailed descriptions of all the settings in
these two screens.
Visual Appearance:
The only really important option here is Viewer template:, which selects the template that
controls the entire appearance of the embedded Windows eBook viewer, including
whether or not it has a Table of Contents pane. These templates are not user-editable
just try them out and see which one you prefer.
Functionality and Style:
These options configure some of the functions of the embedded Windows eBook viewer,
including the language of the user interface and whether the viewer has a keyword index
and a full-text search function. You can also activate some practical security features.

Settings in the HTML Page Templates section

This section provides access to the HTML templates used in all HTML-based output
formats, including both Windows and ePub eBooks. These templates define the layout of
the HTML pages into which the text from your topics is inserted.
Editing HTML templates directly requires experience with editing HTML code. If you are
just getting started with Help & Manual it is recommended that you only use the Simple
Template Layout tab. This allows you to use the default template while you are getting
used to using the program.
For full details on all the settings in this section see Topic Pages 666 in the HTML Help
section of the Project Configuration chapter.
For information on using and editing HTML templates see the Templates and Secondary
Windows 416 and Using HTML Templates 430 chapters in the Reference section.

See also:
Output Formats - eBooks 735
Publishing Options - eBooks 706
5.2.8.2 ePub eBooks

The appearance and functionality of ePub eBook readers are controlled by the hardware or
software readers and cannot be influenced by any settings in your eBook. The only
configuration settings for these eBooks are a required unique identifier (UID) and some
information fields – see below for details. These settings are available in:
· Configuration > Publishing Options > eBooks > ePub Standard: Project
Settings

© 1997 - 2009 by EC Software, all rights reserved

306 Help & Manual 5 - User Help

In addition to this the shared HTML Export Options 684 settings in the Publishing Options
Settings for Webhelp are also used for both Windows Exe and ePub eBooks as well as for
all other HTML-based output formats.

Key Information
ePub is simple to make it as universal as
possible. Avoid complex layouts and
formatting, only use simple tables and
don't use invisible topics. Only a..z, A..Z,
0..9 and _ are permitted in topic IDs in
ePub eBooks!

Install Adobe Digital Editions first!

Before trying to produce ePub eBooks you must download and install the free Adobe
Digital Editions software reader from Adobe. Other software readers may also work, but
only Digital Editions will allow you to test the full functionality.
Your ePub eBooks will not display after publishing unless you install Digital Editions or a
compatible reader!
Adobe Digital Editions download page
If you plan to target other readers and devices you may also want to get those for testing,
of course. See ePub Resources 733 for more information and sources.

Special restrictions and requirements for ePub eBooks

Keep your layout and formatting as simple as possible! ePub eBooks are really designed
to behave like books, not like electronic documents. They are not designed to support
many of the dynamic features you may take for granted in other types of electronic
documents.
Avoid complex formatting and dynamic features
Although ePUB is supposed to fully support XTHML, CSS1 and scripting, most readers
don't, so don't depend on them. Keep everything as simple as possible. Think book, not
website!
Restrictions and requirements for topics
Topics designed for ePub have the following requirements and restrictions:
· Regular text is OK
· Formatted text is OK (all styles are allowed)
· Internal topic links only – no file links or script links
· External HTTP links are supported but they won't work on hardware readers without
web access!
· All image formats supported in H&M can be sued, images are converted according to
your HTML Export options 684 settings
· Simple tables only – no nested tables, no fixed-width tables, no complex tables, no
background images
· Keep your HTML page templates simple – complex and dynamic layouts will often fail

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 307

· No toggles, no JavaScript, no multimedia, no page breaks

· Hotspots in images are not supported by most ePub readers (both hardware and
software)
Restrictions and requirements for the TOC
The TOC in ePUb has the following restrictions and requirements:
· Normal topics entries and chapter entries that are topics (chapters with text) are OK
· Topic entries with anchor references are OK (a TOC entry that links to an anchor in a
topic)
· Chapters without text are OK – the TOC entry will point to the first topic of the
chapter
· No TOC entries that link to external help files or web pages
No special characters in topic IDs
An ePub eBook is a zip archive and can only support 7-bit characters in the internal
filenames. Make sure that your topic IDs only use a..z, A..Z, 0..9 and _, no other
characters. This is also general good practice to avoid possible problems in all project
types.
No invisible topics!
Help & Manual exports invisible topics (topics without TOC entries) as HTML pages,
but the reader software may not display them correctly. Only include topics that actually
have TOC entries, then you can be sure that they will be displayed correctly.

© 1997 - 2009 by EC Software, all rights reserved

308 Help & Manual 5 - User Help

ePub eBook settings in Publishing Options

The only configuration options you need to enter for generating ePub eBooks are an
identifier and a number of standard information fields. The only field that is absolutely
required is the UID, which is the unique identifier for your eBook.
You can use text variables 376 in all these fields! These settings are available in Project
Explorer > Configuration > Publishing Options > eBooks > ePub Standard.
UID (required): Required!
This is the unique identifier of your eBook, so you should attempt to make
it genuinely unique to avoid confusion with other available publications.
You can use any alphanumeric text string here – for example your web
address plus the name of the book. If the book has an official ISBN book
catalog number then use that.
URI: Optional but recommended
A web link, for example to a page with information about the book on your
website. It's a good idea to include this as eBook readers often have
online access. Always include the http:// prefix with the URI, plain www.
addresses may not work!
Subject: Optional but recommended
A short description of your eBook.
Description: Optional, generally helpful
A longer description of your eBook.
Relation: Optional
Relation information for your eBook, this can be an URI (weblink, the new
term for URLs) or other information.
Creator: Optional but recommended
The author of your eBook – if you have entered the author of your project
in your Common Properties you can insert the Tim Green variable here to
use the same text string automatically.
Publisher: Optional but recommended
The publisher (i.e. your company) of the eBook.

Settings in the HTML Page Templates section

This section provides access to the HTML templates used in all HTML-based output
formats, including Windows Exe and ePub eBooks. These templates define the layout of
the HTML pages into which the text from your topics is inserted.
Like topic content, HTML Page Templates for ePub eBooks should be kept as simple as
possible. Complex and dynamic layouts can be expected to fail on at least some readers.
Plan for a book-like reader experience and you will be on the safe side.
Editing HTML templates directly requires experience with editing HTML code. If you are
just getting started with Help & Manual it is recommended that you only use the Simple
Template Layout tab. This allows you to use the default template while you are getting

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 309

used to using the program.

For full details on all the settings in this section see Topic Pages 666 in the HTML Help
section of the Project Configuration chapter.
For information on using and editing HTML templates see the Templates and Secondary
Windows 416 and Using HTML Templates 430 chapters in the Reference section.

Viewing and editing the source files of ePub eBooks

The ePub eBook standard is open, free and fully documented in the OPF specifications
for ePub. Help & Manual produces standard ePub source files that you can also edit and
process manually and with other programs for editing and producing ePub.
Accessing the source files:
When you publish to ePub the source files are automatically written to a new folder in
your project folder called:
~tmpepub
You can edit these files directly with any text editor provided you observe the OPF
specifications for ePub eBooks.
Making an ePub file from the source files:
An ePub eBook is actually a normal zip archive with the extension .epub instead of the
normal .zip extension. After editing your ePub source files you can create a valid ePub
eBook by copying the contents of the ~tmpepub folder to a zip archive and then changing
the extension to .epub.
Important: Make sure that the sub-folders are included in the zip archive! Some zip
programs will store all the files in the zip without internal folders by default.

See also:
Output Formats - ePub eBooks 732
ePub resources 309
5.2.8.3 ePub resources

This page contains a selection of hardware, software and information resources relating to
the ePub format and ePub eBooks. It is not necessarily complete, but it is a good starting-
point.
Important: The reference software reader is Adobe Digital Editions. Before trying to
create ePub eBooks you should download this free reader from Adobe and install
it. If you don't do this you won't be able to view your ePub eBooks after creating
them with Help & Manual.

Hardware devices supporting ePub eBooks

The following hardware readers currently support ePub eBooks, either directly or with
free additional software. The most notably absent device on this list at the moment is the

© 1997 - 2009 by EC Software, all rights reserved

310 Help & Manual 5 - User Help

Amazon Kindle, which still uses its own closed proprietary format – the Kindle can't even
display PDFs without conversion, although a free service is available for this.
The Sony Reader
The Sony Reader was one of the first major hardware eBook readers and it is now a
very mature device with wide support and distribution.
The BeBook Reader
The BeBook reader supports ePub eBooks natively, like the Sony Reader. In addition to
this it also supports a wide variety of other formats and mp3 audio files and audio books.
It is sold under a variety of different names depending on geographical location.
Apple iPhone and iPod Touch
Both these devices from Apple can display ePub eBooks with the free Stanza reader
software available from the Apple App Store that can be accessed in iTunes (see below).
Mobile phones, smartphones, other readers
Many other mobile devices also support ePub eBooks with the free MobiPocket software
(see below).

Software readers for ePub eBooks

Software readers for ePUB e-books are already available on many platforms. The
following list only includes the known software-based readers that support the ePUB
format at the time of writing – others may already be available.
The reference software reader is Adobe Digital Editions, this is the one you should get
for testing.
Adobe Digital Editions (Windows, Apple OS X)
This free program is the reference ePub reader with the best support for ePub and we
strongly recommend that you install it for testing your ePub books. It is currently still the
only reader that fully supports the ePub table of contents.
FB Reader (Windows, Linux, Apple OS X)
Open source reader software, does not yet support the ePub table of contents or
bookmarks.
Openberg (Firefox plugin)
Open source reader software, does yet not support the ePub table of contents or
bookmarks.
MobiPocket (Windows and many mobile devices)
Freeware, support for bookmarks, no support for table of contents yet. The great
advantage of MobiPocket is that it brings eBooks to a wealth of mobile devices, free of
charge.
dotReader (Windows, Linux)
Open source, cross-platform ePub reader, early beta. No support for table of contents.
Stanza (Windows, iPhone, iPod Touch)
Desktop (Windows) and iPhone version available. Supports both bookmarks and the
ePub table of contents. The iPhone/iPod Touch version is available directly from the
Apple App Store, which must be accessed through iTunes.

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 311

Bookworm(any OS with an Internet connection)

Online open source reader, supports the ePub table of contents. Good HTML and CSS
display but requires an active Internet connection.

Online resources for ePub eBooks

International Digital Publishing Forum

This is main home page for ePub and everything relating to the ePub format.

Open Packaging Format specification

Full specifications of the OPF ePub format.

TeleRead blog
An informative and entertaining blog about eBooks.

Jedisaber ePub tutorial

An online tutorial explaining how to make ePub eBooks manually. Useful if you want to
learn about the format and structure of ePubl eBooks.

Feedbooks
Free classics in ePub format.

Snee
Free children's picture books in ePUB format

LexCycle eBook Library

Large library of ePub eBooks maintained by LexCycle, the creators of the Stanza ePUB
reader for Windows and the Apple iPhone and iPod Touch.

See also:
Output Formats - eBooks 735
Publishing Options - eBooks 706

5.3 Publishing Your Projects

To distribute or check your project you need to output it to the help or documentation format
you want to use. This process is known as "compiling". When you compile your project Help
& Manual translates all the information in the database into the selected output format.
This chapter explains how to compile your project to the output formats supported by Help &
Manual.

5.3.1 Microsoft help compilers

The Microsoft help formats HTML Help, the obsolete Winhelp format and MS Help 2.0 are
generated with the help of the standard Microsoft help compilers for these formats. If you do
not have these compilers installed you need to install them before you can publish your
projects to these formats.

© 1997 - 2009 by EC Software, all rights reserved

 312 Help & Manual 5 - User Help

The Winhelp and HTML Help compilers:

The Winhelp and HTML Help compilers are available on the EC Software website at:
http://www.ec-software.com/reshelp.htm
After installing the help compilers go to View > Program Options > Compilers and
make sure that the path to the compiler files are correct. See Program Options -
Compilers 649 for details.

The Visual Studio Help/MS Help 2.0 compiler:

This is not a help format for normal user applications and it cannot be displayed at all on
most users' normal Windows systems. It can only be used for documenting Visual
Studio .NET components, in combination with the Visual Studio .NET programming
package. You will only be able to use this format if you are programming .NET
components with Visual Studio.
The MS Help 2.0 compiler tools can be downloaded from Microsoft with the Visual Studio
Help Integration Kit, which is also known as the VSHIK, but they cannot be used without
the Visual Studio .NET package. You will need to search for the VSHIK on Microsoft's
MSDN site as they frequently change the download location for this kit.

See also:
Customize - Compilers 649
5.3.2 Publication checklist
Before actually distributing your files there are a few things you should check because they
are quite easy to forget:

Title and copyright information:

Have you set the project title, author and copyright information? Settings Here 654

Help window titles:

Have you set the correct titles for your help window title bars? Settings Here 660

Language settings:
Have you set the correct language settings for the language of your project? This is
particularly important if you are using languages requiring special character sets or
Unicode. See International languages setup 94 for details.

Special requirements for ePub eBooks

The ePub eBook format is outstanding for universal distribution across many platforms
and devices but precisely because of this it is also more restrictive than some other
formats. It is designed to be more like a book than an electronic document and it thus has
some special requirements and restrictions.
Before publishing to ePub first visit the Adobe Digital Editions download page and
install the Digital Editions eBook reader. This is essential because without it you will not
be able to view your ePub eBooks after you have created them.

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 313

You will also need to check whether everything in your project is compatible with ePub.
Please also study the information on ePub eBooks in the Configuring Your Output 305 and
Publishing Formats 732 and Configuration Settings 710 chapters before proceeding.

Names of modular projects:

When you are using runtime merging 451 for HLP and CHM files the project filenames and
the output filenames of the HLP or CHM files must be identical. The references between
the child and the master help files are based on the filenames and if project and output
filename don't match the references will be invalid.
If you want to change the name of the output file in the Publish dialog you should also
change the name of the entire project to match, using Save As... in the Application
menu.

Dead links caused by excluded topics

You may have dead links in your project if you have excluded topics from your output
without taking steps to deal with links to the topics that are not present in your output.
You can configure Help & Manual to deal with these dead links automatically in two
different ways, see Program Options - Compilers 649 for details.
These automatic options are useful for a quick fix but it is generally better to use
conditional text tags to exclude the links and replace them with alternative text when
necessary. See Preventing dead links 404 for detailed instructions.

Linked snippets:
Are you using linked snippets (snippets linked to topic files or external files)? If the source
files are in your current project you need to make sure that they will not be included in
your output, otherwise they will be exported too in electronic help formats and the user
will be able to find them with Search.
Select the tab of the each source topic and deselect all the options in Builds which
include this topic. See Re-using content with snippets 149 for details.

Notes and other information you want to exclude:

Does your project contain any author's notes and other "production information" that
users shouldn't see? It's a good idea to use Comments & Bookmarks 143 feature for
information like this to ensure that it isn't included in the output. You can also exclude
information from your output with Conditional Text 410 .

See also:
Configuring Your Output 292
5.3.3 Publishing
Once you have made all your preparations and set your configuration options 292 for the
output format you are using compiling is basically just a question of selecting Publish and
choosing the output format.

© 1997 - 2009 by EC Software, all rights reserved

314 Help & Manual 5 - User Help

How to publish your project

1. Save your project, then select Publish in the Project tab.

2. Select the output format from the list on the left. Some of the options displayed in the
dialog will change depending on the format you choose.
· For details on the options see the reference to the Publish Help Project 590 dialog.
3. Check the Output File: field. In most cases the program will automatically publish to
the project folder, using the project name as the file name. You can change both the
output folder and the file name if you want and Help & Manual will remember this
change next time you publish.
4. Select the output options and click on OK to publish. This can take a couple of minutes
with very large projects.
A report on the publish process including any errors and a list of the files and/or folders
you need to include when you distribute your help 319 to your users is displayed in an
external viewer window. This window contains controls with which you can save the report
to an external HTML file if you want.

Publishing ePub eBooks

Install the free Adobe Digital Editions reader
Before attempting to publish an ePub eBook visit the Adobe Digital Editions download
page install the Digital Editions eBook reader. This is essential because without it you will
not be able to view your ePub eBooks after you have created them.
Check the requirements and restrictions for ePub eBooks
Not all features supported in some other formats are possible in ePub eBooks. Please
study the information on ePub eBooks in the Configuring Your Output 305 and Publishing
Formats 732 and Configuration Settings 710 chapters before proceeding.

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 315

Publishing selected topics only

For test purposes you can publish only the topics that are currently selected in the Table
of Contents pane (TOC). Note that this will result in dead links in topics that contain links
to topics which are not included in your output!
1. Select the topics you want to publish in the TOC pane. You can use Ctrl+Click and
Shift+Click to select multiple topics out of order and sequences of topics. Selecting
chapters automatically selects all the chapters' sub-topics.
2. Select Publish in the Application Menu or the Project tab.

3. Select the output format, then select Selected Topics in the Include Options: box. The
box will be highlighted in yellow to remind you that only selected topics will be included
in your output.
4. Select your other publish options, then click on OK to publish.

© 1997 - 2009 by EC Software, all rights reserved

316 Help & Manual 5 - User Help

Using skins in HTML-based formats

In HTML-based output formats you can apply a completely different layout and
appearance to your published output by choosing a "skin" file in the Publish dialog. Skins
include everything that define the general appearance of your output; your variable
definitions, HTML templates, text and table styles and your Baggage Files.
Help & Manual comes with some sample skins in the \Skins folder in the Help & Manual
program directory. If you have the Professional version of the program you can also save
your own projects as skins to apply their appearance to other projects without additional
formatting.
See Transforming your output with skins 321 for full details.
1. Select Publish in the Application Menu or the Project tab normally.
2. Then select the skin file you want to apply in the Compile with skin: field and click on
OK to publish.

Filtering your output with include options and "Complete" status

You can also filter your output by topic status and with conditional output include options.
For more information see Conditions and Customized Output 399 in the More Advanced
Procedures section and Publish Help File 590 in the Reference section.
Filtering with include options:
With the exception of the Selected Topics option (see above) the Include Options settings
in the Publish dialog are only relevant if you are actually using conditional output to
control which topics and content are included in your published output.
· In the Include Options: section of the Publish dialog select the options matching the
content you want to include in your output.
Only topics and content tagged with matching include options in your project will be
included in your published output. The option for the current output format should always

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 317

be selected.
Filtering by "Complete" status:
This is only relevant if you have actually applied topic status 209 to topics in the TOC. It
allows you to exclude all topics that do not have the status "Complete" from your output,
thus automatically excluding any topics that are unfinished or require review.
Select the option Topic Status: Complete Only below the Include Options box in the
Publish dialog:

Quick-launching your project

The Quick Launch function publishes your output and displays it without displaying the
publish Help File dialog.
This function automatically uses the last publish settings you used with when you
published with the publish dialog. It is thus advisable to publish to the selected format
manually at least once before using Quick Launch.
1. Click on the lower part of the Publish tool in Project > Project to display the Quick
Launch menu:

2. Then just select the output format you want to output to. Your project will be published
and displayed automatically as soon as the publish process is finished.

© 1997 - 2009 by EC Software, all rights reserved

318 Help & Manual 5 - User Help

Points to remember when publishing Webhelp

Compiling Webhelp is almost the same as compiling any other format. However, since
you are actually creating a website consisting of a large number of individual files there
are a couple of additional points you need to bear in mind:
Always publish to an empty folder:
Always publish Webhelp to its own folder, which should preferably be empty. A large
project can consist of several hundred files in this format! (The program will suggest
creating a folder called \HTML inside your project directory, which is a good choice.)
When you publish to Webhelp you can the use the Delete all files in output folder
option to clear the output folder before compiling. You don't need to use this during
normal working but it is a good idea to select it before creating a build that you are
going to publish.
Clearing the output folder makes sure that no files for topics that you have deleted are
included in your output unnecessarily. In addition to taking up space these files will also
be indexed and will appear in the full-text search (see below).
Clearing the output folder is also essential when you change the name of the project,
as this changes the names of a number of important files that are components of your
Webhelp. If you don't clear the folder the old files will remain in place and will be
included in the index.

Timestamps and clearing the output folder:

You don't need to worry about the timestamps of your output HTML files when you
clear the output folder. The the HTML file timestamps are always set to the last time
the topic was edited, not the time when the project was published.

Testing Webhelp locally on Internet Explorer:

Microsoft Internet Explorer now displays a yellow warning bar when you open any
HTML files containing scripting on your local machine. You can disable this warning by
activating the option Enable local testing for MS Internet Explorer in the Publish 590
dialog.
Your Webhelp files will then open normally in Internet Explorer, without the yellow
warning bar. If you plan to deploy your Webhelp for installation on local computers you
can leave this setting activated for your production output if you want.
Important: Note that file links do not work when this option is activated. You should
also deactivate it again before deploying your help on your server as this rather messy
Microsoft "kludge" may have unexpected results when it is used online!

Full-text search issues:

When you are compiling the new Webhelp with full-text search 680 it's important to
understand that the search index is not generated from your project files or from the
files on your server. It is generated from the HTML files on your local computer, after
the HTML files have been generated.
· If the output directory contains any other HTML files these will be included in

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 319

the index.
To prevent this do not place any other files in the output directory. Since the index is
generated locally you can upload other files to your server separately, then they will
not be included in the index.
· Outdated HTML files will be included in the index if you don't delete them.
To ensure that the HTML files of outdated topics are not included in the index use
the Delete all files in output folder option in the Publish dialog to delete the contents
of the output directory before compiling. This will not cause problems with the
timestamps of topic files that have not been changed – the HTML file timestamps are
always set to the last time the topic was edited, not the time when the project was
published.

Test-publishing Asian languages on non-Asian Windows

Normally, you cannot publish help projects written Asian languages on non-Asian
versions of Windows because the necessary language settings don't match. However, if
you just want to do a quick test publish and don't have a Windows version in the
matching Asian language there is a configuration setting that will allow you to do this.
· Go to View > Program Options > Compilers and activate the option Tolerant
handling of Asian languages.
Some features may not work correctly in the resulting help file in Winhelp and HTML Help
if the languages of your Windows version and the help file don't match (Search, Keyword
Index) but you will be able to complete the compilation, which is sufficient for testing.

Publishing Visual Studio Help

Please note that Visual Studio Help (MS Help 2.0) is a special case. Please see the
special Visual Studio Help 694 chapter in the More Advanced Procedures section for
details.
Visual Studio Help is a special help format that is only used for documenting third-party
programming components designed for integration in Visual Studio .NET. It cannot be
used for documenting normal application programs and if you are not a VS.NET system
programmer you don't need to know anything about it!
Support for Visual Studio Help is only available in the Professional version of Help &
Manual.

See also:
Publish Help File 590 (Reference)
Conditions and Customized Output 399
5.3.4 Distribution files
When you compile your output a report is displayed in an external window listing the files
and/or folders that you need to distribute to your users. Here is a summary checklist of the
files you normally need to distribute for each output format supported by Help & Manual:

© 1997 - 2009 by EC Software, all rights reserved

320 Help & Manual 5 - User Help

HTML Help:
HTML Help is compiled to a single CHM file containing everything needed for the fully-
functional help. You will only need to distribute additional files if you are creating a
modular project 446 with multiple help files or if you are accessing additional external files
in your help, for example with file links 220 . If you do access and distribute external files
with HTML Help you must store them in the same directory as the CHM file. Links to
external files with path information will fail on many (but not all) user's computers because
of uncorrected bugs in the Microsoft HTML Help viewer that is an integral part of the
Microsoft Windows operating system.

Classic Winhelp:
The obsolete Winhelp format always consists of two files: An .hlp file containing the
main body of the help and a .cnt file containing the Table of Contents (TOC). If you
forget to include the .cnt file your help will be functional but it will not have a TOC.

Webhelp:
Webhelp is actually a self-contained website. Like any website it consists of a large
number of separate files, including HTML files, graphics files, JavaScript files and other
files all stored in a single folder. If you have a large help project your Webhelp can easily
consist of several hundred files. You must upload the entire output folder including all the
files it contains to your server for Webhelp to work properly! Also, you must upload all the
files to the same directory! Do not make any changes to these files. For example, do not
change the case of file names.
If you are distributing any additional files with your Webhelp you must add them to the
directory manually, or add them to the Baggage Files 485 in the Project Explorer (then they
will be exported automatically).

Adobe PDF:
Adobe PDF output always consists of a single .pdf file.

eBooks:
Windows Exe eBooks consist of a single executable .exe file that contains both the
eBook content and the viewer program needed to display it. This file is completely self-
contained and it is the only file you need to distribute.
ePub eBooks consist of a single file with the .epub extension. This file is actually a zip
archive that contains the XHTML and XML files that make up the ePub eBook.

MS Word RTF:
MS Word RTF is output to a single .rtf file. However, if the file contains images the
graphics files are external and need to be distributed with the .rtf file in the same folder,
otherwise the user will not be able to see them. By default Help & Manual thus outputs
RTF to a separate folder, so that you can transport the .rtf file and the image files
together in the folder.

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 321

Visual Studio Help / MS Help 2.0:

Help 2.0 is normally output to a single, self-contained .hxs file. This is the only file you
need to distribute. However, you can also choose an option to create both an .hxs file
and a separate .hxl file in Configuration > Publishing Options > Visual Studio
Help > Namespace & Options 694 . Please note that this format is not designed for
general help for user applications! Visual Studio Help is only used to document
programming components added to Visual Studio .NET and the compiler can only be
used in combination with the Visual Studio .NET package! This help format is completely
irrelevant for normal help and documentation applications!

See also:
Help Formats 725 (Reference)
5.3.5 Transforming your output with skins
You may already be familiar with the concept of "skins" from other programs: You select a
skin file and the appearance and layout of the entire program is transformed in seconds.
Help & Manual enables you to do this with your HTML-based output. You can save your
entire design in a .hmskin file and then select this file when you publish to apply the layout
to the current project without changing any of the project's own settings.
Please note that you can only save projects as skins if you have the Professional version of
Help & Manual. Standard version users can edit existing skins (for example skins from the
Help & Manual Plus Packs) but they cannot create new skins from their own projects.

Productivity Tip
Skins can only be used for HTML-based
output formats. You can style your PDF
files and printed manuals with print manual
templates 330 , which work in the same way
as skins.

How to use skins - try it now!

1. Open a project of your own, select Publish in the Project tab, then select Webhelp or
HTML Help as the output format.
2. In the Publish dialog 590 click on the Browse button in the Compile with skin: field and
select one of the standard .hmskin files in the Skins folder in the Help & Manual
program directory.

© 1997 - 2009 by EC Software, all rights reserved

322 Help & Manual 5 - User Help

When you publish your output it will have the "look and feel" applied by the skin. You
didn't have to do any design work at all!

How to create a skin file

Skin files contain everything you need to style your HTML-based output: Text and table
styles, user-defined variables, your Baggage files (template graphics and logos), HTML
page templates and all the settings and templates for Webhelp. You can turn any project
into a skin file just by saving it as a skin and you can edit skin files in Help & Manual, just
like normal projects.
1. Open a project with a design that you want to use for other projects.
2. Select Save As... in the Application Menu and choose the Skin XML File option.
3. Choose a place to save the skin, enter a name and save.
4. You will be asked which configuration components of your project you want to include
in your skin. You should normally include all the listed components.
That's all there is to it. You can now compile other projects to HTML-based output
formats with your new skin.

How to edit skin files

Skin files are actually normal single-file projects with some special limitations. You can
open them and edit them like normal projects but you can only edit those components
that are included in the skin, everything else is unavailable.
1. Select Open in the Application Menu and then select Help & Manual skin files (.
hmskin) as the type of file to be opened. (If you don't select this you won't be able to
see the skin files!)
2. Select an .hmskin file to load and edit. You can find some sample skins in the Skins
folder in the Help & Manual program directory.

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 323

3. Now you can edit the settings of your skin. This is exactly the same as editing the
corresponding sections of normal projects to configure your output.
Skins have no topics, you can only edit the relevant sections in the Configuration
and Baggage Files sections in the Project Explorer and the text and table styles in
Write > Styles.

About text and table styles in skin files

Your skin files can include text and table styles. However, for styles to work in skins the
text in the project must use the same style names otherwise Help & Manual cannot
know where to apply the styles.
Basic procedure:
This is just one suggestion to illustrate how skins work, there are many different ways you
could do this you just have to ensure that the style names in all the project files are
identical.
1. Make one or more skin files from a project containing the styles you want to use.
2. Open the skin files and edit the styles for the alternative designs that you want to apply
with the skins.
3. When you create a new project use the original project from step 1 as a project
template 417 then you will start with all the styles you need and you can use your skins
files to redefine the styles when you publish.

Using include conditions to configure features in skins

For advanced users:
You can use include options 441 to turn features in skins on and off. This makes it possible for the
user to choose features in the skin when they publish their projects because include options
stored in skins are loaded into the Include Options: box in the Publish dialog when the skin is
selected.

Key Information
Include options in skins must be defined in
the skin! Include options defined in normal
H&M projects will not be saved in the skin
when you save the project as a skin. You
must edit the skin file and add the include
options you want to use.

For example, suppose you want to give the user the option of having a subtitle underneath the
title in the table of contents in your Webhelp output. It would work like this:
1. Define an include option in the skin, let's say it's called OPT_SUBTITLE, and let's also say that
we've entered TOC header subtitle as the include option description.
2. Add code using the include option to the HTML template for the Webhelp table of contents, for
example (you would also have to define the <%SUBTITLE%> variable in this example, of

© 1997 - 2009 by EC Software, all rights reserved

324 Help & Manual 5 - User Help

course):
<p class="navtitle">Help & Manual 5 - User Help</p>
<IF_OPT_SUBTITLE><p class="nav-subtitle"><%SUBTITLE%></p></IF_OPT_SUBTITLE>
3. When the user loads the skin in the Publish dialog the option [ ] TOC header subtitle will
automatically be loaded from the skin file and displayed in the Include Options: box. The
header will only be displayed if the user selects this option.
You can take this concept as far as you like: For example, you can use the same include option
to change the CSS definitions in the same HTML template so that the formatting will be different
depending on whether the subtitle is included or not.

Including a preview image in a skin

When the user selects a skin in the Publish dialog Help & Manual automatically looks for
a PNG graphic file called $HMSKINPREVIEW.PNG in the skin's Baggage files. If this file is
found a thumbnail version of the preview image is displayed in the Publish dialog. The
user can then click on this image to display a full-size preview.
1. Create your preview image – this will generally be a screenshot of a help file using
your skin – and save it in the PNG format as $HMSKINPREVIEW.PNG.
2. Add the PNG preview file to the Baggage Files section of your skin.
3. Select the PNG file in the Baggage Files section, right-click on it, select Include in
Builds and deactivate all build options for the file. This will prevent the file from being
exported to your published output, where it is not needed.

Using skins to redefine variables and other settings

You don't have to save all your settings in your skin files. For example, it's possible to
create a skin that only defines the user variables in your project you just need to
deselect everything except Variables when you save the skin file. Then you can redefine
your variables in your entire project by selecting the skin file when you publish your
project.
You can do the same with your Baggage files, text and table styles, HTML Page
Templates or any combination.

Applying multiple skins in command lines and batch files

When you publish manually you can only select one skin for the project you are
publishing. However, when you use Help & Manual's command line options you can
specify as many skins as you like one after another.
When you do this the settings in the last skin you specify always have priority for
duplicate settings for example, if you redefine the same variables in two skins the
settings in the second skin are those that will be applied.
See Command Line Options 466 and Skins & redefining variables 478 for more information
on this.

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 325

See also:
The Publish Dialog 590
Command Line Options 466

5.4 PDF and Printed Manuals

In addition to compiling electronic help formats Help & Manual can also generate fully-
formatted user manuals, which can be printed directly or output as Adobe PDF files for
distribution so that users can print their own manuals. Printed manuals are generated by
creating a temporary PDF file and then printing it, providing all the formatting options that
are also available for PDF.

See also:
The Adobe PDF format 737
Using PDF templates 330
5.4.1 About PDF output

Print manual templates

The layout of PDF files and printed manuals is defined in template files with the
extension .mnl that are referred to as "print manual templates". These templates are
edited with a program called the Print Manual Designer, which is included with Help &
Manual.
You can create multiple print manual templates and use them to change the formatting
and layout of your PDF files in seconds this is similar to the skins 321 available for HTML-
based output formats.
See Using PDF templates 330 for more details.

Additional pages and components in PDF files

In addition to the layout (margins etc.) your print manual templates can also add a
number of additional optional pages to your PDF documents that normal help files do not
contain. These can include front and back cover pages, a print-style table of contents, a
foreword, "intro" pages for your top-level chapters, pages of notes at the beginning or end
of the document and so on.
You can also create your own addition pages in your templates and insert "snippet"
objects that load text from external files or from topics in your Help & Manual project.
In addition to this PDF documents have layout components that you do not need in
electronic help: Headers and footers with page and section numbers, margin settings,
formatted headings in the TOC and above topics and so on.
All these features are created and edited in your print manual templates which you can
edit with the Print Manual Designer.

5.4.2 Topic headings in PDF

The formatting of your topic headings in your Help & Manual project is ignored in PDF. This
is one of the key things to understand when generating PDFs in Help & Manual. Only the

© 1997 - 2009 by EC Software, all rights reserved

 326 Help & Manual 5 - User Help

text of your topic headings is exported to the PDF document. The formatting of the headings
is defined in your print manual template 330 , where you also define the layout of your PDF
file.

How topics and headings are exported to PDF

· Topic content:
When you publish to PDF the entire content of your topic files is exported to PDF with
all its formatting as you define it in the Help & Manual editor. Only the margins are set
in the print manual template because there are no margins in the H&M editor, which is
designed primarily for electronic documentation formats.
· Topic headings:
The text of your topic headings are exported from your project as plain, unformatted
text no other content from the header box is imported (i.e. no graphics, hyperlinks
etc). The formatting and positioning of the topic headings are defined in the print
manual template. You can use either the topic caption from the Table of Contents
(TOC) or the topic header from the header box above the H&M editor for your topic
headings. This is useful because it allows you to use longer (heading) or shorter
(caption) versions of the heading texts as necessary.

How topic heading texts are inserted in your PDF documents

Your topic heading texts are inserted in the Table of Contents and Topics sections of
your print manual templates using variables. The Publishing ... variables insert the
headings from the TOC captions for topics in the TOC levels 1-6, the Publishing ...
Publishing variables (Topics section only) insert the headings from the heading box
above the H&M editor.
For more details see the help of the Print Manual Designer program.

5.4.3 Publishing PDF files

Before you generate a PDF file you will probably want to modify one of the standard print
manual templates 330 supplied with Help & Manual for your own needs. These standard
templates provide a basic framework for your user manuals and PDF documents but they
contain a number of elements which you will want to change, like the contents of the cover
page and introduction and so on.

Key Information
A maximum of 6 TOC levels are supported
in PDF files. If you have more levels than
this (which is not recommended) they will
all be displayed on the same level of the
published TOC. Levels below level 6 will
not have headings in the body of your text.

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 327

Step 1: Prepare your print manual template

Follow the instructions in Using PDF templates 330 to create or edit a PDF print manual
template.
Once you have created a personalized print manual template you can use it as often as
you like, both for your current project and for other projects.
It's a good idea to store your edited template in your project directory. This keeps all the
files associated with your project together and makes your project more portable.

Step 2: Configure your PDF settings

1. Open your project and go to Configuration > Publishing Options > Adobe PDF
690 in the Project Explorer to configure the export settings for Adobe PDF. All these

settings only need to be set once for your project. Any changes you make are stored
automatically, including the selection of a print manual template to be used for PDF
export.
2. In the PDF Layout 690 section select the template you edited in Step 1. Use the
button to navigate to the template file, which has the extension .mnl.
See Adobe PDF settings 690 in the Reference section for details on the other available
settings.
A printer driver is needed for PDF output:
Go to View > Program Options > PDF Export 650 and check your reference device
for PDF output.
If you are not using EMF or WMF graphics you will get the best results by setting the
screen device. Otherwise you need to use a printer driver, which does not have to be
the driver for a printer physically connected to your computer.
If you experience any problems with your PDF output they may be caused by
proprietary printer drivers. If this happens try installing a standard driver for a common
printer like a LaserJet or a DeskJet from the Windows CD. Then select this driver as
your reference device in the PDF Export tab.
Embedding fonts in your PDF output file:
If you use rare fonts in your project you should make sure that those fonts are
embedded in your PDF file, otherwise they will not be displayed on computers where
they are not installed. However, note that this will significantly increase the size of your
PDF file, so using rare fonts should generally be avoided wherever possible!
By default Help & Manual automatically embeds all fonts except a list of standard fonts.
To check this exclusion list go to Configuration > Publishing Options > Adobe
PDF Output > Font Embedding 692 .

Step 3: Publish your PDF

Select Project > Publish 590 , and select Adobe PDF as your publishing format.

© 1997 - 2009 by EC Software, all rights reserved

 328 Help & Manual 5 - User Help

See Publishing Your Projects 311 for more details on publishing.

See also:
Publishing Your Projects 311
Using PDF templates 330
Conditions and Customized Output 399
PDF Questions 832 (FAQ)
5.4.4 Printing user manuals
Before you print a user manual you will probably want to modify one of the standard print
manual templates 330 supplied with Help & Manual for your own needs. These standard
templates provide a basic framework for your user manuals and PDF documents but they
contain a number of elements which you will want to change, like the content of the cover
page and introduction and so on.

Key Information
A maximum of 6 TOC levels are supported
in printed manuals. If you have more levels
than this (which is not recommended) they
will all be displayed on the same level of
the published TOC. Levels below level 6
will not have headings in the body of your
text.

Step 1: Prepare your print manual template

Follow the instructions in Using PDF templates 330 to create or edit a PDF print manual
template.
Once you have created a personalized print manual template you can use it as often as
you like, both for your current project and for other projects.
It's a good idea to store your edited template in your project directory. This keeps all the
files associated with your project together and makes your project more portable.

Step 2: Use Print Preview to check your user manual

1. Select Print Manual in the Application Menu and then select Preview... 577

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 329

2. Select the printer you want to use in the Printer section at the top of the dialog (the
printer driver is needed to generate the preview).
3. Select the print manual template you prepared in Step 1 in the Print Manual Template:
field. Use the button to navigate to and select the template file, which has the
extension .mnl. A set of standard templates can be found in the \Templates\pdf folder
in the Help & Manual program directory.
4. Select any Include Options appropriate for your manual. The default selection here is
Print Manual and you will not need to change this unless you have made use of
include options in your project. (See Conditions and Customized Output 399 for more
details on include options and how to use them.)
5. Set the other options in the dialog as you would like to have them, then click on OK to
display the print preview.
You can jump to individual pages in the preview by entering page numbers in the box at
the top of the preview widow.

Step 3: Print your user manual

1. Open your project and select Print Manual in the Application Menu.
2. Select the print manual template you prepared in Step 1 in the Print Manual Template:
field. Use the button to navigate to and select the template file, which has the
extension .mnl.
3. Select any Include Options appropriate for your manual. The default selection here is
Print Manual and you will not need to change this unless you have made use of
include options in your project. (See Conditions and Customized Output 399 for more
details on include options and how to use them.)
4. Set the other options in the dialog as you would like to have them, then click on OK to
print.

© 1997 - 2009 by EC Software, all rights reserved

 330 Help & Manual 5 - User Help

Printing or previewing selected topics only

1. If you only want to print or preview individual chapters or topics select them first in the
TOC with the mouse. Use Ctrl+Click and Shift+Click to select multiple topics.
2. Then follow the instructions above and select Selected Topics in the Include Options:
section in the Print User Manual dialog.
Eliminating cover page, TOC etc.
When you use this method the cover page, TOC and other additional pages defined in
your print manual template will also be generated. To prevent this just make a copy of the
template and edit it to disable all sections except the Topics section. Then use this
"topics-only" template for generating your "quick output".

See also:
Printing topics 153
Print Manual 575 (dialog reference)
5.4.5 Using print manual templates
The layout of Help & Manual's PDF and print manual output is controlled by template files
called "print manual templates" with the extension .mnl that do much more than just define
the appearance of your pages. These templates can also add front and back covers,
multiple title pages at the beginning, an introduction, a formatted table of contents, title
pages for individual chapters, graphics, headers and footers, a formatted index and multiple
endnotes pages. You can also define your own additional pages and insert topics from your
project or external files with a "snippets" function.
All the global variables and user-defined variables from your project file can be used in your
print manual templates. Since the templates are external files you can use them in multiple
projects, applying them to your output just as you apply skins 321 to HTML-based output
formats.

How to select a print manual template

You can select separate templates for PDF output and printed manuals.
Selecting a print manual template for PDF output:
1. Go to Configuration > Publishing Options > Adobe PDF > PDF Layout 690

2. Click on the button in the Print Manual Template: field to select the template you
want to use.

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 331

Selecting a print manual template for printing a user manual:

1. Click on the Application Button and select Print User Manual 575 .

2. Click on the button in the Print Manual Template: field to select the template you
want to use.
In both these dialogs you can open the selected template for editing by clicking on the
Design button next to the template selection field.

How to edit a print manual template

· Select a template with one of the methods described above and select the Design
button next to the template selection field to open it in the Print Manual Designer
program.

OR:
· Select Project > Tools > Manual Designer 537 to open the Print Manual Designer.
Then select File > Open in the Designer to open the template for editing. You can find
a selection of standard templates that you can edit in the \Templates\pdf folder in the
Help & Manual program directory.
The Print Manual Designer is a separate program with its own documentation. See the
help in the Designer for details on how to use it.

Location of the standard print manual templates

Help & Manual comes with a selection of standard print manual templates that are stored
in the \Templates\pdf subdirectory in the Help & Manual program directory. These
templates have the file extension .mnl.

See also:
Templates and Secondary Windows 416

© 1997 - 2009 by EC Software, all rights reserved

 332 Help & Manual 5 - User Help

5.4.6 Embedding files in PDFs

How to embed linked files in PDF documents

You can automatically embed files referenced with file links into the PDF file when you
export your project to PDF. This makes it possible to distribute additional files with your
PDF document without having to use multiple files.
When the user clicks on the link the file will be displayed with the application with which it
is associated in Windows. This works for most file types, including other PDF files,
documents and images of all kinds and even executable EXE files.
1. In the Project Explorer go to Configuration > Publishing Options > Adobe PDF
> PDF Layout and activate the option File links - embed linked files with the following
extensions:.
2. Make sure that the files you want to link to are stored in one of the folders referenced
in your Image Folders 656 list in Project Properties. If you have many folder references
place the files in one of the first few folders in the list.
3. Create your file links using the normal procedure.
When you compile your project the files referenced with file links will be physically
embedded in the PDF file. You no longer need to distribute these files separately as they
are now part of the PDF. This will increase the size of the PDF accordingly, of course.

See also:
Inserting file links 220
5.4.7 CID mode for Unicode fonts
The CID Font Mode option in Configuration > Publishing Options > Adobe PDF >
Font Embedding can reduce the size of your PDF for projects written in Unicode-based
languages, particularly Asian languages. In addition to this it also improves the correct
rendering of special Unicode characters in PDF.
When you set CID Font Mode to Unicode only the characters actually used in the font are
embedded in the PDF file, in a special internal format.
This works correctly with most Asian languages. However, it may sometimes cause
problems with western languages like Russian or other European languages with special
characters.

How to use CID Font Mode

· Western languages:
Set CID Font Mode to CID Off for all normal western languages like English and most
other Western European languages. You should also turn CID off for Eastern European
languages like Russian, Czech, Polish and so on.
· Asian languages:
Set CID Font Mode to Unicode for all Asian languages based on Unicode fonts.
· Special Unicode characters:

© 1997 - 2009 by EC Software, all rights reserved

 Publishing 333

If you use special Unicode characters in your project you may need to activate Unicode
mode to get the characters to display correctly. Please check the rest of your output
carefully for correct rendering when you do this.

About CID Font Mode

Although Help & Manual can generate PDFs from projects written in Unicode-based
languages, the Adobe PDF format does not actually support Unicode directly. This is
because PDF is a universal format designed to be displayed on any computer running
any operating system. If PDF files were encoded with Unicode they would not display on
older operating systems like Windows 98 and Windows NT that have no Unicode
support.
PDF files gets around this problem by using a different encoding internally that can map
and represent all the Unicode characters. PDF currently supports two internal encoding
formats for Unicode: double-byte characters (which are often mistakenly confused with
Unicode) and "character identity definition" or CID.
CID Font Mode: Unicode
When you set CID Font Mode to Unicode the PDF engine does not embed the entire font.
Instead, it only embeds the characters that are actually used, which are stored in a
special internal format. This works well for most Asian languages and will usually provide
a significant reduction in PDF file size.
CID Font Mode: CID Off
When CID Font Mode is set to CID Off Unicode character codes are exported in double-
byte format and fonts are generally embedded in the PDF (except for common fonts like
Arial). This works well with western languages but it does not work with Asian languages
and other languages based on Unicode.

See also:
International languages setup 94
Adobe PDF - Font Embedding 692 (Configuration Options)

© 1997 - 2009 by EC Software, all rights reserved

Part

VI
 More Advanced Procedures 335

6 More Advanced Procedures

The chapters in this section describe functions and procedures that are a little more
advanced. Once you get used to working with Help & Manual you may use them just as
frequently as the functions described in the Basic Working Procedures 83 section. However,
is probably a good idea to wait until you have a good working knowledge of the program
before you start studying these chapters.

6.1 Using Version Control Systems

Key Information
Active support for VCS is only available in
the Professional version of Help & Manual
and is only possible with projects saved in
uncompressed XML. Binary HMXZ projects
cannot be linked to VCS repositories.

If you save your projects in uncompressed XML (recommended anyway and also required
for multi-user editing) you can integrate them directly in your Visual SourceSafe version
control repository. Help & Manual actively supports Microsoft Visual SourceSafe and other
fully-compatible version control systems, with automatic or manual check-in and check-out
for your project files.

Advantages of version control systems

There are two main advantages to using a version control system: Automatic incremental
backups with rollback capability and superior support for multi-user access to your project
from diverse and remote locations.
The benefits of incremental backups should be obvious: They make it possible to return
to an earlier version of your documentation at any time, so you never need to worry about
deleting or rewriting something that you may need again later. And since the backups are
automatic you can focus on your work and not worry about making backups.
The way multi-user editing works does not change for you when your project is linked to a
VCS, but access to the project is handled by the VCS rather than by Help & Manual itself.
Remote access is better, faster and more robust because you are working on a linked
local copy rather than accessing the entire project stored on the server. Only changes
made need to be transferred across the remote link. The changes made by other users
are transferred to your local copy when you open the project, and your changes are
transferred to the VCS database when you save and exit.

Supported version control systems

Help & Manual supports Microsoft Visual SourceSafe with Microsoft's SCCAPI (Source
Code Control Application Programming Interface) versions 1.1, 1.2 and 1.3. Other VSS-
compatible version control systems should also work if they implement the Microsoft
SCCAPI in exactly the same way as Microsoft in Visual SourceSafe, including full support

© 1997 - 2009 by EC Software, all rights reserved

336 Help & Manual 5 - User Help

for the programming interface.

VCS controls in Help & Manual

The VCS controls in Help & Manual Professional will only be displayed if you have active
support for Visual SourceSafe or a fully-compatible VCS installed on the same computer
on which you are running Help & Manual. This means that your VCS database must
already be configured and registered on your computer before you start Help & Manual.
Please see your VCS documentation or contact your system administrator for help if
necessary.
VCS options in the Application Menu:

These options are only displayed if you have active support for a configured VCS
database installed on your computer. Some of the options will be grayed out depending
on the format and status of the project you currently have open.

VCS options in the Ribbon Project tab:

This menu is only displayed if your current project is already linked 339 to a VCS
database. The latest version and check-in / check-out options are only active if you
have activated manual-checkout 346 for the current project.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 337

VCS options in the context menu:

This additional entry in the context menu (right-click on TOC item) is also only
displayed if your current project is already linked 339 to a VCS database. Here too, the
latest version and check-in / check-out options are only active if you have activated
manual-checkout 346 for the current project.

© 1997 - 2009 by EC Software, all rights reserved

 338 Help & Manual 5 - User Help

6.1.1 Introduction
Before using Help & Manual with a version control system (VCS) it's important to understand
how your project is linked to the VCS database and how the two interact. The following
introduction will make it a lot easier to use the VCS support functions because you will
understand what is actually happening when you use them.

Key Information
Once you have got your project linked to
your VCS everything works exactly the
same as it does for multi-user editing on
projects that are not in a VCS. See Multi-
User Editing 518 for full details.

A local project copy is linked to the VCS database

When you use VCS support in Help & Manual there are two copies of your project: A
"local" copy, which is the project you are actually working on, and the version control copy
in the VCS database. The two copies are actively linked – the VCS "knows" when Help &
Manual is working with the files, and Help & Manual also "knows" when someone else is
working on the files from the same database.
The functionality is essentially exactly the same as with multi-user editing – the only real
difference is that the VCS is automatically maintaining backup copies of your project files
in the background. In addition to this the VCS also makes sure that only one person
works on any topic at the same time, thus ensuring that you can never create two
conflicting versions of the same topic.
See the other topics in this chapter for information on how to link projects to your version
control system.

Opening and closing VCS-linked projects

When you open an HMXP project that is linked to a VCS Help & Manual activates the
connection to the VCS database and checks whether any changes have been made to
the copy of the project in the database since the last time you worked on it. If changes
have been made they are updated in your local copy. This also includes changes made
by other users who have linked the same VCS database version to local copies of their
own. You will see both your own changes and changes made in the meantime by other
users.
This updating process is done passively, nothing is actually checked out of the VCS
database until you start editing topics – this makes it possible to only lock those topics
that are actually being worked on. When you edit a topic the topic file is checked out of
the VCS database until you save your project.
When you save your work all the changes you have made are written both to your local
copy and to the copy in the VCS database. Your updated topic is then checked back into
the VCS database so that other users can access it. If another user then accesses their
linked copy it will automatically be updated with the changes that you have made.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 339

Editing topics in VCS-linked projects

When you open a topic for editing the system first checks to see whether anyone else
has that topic checked out of the VCS database.
· If the topic is checked out by another user, you will get a message telling you that it is
locked and read-only. You will not be able to edit the topic until the other user saves
their work and switches to a different topic.
· If the topic is "free" you will be able to edit it. The VCS database copy of the topic is
checked out while you are working so that other users who try to edit it.
· When you save your project and move to another topic your changes are saved to your
local copy and to the VCS database copy. The topic file is checked back in to the VCS
database, after which other users are able to check it out and edit it.

Editing project structure in VCS-linked projects

Here too, the same applies as for normal multi-user editing. Unlike topics, your project
structure and settings cannot be checked out for exclusive editing. All users working on
the project are able to make changes to the Table of Contents and to the project
configuration settings. If two users make conflicting changes the last one who saves their
project will get a conflict resolution dialog asking them to decide if they want to keep their
own changes or the changes made by the previous user.
Always select Refresh Project before editing the TOC or project settings!
If you know that other users may be working on the same project you should always save
your project and select Refresh Project in the Project tab to make sure that your local
copy is updated with any recent changes made by other users. Then you can confidently
make your own changes, after which you should always save immediately to commit your
changes to the VCS database.
See the chapter on Multi-User Editing 518 for more details on this.

See also:
Multi-User Editing 518
6.1.2 Setup and editing
There are two possible scenarios when you are setting up a project that will be connected to
your VCS database: Either your project is a new project that has not yet been added to the
VCS database, or you want to work on a project that is already stored in the VCS database.
In the first case you need to add a copy of your project to the database and link it to your
local version. In the second case you need to create a local copy of the database project
and link it your copy to the database.

Connecting and uploading a local project to a VCS

This assumes that you are working on a project that is not yet stored in the VCS
database. Always check with your system administrator before doing this to make sure

© 1997 - 2009 by EC Software, all rights reserved

340 Help & Manual 5 - User Help

that the project is not already in the VCS. If it is you need to follow the instructions further
below for downloading a project from a VCS to a local copy.
1. Open the Help & Manual project you want to connect to your VCS. Then select
Version Control System > Connect Local Project to VCS in the Application
menu.
If the current project is a single-file HMXZ project select Version Control
System > Save as VCS Project. This will save the project as uncompressed
XML (choose an empty folder) and then connect it to your VCS system. All the
next steps are the same.
2. Select your version control system from the top drop-down list. If no system is
displayed here it means your VCS is not installed or registered correctly on your
system, or that no VCS database has been set up.

If you want you can use Check Version Control System to check the link to the DLL
that links you to the VCS. Then click on Next.
3. The next dialog connects you directly to your VCS database, where you can create a
new project for your Help & Manual project. In addition to the current directory of your
project this dialog shows the last database you accessed and the associated user
name – these will change in the next step if you link to a different database as a
different user.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 341

Click on Open or Create a VCS Project to select the project from your database. It's
a good idea to select Store username in project to keep your username for your
database in your stored Help & Manual project.
4. Clicking on Open or Create a VCS Project will open the access dialog for your VCS.
The screenshot below shows the dialog for Visual SourceSafe 2005, your dialog may
look a little different.

Clicking on OK opens the database navigation dialog of your version control system.
Follow the instructions displayed there to create a new project in your VCS database.
You may need to consult your VCS system documentation for instructions.
5. Once you have created the new project in your VCS database you will be returned to
the Help & Manual dialog and the link data for your project will be displayed:

© 1997 - 2009 by EC Software, all rights reserved

342 Help & Manual 5 - User Help

Then just click on OK to confirm – you will be returned to your Help & Manual project,
which is now linked to your VCS database. This is indicated by the lock icon in the
project name in the Project Explorer:

You can then start editing normally. By default all the check-in and check-out operations
for your VCS system are handled automatically. See Auto & manual check-in/check-out
346 for more information on this subject.

Multi-user editing is performed in exactly the same way as for any other multi-user editing
project – the only difference is that the file locks for topic access are handled by the VCS,
which is transparent to the user. As far as you are concerned everything will behave in
exactly the same way as any other multi-user editing project. See the chapter on Multi-
User Editing 518 for instructions on working in multi-user mode.

Downloading and connecting a project from a VCS database to a local

copy
If a project is already stored in your VCS database you must "download" a linked copy of
it from the database and store it locally before you start working on it. This is done with
the Load VCS Project to Local System function.

Key Information
Don't try to link a project from a VCS
database to a local project using this
function! This could corrupt both the

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 343

database and the local versions.

1. Locate or create the empty folder in which you are going to save your project. There
should not be any other files in this folder.
2. Select Version Control System > Load VCS Project to Local System in the
Application Menu. This displays the following dialog:

3. Click on in the Output File: field and select the empty folder where you want to store
your local copy of the project. Then click on Next to display this dialog:

Select your version control system from the top drop-down list. If no system is
displayed here it means your VCS is not installed or registered correctly on your
system, or that no VCS database has been set up.
If you want you can use Check Version Control System to check the link to the DLL
that links you to the VCS. Then click on Next.
4. The next dialog connects you directly to your VCS database. In addition to the current
directory of your project this dialog shows the last database you accessed and the
associated user name – these will change in the next step if you link to a different
database as a different user. Click on Open a VCS Project to select a project from
your VCS database.

© 1997 - 2009 by EC Software, all rights reserved

344 Help & Manual 5 - User Help

Click on Open a VCS Project to select a project from your VCS database. It's a good
idea to select Store username in project to keep the username for your database in
your Help & Manual project.
5. Clicking on Open a VCS Project will open the access dialog for your VCS. The
screenshot below shows the dialog for Visual SourceSafe 2005, your dialog may look
a little different.

Clicking on OK opens the database navigation dialog of your version control system.
Follow the instructions displayed there for selecting the project from your VCS
database. You may need to consult your VCS system documentation.
6. Once you have selected the project in your VCS database you will be returned to the
Help & Manual dialog and the and the link data for your project will be displayed:

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 345

Then just click on OK to confirm – the local copy of the database project will be
created automatically and the project will be opened in Help & Manual. The project is
now linked to your VCS database. This is indicated by the lock icon in the project
name in the Project Explorer:

You can then start editing normally. By default all the check-in and check-out operations
for your VCS system are handled automatically. See Auto & manual check-in/check-out
346 for more information on this subject.

Multi-user editing is performed in exactly the same way as for any other multi-user editing
project – the only difference is that the file locks for topic access are handled by the VCS,
which is transparent to the user. See the chapter on Multi-User Editing 518 for instructions
on working in multi-user mode.

Editing VCS projects

Editing a project that is linked to a VCS database is basically exactly the same as editing
a normal project. By default your topics will be checked in and out of the VCS database
automatically by Help & Manual. (See Auto & manual check-out 346 for details on the
manual options.)
As soon as you start editing a topic it is automatically checked out of the VCS database
and locked for all other users. Topics that are checked out are identified with additional
icons in the Project Explorer – you will see green check icons for topics that you have
checked out and red check icons for topics checked out by other users.

© 1997 - 2009 by EC Software, all rights reserved

 346 Help & Manual 5 - User Help

In multi-user editing mode everything works just as it does when multiple users are
editing a project that is not linked to a VCS database. See Multi-User Editing 518 for more
details.
When you save your project your topic files are automatically checked back into the VCS
database and unlocked for other users to access – the check icons will then be cleared
from the topics in the Project Explorer. Here too, you don't have to do anything yourself.

Converting a compressed HMXZ project to a VCS project

You can only link uncompressed XML projects (.hmxp project file) to a VCS database. If
your project is stored in the compressed, single-file HMXZ format you must first convert it
to uncompressed XML. There are two ways to do this:
· Use Save As... in the Application Menu to manually save your project to
uncompressed XML, then use Connect local project to VCS (see above) to connect
it to your VCS database.
· Alternatively, you can use Version Control System > Save as VCS Project in the
Application Menu to save a new copy of your project in uncompressed XML and then
connect the copy to the VCS database in one process. Apart from the first step (save to
uncompressed XML) the procedure is exactly the same as for Connect local project
to VCS (see above).

See also:
Multi-User Editing 518
6.1.3 Auto & manual check-out
By default Help & Manual will automatically check your topics out of the VCS database when
you edit them and check them back in when you save and move on to another project. In
most scenarios this is the best choice and you should not change it unless you have a
specific reason for doing so.
If you wish, however, you can also configure your project for manual check-out and check-
in. Then your project will be displayed in read-only mode when you open it and you will have
to check out your topics manually in order to edit them. You must also remember to check
your topics back in again when you finish your work.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 347

Working with automatic check-out and check-in

This is the default mode for VCS projects. In this mode you don't need to change the way
you work at all. The only difference you will notice is the icon on your project name in the
Project Explorer indicating that the project is linked to a VCS database.
As soon as you start editing a topic it is automatically checked out of the VCS database
and locked for all other users. Topics that are checked out are identified with additional
icons in the Project Explorer – you will see green check icons for topics that you have
checked out and red check icons for topics checked out by other users.

In multi-user editing mode everything works just as it does when multiple users are
editing a project that is not linked to a VCS database. See Multi-User Editing 518 for more
details.
When you save your project your topic files are automatically checked back into the VCS
database and unlocked for other users to access – the check icons will then be cleared
from the topics in the Project Explorer. Here too, you don't have to do anything yourself.

Activating and using manual check-out and check-in

You can only activate manual check-out/check-in for your entire project. To turn it on go
to Project Explorer > Configuration > Common Properties > Miscellaneous and
activate the check box by Manually check out and check in topics. Then save your project
to apply the setting.
This will automatically switch all the topics in your project to read-only mode (they will be
grayed out in the Project Explorer). To edit a topic you must now check it out manually:
1. Select the topic you want to edit in the TOC or Topic Files section.
2. Select Project > Manage Topics > File > Check out or right click on the topic in
the Project Explorer and select Version Control System > Check Out in the
context menu.
3. The topic name will be displayed with a green checked-out icon in the Explorer and
you can now edit it normally.

© 1997 - 2009 by EC Software, all rights reserved

 348 Help & Manual 5 - User Help

4. When you have finished editing save your changes, then select Check In in the Project
tab or the context menu. This checks the topic with your changes back into the VCS
database and the topic is switched back to read-only in the Project Explorer.
That is really all there is to it. Everything else is exactly the same as editing a normal
project. You just have to remember to check in your open topics before you close your
project, otherwise you and other users will see a conflict resolution dialog from your VCS
the next time you access the project because it will see that there are topic files checked
out.

See also:
Multi-User Editing 518
6.1.4 Graphics and additional files
Only your actual project files are automatically managed by the version control system. Your
graphics files and any additional files you add to your project folder manually are not
included. If you want to manage these files in your VCS you must add them yourself with the
facilities provided by your VCS, and check them in and out manually when you want to edit
them.
This is necessary because these files are not edited by Help & Manual, but with your
graphics program or with other editors. These programs won't have any facilities for
checking files in and out of your VCS database, so they would not be able to access them
directly. This is why you need to add these files to your VCS repository yourself and check
them out using your VCS program's administration interface when you need to edit them.
See your VCS documentation or ask your administrator for details on how to do this.

Alternative: Baggage Files

All the files in your Baggage Files 485 section are automatically included in your VCS
database because they are an integral part of your project. If you are saving your project
in uncompressed XML – which is required for VCS support anyway – there is no
restriction on the number and size of files you put in your Baggage. (You should not put
too much in the Baggage in compressed, single-file HMXZ projects!)
Even if you originally reference your graphics files in other folders the ones in your
Baggage Files will always be used if they are there and have matching names. This is
because Help & Manual always looks in the Baggage first for any referenced files.
Tip: Adding multiple files to the Baggage

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 349

You can add multiple files to the Baggage by selecting Add File and then selecting
multiple files in the Open dialog. Use Ctrl+Click, Shift+Click and Ctrl+A to select multiple
files there, just as you would in any other Windows dialog.
Tip: Adding files in Windows Explorer
You can also add files to the Baggage by copying them to your project's Baggage folder
in Windows Explorer. However, you must do this before linking your project to your VCS!
If you do it afterwards they will not be added to the VCS database, they will still be treated
as external files.

6.1.5 Backups and disaster recovery

Projects linked to a VCS database generally behave in exactly the same way as normal
projects. Only backups and disaster recovery need to be handled a little differently.

Backups of VCS projects

If your VCS system is managed correctly you don't need to make backups of your local
copy of your VCS project. The entire backup strategy is handled by the VCS system, with
incremental backups that allow you to return to earlier versions of your topics and
projects if necessary. You just need to make sure that your VCS database is backed up
as well, so that you do not lose everything it contains if disaster strikes.
Turn on the automatic backup function
Despite this, however, it is still a good idea to turn on the automatic backups function in
Help & Manual, which you can access in View > Program Options > General. This will
create regular compressed backups of your project in your project folder in a single file
with the extension .hmxz~~. These backups are not linked to your VCS database and
they can be opened normally in Help & Manual by removing the two tilde characters from
the file extension.
If you ever lose your VCS database this backup file will give you an additional emergency
fallback option.

Disaster recovery – unbinding your local copy from the VCS

If a disaster strikes and your VCS database is deleted, corrupted or otherwise becomes
permanently unavailable you will not be able to open the local version of your project. If
you have also failed to make backups your local copy may be the only copy of the project
you have and you will want to recover your project from that.
Recover from your automatic backup file:
If you have activated the automatic backup feature (see above) you can recover the last
version saved in the automatic backup file in your project folder, which is called
projectname.hmxz~~. To make the file readable just delete the two tilde (~) characters in
the extension, then you can open it in Help & Manual. However, depending on the backup
interval you have set this file may not contain the very last changes you made before
closing your project the last time.

© 1997 - 2009 by EC Software, all rights reserved

 350 Help & Manual 5 - User Help

Unbinding the local copy from the VCS database:

To make the local copy editable you need to make it writable and manually unbind it from
the VCS database. Please only do this in a genuine disaster situation – you will not be
able to re-bind the project to an existing VCS database version after doing this!!
1. Reset the Read-Only attribute on all the files in your project folder. To do this select
the files in Windows Explorer, right-click, select Properties and then deactivate the
Read-only checkbox and apply. Do this for all the files in all the folders in your project
folder.
2. Locate and delete or rename all the *.scc files in your project folder and subfolders.
There should be one in every folder inside your project folder.
3. Open the main *.hmxp project file in a text editor and locate the <config-group
name="versioncontrolsystem"> block of code and delete it, then save the file. The
block should look something like this:
<config-group name="versioncontrolsystem">
<config-value name="provider">Microsoft Visual SourceSafe</config-value>
<config-value name="server">E:\Data\Databases\VSS</config-value>
<config-value name="projectname">&quot;$/ModuleB&quot;, FFAAAAAA</config-
value>
<config-value name="localdirectory">E:\Help Projects\DemoHelp\Module B</
config-value>
</config-group>
After doing this you should be able to open and edit the project normally.

6.2 Toggles: Expanding Text and Images

This feature enables you to create expanding text and images in your projects with just a
few simple clicks. Toggles are powerful and easy to use and they can make your help much
more useful and accessible to the user. They make it possible to scan the content of a topic
quickly and then click to display only the relevant information.
The Toggles feature is only supported in Help & Manual Professional. The Standard version
can edit toggles created with the Professional version but you cannot create new toggles or
publish active toggles.

6.2.1 About toggles

There are three different types of toggles:

Expanding section toggles

These toggles create a header with a hidden block of text that is displayed when the user
clicks on the header. Here is an example of an expanding section toggle:
Support for toggles in Help & Manual's output formats
HTML Help, Webhelp and Visual Studio Help / MS Help 2.0.
Toggles are fully functional in all these formats. In Webhelp JavaScript must be
turned on for the toggles to be operational. If JavaScript is turned off the toggles are

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 351

automatically displayed in their expanded state.

PDF, MS Word RTF and Printed Manuals
In all these static formats toggles are automatically displayed in their expanded
state. This is the default setting – however, you can also choose to have them
displayed in their collapsed state.
Winhelp and eBooks
Winhelp and Windows Exe and ePub eBooks do not support JavaScript and so all
text toggles are displayed as static text and in their expanded state. Image toggles
will display the target version of the toggle image in a separate page when the user
clicks on it.
Note: The ePub format does officially support scripting but since virtually no readers
implement this support it should never be used in ePub.

Expanding inline text toggles

These toggles create a link like thisInline text toggles can be used instead of popups for definitions
and other references. that expands when the user clicks on it to display additional text, that
can be formatted in a different way to highlight it. The text is displayed in the flow of the
paragraph, as though it had been pasted into the paragraph.

Expanding image toggles

These toggles create a small version of a graphic or other image that expands when the
user clicks on it. Here is an example of an expanding image toggle:

Click on the image to switch back to the smaller version!

6.2.2 Expanding section toggles

Expanding sections display text and other content – as much as you like – when the user
clicks on the header. There are no restrictions on the content of expanding sections. You
can insert anything that you can use in normal topics, including other expanding sections
and snippets 149 .

Productivity Tip

© 1997 - 2009 by EC Software, all rights reserved

352 Help & Manual 5 - User Help

Avoid using additional tables inside your

expanding section toggles if you also plan
to publish to PDF or printed manuals. If
you do, page breaks may not work
correctly inside the rows containing
additional tables.

How to create a new expanding section

Expanding sections are handled by placing all the text and other content you want to
include in the section in a single-cell table. Normally, this table will be created
automatically by the Toggle function but you can also use an existing table if you want
(see further below).
1. Click in your topic in the place where you want to insert an expanding section toggle. If
you want to use existing text as the expanding section header select it in the editor.
2. Select the Insert Toggle tool in Write > Insert Object and select the Expanding
Text option at the top and Toggle a Table: in the middle of the dialog (these are the
default settings).

3. Configure the settings in the Insert Toggle dialog 629 and then click on OK to insert the
toggle. This will create the toggle header with an empty, single-cell table below it.

4. Enter or copy the text and other content you want to include in your expanding section
in the table. See further below for details on using existing text for expanding sections
and expanding existing tables.
You can have a maximum of one empty paragraph between the expanding section

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 353

header and its table. If you have two or more empty paragraphs the expanding section
will not work!
5. Format the header of your expanding section if you want. You can also use styles on
the header paragraph, but you should switch off the "blue underlined" link style in the
toggle settings when you do this. See below for more details.
You can adjust the left and right indents of the toggle table by formatting the paragraph
containing the table. See below for details.

Using an existing table for the expanding section

Normally, the Toggle Tool will automatically create an empty, single-cell table together
with your expanding section header when you create the toggle. However, you can also
toggle an existing table.
To do this just follow the instructions above to create a toggle directly above the table you
want to "toggle". In the Toggle a Table: setting select the option Toggle the table below
this link. This option will only be displayed if there is actually a table below the paragraph
where you are creating the toggle!
When you toggle an existing table you may need to adjust the indents of the toggle and
the table. See further below on this page for instructions.
Toggling existing tables with IDs:
Toggle links know which table to toggle by referencing the ID of the table, which is
assigned automatically when you publish your output. If you have already assigned an ID
to your existing table this ID will be overwritten by the toggle ID. If you want the table to
keep its ID you must enter this ID as the toggle ID in the Insert Toggle 629 dialog. Then it
will still be overwritten, but with the correct ID.

Formatting the expanding section headers

By default, the header (caption) of your expanding section either uses the standard
hyperlink format or plain formattable text, depending on whether the Link Style option is
selected in the Insert Toggle 629 dialog.
Using manual formatting and styles:
If you deselect the Link Style option the header initially has the same style as the
paragraph in which it is located. You can then apply manual formatting or use a style to
format it.
· To use manual formatting select the entire toggle header and use the font formatting
tools in the Write tab. You must format the entire toggle header in exactly the same
way, otherwise you will have breaks in the toggle link.
· To use a style just click in the toggle header and select the style you want to use in the
Style Selector in Write > Font.
Using CSS styles in HTML-based output:
Help & Manual exports individual CSS classes for all three toggle types. (The class

© 1997 - 2009 by EC Software, all rights reserved

354 Help & Manual 5 - User Help

dropdown-toggle is assigned to the toggle headers of expanding sections.)

This means that you can define CSS styles in your HTML template to control both the
appearance and behaviour of your toggle links. See Formatting toggle links 361 topic for
details.
Note that CSS formatting only works on links when the Link Style option is selected in
the Insert Toggle 629 dialog! Otherwise you must format the toggle link manually or with a
style (see above).

Adjusting the indents for expanding sections

When you create the expanding section table together with its toggle both are
automatically given the same indent. Normally this will be fine and will not need to be
changed. However, you may want to use a different indent and if you are using a toggle
with an existing table you will probably need to make some adjustments.
Adjusting the indent of the toggle header:
The expanding section toggle header is a normal paragraph with a hanging indent for the
toggle icon (if you are using one). Just click anywhere in the toggle and adjust the indent
settings 172 as you would for any other paragraph. You can also use a paragraph style 167
to apply the desired indents to the toggle header.
Adjusting the indent of the toggle table:
The table containing the expanding text for the toggle is a normal table. Like any other
table, it is effectively a single object in a paragraph that cannot contain any other objects.
To adjust the indent of this table you need to adjust the indent settings 172 of the
paragraph containing the table. This too can be done with manual formatting or with a
style. See Indenting tables 262 for detailed instructions on how to do this.

Using your own icons in the headers

You can also use your own icons in your toggle headers. Just select Custom Icons in the
Icon: field when you are defining or editing your toggle. Then select your icon files for the
Collapsed: and Expanded: icon states in the fields directly below.
· You will probably have to adjust the indents of your toggle and its table manually when
you use your own icons (see above).

Replacing the standard icons with your own

When you choose one of the standard icon pairs for an expanding text toggle, Help &
Manual first looks in your project folder to see if the necessary graphics files are there. If
they are not there, it will write copies of the files to your project folder from its internal
database.
This means that if you store icons of your own in your project folder using these names
they will be used instead of the standard icons. You can also "swap" the open and closed
state icons around by renaming the icon files in your project folder.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 355

To replace the standard icon pairs with your own icons:

Just give your icons the names of the standard icon pairs (see below) and store them in
your project folder. Help & Manual will not overwrite them and they will be used
automatically when you select the corresponding standard icon option (Plus/Minus
Symbol, Folder, Arrow).

Standard Icons Filenames

Plus/Minus hmtoggle_plus0.gif
Symbol hmtoggle_plus1.gif

Folder hmtoggle_folder0.gif
hmtoggle_folder1.gif

Arrow hmtoggle_arrow0.gif
hmtoggle_arrow1.gif

See also:
Indenting tables 262
Using indents 172
Formatting toggles with CSS 357
Toggle IDs 359
Editing and copying toggles 360
6.2.3 Expanding inline text toggles
When you click on an expanding inline text toggleThis is the expanding text of the inline text toggle. It
is formatted with a normal style that has been designed to make the text stand out from the paragraph. its text
is "inserted" in the topic directly after the link, as though it had been pasted into the
paragraph. This is ideal for short explanations and definitions that would otherwise disturb
the flow of the topic. It is also simpler than using a popup topic and cannot trigger popup
blockers in browsers.

How to create an inline text toggle

Making inline text toggles is quick and easy. Basically you just enter a caption, your inline
text and an optional tooltip and you're done. You can also choose a style to format the
inline text.
1. Click in your topic in the place where you want to insert your inline text toggle. If you
want to use existing text as the toggle link text select it in the editor first.
2. Select the Insert Toggle tool in Write > Insert Object and select the Expanding
Text option at the top and Toggle Inline Text: in the lower part of the dialog.

© 1997 - 2009 by EC Software, all rights reserved

356 Help & Manual 5 - User Help

See Insert Toggle 629 for details on all the settings in the Insert Toggle dialog.
3. Enter a caption (the link text to be displayed) in the Caption: field if you did not select
text in the editor for the caption.
4. Enter your inline text in the text entry box directly below the Toggle Inline Text: option.
You can only enter plain text here. You can enter carriage returns with the Enter key
and they will be converted to line breaks in the output.
5. Choose a style for the inline text in the Format text with style: field. It is best to define
a style that makes the text stand out against the normal text in your topic.
6. Click on OK to insert the toggle, which will be displayed in your topic in the same way
as other hyperlinks.

Formatting the text of inline text toggles

The inline text of these toggles can only be formatted with styles. You can only apply a
single style to the entire inline text and the style must be selected in the Insert Toggle 629
dialog. You should define a style that makes the text stand out well against the rest of the
text in the paragraph, otherwise the user may be confused after clicking on the toggle
because the new text won't be immediately visible.
Selecting a style in a new toggle:
Select the style in the Format text with style: field. If you need to define a style 161 first just
save the toggle and then double-click on the toggle link in the editor later to open the Edit
Toggle dialog.
Applying or changing the style in an existing toggle:
Double-click on the toggle link in the editor to open the Edit Toggle dialog, then select the
style in the Format text with style field.

Formatting inline toggle links

By default, the link of your inline text toggle is displayed either with the standard hyperlink

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 357

format or as plain formattable text, depending on whether the Link style option is selected
in the Insert Toggle 629 dialog.
Using manual formatting and styles for the toggle links:
If you deselect the Link style option the link initially has the same style as the paragraph
in which it is located. You can then apply manual formatting to it or use a style to format
it.
· To use manual formatting select the entire toggle link and use the font formatting
tools in the Write tab. You must format the entire toggle header in exactly the same
way, otherwise you will have breaks in the toggle link.
· To use a style select the entire toggle link and then select the style you want to use in
the Style Selector in Write > Font.
Using CSS styles in HTML-based output:
Help & Manual exports individual CSS classes for all three toggle types. This means that
you can define CSS styles in your HTML template to control both the appearance and
behaviour of your toggle links. (The inline-toggle class is used for expanding inline
text toggles.) See Formatting toggle links 361 for details.

See also:
Text Formatting and Styles 155
Formatting toggles with CSS 357
Toggle IDs 359
Editing and copying toggles 360
6.2.4 Expanding image toggles
Expanding image
toggles like the one on
the right use a small
"display version" of the
image that the user can
click on to display the
full version. This can
make your topic pages
much easier to read
because the larger
versions of the image
are only displayed when
needed.
Help & Manual does all Click on the image to collapse it!
the work for you. You
just select the full-size
image you want to
display and the smaller
version is generated
automatically.

© 1997 - 2009 by EC Software, all rights reserved

358 Help & Manual 5 - User Help

How to create an expanding image toggle

To make an expanding image toggle you just select the image you want to use, choose a
zoom factor for the thumbnail display version and enter tooltips and/or captions if you
want to use them.
1. Click in your topic in the place where you want to insert your expanding image toggle.
Don't select any text (it would be deleted when you insert the image toggle).
2. Select the Insert Toggle tool in Write > Insert Object and select the Screenshot
Toggle option at the top of the dialog.

See Insert Toggle 629 for details on all the settings in the Insert Toggle dialog.
3. Select the image you want to toggle by clicking on the browse button in the Picture
file name: field. This file should be stored in your graphics folder or project folder, just
like all the other graphics in your project.
4. Select a zoom factor for the preview version and enter tooltips and captions for the
expanded and collapsed versions.
5. Click on OK to insert your expanding image toggle.

Using a different image for the preview

You can specify a completely different image for the preview/collapsed state version. For
example, you could use a button image that the user clicks on to display a larger image,
like this:

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 359

This is the expanded version.

Just select the Picture: option beneath When collapsed, use different settings... and then
select the image you want to use.
When you use this option you are completely responsible for the size and appearance of
the collapsed state version. Help & Manual will not apply a zoom factor for you.
You can enter separate captions and tooltips for the preview and the expanded image.

Converting existing images into toggles

You can convert any image in your project into a toggle image. Just right-click on the
image and select Picture > Convert Picture to a Toggle... The procedure is then the same
as for inserting a new image toggle.

Formatting the toggle image with CSS

The CSS class image-toggle is automatically applied to the <img> tag for your image
toggles. If you know how to use CSS and HTML you can add style definitions for this
class to your HTML template to control the formatting of your toggle image. See
Formatting toggles with CSS 361 for details.

See also:
Formatting toggles with CSS 361
Toggle IDs 359
Editing and copying toggles 360
6.2.5 Toggle IDs
The toggle ID is optional and we recommend that you leave this field blank in the Insert
Toggle 629 dialog. Then Help & Manual will automatically assign a unique ID to each toggle
when you publish your help. If you don't know what HTML IDs are and how they can be used
you can ignore the ID field and this topic entirely you don't need to worry about it.

© 1997 - 2009 by EC Software, all rights reserved

 360 Help & Manual 5 - User Help

When you need static, manually-entered IDS

You only need to enter your own ID manually if you plan to access the toggle IDs with
your own code after generating your help. The automatically-assigned IDs can change
every time you compile (they are based on the sequential order of the toggles on the
page) and so you must enter a manual ID if you always want to have the same ID to refer
to.
When you use your own IDs you have to make sure that each ID is unique in the current
topic. If you use the same ID more than once in the same topic your toggles will not work
properly.

Copying toggles containing manually-entered IDs

If you make copies of toggles containing manually-entered IDs within the same topic you
must change the IDs in the copies, otherwise you will have ID conflicts. Help & Manual
automatically flags toggles containing ID conflicts by highlighting them in red.
Copying toggles containing manually-entered IDs to other topics will not cause conflicts
unless the other topic already contains a toggle or another element with the same ID.

See also:
Editing and copying toggles 360
6.2.6 Editing and copying toggles
Toggle links are normal hyperlinks so editing the links is basically just the same as editing
any other kind of hyperlink. They can also be copied and moved in the same way as normal
text. The toggle content in expanding section toggles is just normal text in a single-cell table
and can be edited normally.
The text of inline text toggles is stored in the Edit Toggle dialog and can be edited by
double-clicking on the toggle link.
Expanding image toggles can be edited by double-clicking on them.

How to edit toggles

Toggle links and settings:
To edit an expanding section or inline text toggle just double-click on its link in the editor
(it looks just like an ordinary hyperlink), or right-click on it and select Edit in the context
menu. This opens the Edit Toggle 629 dialog in which you can change all the settings of
the toggle.
Toggle contents:
Expanding inline text toggles contain plain text only and must be edited in the Edit Toggle
dialog, where you can also apply a style to make the text stand out from the rest of the
topic page.
Editing the contents of expanding section toggles is exactly the same as editing normal

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 361

text in the editor. You just have to be careful that all the text is inside the table and that
you never insert more than one empty paragraph between the expanding section's table
and its header.
Expanding image toggles:
Just double-click on the toggle in the editor to access its settings.

How to copy toggles

There are no restrictions on copying toggles. The copies will be fully functional, both
within the same topic and when you copy them to other topics.
When you copy expanding section toggles you just need to make sure that you copy both
the toggle header and the toggle table containing the expanding content, because these
are two separate items.
Caution with expanding section toggles to which you have assigned IDs
You only have to be a little careful when you copy toggles in which you have entered the
toggle IDs yourself. When the IDs are manually entered they will not be updated
automatically. This is OK when you copy a toggle to a different topic but duplicate IDs
within the same topic will cause conflicts.
When you copy toggles containing manually-entered IDs within the same topic you
should always edit the toggle and update the IDs. (Help & Manual automatically highlights
toggles with duplicate ID conflicts in red.)

See also:
Toggle IDs 359
6.2.7 Formatting toggles with CSS
When your help is exported to HTML-based formats the <a> link tags for the text toggles
and the <img> tag for the image toggles are exported with CSS classes, which makes it
possible to change the appearance and behavior of your toggle links by adding CSS style
definitions for these classes to the HTML template for your topic pages.
Following the instructions in this topic requires some experience with writing HTML manually
and using CSS styles. If you feel stumped by this we recommend that you get an
experienced friend or colleague to help you.
See the Using HTML Templates 430 and About HTML Templates 810 chapters more
information on using and editing HTML templates.

The CSS class names for the toggle link types

Help & Manual exports CSS classes to the main tags of all three toggle types. The
classes are applied to the <a> link tags for the expanding section and expanding inline
text toggles and to the <img> image tag for the expanding image toggles.
You must use the classes directly as properties of the tags that you want to apply them
to, otherwise they won't work properly. This means that you must use the syntax img.

© 1997 - 2009 by EC Software, all rights reserved

362 Help & Manual 5 - User Help

image-toggle {} for defining styles for your image toggles and a.inline-toggle {}
and a.dropdown-toggle {} for defining styles for your text toggle links.

Toggle Type Class Name Link Code Example

Expanding dropdown- <a class="dropdown-toggle" title="Tooltip

section toggle text"
toggles: href="...JavaScript toggle code...">
Section toggle header/link text</a>

Expanding inline-toggle <a class="inline-toggle" title="Tooltip

inline text text"
toggles: href="...JavaScript toggle code...">
Inline toggle link text</a>

Expanding image-toggle <img id="TOGGLE0186A2" class="image-toggle"

image src="imagename.jpg" border="0"
toggles: alt="imagename.jpg" title="Tooltip text">

Example of style CSS class definitions for toggles

The following example shows you how to format your toggle links and images with a CSS
style definition using the class names listed above. The style definitions are shown
inserted in the standard HTML template for topic pages. The toggle styles are shown in
blue, the other style definitions are for the other hyperlink types in the help.

Sample CSS Definitions for Toggles

<%DOCTYPE%>
<html>
<head>
<title><%TOPIC_TITLE%></title>
<meta name="generator" content="Help &amp; Manual" />
<meta name="keywords" content="<%TOPIC_KEYWORDS%>" />
<meta http-equiv="Content-Type" content="text/html;
charset=<%DOCCHARSET%>" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<link type="text/css" href="<%STYLESHEET%>" rel="stylesheet"
/>

<style type="text/css">
<!-- These are the normal hyperlink styles -->
a { color: #0000FF; text-decoration: none }
a:visited {color: #0000FF }
a:hover {color: #E4641C; text-decoration: underline }
a.weblink {color: #0000FF; text-decoration: underline }
a.weblink:visited {color: #0000FF}
a.weblink:hover {color: #E4641C }
a.popuplink {color: #FF0000; text-decoration: none}

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 363

a.popuplink:visited {color: #FF0000}

a.popuplink:hover {color: #FF0000; text-decoration:
underline}
a.filelink {color: #04BC14; text-decoration: none}
a.filelink:visited {color: #04BC14}
a.filelink:hover {color: #04BC14; text-decoration: underline}
<!-- These are the toggle styles -->
a.dropdown-toggle {color: Navy; text-decoration: none; font-
weight: bold; font-family: "Times New Roman", Times, serif; }
a.drop-down-toggle:visited {color: Navy; }
a.drop-down-toggle:hover {text-decoration: underline}
a.inline-toggle {color: Green; text-decoration: none; font-
weight: bold; font-family: "Times New Roman", Times, serif; }
a.inline-toggle:visited {color: Green; }
a.inline-toggle:hover {text-decoration: underline}
img.image-toggle { border: border-width: 2px; border-color:
red; border-style: solid;}
</style>

</head>
<body style="margin: 0px 0px 0px 0px; background: <%
TOPIC_TEXT_BGCOLOR%>;">
....

See also:
Using HTML Templates 430
About HTML Templates 810
6.2.8 Expand All / Collapse All
You can create special links with which you can allow the user to expand and collapse all the
toggles in the current topic with a single click. There are a number of very useful things you
can do with this feature. For example, it allows you to write help for both novice and
experienced users on the same page. You could then create More Detail / Less Detail
links in the topic header for switching between the two versions. You can also use it to
create a Print button that will pre-expand all the toggles in the current topic before it is
printed.

How to create Expand All and Collapse All links

1. Click in the place where you want to insert the links, for example in the header of your
topic.
2. Select the Link tool in Write > Insert and choose Script/Macro at the top of the
dialog and HTML JavaScript as the script/macro type.
3. Enter the following code in the Script: editing box (you need to create a separate link
for each function):

© 1997 - 2009 by EC Software, all rights reserved

364 Help & Manual 5 - User Help

Expand All: Collapse All:

javascript:HMToggleExpandAll(true) javascript:HMToggleExpandAll
(false)

Adding Expand All and Collapse All links to all pages

To add Expand All / Collapse All links to all your pages you need to insert the
necessary code manually in the HTML template for your pages. You will need some
experience in editing HTML for this. See The topic page templates 433 in the Using HTML
Templates 430 chapter for detailed instructions on how to add code to your topic page
templates.
· Locate the position in the template where you want to insert your links and then insert
the following code (you can change the title text to insert your own tooltips, of
course):

Expand All: Collapse All:

<a href="javascript: <a href="javascript:
HMToggleExpandAll(true)" HMToggleExpandAll(false)"
title="Tooltip text">Expand All</a> title="Tooltip text">Collapse All</
a>

Locating the correct position in the template:

The <%TOPIC_TEXT%> variable in the HTML template inserts the content of your topic
from the editor into the template. This means that everything inserted directly above this
variable is inserted directly before the beginning of your normal topic content, everything
directly below it is inserted directly after the end of your topic content.
The topic header is in the code between the <IF_TOPIC_HEADER> and </
IF_TOPIC_HEADER> tags. The header components are in a table. You may need to add
cells or rows to achieve the effect and positioning you want.

Conditional Expand All and Collapse All

There is a special conditional tag called <IF_TOGGLES> that you can use in your HTML
templates. This condition only evaluates true if the current topic contains one or more
toggles. This means that you can use them to create Expand All / Collapse All links that
will only be displayed in topics containing toggles.
You use this condition just like any other condition in HTML templates. Just enclose the
link code (and any other additional code you are using for the links) in a pair of
<IF_TOGGLES> condition tags, like this:
<IF_TOGGLES><a href="javascript:HMToggleExpandAll(true)" title="Tooltip
text">Expand All</a>
<a href="javascript:HMToggleExpandAll(false)" title="Tooltip
text">Collapse All</a></IF_TOGGLES>

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 365

Creating a Print button that pre-expands your toggles

You can use the Expand All function to create a Print link for HTML Help and Webhelp
that will pre-expand all the toggles in the current topic before printing it. For instructions
Printing topics containing toggles 367 .

See also:
Using HTML Templates 430
The topic page templates 433
About HTML Templates 810
6.2.9 Toggle troubleshooting
Toggles are generally stable and reliable but since they are based on HTML and JavaScript
there are a few things you need to keep in mind when you are using them. Among other
things, toggles only work in formats that support both HTML and JavaScript. They are
converted to static text in all other formats and they are displayed expanded by default in
browsers without JavaScript support or with JavaScript turned off.

Problems with toggle IDs

When you need to enter IDs manually:
The ID field in all three toggle types is optional and we strongly recommend that you
leave it blank unless you have a very good reason for using your own IDs – for example if
you need to access the IDs with your own program code in the output generated by Help
& Manual. If you need to do this you must enter your own IDs manually because the
automatically-assigned IDs may change every time you publish your output.
If you enter your IDs manually you must make sure that there are no conflicts between
them in the same topic. Duplicate IDs in different topics are OK but duplicate IDs within
the same topic will cause problems and malfunctions.
Toggles don't work or clicking on one toggle "toggles" a different toggle:
This can happen if you have duplicate IDs in the same topic when you are entering your
IDs manually. Check all the toggles in the topic for duplicate IDs. Invalid or duplicate IDs
will be displayed highlighted in red in the editor.

Problems with expanding section toggles

Clicking on the header doesn't "toggle" the section:
If you don't have duplicate IDs (see above) you have probably entered more than one
empty paragraph between the toggle header and the toggle table. You can have one
empty paragraph between the two but not more.
Unwanted interaction with other images in the same line as the header:
The toggle header icon is a normal image. If you insert other images directly next to it the
toggle may also attempt to toggle those images. You can usually solve these problems by

© 1997 - 2009 by EC Software, all rights reserved

 366 Help & Manual 5 - User Help

editing the toggle (double-click on the header link) and saving it again with OK.

Problems with formatting in toggle links

The toggle link is broken into several individual links:
This happens when you try to format different parts of the link text differently. You can
format toggle links but you must format the entire text in exactly the same way, otherwise
the link will be broken up.
CSS styles are not applied to the links:
CSS styles 361 will only work if the Link style option is checked in the Edit Toggle 629 dialog.
If this option is not checked you must format the links in the editor, either manually or with
styles.

Image toggles result in larger output files

This is normal because each image toggle must use two images instead of one. In
addition to this you are probably using a larger image for the full-size version than you
would normally use. It is thus advisable to use image toggles sparingly and not to use
images that are larger than absolutely necessary, even in the full-size versions.

Page break problems in PDFs and printed manuals

Help & Manual can create page breaks within table rows and not just at row boundaries.
This means that it is OK to have a large expanding section toggle consisting of just one
big table cell with multiple paragraphs of text and other content.
However, page breaks inside tables may not work correctly if you insert tables inside
other tables. If you want to be sure your pages will break correctly in PDF don't insert
additional tables inside your main toggle tables.

See also:
Formatting toggles with CSS 361
Working with Tables 253
6.2.10 Updating old expanding sections
If you have imported Help & Manual 3 projects with manually-programmed expanding
sections you will probably want to replace them with toggles because they are much easier
to manage.

How to convert your old expanding sections

The new toggles are not compatible with manually-programmed expanding sections so
you need to remove the old expanding sections and replace them with toggles.
Step 1: Remove all the code of the old expanding sections:
1. Check through your HTML template and remove all the code that you added to create

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 367

your expanding sections.

2. In the Project Explorer check Project Files > Baggage Files for any files added for
your expanding sections and delete them.
3. In the Project Explorer check Configuration > Publishing Options > HTML Help
> Extended .HHP Settings for any references added for your expanding sections
and delete them.
4. For each expanding section in your project delete any manually-inserted plain HTML
code blocks in your topics.
Step 2: Create the new expanding section toggles:
1. Create a single-cell table for each expanding section and cut and paste the contents of
your expanding section into the table.
2. Position the cursor in an empty paragraph directly above the table.
3. Select the Insert Toggle tool in Write > Insert Object, then select the Expanding
Text and Toggle a Table: options.
4. In the drop-down box below the Toggle a Table option select Toggle the table below
this link so that the toggle uses the table containing your old expanding section text.

See also:
Expanding section toggles 351
6.2.11 Printing topics containing toggles
You need to do a little planning to make it possible for your users to print topics containing
toggles. Of course, this is only necessary in the formats where toggles are "active" – toggle
printing is not a problem in formats like PDF and Word RTF because the toggles are always
static in these formats, so their entire contents are always printed (provided you have
configured the toggles to be displayed expanded in print mode).
In all formats where dynamic toggles are supported (Webhelp, HTML Help, MS Help 2.0) the
toggles are always printed exactly as they are currently displayed. Expanded toggles are
printed expanded, collapsed toggles are printed collapsed.
Generally, your users will want to print out the entire contents of the topic, including the
contents of all toggles.

Including Expand All and Collapse All links

The simplest method is to provide your user with Expand All / Collapse All links in your
topic header, as explained in the topic Expand All / Collapse 363 all in this chapter. Then
they can click on Expand All before they print.
The disadvantage of this method is that you have to explain it to your users. If they miss
the explanation it may take them a while to figure out what they need to do, and they may
waste a lot of paper in the process.

© 1997 - 2009 by EC Software, all rights reserved

368 Help & Manual 5 - User Help

Creating an auto-expanding Print link

The best solution is a Print link that automatically expands the toggles in the topic. These
are created in exactly the same way as an Expand All link, you just need to add one
more small snippet of code to send the topic to the printer after expanding the toggles:
1. Follow the instructions for creating Expand All links 363 to create a new link in the
location where you want to have your Print link.
2. Create the code for the link as follows:

Code for a Script Link: Code for your HTML template:

javascript:HMToggleExpandAll(true); <a href="javascript:
print(); HMToggleExpandAll(true); print
();">Print this Topic</a>

See Expand All/Collapse All 363 for more detailed instructions on creating Print links and
buttons.

Print link with an icon instead of a text link

You can also use an icon instead of a text link for the Print function. If you use the Link
tool in the Write tab you just need to select Picture as the style and then select an
appropriate printer icon. If you add the link to your HTML template you need to enter the
code manually.
Static icon in the HTML template:
<a href="javascript: HMToggleExpandAll(true); print();">
<img name="printbutton" border="0" alt="Print This Topic" title="Print This
Topic" src="print2.gif"></a>

Icon with a mouseover function in the HTML template:

<a href="javascript: HMToggleExpandAll(true); print();" onmouseover="document.
images.printbutton.src='print1.gif'" onmouseout="document.images.printbutton.
src='print2.gif'">
<img name="printbutton" border="0" alt="Print this Topic" title="Print this
Topic" src="print2.gif"></a>
Add your icon images to the Baggage Files 485 section and replace the image names in
the above code with the filename of your own icon.

Excluding the Print link in unsupported formats

If you also plan to generate Windows Exe or ePub eBooks from your project you must
exclude the Print link there because toggles and JavaScript are not supported in eBooks
(toggles are always displayed as static text, fully expanded).
· If you use script links enclose the links in conditional text 410 tags to make sure that
they are only included in the output formats where dynamic toggles are supported
(HTML Help, Webhelp and MS Help 2.0).

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 369

· If you use links in your HTML templates enclose the link code in a pair of
<IFNOT_EBOOK> </IFNOT_EBOOK> build conditions 415 to make sure that they are
excluded from eBooks. This will work for both Windows Exe and ePub eBooks.

See also:
Using HTML Templates 430
The topic page templates 433
About HTML Templates 810

6.3 Using Context-Sensitive Help

Context-sensitive help is used in software applications, both stand-alone applications and
web applications. It is defined as help relevant to what the user is currently doing in your
application. For example, if the user presses F1 or clicks on a Help button in a dialog they
would see a help topic describing that dialog that is context-sensitive help.
Implementing context-sensitive help takes a little work up front but it will bring considerable
benefits for you in the long run because it will make your product easier to understand for
your users.
The options you have for implementing context-sensitive help depend on your output format,
because different formats support different ways of making calls to your help files.

See also:
Context-Sensitive Help & Popups 788 (Reference)
IDs, Context Numbers and Keywords 801 (Reference)
Creating popup topics 125
Creating topics without TOC entries 112
Organizing invisible topics 210
6.3.1 Context help support by output format
The options you have for implementing context-sensitive help depend on your output format,
because different formats support different ways of making calls to your help files. This topic
lists the different types of context help possible in the output formats supported by Help &
Manual.
For more details on context-sensitive help, the available context-sensitive help technologies
and implementation information for programmers see the Context-Sensitive Help & Popups
788 chapter in the Reference section.

HTML Help and Winhelp

These are the standard Microsoft help formats for Windows applications. They are used
for help installed locally on the user's computer. Winhelp is now obsolete and is not
officially supported in Windows Vista.
Calls to HTML Help (CHM files) and Winhelp (HLP files) are made using the HTML Help
and Winhelp APIs, which are documented in the help files delivered with the free
Microsoft help compilers. For details see Application calls to context-sensitive topics 372 .
Making the calls is up to your programmers; each programming language has different

© 1997 - 2009 by EC Software, all rights reserved

 370 Help & Manual 5 - User Help

methods for doing this. You can download programming tutorials from our website.
Supported context-sensitive help types
· Calls to specific help topics
Display a specific topic in your help, inside the main help window.
· Calls to anchors in specific help topics
Display a specific topic in your help file in the main help window and scroll down to an
anchor 226 (jump target) within the topic.
· Field-level popups
These are small popup windows displayed in your application. They are read from the
help file but the main help window is not opened. Useful for documenting individual
fields and controls in your application (thus the name).
· Training card help
Training card help uses the HTML ActiveX control (CHM) or WinHelp macros (HLP) to
create special interactive links between your help topics and your application. In theory
you can use training card help to create interactive tutorials that guide users through
steps of doing things in your program. In practice it is so difficult to implement that most
developers try it out once and then decide that it is not worth their time. You can insert
ActiveX objects for training card help with Help & Manual's Write > Insert Object >
Plain HTML Code command (HTML Help) or with hyperlinks using Winhelp macros.

Webhelp
Webhelp is displayed in a normal web browser like Firefox, Safari, Opera or even Internet
Explorer. It is used for help accessed on networks and the Internet. Calls to Webhelp are
made with normal URLs 373 .
Supported context-sensitive help types
· Calls to specific help topics
Display a specific topic in your help, inside the main help window.
· Calls to anchors in specific help topics
Display a specific topic in your help file in the main help window and scroll down to an
anchor 226 (jump target) within the topic.

Adobe PDF, eBooks, Word RTF

These print-style formats do not support any real context-sensitive help features. You can
open the help files with a link to the file but that is all. You cannot make calls to individual
topics within the help files.

See also:
Context-Sensitive Help & Popups 788
6.3.2 Creating context-sensitive topics
Context-sensitive help displays a normal topic or a popup topic. Context-sensitive popup
topics are known as "field-level popups" because they are displayed directly in your

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 371

application, not in the main help window. Field-level popups are only supported in HTML
Help and the obsolete Winhelp format. The JavaScript popups used in Webhelp cannot be
used as field-level popups.
As the help author you don't need to do anything special to create context-sensitive topics.
They are simply normal TOC topics and normal popup topics. They become "context-
sensitive" when they are called directly from the application. What makes field-level popup
topics a little different is the fact that they can be called on their own, without the help, but
within the help they are still just the same as other popup topics.
For more background information see the Context-Sensitive Help & Popups 788 chapter in
the Reference section.

How to create a normal context-sensitive topic

Normal context-sensitive topics are simply normal topics in the TOC. Just follow the
instructions in Creating new topics 110 to create a new topic in the TOC.
These topics become context-sensitive topics when they are called directly from the
application. How this is done depends on the programming language and your output
format. For details see Application calls to context-sensitive topics 372 .
Plain text popup topics used in HTML Help must have context numbers! This is required
by the Microsoft HTML Help API for popups and if your popup topics do not have help
context numbers they will not be exported to the internal popup text file in the CHM.

How to create and use field-level popup topics

Field-level popup topics are simply normal popup topics. Just follow the instructions in
Creating popup topics 125 to create and edit popup topics.
Popup mode for field-level popups:
Field-level popup topics are only supported in Winhelp and HTML Help. In HTML Help
you must select Text-only popups in Configuration > Publishing Options > HTML
Help > Popup Topics. There are no special configuration settings for field-level popups
in Winhelp.
Plain text popup topics used in HTML Help must have context numbers! This is required
by the Microsoft HTML Help API for popups and if your popup topics do not have help
context numbers they will not be exported to the internal popup text file in the CHM.
Using field-level popups:
To use field-level popups your programmers must call the popup topic inside the help file
from your application, using the appropriate API calls for HTML Help or Winhelp. The
syntax of these calls depends on your programming language. You can download
tutorials for most current languages from our website. See Application calls to context-
sensitive topics 372 for more details.
Auto-generating your popup topics from a map file:
If your programmers provide you with a "map file" of the topic IDs and context numbers
for the elements in the program that need to be documented you can also generate your

© 1997 - 2009 by EC Software, all rights reserved

 372 Help & Manual 5 - User Help

field-level popup topics automatically! See Auto-generating context-sensitive topics 375 for
details.
Don't use links in field-level popups:
Even in the obsolete Winhelp format where links are supported it is bad practice to use
links in field-level popups. These topics are designed to be viewed, read quickly and then
closed again. If you need to use links it is better to use a normal topic instead of a popup
topic. Then the programmer can make a context call to the normal topic, which will call up
entire help so that the user can browse it.

Popups in HTML Help are plain text only

HTML Help popups 798 are plain-text only, they do not support graphics or formatted text
like the popups in the obsolete Winhelp format. In the past, help authors used to create
HTML Help with an additional Winhelp file for the popups. This approach was known as
"dual-mode help".
Since Winhelp is now obsolete dual-mode help is no longer supported in Help & Manual
because using it makes your help incompatible with Windows Vista.

See also:
Creating popup topics 125
Auto-generating field-level popups 375
Context-Sensitive Help & Popups 788
Organizing invisible topics 210
6.3.3 Application calls to context-sensitive topics
Making the calls to your context-sensitive topics is basically a job for the programmer, not
the help author (you may be both, of course). In the help itself there is no difference
between context-sensitive topics and popups and normal topics and popups – the difference
is how they are called from the application.
The HTML Help CHM files, Winhelp HLP files and Visual Studio Help/Help 2.0 HSX files
generated by Help & Manual are fully standard-compliant so you can use all the standard
procedures for linking to and calling context-sensitive topics.
Context calls to Webhelp are made with regular URLs. For details see Application calls to
Webhelp 373 .

Calls to normal topics in the TOC

These are normal topic calls that open the main help viewer at the topic you are making
the call to. See your programming language's documentation for making calls to the help
format you are using.
See Application calls to Webhelp 373 for details of the URL syntax for making calls to
Webhelp topics.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 373

Calls to Winhelp and HTML Help popups

Application calls to field-level popups are made using the popup interfaces of the
Microsoft HTML Help and Winhelp APIs. The syntax for these calls depends on the
programming language you are using. See the section on tutorials and resources for
programmers below.
Application calls to HTML Help popups can only be made if you use HTML Help's own
plain-text popup format, in which the popup texts are stored in a special plain-text file
inside the CHM file..This option is activated in Configuration > Publishing Options >
HTML Help > Popup Topics in the Project Explorer, where you can also specify the
name of the text file to be generated.
Plain text popup topics used in HTML Help must have context numbers! This is required
by the Microsoft HTML Help API for popups and if your popup topics do not have help
context numbers they will not be exported to the internal popup text file in the CHM.

Tutorials and resources for programmers

· The APIs of HTML Help and the obsolete Winhelp format are fully documented in the
help files delivered with the free Microsoft help compilers for these formats. You can
find them in the program directories of the HTML Help Workshop and Microsoft Help
Workshop compiler packages.
· Tutorials for interfacing between your help and your application in the most major
programming languages are available on the tutorials page at the EC Software
website.
· A free set of tools for interfacing to help and context-sensitive help Borland Delphi and
Borland C++ is also available at the website, on the Delphi resources page.
· The following websites are also highly recommended as good sources of up-to-date
information on interfacing with help files from your application:
The MS Help Wiki
Helpware.net
MSDN HTML Help Reference
The HTML Help Center

See also:
Context-Sensitive Help & Popups 788 (Reference)
6.3.4 Application calls to Webhelp
You can create context-sensitive calls to Webhelp 730 (web HTML) from your application or
web pages with normal URLs using the syntax explained below. These calls can be made
locally, across networks or across the Internet.
Field-level popups are not supported in Webhelp, they can only be implemented with HTML
Help (CHM) or Winhelp (HLP). The JavaScript popups 129 supported in Webhelp can only be
used within your help, you cannot make calls to them from your application or web pages.

© 1997 - 2009 by EC Software, all rights reserved

374 Help & Manual 5 - User Help

How to make calls to Webhelp topics

Calls to Webhelp must be normal URLs, made in the same way as any other URL link
that opens a browser with a specific web location or local HTML file, using exactly the
same syntax:
Calling syntax:
index.html?topicname.htm#anchorname

Examples:
This example uses the standard file names and extensions and accesses an anchor in
the referenced topic:
index.html?introduction.htm#gettingstarted
The following example shows a call to a project that was compiled with both a non-
standard index file name and a non-standard extension for the topic files (see below).
There is no reference to an anchor in this example.
help.html?new_features.html

Elements of the calls:

index.html This is the name of the index file of your Webhelp (this is the default, it
can be changed in the Publish 590 dialog when you compile). If you use
this on its own it will simply display the help system with the standard
home topic.

?topicname. This is the name of the topic you want to display. This is created by
htm combining the topic ID 205 with the extension .htm..
This is the default topic extension, you can change it in Project
Configuration > Publishing Options > Webhelp > HTML
Export Options 684 . (These settings are shared with the other HTML-
based output formats and can also be accessed in the HTML Help and
Visual Studio Help sections.)

#anchorname Optional. This is the name of an anchor 226 in the topic that you want to
jump to.

Calling Webhelp topics without the TOC

Normally, a link to a topic file will automatically display the entire help with the TOC even
if you don't include the index.html part of the URL. This is achieved with a redirect script
in every topic page. However, It is also possible to call just the topic without the TOC if
you want. You do this by adding a simple switch to your URL.
Calling syntax for topic only:
topicname.htm?toc=0#anchorname (with an anchor)
topicname.htm?toc=0 (without an anchor)

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 375

Avoid direct calls to the topic file

Theoretically you don't actually need to include the index.html file in the URL. If you
make a direct call with the format topicname.htm or topicname.htm#anchorname this
will automatically display the entire help system with the Table of Contents.
This is not a good idea, however: Under some circumstances it can confuse the browser
history, making it impossible for users to navigate with the Back and Next buttons.
It is thus always advisable to use the full call including the index file, using the standard
syntax:
index.html?introduction.htm#gettingstarted

See also:
Creating popup topics 125
Context-Sensitive Help & Popups 788
Topic files without TOC entries 210
6.3.5 Auto-generating topic files
Complex applications have a lot of components and controls and if you document them all
with context-sensitive topics this means you need to create a lot of topics. This can be a
very tedious task and it's also easy to make mistakes, because it means entering hundreds
of context numbers and topic IDs that may not have very descriptive names.
Help & Manual can do all this work for you with the help of map files 799 , which are simple text
files containing lists of the topic IDs and help context numbers to be used for documenting
the controls in the program. These files can be provided by the programmers (they can be
generated by most modern programming languages). They have a standard format and
syntax and Help & Manual can use them both to apply missing help context numbers to
existing topics and to generate missing topics with the necessary IDs and help context
numbers.

How to auto-generate your topic files with the map file

1. Obtain the map file from the programmers and make sure that it only contains the
topics you want to use.
Plain text popup topics used in HTML Help must have context numbers so make sure
you include context numbers in your map file! This is required by the Microsoft HTML
Help API for popups and if your popup topics do not have help context numbers they
will not be exported to the internal popup text file in the CHM.
2. Open your project (you might want to make a backup first) and select Project >
Tools > Context Tool:

© 1997 - 2009 by EC Software, all rights reserved

 376 Help & Manual 5 - User Help

3. Click on Import map file... and select the map file. A dialog will be displayed asking you
whether you want to merge or replace the existing numbers
Replace:
This deletes ALL context numbers in the current project and replaces them with the
numbers from the map file.
Merge:
This only replaces the context numbers for topics with matching IDs. All other topics
are left unchanged.
Auto-generating topics:
When you import a map file any topic IDs in the file that don't exist in your project will be
listed in red in the Context Tool editing box. When you click on OK the tool will ask you if
you want to create topic files for these IDs.
If you say yes the files will be created in the Topic Files section, without TOC entries. If
you want to create TOC entries for the new topics you must do this manually. 112

See also:
About map files 799
The Help Context Tool 539

6.4 Using Variables

Variables are used to insert text that may change in your output when you compile your
project. They are ideal for things like program names and version numbers – to update you
then just need to edit the variable definition and recompile. Predefined variables make it
easy to insert things like the current date, the title of your help project and so on.
Variables have no effective length limit you are unlikely to be able to enter more than 2
gigabytes of text in the variable definition fields. User-defined variables can contain either

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 377

plain text or HTML code this allows you to use variables to insert HTML code in your
topics. Help & Manual supports both a wide selection of predefined variables and user-
defined variables.
You can set different values for variables in individual topics and redefine some or all of your
variables with a list of values stored in an external text file when you publish your project.

See also:
Variables in HTML templates 439
Variables and Conditional Output 772 (Reference)
6.4.1 Where you can use variables
The following table provides a quick reference showing where you can use which kinds of
variables.
You can use both HTML variables and plain text variables in all locations. However, whether
or not it makes sense to use HTML variables in all locations depends on the code you use,
of course! In output formats not based on HTML (PDF, RTF, printed manuals, Winhelp) the
text portion of the variables will be extracted automatically.

Location: Supported variables:

Topic text and Plain-text variables:
headers
Global predefined variables and user-defined variables inserted
with the Text Variable tool in Write > Insert Object:
<%VARIABLE_NAME%>
Note that variables typed in manually are not highlighted in the
editor and double-clicking on them will not open the variable
selection list.
HTML variables:
HTML variables inserted in these locations will only insert the
text portion of the HTML code. For example, if the variable
contains:
<a href="http://www.ec-software.com>EC Software
Website</a>
only "EC Software Website" will be inserted. All the HTML code
(blue) will be stripped out. If there is no plain-text portion
nothing will be inserted.

TOC, keywords, image Plain-text variables:

captions, link
captions, macros in
Global predefined variables and user-defined variables inserted
macro links manually by typing the variable names.
HTML variables:
In these locations only the plain-text portion of HTML variable
values will be inserted (see example above). If there is no

© 1997 - 2009 by EC Software, all rights reserved

 378 Help & Manual 5 - User Help

plain-text portion nothing will be inserted.

HTML code objects Plain-text variables:

and scripts in script
links
Global predefined variables and user-defined variables inserted
manually by typing the variable names.
Important: You cannot use HTML template variables 778 in
HTML code objects or script links because the code objects are
parsed together with the topic content, before it is inserted in
the template.
HTML variables:
You can use HTML variables in HTML code objects and scripts
in script links. However, don't use HTML template variables as
part of the variable value because they won't be parsed (see
above).

HTML templates Plain-text variables:

Global predefined variables, user-defined variables and special
HTML template variables inserted manually by typing the
variable names.
HTML variables:
You can use HTML variables without restriction in HTML
templates. The HTML code stored in the variable will be
inserted in the in the template. You can also use HTML
template variables 778 as part of the value of the HTML variable.

PDF templates Plain-text variables:

Global predefined variables, user-defined variables and special
PDF template variables inserted manually by typing the variable
names.
HTML variables:
HTML variables will only insert the plain-text portion of the
variable value in PDF templates. If there is no plain-text portion
nothing will be inserted.

See also:
Variables and Conditional Output 772 (Reference)
6.4.2 User-defined variables
You can define any number of your own variables to use in your project. These user-defined
variables are stored with your project, which means that they are only available to the project
in which they are defined. However, you can transfer variables between projects with the
Export and Import functions (see below).
User-defined variables can be used almost everywhere in your projects: In topics and

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 379

headers, the Table of Contents, keywords, image captions, link captions, macros, scripts,
HTML code objects, HTML templates and PDF templates. See the other topics in this
section for details on using variables in these locations.
See Inserting variables in topics 386 and Inserting variables in other locations 388 for details on
how to use variables in your projects.

Plain-text variables and HTML variables

You can define two different types of variables: Text variables and HTML variables. Both
types have no effective length limit (theoretically you could enter up to 2 gigabytes of
text). See The power of editable variables 395 for more details on using HTML variables.
Plain-text variables:
Plain-text variables contain text only. The text is inserted as plain text wherever you use
the variable. You can use them anywhere where variables are supported.
HTML variables:
HTML variables contain HTML code. They are designed primarily for use in HTML
templates and HTML code objects. If you use an HTML variable anywhere else (for
example in a topic in the Help & Manual editor) only the text portion of the variable value
will be inserted. If there is no text portion nothing will be inserted.

How to define a variable

1. In the Project Manager go to Configuration > Common Properties > Text
Variables.
2. Select Add, enter the name for your variable and click on OK.

You don't need to worry about case, the variable name will be converted to all upper
case automatically.
3. Select HTML or Text in the Type column. HTML Variables can contain HTML,
JavaScript and CSS code in addition to normal text.
4. If you want to protect the variable against accidental editing select Yes in the
Protected column. The values of protected variables are shown grayed out.
5. Click in the Value column next to your new variable and enter the text or HTML code.

© 1997 - 2009 by EC Software, all rights reserved

380 Help & Manual 5 - User Help

There is effectively no limit to the amount of text you can enter you are unlikely to be
able to enter more than 2 gigabytes of text in the Value column!

Variable name syntax

Exactly the same variable name syntax is used for variables in all parts of your projects:
<%VARIABLENAME%>
· Since you can also type variables manually in topic text and topic headers it is
important to observe this syntax! The variable name VARIABLENAME must be in all
upper case and it must be enclosed between opening and closing <% and %> tags.
· Spaces are allowed in variable names because the beginning and end of the variable
are clearly defined by the <% and %> tags. For example:
<%VARIABLE NAME WITH SPACES%>

How to edit user-defined variables

· In the Project Manager go to Configuration > Common Properties > Text
Variables.
OR:
· Double-click on a variable in the editor and select More... to go the Text Variables
configuration screen.

The second option only works with variables entered with Insert > Text Variable.
Variables typed in manually are not highlighted and you cannot display the variables list
by double-clicking on them.

Importing and exporting your user-defined variables

You can use these features to copy variables between projects and to define variables in
a text editor and then load them into your project. (This can be easier than defining a lot
of long variables directly in Help & Manual.)

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 381

Exporting user-defined variables:

1. In the Project Manager go to Configuration > Common Properties > Text
Variables.
2. Select to Export your project variables to a text file.

Importing user-defined variables from a file:

1. Use an editor like Windows Notepad to create a list of variables in a plain text file,
using the following syntax:
VARIABLENAME1=Variable value
MYVARIABLE=another variable value
One variable per line, variable name all in capital letters, no spaces on either side of
the = character, no quotes. You can also enter HTML code for HTML variables, of
course.
2. Import the variables with the Import button in the Text Variables section in your Project
Configuration.
3. If your list includes HTML variables you must manually change the type of the
variables to HTML after importing, otherwise the code will be interpreted as plain text.
Use the Export function (see above) to see an example of the necessary format and the
syntax of the file.
Importing user-defined variables from another project:
You can also import all the user-defined variables from another Help & Manual project.
To do this just click on Copy properties from... at the bottom of the Text Variables editing
window and select the project you want to import the variables from. This will overwrite
the variables in the current project.
If you want to merge the variables from another project you must export them to a text file
and then import them from the text file (see above).

See also:
Variables and Conditional Output 772 (Reference)
6.4.3 Global predefined variables
There are a large number of global predefined variables that you can use to insert items that
you may want to change, for example the title of the project, the copyright note, the date and
time in various formats and the date and time at which the current topic was last edited.
Some of the predefined variables have automatic values, others take their values from the
Configuration section of your project. See Global predefined variables 774 for a list of the
available variables, what they do and where they get their values.
See Inserting variables in topics 386 and Inserting variables in other locations 388 for details on
how to use variables in your projects.

Where you can use global predefined variables

Help & Manual's global predefined variables can be used almost everywhere in your

© 1997 - 2009 by EC Software, all rights reserved

 382 Help & Manual 5 - User Help

projects: In topics and headers, the Table of Contents, keywords, image captions, link
captions, macros, scripts, HTML code objects, HTML templates and PDF templates.
You cannot use HTML code in global variables:
Note that all global variables are plain-text variables so you cannot use them to insert
HTML code. Even if you create an HTML variable and use it as the value of a global
variable only the plain-text portion of the variable will be inserted.
See Inserting variables in topics 386 and Inserting variables in other locations 388 for details
on how to use variables of all kinds in all these locations.

Variable name syntax

Exactly the same variable name syntax is used for variables in all parts of your projects:
<%VARIABLENAME%>
Since you can also type variables manually in topic text and topic headers it is important
to observe this syntax! The variable name VARIABLENAME must be in all upper case
and it must be enclosed between opening and closing <% and %> tags.

See also:
Variables and Conditional Output 772 (Reference)
Global predefined variables 774 (Reference)
6.4.4 Editing, formatting and disabling variables
This topic describes how to edit variables in the Help & Manual editor, how to format the
content of variables in your output (i.e. with bold text or text styles) and how to disable
variables so that the variable name is displayed in your output instead of the content of the
variable.

HTML variables and plain text variables

You can create user-defined variables in two modes: As plain text or as HTML code. If
you set the variable to HTML mode you can include any HTML code, JavaScript and CSS
you like as long as the syntax is correct. You are responsible for this no syntax
checking is performed!
HTML variables will only insert the full HTML code in HTML templates and HTML code
objects. In other locations only the plain-text portion of the variable value will be inserted.
If there is no plain-text portion nothing will be inserted.

How to edit the values of variables

In the Project Explorer go to Configuration > Common Properties > Text Variables
and edit the values of the variables in the list. If the variable value is grayed out it is
protected and you must first unprotect it by setting the protected switch to No in the
Protected column.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 383

You can also double-click on a highlighted button variable in the editor and then select
More... to display the variable editing window. (This is not possible with manually-typed
variables without a button highlight.)

How to edit the names of variables

You cannot edit the names of variables in your variable definitions – they are fixed there
and to "edit" the name you need to create a new variable with the desired new name.
This section is about editing the names of variables that you have inserted in the topics in
your project.
Variables in your project are actually always just plain text variable names identified by
the tag delimiters <% and %>. When you use the Insert > Text Variable function the
variables are displayed as highlighted buttons for easy identification and you can double-
click on them to display the variables list, but this is just for convenience.
You can also type in variables manually. The clickable highlight is just an editing
convenience to make the variables easier to see and use.
Editing the names of variables inserted with the Variable tool:
· To edit a variable name just click once inside the highlighted variable name and type.
(If you change the variable to one that does not exist it will not work, of course...)

© 1997 - 2009 by EC Software, all rights reserved

384 Help & Manual 5 - User Help

· To display the variables list double-click on the highlighted variable in the editor. If
you then select a different variable from the list it will replace the original variable in the
editor.

Editing the names of variables typed manually:

Variables typed manually are normal text and their names can be edited normally. They
cannot be highlighted and you cannot double-click on them to display the variables list.
Highlighted variables at the beginning of a paragraph:
If a highlighted variable is at the beginning of a paragraph you can't insert any text before
it; all the text you type to the left of the variable will also be highlighted. Here is how to
solve this problem:
1. Click to the left of the variable and press Enter to create a new paragraph.
2. Press the space bar followed by Backspace and type your text.
3. Click to the right of the new text and press Delete to bring the variable up into the
same paragraph.
If you type text instead of pressing the space bar it will be highlighted as a variable. To
correct this just right-click on the highlight and select Convert to plain text.

How to use formatting and styles with variables

The values of variables are stored as plain text, without any formatting information.
However, you can easily turn the content of variables into formatted text with bold,
underline or styles in your output by formatting the variable name in the Help & Manual
editor.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 385

Formatting variables manually:

1. Select the variable in the editor so that the entire variable is highlighted. This is the
same for both variables typed manually and variables inserted with the Text Variable
tool in Write > Insert Object.

Formatting the variable formats the variable

contents in your published output.
Be careful to select the entire variable – if you only format part of the variable it can no
longer be identified correctly by the compiler!
2. Use the formatting options in Write > Font to format the variable. For example, if you
format the variable with bold and italic the variable's value will be bold and italic in your
output.
Formatting variables with styles:
If you include variables in paragraphs that use paragraph and font styles you don't need
to do anything – the variables' values will automatically be formatted like the rest of the
text in the paragraph.
If you have defined text-only styles (see Defining styles 161 ) you can apply them to
variables:
1. Select the variable in the editor so that the entire variable is highlighted (this is the
same for both variables typed manually and variables inserted with Insert > Text
Variable).
Here too, be extremely careful to select the entire variable – if you only format part of
the variable it can no longer be identified correctly by the compiler!
2. Apply your text-only style by selecting it in the style selector in the Toolbar, pressing
the hotkey combination you have defined for the style or by selecting Format >
Format with Style.

How to disable variables

Sometimes you may want to include the variables themselves rather than their values in
your output. For example, this was necessary in this help in all the places where
examples of the variables are displayed if we had not disabled the variables here the
values of the variables would have been displayed and the examples wouldn't have made
much sense!
· To disable variables just type a \ backslash character between the opening <% tag
delimiter and the variable name. This works in exactly the same way for all variables
anywhere in your project. It also works both for the green highlighted variables inserted
with Insert > Text Variable and variables typed in manually.

© 1997 - 2009 by EC Software, all rights reserved

 386 Help & Manual 5 - User Help

· Note that you only need to disable variables that are actually defined in the place where
you are using them. You don't need to use the backslash character to disable
undefined variables or for variables that are not supported where you are using them.
For example, if you type the special HTML template variables 778 in a topic the variable
names will always be displayed in the output because they are not defined there.
· To also include the backslash character as shown in the examples below just type two
backslash characters!
Examples:
To enter the backslash in highlighted variables just click inside
the variable and start typing.
<%\TIMELONG%> All the examples on the left were typed with two backslashes
<%\NOW%> inside the variable to show how they are entered in the editor.
With a single backslash you would simply see the variable name
<%\AUTHOR%> in the output.
<%TOPIC_TEXT%> These two examples were entered without backslashes. They
<%FANTASY_VARIABLE%> do not need to be disabled because they are not supported in
normal topics – the first is a HTML template variable, the second
is simply undefined.

How to disable the variable highlight

The highlight displayed for variables inserted with Insert > Text Variable uses the
same system as the highlighting used for hyperlinks. You can turn the highlight off by
right-clicking on the variable and selecting Convert to plain text in the context menu
displayed.
The variable will still work when you do this, but it is then just like a manually-typed
variable. You can no longer-double click on it to display the variables list.
This is not reversible! You can undo it with Ctrl+Z or Undo in Write > Editing directly
after making the change but later you cannot convert an non-highlighted variable to a
highlighted one. The only alternative is to re-enter the variable with Insert > Text
Variable.

See also:
Variables and Conditional Output 772 (Reference)
6.4.5 Inserting variables in topics and headers
You can use both Help & Manual's predefined variables and your own user-defined variables
in your topics and topic headers. These are all displayed automatically in the Insert Text
Variable 627 dialog so you don't need to refer to a list to use them.
If you use HTML variables in your topics and headers only the plain-text portion of the
variable value will be inserted. If the variable does not contain a plain-text portion nothing will
be inserted.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 387

How to insert and edit variables with the Variables Tool

The procedure is identical for predefined variables and user-defined variables. They are
all displayed together in the same dialog:
1. Click in the editor where you want to insert the variable, either in the text or the topic
header above the text.
2. Select Write > Insert Object > or press Ctrl+T.

3. Select the variable you want to use from the list and click on OK (or just double-click
on the variable in the list).
Variables inserted with this method are displayed with a button-style highlight like this:
This is only to make the variable easier to see in the editor. Variables
typed in manually (see below) are also fully functional.See Variables and Conditional
Output 772 for lists of the available predefined variables and what they do.
Editing highlighted variables:
Double-clicking on a variable opens the Insert Variable 627 dialog with which you can
change the variable to a different variable or access the Edit Variables dialog by clicking
on More...

How to type in variables manually

Variables can also be typed in manually in topics and headers. They are evaluated
automatically when you publish your output and work in exactly the same way as
variables entered with the Insert Variable dialog.
· Just type in the variable exactly as it appears in the variable list. Use all upper-case
characters, and enclose the variable name in <% and %> tag delimiters. Spaces are
permitted in variable names.
· Example: This sentence contains a <%USER_DEFINED_VARIABLE%> typed in
manually.
Variables inserted with this method are not highlighted in the topic text and you cannot
double-click on them to open the Edit Variables dialog. Also, if you make a mistake when

© 1997 - 2009 by EC Software, all rights reserved

 388 Help & Manual 5 - User Help

you type the name of a variable it won't work!

Date and time formatting in variables

A number of the predefined variables in Help & Manual like <%NOW%> and <%
TOPICLASTEDITED%> enter the current date or time or the date or time associated with an
item in your project. Normally these variables will automatically use the date and time
format set in your Windows configuration. However, you can also define the date format
by adding a format string to the variable in parentheses like this:
<%NOW(dddd, mmmm d, yyyy)%>
See Date & time formatting in variables 776 for details of the syntax.
Note that this only works with variables that return date and time values, if you add format
strings to any other variables the variable will no longer work. Also, you can only use this
option by editing variables in the Help & Manual editor you cannot use the date and
time formatting syntax in variable definitions.

See also:
Variables and Conditional Output 772 (Reference)
Where you can use variables 377
Editing, formatting and disabling variables 382
Date & time formatting in variables 776
6.4.6 Inserting variables in other project locations
You can also use all the global predefined variables and your own user-defined variables in
the captions in the Table of Contents, keywords, image captions, link captions, macros and
scripts, HTML code objects, HTML templates, PDF print manual templates and text entry
fields in your project's Configuration section.
There is one difference, however: In all these locations you cannot use the Write > Insert
Object > tool, you must type the variables in manually.
If you use HTML variables anywhere except in HTML templates and HTML code objects
only the plain-text portion of the variable value will be inserted. If the variable does not
contain a plain-text portion nothing will be inserted.

How to display available variables

· Go to Configuration > Common Properties > Text Variables in the Project
Explorer to view and edit your user-defined variables.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 389

· See global predefined variables 774 for a list of the available predefined variables.

How to use variables in the TOC

1. In the Project Explorer, click on the TOC entry you want to edit and press F2 to
activate caption editing.
2. The variable insertion dialog used in topics is not available here! Type in the variable
exactly as it appears in the variable list.
Examples:
<%DATELONG%> A predefined variable (the date in long format)
<%MYPROJECT% A user-defined variable
>

How to use variables in keywords

Text variables are supported both in normal index keywords and in A-keywords.
· The procedure here is exactly the same: Just type in the variable, entering it exactly as
it is listed, complete with the opening <% tag and the closing %> tag.
See Keywords and Indexes 273 for details on editing and using keywords.

How to use variables in image captions

1. Double-click on the graphic in the editor to open its properties dialog.
2. Type in the variable in the Image Caption field, entering it exactly as it is listed,
complete with the opening <% tag and the closing %> tag.

How to use variables in link captions

You can also use text variables in link captions, i.e. the texts of hyperlinks shown in your
topics. You can edit these directly, just by clicking once in the caption and typing, but it is
still a little easier to double-click on the link to edit it in its properties dialog.

© 1997 - 2009 by EC Software, all rights reserved

390 Help & Manual 5 - User Help

1. Double-click on the link to display the Hyperlink dialog 617 .

2. Type in the variable in the Caption: field, entering it exactly as it is listed, complete with
the opening <% tag and the closing %> tag.

How to use variables in macros and scripts

You can also use text variables in macros and scripts inserted in macro and script links
and graphics hotspots.
HTML variables are supported in scripts.
· Just follow the instructions for inserting macros and scripts in macro and script links 223
and graphics hotspots 246 and type the variable in the Script: editing field in the place
where you want to use it, entering it exactly as it is listed, complete with the opening <%
tag and the closing %> tag.

How to use text variables in HTML code objects

Both text variables and HTML variables are also supported in HTML code objects 231
inserted with tool in Write > Insert Object.
· Here too, just type in the variable in the code object using the standard syntax and the
opening and closing <% and %> tags around the variable name (spaces are permitted in
variable names). The variables will be parsed and replaced automatically when you
compile your project.
Remember that no syntax checking is performed on the contents of HTML code objects;
you are entirely responsible for the proper syntax and structure of your HTML code!
Important: You cannot use HTML template variables 778 in HTML code objects because
the code objects are parsed together with the topic content, before it is inserted in the
template.
See The power of editable variables 395 for some powerful additional features available
with HTML variables!

Date and time formatting in variables

A number of the predefined variables in Help & Manual like <%NOW%> and <%
TOPICLASTEDITED%> enter the current date or time or the date or time associated with an
item in your project. Normally these variables will automatically use the date and time
format set in your Windows configuration. However, you can also define the date format
by adding a format string to the variable in parentheses like this:
<%NOW(dddd, mmmm d, yyyy)%>
See Date & time formatting in variables 776 for details of the syntax.
Note that this only works with variables that return date and time values, if you add format
strings to any other variables the variable will no longer work. Also, you can only use this
option by editing variables in the Help & Manual editor you cannot use the date and

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 391

time formatting syntax in variable definitions.

See also:
Variables and Conditional Output 772 (Reference)
6.4.7 Counter variables for numbering
You can define counter variables to number anything in your project that needs consecutive
numbering for example illustrations, figures, tables and so on. You can define as many
different counter variables as you like and you can define the starting number to be used for
each variable, which makes it possible to use the variables across multiple projects.

Key Information
If you use a counter variable inside topic
captions you must only use it in topic
captions. If you use it both in captions and
in normal topic text the numbering will be
wrong. (Variables in captions are evaluated
in a separate pass when you publish.)

Restrictions of counter variables

In their present form counter variables are quite simple. They will provide you with
continuous numbering but that is all. You cannot "refer" to them with variables in
references like "See Figure XX". This and other features are planned for future updates.

How to define counter variables

Counter variables are identified by two ++ characters at the end of the variable name.
Otherwise counter variables can have any name you like, just like normal user-defined
variables.
The value of the variable is the number before the number you want to start with. This
means if you want to start with 1 you must enter "0". If you want to start with 10 you must
enter "9" and so on (without the quotes).
1. Define a text variable with two + characters at the end of its name, for example
IMAGENO++, FIGURE++ and so on.
2. Set the value of the variable to 0 if you want to start counting at 1, to 89 if you want to
start counting with 90 and so on. (Always one less than the number you want to use,
the value is always incremented whenever the variable is used.)

How to use counter variables

Just insert the variable in the place where you want the count to be displayed. Each time
you use the same variable the variable's last value will be increased by 1. For example, to
number your images just type the counter variable in the image caption field of the Insert
Image dialog with appropriate text, for example

© 1997 - 2009 by EC Software, all rights reserved

 392 Help & Manual 5 - User Help

The Insert Image dialog (select Write > Insert > Image, or double-click an existing image
to display)

Variables in image captions:

Counter variables in image captions are evaluated in a separate pass when you compile.
This means that if you use a counter variable in an image caption you must never use the
same variable anywhere else in the current project you can only use that variable in
image captions. If you also use the variable in other locations the count will be incorrect.

Using counter variables in modular projects

You can use these variables in modular projects. You just need to reset the starting value
of the variables in your child projects if you are using runtime merging for HTML Help or
Winhelp.
Publish time merging:
If you are using publish time merging you just need to define the variable in the master
project and then use it throughout all your projects. Publish time merging is the only
option available for all formats except HTML Help and Winhelp. In HTML Help and
Winhelp you can choose either publish time merging or runtime merging,
Runtime merging in HTML Help and Winhelp:
If you are using runtime merging for your HTML Help or Winhelp output you must define
the correct starting values for each variable in the child projects. To do this you need to
check the final value in the preceding project and set the starting value to that value.
For example, if the final value of your IMAGENO++ variable in Project A is 63 you need to
define the value of IMAGENO++ in Project B as 63. Then the value will be incremented
correctly to 64 the first time you use the variable in Project B.

See also:
Working with Modular Help Systems 446
6.4.8 Find and replace variables
You find and replace text variables in exactly the same way as you would find and replace
normal text. You can replace variables with variables, normal text with variables and
variables with normal text.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 393

How to find and replace variables

1. Select Find & Replace 141 in the Edit menu.
2. To search for a variable or replace text with a variable enter:
<% + VARIABLENAME + %>
For example if your variable is called DEMOBUILD you would type:
<%DEMOBUILD%>
When you insert or replace variables with Find and Replace the variables are not
highlighted in the topic text. This is exactly the same as typing in variables manually 386 –
the variables are still fully functional, they are just not highlighted in the text. (The
highlight is just an editing convenience to make the variables easier to see.)

See also:
Variables and Conditional Output 772 (Reference)
6.4.9 Variables in HTML templates
The HTML templates that generate the pages in Help & Manual's HTML-based output
formats (HTML Help, Webhelp, Windows Exe and ePub eBooks and Visual Studio Help)
make extensive use of variables. You can use all global predefined variables and all your
user-defined variables in your HTML templates
There are also a number of special predefined variables for use in these templates only. For
details on these variables and how to use them see Variables in HTML templates 439 .

HTML variables in HTML templates

HTML variables are primarily designed for use in HTML templates and HTML code
objects you can use them in other locations but then only the text portion of the variable
value will be inserted.
The code stored in the HTML variable must make sense in the template, of course, you
are entirely responsible for that!

Don't edit HTML templates if you don't understand HTML!

Any changes you make to the HTML templates are not checked for plausibility or syntax
errors. You are entirely responsible for all the code you enter and all the changes you
make. Making changes to the template code without knowing what you are doing can
cause serious errors and malfunctions.

See also:
Using HTML Templates 430
Variables in HTML templates 439
Conditional output in HTML templates 441
The power of editable variables 395

© 1997 - 2009 by EC Software, all rights reserved

 394 Help & Manual 5 - User Help

6.4.10 Redefining variables

You can always change the definitions of your variables individually in Configuration >
Common Properties > Text Variables in the Project Explorer. In addition to this you can
set different values for specific variables in individual topics. When you publish your project
you can also redefine some or all of the variables in your entire project with a project skin or
a variable definitions file.

How to redefine variables in individual topics

If you want a variable to have a different value in individual topics you can redefine it in
the tab of the corresponding topics. Note that this is only possible with user-defined
variables. You cannot define Help & Manual's standard variables with this feature.
1. Select the topic in the Project Explorer, then select the tab behind the main editor
window.

2. Click on the + button next to the Topic Variables box at the bottom of the window.
3. Select the variable you want to redefine and click OK, this adds the variable to the
Topic Variables list.
4. Click in the Value field and enter a new value. The values you enter here will only be
used in the current topic.
See The power of editable variables 395 for more information on the kind of things you can
do with this feature.

How to redefine some or all variables when you publish

When you publish your project you can redefine some or all of the variables in the entire
project in two different ways: With "skins" and with the command line compilation feature.
Redefining your variables with skins:
1. Create a project skin (only possible with Help & Manual Professional) containing the
alternative definitions of your variables (and anything else you want to change in your
project). If you only want to redefine your variables you can create a skin that only
contains your variable definitions. See Transforming Your Output with Skins 321 for
more details.
2. When you publish your project 313 to an HTML-based output format select the skin file
in the Publish 590 dialog.
Note that skins can't be selected in the Publish dialog in non-HTML formats you need to
use command line compiling (see below) for those formats where skins are not directly
available.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 395

Redefining your variables from the command line:

You can also create a simple text file containing a list of definitions of the variables you
want to change. You can then specify this file in the command line to redefine all the
variables in your project with the values in the file.
In addition to this you can also specify a project skin file in the command line, to apply a
completely different appearance to the entire project as well as redefining the variables.
For more details on using these features see Skins & redefining variables 478 in the
Command Line chapter and Transforming Your Output with Skins 321 .

See also:
Variables and Conditional Output 772 (Reference)
Transforming Your Output with Skins 321
Command Line Options 466
Skins & redefining variables 478
6.4.11 The power of editable variables
Help & Manual's variables have two features that make them extremely powerful and
flexible:
· You can define variables as HTML variables or as plain-text variables
· You can redefine user variables on a per-topic basis
These two features are particularly powerful when you are generating HTML-based output.
For example, you can perform search engine optimization on a per-topic basis and you can
add individual JavaScript code to the HTML templates of every topic. We are sure that you
will come up with additional uses for this powerful feature experiment!

Key Information
HTML variables only insert HTML code in
HTML templates and HTML code objects.
If you insert an HTML variable in the body
of your topic only the text portion of the
variable value will be used.

How to use editable variables

Note that you can redefine both user-defined variables and global variables on a per-topic
basis with this method.
1. Define an HTML or plain-text variable.
2. Insert the variable in a topic, an HTML template or an HTML code object.
3. Select a topic in the Project Explorer, select the tab and redefine the variable in the
Topic Variables table just click on the + button, select the variable you want to
redefine and then enter a new value for it.

© 1997 - 2009 by EC Software, all rights reserved

396 Help & Manual 5 - User Help

The value you enter for the variable in the tab will be used in all output formats, but only
in the current topic. This is rather trivial when you are just using variables in your topic
text but becomes very powerful in HTML templates.

How to do per-topic search engine optimization

All your topic keywords are automatically included in your topic page head section in a
<meta> keywords tag. However you may want to add additional meta information yourself
to fine-tune your site's search engine performance. You can do this with editable HTML
variables. This simple example shows you how to do this.
1. Define an HTML variable and enter the HTML code for your meta tag as the variable's
value, for example:
<meta name="description" content="<%TOPIC_HEADER_TEXT%>" />

Using the <%TOPIC_HEADER_TEXT%> variable as the default value for the content
attribute means that you won't have to edit the description for every single topic, just
for the topics where you want to include additional information in the description.
2. Insert the variable in the <head> section of your HTML topic page template in the
position where you want to insert the meta tag (see Using HTML Templates 430 for
details). Let's assume you have called the variable <%METADSCR%>:
<head>
<title><%TOPIC_TITLE%></title>
<meta name="generator" content="Help &amp; Manual" />
<%METADSCR%>
...
If you do nothing else every topic will now contain the text from the topic header as the
meta description text. Next you want to redefine this text for individual topics.
3. In the Project Explorer select the topic for which you want to redefine the meta tag.
Select the tab, click on +, select the <%METADSCR%> variable from the list and then
enter the new code that you want to insert. That's it. (Using words defined as
keywords in the description is often helpful.)

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 397

This is a very simple example that just demonstrates the basic principle. Variables are so
flexible that you can find a number of different ways of doing this: For example, instead of
using an HTML variable for the entire line of code you could define <%METADSCR%> as a
plain-text variable, enter <%TOPIC_HEADER_TEXT%> as its value and use it like this:
<meta name="description" content="<%METADSCR%>" />
If you do nothing the topic header text is still inserted as the description. To redefine the
content for individual topics you then just need to enter the new description text, not the
entire line of code.

How to insert individual script code in topics

When you add your own JavaScript functions to your topics it is generally good practice
to add the functions to the <head> section of your HTML page template and call the
functions from within the topic with HTML code objects 231 inserted in the topic. If you
need different code functions in individual topics you can achieve this with editable
variables.
Variables containing the actual code:
This assumes that you are going to insert the entire body of your JavaScript code in the
<head> section of your HTML topic page template.
1. Define an HTML variable and paste your entire JavaScript code block in as the
variable value, including the opening and closing <script> tags if appropriate.
You can insert as much code as you like but it cannot include line breaks so you must
use semicolons to terminate all statements and then remove all line breaks in your
editor with search and replace before copying and pasting.
2. Insert the variable in the appropriate position in your HTML topic page template (see
Using HTML Templates 430 for details). For example, suppose you want to add a block
of code with a variable called <%JS_USERPOLL%>:
<meta http-equiv="Content-Style-Type" content="text/css" />
<link type="text/css" href="<%STYLESHEET%>" rel="stylesheet" />
<%JS_USERPOLL%>
</head>
3. To redefine the code for an individual topic select the topic in the Project Explorer and
select the tab. Then click on +, select the <%JS_USERPOLL%> variable from the list and
paste in the new code that you want to insert as the new variable value. That's it.
Of course, you could also use variables within your JavaScript code to replace just part of
the code on a per-topic basis.

© 1997 - 2009 by EC Software, all rights reserved

398 Help & Manual 5 - User Help

Variables containing a reference to a .js file:

This assumes your code is contained in an external .js file that you are referencing in
your HTML topic page template.
1. Save the different versions of your JavaScript code in text files with the extension .js
and add all the files to your Baggage Files 485 to ensure that they will be exported
correctly when you publish your project.
2. Define a plain-text variable and enter the name of the main JavaScript file (the one
that will be used in most topics) as the variable value.
3. Add the include reference to your HTML topic page template (see Using HTML
Templates 430 for details) and use the variable instead of the name of the JavaScript
file . For example, suppose the variable is called <%JS_FUNCS%>:
<meta http-equiv="Content-Style-Type" content="text/css" />
<link type="text/css" href="<%STYLESHEET%>" rel="stylesheet" />
<script type="text/javascript" src="<%JS_FUNCS%>"></script>
</head>
4. To select a different JavaScript file for an individual topic select the topic in the Project
Explorer and select the tab. Then click on +, select the <%JS_FUNCS%> variable from
the list and enter the name of the alternative JavaScript file as the new variable value.
That's it.

Redefining the <title> tag and template variables

The <title> tag:
You can redefine the current topic's <title> tag directly in the tab, in the <TITLE> Tag:
field. The contents of this field are normally the same as the topic caption from the Table
of Contents but if you edit it here the edited version will be inserted in the <title> tag in
your HTML-based output, and this too can be useful for search engine optimization.
Other redefinable template variables:
Note that you can also redefine a number of HTML template variables on a per-topic
basis with the Topic Variables section in . For example you can also redefine <%
TOPIC_TITLE%> (normally returns the TOC caption of the topic), <%TOPIC_TITLE_PATH%>
(the path to the current topic in the TOC of the project) and <%TOPIC_HEADER_TEXT%>
(the text from the header box above the editor).
See HTML template variables 778 in the Reference section for more details of the
specialized HTML template variables available.

How to redefine all your variables

You can also take redefining variables a step further: You can redefine all the variables in
your entire project when you publish with a project skin or variable definition file.
For full details on this see Transforming your output with skins 321 and Skins & redefining
variables 478 . The skins method can be used from the Publish dialog and it can also apply
a completely different layout and style to your entire project. The variable definition file

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 399

method can only be used from the command line but it can also be used to redefine
global variables, which is not possible with the skin method.

See also:
Redefining variables 394
Transforming your output with skins 321
Skins & redefining variables 478
HTML template variables 778 (reference)
6.4.12 Variables in PDF templates
You also can use all the global predefined variables and your user-defined variables in text
objects in your PDF templates.
In addition to this there are large number of special predefined variables for use in PDF
templates only. These are described in the help of the Print Manual Designer program used
to edit the PDF templates that control the formatting of your PDF output and printed
manuals.
To start this program select Project > Tools > Manual Designer or go to Configuration
> -Format Settings > Adobe PDF > PDF Layout and click on the Design button. The
second option is preferable because this automatically opens the print manual template
currently associated with your project.

How to use text variables in PDF print manual templates

Just type the variable into the text of the text object. Always type the variables exactly as
listed, complete with the opening <% tag and the closing %> tag – for example <%TITLE%>
or <%VERSION%>.
· For more details see the help included with the Print Manual Designer program.
· HTML variables will work without modification in PDF documents but they will only
insert the plain-text portion of the variable value – if there is no plain-text portion
nothing will be inserted.

See also:
PDF and print manual templates 425
PDF and Printed Manuals 325

6.5 Conditions and Customized Output

There are many situations where you may want to generate different output versions of your
projects with different content. You might need different versions of your documentation for
light and professional versions of a program, or specific products might have different
names in different versions.
It is also often necessary to change your content to adapt it to the output format – for
example, things that you can write in the electronic HTML Help version of the help might not
make sense or might need to be expressed or formatted differently in the PDF print version.

See also:
Using Variables 376

© 1997 - 2009 by EC Software, all rights reserved

 400 Help & Manual 5 - User Help

Variables and Conditional Output 772

Conditional output in HTML templates 441
6.5.1 How conditional output works
Help & Manual projects are made up of chapters, topics and the content of topics. You can
use conditional output to include or exclude content on all three levels entire chapters,
topics or specific content within topics. You do this by "tagging" chapters, topics and content
with conditions known as "include conditions" or "build conditions". Then when you publish
your project you select or deselect the matching tags in the Publish dialog 590 to include or
include the tagged content.
This is a two-step process, which is outlined below. For full details please study the rest of
this chapter.

Step 1: Tag your content with include conditions

This step identifies the content you want to include or exclude when you publish. You can
tag the content with format conditions (PDF, CHM, HTML etc) or user-defined conditions
(for example DEMOBUILD, BILLS_VERSION, FUTURE_FUNCTIONS you can define
any condition tag name you like).
Tagging content in topics
This is done with the Conditional Text Tool in Write > Insert Object. This tool
places "conditional text" tags at the beginning and end of the content you want to include
or exclude, using an IF ... END syntax. For example IF_PDF ..... END, or IF_PDF,
HTML,CHM ... END and so on

Tagging topics and chapters

This is done with the Change > Include in Builds settings in Project > Manage Topics.
These settings can also be accessed by right-clicking on topics in the Table of Contents
or Topic Files sections of the Project Explorer.
If you tag a chapter with build conditions the tags will also be set for all the chapter's sub-
topics.

Step 2: Select the include options when you publish

When you publish your project you then select or deselect the available include options in
the Publish dialog. Format conditions are selected automatically, so if you are compiling
to PDF all content tagged with IF_PDF will be included in your output.
User-defined conditions must be selected manually: For example, to include all content
identified with DEMOBUILD you need to select the DEMOBUILD option in the Publish
dialog, and to exclude it from your output you deselect it.

6.5.2 About include options

Using include options gives you very fine control over what you include and exclude in your
published output. You can "tag" chapters, topics and content within your topics with these
conditions.
When you generate your output you then select the corresponding include options in the
Publish 590 dialog to include or exclude the items tagged with those options from your

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 401

published output.

Including/excluding topics and content

You can tag both topics and content within topics with include options.
· Topics are tagged with Change > Include in Builds in Project > Manage Topics.
· Content is tagged with the Conditional Text tool in Write > Insert Object.

Format include options and user-defined include options

There are two different kinds of include options, those based on your publishing format
and those defined by the user. The format-based options are used to create different
versions on the basis of your output format for example alternative text for the PDF
version. The user-defined options are used to create fundamentally different versions of
your project for example for different versions of your product or for different customer
groups.
Format-based include options:
These include options are predefined. They correspond to the output formats supported
by Help & Manual. For example, if you tag an item or topic content with the HTML Help
option it will only be included when you publish to HTML Help.
User-defined include options:
These include options are conditions that you define yourself. You can define as many of
them as you want. You can tag text and topics with them in exactly the same way as with
the format-based options. They are defined in Configuration > Common Properties
> Custom Builds.
When you tag content with a user-defined include option it will only be included in your
output if you activate the corresponding option in the Publish 590 dialog. Otherwise it will be
excluded.

Other conditional output features

In addition to include options you can also control and vary your output with variables 376 ,
HTML template conditions 415 and modular projects 446 .
For more background information see the Variables & Conditional Output 772 chapter in
the reference section.

Important: Include options use OR logic

The most important thing to understand is that conditions use OR logic. This means that
only one condition needs to evaluate true to include or exclude the content it refers to. If
multiple conditions apply the corresponding content will also be included but only one
condition is needed.

© 1997 - 2009 by EC Software, all rights reserved

 402 Help & Manual 5 - User Help

This means you need to be careful with tagging using multiple conditions. For example, if
you tag a topic for both CHM (HTML Help) and TEST_BUILD you will never be able to
exclude that topic from your HTML Help output, because the CHM tag will always include
it.
Topics and chapters:
· By default, all new topics are tagged with the option ALL Builds. This means that they
will always be included.
· If you tag a topic with a format condition (e.g. CHM) that topic will only be included in
that output format.
· If you tag a topic with a format condition (e.g. CHM) and a user-defined condition (e.g.
TEST_BUILD) that topic will always be included in the matching output format. In
addition to that, it will also be included in any other output formats when you activate
the corresponding include option in the Publish 590 dialog.
· IFNOT simply reverses the logic – IFNOT CHM includes content in all formats except
HTML Help.
Content in topics
· By default all topic content is included in all output unless it is explicitly excluded with
conditional text tags.
· Tagging content with a format condition only includes that content in that output format.
· Tagging content with a user-defined condition only includes that content when the
matching condition is activated in the Publish 590 dialog.
· Here too, IFNOT reverses the logic – IFNOT HTML includes the tagged content in all
formats except Webhelp.

6.5.3 Using conditional output

Conditional output works in the same way on all the levels where it is supported: You mark a
part of your project (text, graphic, topic, chapter etc.) with a condition, referred to as an
"include option" or "build option", and then choose whether you want to apply the condition
when you publish your project.

Step 1: Tag topics or content with conditions

Tag a topic or chapter
1. Select the topic or chapter in the TOC in the Project Explorer.
2. Select Change > Include in Builds in Project > Manage Topics and select the
conditions you want to apply. (You can also access these options by right-clicking on a
topic in the Project Explorer.)
3. If you are excluding a topic right-click on the topic entry in the TOC and select Check
Referrers to see whether any other topics link to the topic you want to exclude. If so,
you need to use the Conditional Text tool (see below) to exclude any links to the topic
and replace them with alternative text when the topic they link to is excluded.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 403

When you tag chapters all their sub-topics will be tagged with the same conditions
automatically. See Topic include options 407 for full details.
Tag content in a topic
1. Select the text you want to tag in the editor.
2. Select the Conditional Text tool with Write > Insert Object > and choose the
options you want to apply.
See Conditional text include options for full details 410 .

Step 2: Activate the condition when you publish

When you publish your project select the include options that you want to apply in the
Publish 590 dialog, in the Include Options box on the right. You can choose to apply
individual options, combinations of options, all options or no options for every compile
run.
Include options based on output format are activated automatically when you select that
format. For example, when you compile to HTML Help the HTML Help include option is
activated.
Remember that include options use OR logic! The content will be included if one or more
of the selected include options applies when you publish.

How to "filter" topics by build/include options

You can use include options to "filter" the display of your topics in the TOC and Topic
Files section of the Project Explorer. This makes it possible for you to see only the topics
that will be included in a specific build, so that you can preview the results of specific build
options without publishing your project.
1. Apply build options to one or more topics if you don't do this filtering will not have any
effect! See Conditions and Customized Output 399 for details.
2. Select Explore > Filter in Project > Manage Topics and set the filter options you
want to apply. The filter settings are also available from the right-click menu in the
Project Explorer (Explore > Filter).
This works both in the TOC and in Topic Files. This only filters entire topics, it does not
filter conditional text tagged within your topics.
The current build settings of topics are shown in the Project Explorer. Topics and
chapters set to All Builds (the default) will always be included, of course you cannot
hide them.

See also:
Variables and Conditional Output 772 (Reference)
Publishing Your Projects 311
Managing topics in the Explorer 211

© 1997 - 2009 by EC Software, all rights reserved

 404 Help & Manual 5 - User Help

6.5.4 Preventing dead links

Excluding topics from your output can create dead hyperlinks. If there are links to the
excluded topics in other topics those links will not have any targets and will produce errors or
do nothing when the user clicks on them. You need to plan your project to prevent this from
happening.
Help & Manual has several functions that can help you to prevent and eliminate dead
hyperlinks caused by excluding topics. If you use them correctly you can easily locate all
potential dead links and automatically replace them with alternative text or links.

How to use Find Referrers to locate potential dead links

Whenever you set an include option to exclude a topic you should always use the Find
Referrers function to check for any links to the excluded topic in other topics.
1. Select the topic you plan to exclude in the Project Explorer. You can select either a
TOC item or a topic file.
2. Right-click on the topic name in the Project Explorer and select Find Referrers in the
context menu. Alternatively you can also select Find > Find Referrers in Project >
Manage Topics.
3. This displays the topic referrer report. Double-click on its title bar to display it in an
external window, this makes it easier to use (double-clicking on the title bar again re-
docks it to the Help & Manual window):

Links to the topic in other topics are listed in the Is referred by column. The Links to
column only shows topics that the current topic links to, which you don't need to worry
about here.
4. Click on the links in the Is referred by column to display the topics so that you can use
conditional text to eliminate dead links (see below). When you are finished you can
return to the current topic by clicking on its link in the Topic column.

How to use Conditional Text to replace dead links

When you exclude topics from your published output you do this with include options.
You can prevent dead links to the topic by using the exactly the same include options to
also exclude the hyperlinks that would be dead. This is then automatic the hyperlinks

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 405

will always be excluded whenever the topic they link to is excluded, because they are
both controlled by the same include options.
You can also use additional include options to include alternative text or even alternative
links whenever the topic is excluded.
1. Use Find Referrers (see above) to locate all topics containing links to the topic you
want to exclude.
2. Open the topic containing the link that you want to exclude in the editor and locate the
link.
You now need to decide what needs to be excluded and replaced. We will assume
that you want to exclude the entire sentence containing the link and replace it with an
alternative sentence.
Excluding the link:
3. Select the entire sentence containing the link and select the Conditional Text Tool
in Write > Insert Object.

4. Now select exactly the same include options that you are using to exclude the topic
the link points to and click on OK.
In the example above we have selected Webhelp and Adobe PDF. This means that
the link will only be included when you publish to Webhelp or PDF, it will be excluded
from all other formats. Since the options match those set for the topic the link points to
it will be excluded whenever the topic is excluded and included when it is included.
Including alternative text and/or links:
5. If you want, you can now write an alternative sentence with or without a link to a
different topic and use conditional text to include the alternative text whenever the
original text is excluded.
The easiest way to do this is with IFNOT. In the above example we would also select
Webhelp and Adobe PDF, but in combination with IFNOT instead of IF. This will
ensure that the alternative is always included when the original is excluded, and vice
versa.

How to set publishing options to manage dead links

These options can be configured in View > Program Options > Compilers. They not
a real solution. They should only be used as a safety net to handle any dead links you

© 1997 - 2009 by EC Software, all rights reserved

 406 Help & Manual 5 - User Help

may have accidentally missed when planning your project.

Option 1: Export excluded topics if referenced by another topic
This option prevents dead links by exporting your excluded topics when you publish if
there are any other topics that contain links to them. When this is done no TOC entry is
exported for the topic, so it can only be displayed by clicking on the links to it. Don't use
this option if the topics you are excluding contain information you don't want a specific
user group to see!
All nominally excluded topics that get included by this option will be listed as "implicitly
exported" in the compiler report when you publish your project.
Option 2: Remove dead links to topics that have been excluded
This option simply deactivates dead links to topics excluded from your output. The link
caption text is still there but it is normal text, no longer a hyperlink. This is definitely safer
than Option 1, because it always ensures that excluded content remains excluded.
However, depending on the context the plain text in place of the links may be confusing
for your users.
All links turned into plain text in this way are listed in the compiler report.

6.5.5 Defining include options

There are two kinds of include options (also known as build conditions): Output format
include options and user-defined include options. Output format options are used to include
or exclude content in specific output formats (HTML Help, WinhelpNote that Windows Vista does
not support Winhelp. If you want to be compatible with Vista you must transition to a different help format.,
PDF etc). User-defined options are used to create different versions of your project in any
output format. In both cases you select or deselect the include options you want to apply
when you publish your project.
Both types of include options are displayed in the same lists and are accessed in the same
way. For details see the other topics in this chapter.

How to define your own include options

An include option or "custom build" condition is basically just a named tag with which you
can identify topics or content in your topics. Once you have tagged your content you can
then include or exclude it with the Include Options settings in the Publish 590 dialog.
1. In the Project Explorer go to Configuration > Common Properties > Custom
Builds.
2. Use Add and Delete to add and delete include options. When you define a new include
option you must enter a "Build ID". This is the actual include option tag and it cannot
be changed later. (Changing it would break existing conditions in your project.)
3. Click in the Display Text column to edit the descriptive texts for your include options.
These are just informative and do not have any effect on the functioning of the
conditions. Keep them short because they must be displayed in selection lists in
dialogs, which are generally quite narrow.
4. All the definitions you enter here are automatically displayed in all locations where
include options are used.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 407

See also:
Conditions and Customized Output 399
Conditional text include options 410
Topic include options 407
6.5.6 Topic include options
Topic include options are used to include or exclude entire topics or chapters from your
output on the basis of one or more conditions. When you apply topic includes to a chapter
you can include or exclude all the chapter's sub-topics with a single setting.

Separate TOC entry and topic file include options

Your TOC entries and topic files are actually two separate items: The TOC entries are
connected to the topic files by a kind of hyperlink. The TOC entry and the topic files also
have separate include options. If you work in the TOC you will normally not need to think
about this because the matching include options for the associated topic files will be set
automatically.
However, the situation is different if you have multiple TOC entries 208 for the same topic
in the TOC. Then you need to think about what happens when you set different include
options for TOC entries linked to the same topic file.
Please see Topic entry and topic file include options 787 for more information, also on
setting include options for topic files directly.

How to set topic include options in the TOC

1. Select the topic or chapter you want to include or exclude by clicking on its entry in the
Table of Contents (TOC). You can select multiple topics and chapters with Ctrl+Click
and Shift+Click.
2. Select the topic in the TOC, then select Change > Include in Builds in Project >
Manage Topics and select the conditions you want to apply. You can select multiple
options.
You can also access these options by right-clicking on a topic in the Project Explorer.
3. Select Find > Referrers in Project > Manage Topics to make sure that there are no
links to the topic that will be dead in the output if the topic is excluded.
If you wish, you can include such topics 649 in your output automatically to prevent dead
links.
· ALL BUILDS is the default. Selecting it deselects all other options.
· Including or excluding a chapter automatically includes or excludes all the sub-topics
and other chapters it contains without displaying any changes in the include options of
th sub-topics and sub-chapters. You only need to apply settings to individual sub-topics
and sub-chapters if you want them to be different from those of their "parent" chapter –
for example to exclude individual topics.
· Including a sub-topic automatically includes its parent chapter topic; you can't include a
topic that has a parent without including its parent as well.

© 1997 - 2009 by EC Software, all rights reserved

408 Help & Manual 5 - User Help

· If you exclude all the sub-topics of a chapter and include the chapter topic the chapter
will be converted to a normal topic when you compile.

How include options are applied to sub-topics

Including/excluding a chapter automatically includes/excludes its sub-topics
Include options you apply to a chapter are not automatically applied to sub-topics.
However, they don't need to be – if you include a chapter its sub-topics are included
automatically, if you exclude a chapter its sub-topics are excluded automatically.
Excluding all a chapter's sub-topics
It works a little differently the other way round: If you exclude all of a chapter's sub-topics
this will not exclude the chapter. However, if the chapter no longer has any sub-topics it is
no longer a chapter – it will be automatically converted to a normal topic when you
publish your project.

How to set topic include options in the Topic Files section

You should generally set and change include options for topics in the TOC, then the
options for the associated topic files will be set automatically. However, for topics without
TOC entries you must set the include options directly in Topic Files, in the Project Files
section of the Project Explorer. Just select the topic file and then set the include options
in exactly the same way as for a TOC entry
Important: Setting topic file include options does not automatically set the corresponding
include options for any linked TOC entries. You should always work directly in the TOC
for topics that have TOC entries unless you have a specific reason for wanting to set the
options for the topic files only.
See Topic entry and topic file include options 787 for more background information.

Checking for and correcting links from other topics

When you exclude topics from your output it is important to make sure that there are no
links to the excluded topic from other topics in your project. If there are, the links will be
dead in your output when the user clicks on them either nothing will happen or an error
will be displayed (this depends on the output format).
See Preventing dead links 404 for a more detailed discussion of this subject and strategies
for dealing with the problem efficiently.
Checking for dead links
1. Right-click on the TOC entry of the topic you want to exclude and select Find
Referrers in the context menu.
2. If any links to the current topic are listed click on the links to jump to the topics
containing the links so that you can correct them.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 409

Correcting dead links with conditional text

You can use the same condition that you are using to exclude the topic to simultaneously
exclude the links to the topic. You just need to enclose the links in conditional text 410 tags
using the same condition that you used to exclude the topic.
For example, if you want the topic to only be included in HTML Help output you would tag
all the links to the topic with an IF CHM conditional text condition to match the HTML Help
setting in Builds which include this topic. The procedure is similar for user-defined
conditions.
Inserting alternative text to replace the excluded links
In addition to excluding the links you can also use conditional text 410 tags to include
alternative text to replace the links that are being excluded. For example, if the topic is
only to be included in HTML Help you might use an ELSE or an IFNOT CHM condition to
include the alternative text in all other formats, or an IF PDF condition to show the
alternative text in the PDF version. Here too, the procedure is similar for user-defined
conditions.

How to apply include options when you publish

1. Select Publish in the Project tab or the Application Menu.
2. Select your output format, then check the options in the Include Options: setting in the
Publish 590 dialog.

3. Select the options you want to apply from the list by checking the boxes next to the
names in the Include Options section on the right.
All topics whose include options match the options selected here will be included in
your output. Topics whose options don't match will be excluded.
4. Check the other settings in the dialog and click OK to publish.
The include option for the current output format is always selected automatically but it is
only relevant for topics not tagged with ALL BUILDS. Any other include options must be
selected manually.

© 1997 - 2009 by EC Software, all rights reserved

 410 Help & Manual 5 - User Help

See also:
Conditions and Customized Output 399
Topic entry and topic file include options 787
Preventing dead links 404
Defining include options 406
Topic include options 407
Command Line Options 466
6.5.7 Conditional text include options
Conditional text include options are used to include or exclude specific passages of text and
other items within a topic on the basis of one or more conditions.
See Command Line Options 466 for details on how to use these options from the command
line and in batch files.

Key Information
A condition that starts before a table must
end after the table. You cannot start a
condition before a table and end it inside
the table. Inside tables conditions must
start and end inside the same cell.
Conditional text cannot span table cells!

Method 1: Select text first

This is the fastest and easiest way because it automatically inserts the condition tags at
the beginning and end of the text and other content you want to tag. If you want to use
an ELSE tag as well you must still insert it manually, however (see further below).
1. Select the text or items you want to include or exclude in the editor.
2. Select Write > Insert Object >
3. In the dialog displayed select:
IF to include the selection if the condition is True when you publish (e.g. include text in
CHM output)
IFNOT to include the selection if the condition is False when you publish (e.g. include
text in all outputs except CHM)
4. Select all the conditions you want to apply by checking the boxes next to their names.
You can apply multiple conditions in a single conditional text tag.
5. Click on OK. The beginning and end of the conditional text block are marked by
orange tags in your text.

Method 2: Setting the IF and ENDIF tags manually

When you use this method you must insert the IF, ENDIF and ELSE (if used) tags
separately, selecting the Conditional Text tool once for each individual tag.
1. Click in the position where you want the text condition to begin.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 411

2. Select Write > Insert Object >

3. In the dialog displayed select:
IF to include the selection if the condition is True when you publish (e.g. include text in
CHM output)
IFNOT to include the selection if the condition is False when you publish (e.g. include
text in all outputs except CHM)
4. Select all the conditions you want to apply by checking the boxes next to their names.
You can apply multiple conditions in a single conditional text tag.
5. Click on OK to insert the tag.
6. Click in the position where you want the text condition to end.
7. Select the Conditional Text tool again and insert the ENDIF condition.

Nesting include tags

You can nest conditional text blocks but do this with caution, it is easy to get confused
with complex conditions and to produce unexpected results.
Nested tags are evaluated starting with the outer tags. Evaluation stops as soon as a
condition evaluates as false, effectively creating AND logic. For example:
IF_CHM IF_DEMOBUILD content content content content ENDIF ENDIF
In the above example the content will only be included if the output format is CHM and
DEMOBUILD is selected in the Publish dialog.

Using the ELSE condition

The ELSE condition can be used to provide an alternative text to be displayed if your main
condition is not fulfilled. It is inserted as a single tag between a pair of IF/ENDIF or
IFNOT/ENDIF tags. The ELSE condition is not associated with any include options. It
simply provides an alternative block of content to be included if the previous conditions
do are not evaluate as true when you compile.
· Just click in the position in the text where you want to insert the ELSE condition, select
Write > Insert Object > , and then select ELSE.
If the main condition evaluates True when you publish then everything between the IF
tag and the ELSE tag is output. If the main condition evaluates False when you publish
then everything between the ELSE tag and the ENDIF tag is output.

Example:
The following condition will output TEXT 1 if the output format is HTML Help (CHM),
otherwise it will output TEXT 2:
IF_CHM Text 1 ELSE Text 2 ENDIF

© 1997 - 2009 by EC Software, all rights reserved

 412 Help & Manual 5 - User Help

How to edit text conditions

Double-click on the orange text condition tag in your text to display the Text Condition
dialog, or right-click on the tag and select Edit.

How to apply include options when you compile

1. Select Publish in the Project tab or the Application Menu.
2. Select your output format, then check the options in the Include Options: setting in the
Publish 590 dialog.
3. Select the options you want to apply from the list by checking the boxes next to the
names in the Include Options section on the right.

All content tagged with conditional text include options matching the Include Options
selected here will be included or excluded in your output, depending on whether you
used IF or IFNOT.
4. Check the other settings in the dialog and click OK to publish.

See also:
Conditions and Customized Output 399
Defining include options 406
Topic include options 407
Command Line Options 466
6.5.8 Modular projects include options
You can "merge" additional Help & Manual projects ("modules") into your current project by
inserting them in your Table of Contents, in the same way as inserting a new topic. This also
makes it possible to use conditional output include options on entire modules in the same
way as on individual topics.
A module include option can include or exclude an entire project with its entire directory tree,

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 413

all its chapters, sub-chapters and topics and all its invisible topics as well. If the module also
has child modules a single module include option can include or exclude multiple projects.
Since you can edit modular projects directly in the Project Explorer you can also apply
individual include options to all the chapters and topics in the merged project. The settings
will be saved with the original merged project.
See Working with Modular Help Systems 446 for details on creating and using modular
projects.

How to set module include options

In a project containing child modules select the child module you want to include or
exclude by clicking on its Table of Contents entry in the TOC of the master project.

Including or excluding entire modules:

1. Select Change > Include in Builds the Project > Manage Topics.
2. Select all the options you want to apply by clicking in the boxes next to the options'
names. You can select multiple options.
Including or excluding module topics and chapters:
Just select the chapters inside the module and apply include options as you would for
normal topics and chapters. You can also use conditional text 410 include options for
content inside the chapters in the normal way.
Before excluding a module generate a project report 534 to make sure that excluding the
module will not create any dead links. (Links with targets in other help files and projects
are listed in the reports.) You can get around this problem by creating links between
modules with A-keywords 281 .

How to apply include options when you compile

The include option for the current output format is always selected automatically. Any
other include options must be selected manually. However, if you select user-defined
include options you must always also select at least the option for the current output
format.
1. Select Publish in the Application Menu or in the Project tab.

© 1997 - 2009 by EC Software, all rights reserved

 414 Help & Manual 5 - User Help

All modules whose Include Options match the Include Options selected here will be
included in your output.
2. Select the options you want to apply from the list by checking the boxes next to the
names.
3. Select your compile options 590 , then click on OK to compile.

See also:
Working with Modular Help Systems 446
Defining include options 406
6.5.9 Redefining variables
You can always change the definitions of your variables individually in Configuration >
Common Properties > Text Variables in the Project Explorer. In addition to this you can
set different values for specific variables in individual topics. When you publish your project
you can also redefine some or all of the variables in your entire project with a project skin or
a variable definitions file.

How to redefine variables in individual topics

If you want a variable to have a different value in individual topics you can redefine it in
the tab of the corresponding topics. Note that this is only possible with user-defined
variables. You cannot define Help & Manual's standard variables with this feature.
1. Select the topic in the Project Explorer, then select the tab behind the main editor
window.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 415

2. Click on the + button next to the Topic Variables box at the bottom of the window.
3. Select the variable you want to redefine and click OK, this adds the variable to the
Topic Variables list.
4. Click in the Value field and enter a new value. The values you enter here will only be
used in the current topic.
See The power of editable variables 395 for more information on the kind of things you can
do with this feature.

How to redefine some or all variables when you publish

When you publish your project you can redefine some or all of the variables in the entire
project in two different ways: With "skins" and with the command line compilation feature.
Redefining your variables with skins:
1. Create a project skin (only possible with Help & Manual Professional) containing the
alternative definitions of your variables (and anything else you want to change in your
project). If you only want to redefine your variables you can create a skin that only
contains your variable definitions. See Transforming Your Output with Skins 321 for
more details.
2. When you publish your project 313 to an HTML-based output format select the skin file
in the Publish 590 dialog.
Note that skins can't be selected in the Publish dialog in non-HTML formats you need to
use command line compiling (see below) for those formats where skins are not directly
available.
Redefining your variables from the command line:
You can also create a simple text file containing a list of definitions of the variables you
want to change. You can then specify this file in the command line to redefine all the
variables in your project with the values in the file.
In addition to this you can also specify a project skin file in the command line, to apply a
completely different appearance to the entire project as well as redefining the variables.
For more details on using these features see Skins & redefining variables 478 in the
Command Line chapter and Transforming Your Output with Skins 321 .

See also:
Variables and Conditional Output 772 (Reference)
Transforming Your Output with Skins 321
Command Line Options 466
Skins & redefining variables 478
6.5.10 HTML template conditions

Key Information
The ELSE condition is not available in
HTML templates.

Conditional output and variables are also supported in your project's HTML templates. You

© 1997 - 2009 by EC Software, all rights reserved

 416 Help & Manual 5 - User Help

can use all the same include conditions in HTML templates that you can use in your topics
with the Conditional Text tool. In addition to this there are also a number of special
predefined conditional switches that are available in HTML templates only.
For details see Conditional output 441 in the chapter on using HTML templates.

See also:
Using HTML Templates 430
Conditional output in HTML templates 441
HTML template output conditions 782 (reference list)

6.6 Templates in Help & Manual

Templates are like an empty framework for topics, projects, PDF files and printed manuals.
They are used to define the layout and appearance of these objects and to include text and
other elements that the objects always or usually contain so that you don't have to enter
them manually every time.

See also:
Help Windows 807
6.6.1 Template types
The following template types are used in Help & Manual:
Project templates: A project template is an empty project that stores all the settings
you want to use in a project, including all your Project
Configuration settings, text styles, HTML templates and so on.
Project templates can also include topic content that you want to
use in every new project.
Skins: Skins are applied when you publish to HTML-based output. They
apply a complete pre-designed layout to your project with a single
click. You can save and edit your own skins or used predefined
ones. Skins can only be created with the Professional version of
Help & Manual. You can use existing skins with the Standard
version but you cannot save or edit your own skins.
Topic content Topic content templates are entire topics and can include
templates: everything that a topic can include. They can be loaded manually,
or automatically when you create a new topic.
Print manual These templates define the layout and appearance of your PDF
templates: (PDF and output and printed manuals. They are created and edited with the
printed manuals) Print Manual Designer, a separate program included with Help &
Manual.
HTML templates: These templates define the layout, general appearance and
features of your topic pages in Help & Manual's HTML-based
output formats. The topic page templates for your topics can be
viewed and edited with the Project Explorer in the Configuration >
HTML Page Templates section.
The additional HTML templates for the various components of

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 417

Webhelp (TOC, Index, Search, frameset) can be viewed and

edited in Configuration > Publishing Options > Webhelp.
eBook templates: These templates control the layout and appearance of the viewer
used to display Help & Manual's eBook format. They are not
editable – you can think of them as predefined "skins" for the
eBook viewer.

6.6.2 Templates for projects

A help project template is simply an entire Help & Manual project with all its settings,
including all your styles and all the settings and items in the Project Explorer. A project
template can include topics with content but it does not have to. If you have topics that you
always use (for example terms and conditions, introductions and so on) you may want to
include them.

The difference between skins and project templates

Unlike skins 419 , project templates are used as a model for new projects. You can also
apply project templates to existing projects but this is a little more complicated (see
below).
Skins are applied when you publish and do not affect the settings in your current project,
the settings in project templates become an integral part of your project.

How to create a project template from an existing project

This is generally the easiest way to create a project template because then you don't
have to go through all the project settings.
1. Create a backup copy of the project you want to use as a template and open the
backup.
2. Delete all the topics you don't want to include in the template and edit any topics that
you do want to include so that they do not contain any unnecessary text or other items.
3. Select Save As in the Application Menu and save the edited project in a safe place.
You don't have to use a special format, a project template is exactly the same as a
normal Help & Manual project.

How to use a template to create a new project

Make a copy of the template project and edit:
Just make a copy of the template project file or project folder (if you are using
uncompressed XML format), rename the .hmxz (compressed) or .hmxp (uncompressed)
file and start editing. That is all there is to it.

How to apply a template to an existing project

You can also apply project templates to existing projects. However, this cannot be done

© 1997 - 2009 by EC Software, all rights reserved

418 Help & Manual 5 - User Help

in one process, you need to choose the parts of the template you want to apply.
Step 1: Apply the template stylesheet
1. Open the project you want to apply the template to and select Styles > Edit Styles in
the Write tab.
2. Click on the Copy Styles From... and then select the project file you want to copy the
stylesheet from.
Note that this will overwrite all the styles in your existing project!
Step 2: Apply the Project Configuration settings
All the other settings in your projects are stored in the Configuration 652 section in the
Project Explorer. You must import the properties here section by section:
1. Select the Configuration section of your project in the Project Explorer.
2. Select a section that you want to copy and click on the Copy Properties From... button
at the bottom of the screen. Then select the project you want to copy the properties
from.
You will be asked whether you want to copy the properties from just the current sub-
section or from the entire section (for example: just the Image Folders section of
Common Properties or the entire Common Properties section).
Note that this will overwrite all the settings in your existing project!
3. Repeat for all the template sections you want to copy.
If you want to copy the complete template import all the Common Properties and
HTML Page Templates sections, plus all the Publishing Options sections for any
output formats you are using.
Step 3: Import the Baggage Files
If your original project also contains Baggage Files 485 you should import those to the new
project as well.
1. Select the Baggage Files section in the Project Explorer.
2. Select Add File > Add New File in Project > Manage Topics and select the Help &
Manual project you want to import the Baggage files from.
3. You will be asked if you want to import the Baggage Files from the selected project.
Confirm to import the files.

How to use the Help & Manual help template

Do you like the appearance of the Help & Manual help? In case you do we've included a
template project containing all the integrated features that you can use for your own
projects. It is stored in the Examples\Template for New Projects folder in your My
Documents directory (Documents in Vista) and is called HELPMAN.hmxz.
Some sample skin files 419 based on this template are also available, which you can apply
to your projects when you compile to HTML-based output formats. These can be found in
the \Templates\HTML Skins folder in the Help & Manual program directory.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 419

The project template contains everything you need, including instructions for using it in
your own projects and the graphics for the mouseover buttons in the headers, the code
for the non-scrolling headers etc.
Using the template for a new project:
Just make a copy of the template project under a different name and start editing (see
above).
Applying the template to an existing project:
Follow the instructions for applying project templates to existing projects (see above) and
copy the styles, Configuration sections and Baggage files from the template project.
This template project is set up for HTML Help and Webhelp so you need to copy the
following sections:
· Styles
· Common Properties (entire section)
· HTML Page Templates (entire section)
· Publishing Options > HTML Help (entire section)
· Publishing Options > Webhelp (entire section)

See also:
Creating Projects 83
Creating and Editing Topics 108
6.6.3 Skins
You may already be familiar with the concept of "skins" from other programs: You select a
skin file and the appearance and layout of the entire program is transformed in seconds.
Help & Manual enables you to do this with your HTML-based output. You can save your
entire design in a .hmskin file and then select this file when you publish to apply the layout
to the current project without changing any of the project's own settings.
Please note that you can only save projects as skins if you have the Professional version of
Help & Manual. Standard version users can edit existing skins (for example skins from the
Help & Manual Plus Packs) but they cannot create new skins from their own projects.

Productivity Tip
Skins can only be used for HTML-based
output formats. You can style your PDF
files and printed manuals with print manual
templates 330 , which work in the same way
as skins.

How to use skins - try it now!

1. Open a project of your own, select Publish in the Project tab, then select Webhelp or
HTML Help as the output format.
2. In the Publish dialog 590 click on the Browse button in the Compile with skin: field and
select one of the standard .hmskin files in the Skins folder in the Help & Manual

© 1997 - 2009 by EC Software, all rights reserved

420 Help & Manual 5 - User Help

program directory.

When you publish your output it will have the "look and feel" applied by the skin. You
didn't have to do any design work at all!

How to create a skin file

Skin files contain everything you need to style your HTML-based output: Text and table
styles, user-defined variables, your Baggage files (template graphics and logos), HTML
page templates and all the settings and templates for Webhelp. You can turn any project
into a skin file just by saving it as a skin and you can edit skin files in Help & Manual, just
like normal projects.
1. Open a project with a design that you want to use for other projects.
2. Select Save As... in the Application Menu and choose the Skin XML File option.
3. Choose a place to save the skin, enter a name and save.
4. You will be asked which configuration components of your project you want to include
in your skin. You should normally include all the listed components.
That's all there is to it. You can now compile other projects to HTML-based output
formats with your new skin.

How to edit skin files

Skin files are actually normal single-file projects with some special limitations. You can
open them and edit them like normal projects but you can only edit those components
that are included in the skin, everything else is unavailable.
1. Select Open in the Application Menu and then select Help & Manual skin files (.
hmskin) as the type of file to be opened. (If you don't select this you won't be able to
see the skin files!)
2. Select an .hmskin file to load and edit. You can find some sample skins in the Skins

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 421

folder in the Help & Manual program directory.

3. Now you can edit the settings of your skin. This is exactly the same as editing the
corresponding sections of normal projects to configure your output.
Skins have no topics, you can only edit the relevant sections in the Configuration
and Baggage Files sections in the Project Explorer and the text and table styles in
Write > Styles.

About text and table styles in skin files

Your skin files can include text and table styles. However, for styles to work in skins the
text in the project must use the same style names otherwise Help & Manual cannot
know where to apply the styles.
Basic procedure:
This is just one suggestion to illustrate how skins work, there are many different ways you
could do this you just have to ensure that the style names in all the project files are
identical.
1. Make one or more skin files from a project containing the styles you want to use.
2. Open the skin files and edit the styles for the alternative designs that you want to apply
with the skins.
3. When you create a new project use the original project from step 1 as a project
template 417 then you will start with all the styles you need and you can use your skins
files to redefine the styles when you publish.

Using include conditions to configure features in skins

For advanced users:
You can use include options 441 to turn features in skins on and off. This makes it possible for the
user to choose features in the skin when they publish their projects because include options
stored in skins are loaded into the Include Options: box in the Publish dialog when the skin is
selected.

Key Information
Include options in skins must be defined in
the skin! Include options defined in normal
H&M projects will not be saved in the skin
when you save the project as a skin. You
must edit the skin file and add the include
options you want to use.

For example, suppose you want to give the user the option of having a subtitle underneath the
title in the table of contents in your Webhelp output. It would work like this:
1. Define an include option in the skin, let's say it's called OPT_SUBTITLE, and let's also say that
we've entered TOC header subtitle as the include option description.
2. Add code using the include option to the HTML template for the Webhelp table of contents, for

© 1997 - 2009 by EC Software, all rights reserved

422 Help & Manual 5 - User Help

example (you would also have to define the <%SUBTITLE%> variable in this example, of
course):
<p class="navtitle">Help & Manual 5 - User Help</p>
<IF_OPT_SUBTITLE><p class="nav-subtitle"><%SUBTITLE%></p></IF_OPT_SUBTITLE>
3. When the user loads the skin in the Publish dialog the option [ ] TOC header subtitle will
automatically be loaded from the skin file and displayed in the Include Options: box. The
header will only be displayed if the user selects this option.
You can take this concept as far as you like: For example, you can use the same include option
to change the CSS definitions in the same HTML template so that the formatting will be different
depending on whether the subtitle is included or not.

Including a preview image in a skin

When the user selects a skin in the Publish dialog Help & Manual automatically looks for
a PNG graphic file called $HMSKINPREVIEW.PNG in the skin's Baggage files. If this file is
found a thumbnail version of the preview image is displayed in the Publish dialog. The
user can then click on this image to display a full-size preview.
1. Create your preview image – this will generally be a screenshot of a help file using
your skin – and save it in the PNG format as $HMSKINPREVIEW.PNG.
2. Add the PNG preview file to the Baggage Files section of your skin.
3. Select the PNG file in the Baggage Files section, right-click on it, select Include in
Builds and deactivate all build options for the file. This will prevent the file from being
exported to your published output, where it is not needed.

Using skins to redefine variables and other settings

You don't have to save all your settings in your skin files. For example, it's possible to
create a skin that only defines the user variables in your project you just need to
deselect everything except Variables when you save the skin file. Then you can redefine
your variables in your entire project by selecting the skin file when you publish your
project.
You can do the same with your Baggage files, text and table styles, HTML Page
Templates or any combination.

Applying multiple skins in command lines and batch files

When you publish manually you can only select one skin for the project you are
publishing. However, when you use Help & Manual's command line options you can
specify as many skins as you like one after another.
When you do this the settings in the last skin you specify always have priority for
duplicate settings for example, if you redefine the same variables in two skins the
settings in the second skin are those that will be applied.
See Command Line Options 466 and Skins & redefining variables 478 for more information
on this.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 423

See also:
The Publish Dialog 590
Command Line Options 466
6.6.4 Content templates for topics
A topic content template is an XML file containing the "framework" of a topic it is used to
create topics with repetitive content, for example identical tables and headings and so on.
Topic content templates can contain everything that a topic can contain, including tables,
formatted text, graphics, links and so on. You can create as many content templates as you
like and load them with you create topics with standard layout that you use repeatedly. You
can also create content templates that are loaded automatically when you create new topics.

How to create a topic content template

1. Create a new topic. The topic ID is irrelevant because you are going to delete the topic
as soon as you have saved the template.
2. Edit the topic and add everything that you want to have in the template. You can use
all the features that you can use in a normal topic, including tables, graphics,
formatted text, hyperlinks and so on.
3. Enter the topic header (in the area above the editor, not in the TOC) exactly as you
want it to appear in the topic. See the instructions below for automatically inserting the
TOC caption in the header.
4. Select File > Save Topic to File in Project > Manage Topics and save the topic as
an XML file in the project folder, using the following naming syntax:
filename.template.xml
The .template. part of the name is essential, it identifies the XML file as a template.
Templates must be stored in the current project directory and must use this naming
syntax.
Examples:
intro.template.xml
functiondocs.template.xml
standarddocs.template.xml
5. Delete the topic you have just created if you don't want to use it in your project now.

How to use topic content templates

To create a new topic with a template:
1. Choose one of the Add Topic options in the Project tab to create a new topic.
2. Select the template in the Topic Template: field of the Insert New Topic or Chapter
dialog.

© 1997 - 2009 by EC Software, all rights reserved

424 Help & Manual 5 - User Help

Note that the template will only appear in the Topic Template: field for selection if it is
stored in your project directory using the filename.template.xml naming syntax (see
above for details).
To load a template into an empty topic:
1. Create an empty topic.
2. Select File > Load Topic from File in Project > Manage Topics and select the
template file you want to load.
Don't try to load a template into an existing topic, this will overwrite the entire contents of
the topic!

Insert the TOC caption in the topic header

When you create topic templates to use for creating new topics you can include a special
variable in the header that will automatically insert the topic caption (the title of the topic
you enter in the Add Topic dialog) in the header of the topic. If you don't use this variable
the template will be loaded with the header saved with the topic.
You also need to insert this variable in the Title Tag: field in the Topic Options tab so that
the header text of your topic is used there as well – otherwise the header text stored with
the content template file will be used.
1. Delete the header of the template topic (in the area above the editor, not in the TOC)
and replace it with the following variable:
%TEXT%
2. Type in the variable manually exactly as shown, using all upper case. Only enter %
and % before and after the variable name. This is the only variable that does not use <
% and %> tags.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 425

You can also include other text and elements in the header, including graphics. Only
the variable is replaced when a new topic is created.
3. Select the Topic Options tab and type the same %TEXT% variable in the <TITLE> Tag:
field:

This variable only works when you create a new topic with a content template file. The %
TEXT% variable is not translated when you load the template into a empty topic with File >
Load Topic from File in Project > Manage Topics.

Topic content templates for topic styles

If you frequently use topics with different standard styles you could create a separate
template for topics with each set of styles already preset in the topic header and body.
Then you just need to select the appropriate template when you create a new topic (see
above).

See also:
Creating new topics 110
Exporting and importing topics 204
6.6.5 PDF and print manual templates
The layout of Help & Manual's PDF and print manual output is controlled by template files
called "print manual templates" with the extension .mnl that do much more than just define
the appearance of your pages. These templates can also add front and back covers,
multiple title pages at the beginning, an introduction, a formatted table of contents, title
pages for individual chapters, graphics, headers and footers, a formatted index and multiple
endnotes pages. You can also define your own additional pages and insert topics from your
project or external files with a "snippets" function.
All the global variables and user-defined variables from your project file can be used in your
print manual templates. Since the templates are external files you can use them in multiple
projects, applying them to your output just as you apply skins 321 to HTML-based output
formats.

© 1997 - 2009 by EC Software, all rights reserved

426 Help & Manual 5 - User Help

How to select a print manual template

You can select separate templates for PDF output and printed manuals.
Selecting a print manual template for PDF output:
1. Go to Configuration > Publishing Options > Adobe PDF > PDF Layout 690

2. Click on the button in the Print Manual Template: field to select the template you
want to use.
Selecting a print manual template for printing a user manual:
1. Click on the Application Button and select Print User Manual 575 .

2. Click on the button in the Print Manual Template: field to select the template you
want to use.
In both these dialogs you can open the selected template for editing by clicking on the
Design button next to the template selection field.

How to edit a print manual template

· Select a template with one of the methods described above and select the Design
button next to the template selection field to open it in the Print Manual Designer
program.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 427

OR:
· Select Project > Tools > Manual Designer 537 to open the Print Manual Designer.
Then select File > Open in the Designer to open the template for editing. You can find
a selection of standard templates that you can edit in the \Templates\pdf folder in the
Help & Manual program directory.
The Print Manual Designer is a separate program with its own documentation. See the
help in the Designer for details on how to use it.

Location of the standard print manual templates

Help & Manual comes with a selection of standard print manual templates that are stored
in the \Templates\pdf subdirectory in the Help & Manual program directory. These
templates have the file extension .mnl.

See also:
PDF and Printed Manuals 325
6.6.6 HTML templates
HTML templates are used to define the layout of all Help & Manual's HTML-based output
formats (HTML Help, Webhelp, eBooks and Visual Studio Help). In topic pages what you
enter in the editor defines the content, the templates define the framework in which your
content is presented. The HTML templates are stored together with your project.
The same HTML topic page templates are used for the topic pages in all three formats. In
addition to this there are also separate templates for the frameset file and the Table of
Contents and Keyword Index frames used in Webhelp, where they emulate the HTML Help
viewer user interface.

You don't normally need to think about HTML templates

For normal work with Help & Manual you don't have to think about what HTML templates
contain and how to edit them. That is all handled in the background by the program. A
simple style editor is provided that allows you to modify the basic layout of your pages in
the associated output formats without having to edit the HTML code directly.

Accessing and editing the HTML templates

For everyday work you can adjust the settings of your HTML page templates just as you
would adjust any of the other output settings in your Project Configuration 652 settings. The
simple style editor hides the HTML code with a point-and-click interface.
The HTML topic page template:
In new projects there is just one HTML topic page template called Default, which is
assigned to all new topics automatically. It can be viewed and edited in the Configuration
section of your project in the Project Explorer, in Configuration > HTML Page
Templates, where you can also create new templates.
Among other things, the HTML topic page template defines the background colors of your

© 1997 - 2009 by EC Software, all rights reserved

428 Help & Manual 5 - User Help

topic and topic header in HTML-based output formats and the Top, Previous and Next
navigation links displayed in the topic header in these formats.

The Simple Template Layout tab provides most of the functions you will normally need,
see this topic 123 for some basic instructions.
The HTML templates for Webhelp components:
There are also additional HTML templates for Webhelp, which define the layout frameset,
TOC, Search, and Index components of the Webhelp user interface. These are accessed
in Configuration > Publishing Options > Webhelp.

Setting the background colors of topics and headers

The background colors of topics and headers are set in the HTML page template for all
output formats where they are relevant except Winhelp. Background colors are not used
in RTF, PDF and printed manuals.
See Background colors and help viewers 93 for details on how to set the background
colors in the HTML page template.

Doing more with HTML templates

If you are familiar with writing HTML Help & Manual's HTML templates are a very
powerful tool that gives you a great deal of control over the appearance of your output
pages in all HTML-based formats.
If you feel like getting under the hood and finding out what you can do with HTML
templates have a look at the Using HTML Templates 430 chapter in the More Advanced
Procedures section.

See also:
Webhelp settings 674
Using HTML Templates 430

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 429

6.6.7 Windows Exe eBook templates

The layout of the topic pages in the Windows Exe and ePub eBook formats is defined by the
same HTML templates that are used for the topic pages of HTML Help and Webhelp.
In addition to this, however, Windows Exe eBooks also use a special kind of template that
defines the appearance and layout of the eBook viewer, which is stored together with every
eBook you output. This program is part of every eBook, enabling the eBook to "display itself"
on any Windows computer running Windows 95 or later without any other software.
ePub eBooks do not have any additional templates – the appearance and functionality of
ePub viewers cannot be controlled in any way by settings in the ePub file.

Selecting Windows Exe eBook templates

A set of different Windows Exe eBook templates is included with Help & Manual and can
be found in the \Templates\ebooks folder in the Help & Manual program directory.
These templates can have the extension .skin or .dfm.
1. In the Project Explorer go to Configuration > Publishing Options > eBooks>
Windows: Visual Appearance.
2. Click on the button in the Viewer Template: field to locate and select a template.
The eBook templates have descriptive names that indicate their features.

See also:
Windows Exe eBook settings 706
6.6.8 Using secondary windows
Secondary windows are only relevant in the Microsoft HTML Help and Winhelp formats.
They are used to display individual topics in external windows. In addition to this you can
use secondary windows in Winhelp to define different header and topic background colors
for individual topics. In all other formats header and topic background colors are defined in
the HTML page templates 93 .

Productivity Tip
Avoid using hyperlinks in secondary
windows. Although an external window is a
full instance of the help viewer hyperlinks
between it and the main help can quickly
get very confusing for the user.

How to display topics in external windows

In HTML Help and Winhelp you can use additional help window definitions to display
topics in external windows when they are opened with hyperlinks. Topics can only be
displayed in external windows in these two formats and the help window settings have no
effect in other help formats.
Important: Help window types can only be used in hyperlinks.
You cannot directly associate a help window type with an individual topic and you cannot

© 1997 - 2009 by EC Software, all rights reserved

 430 Help & Manual 5 - User Help

set a topic in the TOC to open in an external window when you click on its TOC entry.
HTML Help:
1. In the Project Explorer go to Configuration > Common Properties > Help
Windows and create at least one secondary help window type definition with Add.
Adjust the settings of the window definition as you want the external window to appear
in addition to the size and position you may want to switch off navigation controls
etc. in the help window definition's HTML Help Options tab.
2. In the HTML Help Options tab activate the option Links to secondary help windows
open a new help window.
3. When you create a hyperlink to a topic specify the secondary help window type with
the Window: setting in the link definition.
When the user clicks on the hyperlink the target topic it will now be displayed in an
external window in HTML Help, with all the settings defined for the window type in step 1.
Winhelp:
No special settings are required for Winhelp because links to secondary windows always
open in external windows in Winhelp. Just specify a secondary window in the hyperlink
definition, then the hyperlink will open the target topic in an external window.

Setting background colors in Winhelp

Winhelp stores the background colors of the topic and header in the help window
definition. All other formats save the background colors in the HTML page template.
You can apply different background colors to individual topics in Winhelp by defining a
new help window with different colors and selecting it in the Help Window: field in the tab
behind the main editor window.
See Background colors and help viewers 93 for details on how to set the background
colors in Winhelp and other formats.

See also:
Help Windows 807
Using help windows 121
Links and secondary windows 231
HTML templates 427
Using HTML Templates 430

6.7 Using HTML Templates

HTML templates are used to define the topic layout of all Help & Manual's HTML-based
output formats (HTML Help, Webhelp, Windows Exe and ePub eBooks and Visual Studio
Help/MS Help 2.0). What you enter in the editor defines the content of your topics, the
templates define the framework in which your content is presented. The HTML templates
are stored together with your project.
In addition to this there is an additional set of HTML templates for the special components of
Webhelp output (TOC, Index, Search, frameset).

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 431

See also:
HTML templates 810 (Reference)
Help Windows 807 (Reference)
Templates and Secondary Windows 416
Using help windows 121
6.7.1 Types of HTML templates
There are two categories of HTML templates: The HTML topic page templates that define
your topic pages in all HTML-based output formats and an additional group of HTML
templates used to define the additional components of Webhelp output.

HTML topic page templates:

These are the templates for your topics and they are used for all HTML-based output
formats. They define everything in your topic pages except the topic content. They are
stored in Configuration > HTML Page Templates.

Additional templates for Webhelp:

In addition to this there are also separate templates for the Frameset 437 and the Table of
Contents 437 , Keyword Index 438 and Full-text Search 438 frames used in Webhelp to
emulate the HTML Help viewer user interface. These templates are stored in
Configuration > Publishing Options > Webhelp.

6.7.2 Editing HTML templates

All the various HTML templates used in your projects can be edited directly in the
Configuration section of your project where they are stored. Help & Manual has an
integrated HTML code editor with syntax highlighting, search and replace and spell
checking.

Editing HTML templates requires familiarity with HTML:

You must be familiar with manual HTML coding to edit the HTML templates yourself.
Your code is also entirely your own responsibility – it is not syntax-checked in any way by
Help & Manual. Only delete or change code in the standard templates if you really
understand what you are doing, otherwise you may experience unexpected errors and
malfunctions in your output!
When making code changes it is good practice to publish regularly to test the results of
your changes, otherwise it can be difficult to localize identify the changes that are causing
a specific problem.

Template locations
Topic page templates:
In the Project Explorer go to Configuration > HTML Page Templates to edit the
templates for your topics. By default there is just one template called Default that is used
for all topics. However, you can define additional templates and assign them to individual
topics in the tab, in the HTML Page Template: field.

© 1997 - 2009 by EC Software, all rights reserved

432 Help & Manual 5 - User Help

These templates are used for all HTML-based output formats. The same templates are
used for all formats, you cannot define different templates for specific output formats.
Webhelp templates:
In the Project Explorer go to Configuration > Publishing Options > Webhelp to edit
the additional templates for the help frameset (Layout), Table of Contents, Keyword Index
and Search panes in your Webhelp output.

How to edit HTML templates

All the templates have two editing modes, in two tabs. In the simple mode tab you can
make a number of changes without actually having to edit the HTML code directly. This is
recommended for most users. The HTML code tab gives you direct access to all the code
of the template you should only use this option if you have experience with editing
HTML and CSS code.
Simple editing mode:
Note that the Simple Template Layout tab is only available for the standard Default
template. All additional topic page templates you create can only be edited in HTML
Source Code mode.
1. Select the template you want to edit then select the Simple Template Layout tab in the
editor window.

2. Make your changes and additions, then save your project to save your changes.
See HTML Page Templates 666 and Webhelp 674 in the Reference section for details on the
settings for each template type.
Editing the HTML code:
Note that user-created HTML page templates can only be edited in HTML Source Code
mode.
1. Select the template you want to edit then select the Edit HTML Code tab in the editor

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 433

window.

2. Edit the template in the editor window displayed. The editor supports syntax
highlighting to make editing easier. See the other sections in this chapter for details on
the contents of the different template types.
3. When you are finished save your project to store your changes.
The changes will be applied immediately but most of them may only be visible in your
compiled output. However, any background colors you set for your topic body and header
will be displayed in the editor directly.

See also:
Templates and Secondary Windows 416
Help Windows 807 (Reference)
6.7.3 HTML topic page Templates
The HTML topic page templates are used to define the layout and behavior of topic pages in
all HTML-based output formats (HTML Help, Webhelp, Windows Exe and ePub eBooks and
Visual Studio Help / MS Help 2.0). By default there is just one template called Default which
is assigned to new topics automatically. However, you can define as many different
templates as you like.
You can assign a different template to any topic in the tab behind the main editor window.
Just select the template you want to use in the drop-down list in the HTML Page Template:
field.
See Editing HTML templates 431 for details on how to edit templates.

Template location
Configuration > HTML Page Templates

© 1997 - 2009 by EC Software, all rights reserved

434 Help & Manual 5 - User Help

Simple Template Layout tab

This tab is only available for the standard Default topic page template. All user-defined
templates can only be edited in the HTML Source Code tab.

Background colors:
These settings set the background colors for your topic header and body. The colors will
be shown in the Help & Manual editor.
Text above topic:
Everything you enter in this box is inserted at the top of every topic, before your topic text.
Effectively, this adds a header to your topics (beneath the actual topic header containing
the topic title). This text is only shown in your output, not in the Help & Manual editor.
You can enter HTML tags here to format the text, including references to images.
Topics with headers have <Top>, <Previous> and <Next> links:
This allows you to activate navigation links in your topic headers, either as simple text
links or is a graphical icons. To insert an icon click in the Image File column, click on the
Browse button and select the file.
Image files must be located in one of the folders listed in your Project Search Path
settings in Configuration > Common Properties > Project Search Path.
Text below topic:
Everything you enter in this box is inserted at the bottom of every topic, after your topic
text. Effectively, this adds a footer to your topics. This text is only shown in your output,
not in the Help & Manual editor.
Here too, you can enter HTML tags here to format the text, including references to
images.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 435

HTML Source Code tab

This tab gives you full access to the HTML code of the template file. Editing HTML
templates directly requires experience with editing HTML code. If you are just getting
started with Help & Manual it is advisable to only use the Simple Template Layout tab.
This allows you to use the default template while you are getting used to the program.
For full details on all the settings in this section see HTML Page Templates 666 in the
Reference section.

Structure of topic page templates

Topic content:
The most important thing to know about topic page templates is that your final HTML
pages are made by combining code of the template with the contents of the topics edited
in Help & Manual. In HTML terms, the content from the editor is everything between the
<body> and </body> tags, the HTML template provides everything else.
The content of your topic is inserted in the template at publish time by the variable <%
TOPIC_TEXT%> in the template. When you compile, the HTML page is created by
replacing this variable in the template with the content of the current topic.
The topic header:
The topic header is also generated by the template. It is created by the code between
the <IF_TOPIC_HEADER> and </IF_TOPIC_HEADER> conditions. (These condition tags are
always stripped out before your project is published. The output code contains no
proprietary tags.)
You can add material to the header on every topic page by adding text, links images etc.
between these condition tags. The contents of the header box from the editor is inserted
with the variable <%TOPIC_HEADER%>.

Creating "headers" and "footers":

You can create "headers" and "footers" in the body of your topic by editing the HTML
template and adding material above and below the <%TOPIC_TEXT%> variable. Everything
above this variable will be a header, everything below it will be a footer. This can also be
done in the Simple Template Layout tab, which provides text entry boxes for this purpose.

Breadcrumb trail navigation links

The <%TOPIC_BREADCRUMBS%> variable can be used to create a "breadcrumb trail" of
navigation links to the topics above the current topic in the TOC tree. This can be useful
for showing the user where they are.
For example, if the current topic is The Editor in the sequence Introduction > About the
Program > User Interface > The Editor, inserting the <%TOPIC_BREADCRUMBS%> variable
would create this series of links in your output (note that the current topic is not included):
Introduction > About the Program > User Interface

© 1997 - 2009 by EC Software, all rights reserved

436 Help & Manual 5 - User Help

The links are active, i.e. clicking on them will take the user to the referenced topics. For
example, this feature is used to create the breadcrumb trail of links above the headers in
the HTML Help and Webhelp versions of this help.
How to insert a breadcrumb trail:
These instructions show you how to insert a breadcrumb trail at the top of the topic text,
directly below the header.
1. Select the Default template in Configuration > HTML Page Templates and locate
the following code:
<!-- Placeholder for topic body. -->
<table width="100%" border="0" cellspacing="0" cellpadding="5">
<tr valign="top"><td align="left">
<%TOPIC_TEXT%>
</td></tr></table>
2. Add the following code (highlighted in blue):
<!-- Placeholder for topic body. -->
<table width="100%" border="0" cellspacing="0" cellpadding="5">
<tr valign="top"><td align="left">
<IF_TOPIC_BREADCRUMBS><p style="font-size: 8pt; margin-bottom: 15px">
<%TOPIC_BREADCRUMBS%> &gt; <%TOPIC_TITLE%></p></IF_TOPIC_BREADCRUMBS>
<%TOPIC_TEXT%>
</td></tr></table>
The <IF_TOPIC_BREADCRUMBS> condition ensures that the trail is only inserted where it is
relevant. (The breadcrumbs variable is empty in top-level topics and in all topics in the
Invisible Topics section.)
If you want you can also use <IFNOT_TOPIC_BREADCRUMBS> to insert alternative content
to be displayed in top-level topics.
Note that the title of the current topic is not included in the <%TOPIC_BREADCRUMBS%
> variable because it may not be needed if the topic title is visible directly above the
breadcrumb trail. In our example we have included the current topic title with the <%
TOPIC_TITLE%> variable to show how it is done. (The &gt; code inserts the > character,
which could otherwise be misinterpreted by some browsers.)
For more details on variables and output conditions in HTML templates see HTML
template variables 778 and HTML template output conditions 782 .
Breadcrumb trail without active links:
If you need to create a breadcrumb trail without active links you can do this with the <%
TOPIC_TITLE_PATH%> variable. This is almost the same as the breadcrumbs variable but
it creates no links and also includes the title of the current topic. See HTML Template
Variables 778 for details.

Navigation links to parent chapter

Have you tried clicking the green "home" button in the header of this help? Instead of
taking the user rigidly to the default page of the help it automatically links to the parent
chapter of the current topic, if there is one. If the current topic doesn't have a parent
chapter (for example if its top chapter is a chapter without text 110 ) the link will

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 437

automatically take the user to the project's default topic.

You can do this with the variable <%HREF_PARENT_CHAPTER%> 778 . Just use this variable
instead of the <%HREF_DEFAULT_PAGE%> variable in your topic page template. Everything
is automatic – when you compile the correct links are generated automatically to the
parent chapter or the default topic, depending on whether a parent chapter is available or
not.

See also:
Editing HTML templates 431
HTML template variables 778
HTML template output conditions 782
Variables 439
Conditional output 441
Help Windows 807
6.7.4 The Layout template for Webhelp
The layout template is the "frameset" template that defines the frames containing the topic
pane and the navigation pane, and also the header frame if you are using a three-frame
layout. Basically it only provides the external framework and tells the browser which files to
load into which frames. This means that you should not normally have any reason to edit it.
This template is highly specialized and should only be edited if you have advanced HTML
editing skills. It is essential for the proper functioning of the entire navigation system in
Webhelp and editing errors you make here can easily make your help unusable.
See Editing HTML templates 431 for details on how to edit templates.

Template location
Configuration > Publishing Options > Webhelp > Layout

See also:
Editing HTML templates 431
HTML template variables 778
HTML template output conditions 782
Variables 439
Conditional output 441
6.7.5 The TOC template for Webhelp
This HTML template is only used in Webhelp. It generates the Table of Contents (TOC)
pane in the frame layout that emulates the appearance and functionality of the HTML Help
viewer in a normal browser.
Be particularly careful when editing this template! The TOC template is an integral part of
the dynamic TOC of your Webhelp output. Its code is essential for the proper functioning of
the help.
When you publish the actual table of contents for your project is inserted in the TOC page
by the <%TABLE_OF_CONTENTS%> variable.
See Editing HTML templates 431 for details on how to edit templates.

© 1997 - 2009 by EC Software, all rights reserved

 438 Help & Manual 5 - User Help

Template location
Configuration > Publishing Options > Webhelp > Table of Contents

Script links for expanding and collapsing the TOC

You can use the following code to create links that will allow the user to expand and
collapse the entire TOC with a single click:
<a href="javascript:parent.fullexpand()">Expand the TOC</a>
<a href="javascript:parent.fullcollapse()">Collapse the TOC</a>
Note that these links can only be used within the TOC template. You cannot use them in
your topic pages or in other panes of the navigation frame.

See also:
Editing HTML templates 431
Variables 439
Conditional output 441
Help Windows 807
6.7.6 The Search template for Webhelp
This HTML template is only used in Webhelp and is only active if you have the Professional
version of Help & Manual. It generates the Search pane in the frame layout that emulates
the appearance and functionality of the HTML Help viewer in a normal browser.
The Search template is an integral part of the full-text search function in the Webhelp
output. Its code is essential for the proper functioning of the search function. Please be
extremely careful when you are editing this template – if you don't understand what a piece
of code is for it's better to leave it alone!
The standard search script is inserted in the Search page by the <%SEARCH_SCRIPT%>
variable. You can't edit this script but you can configure all the text used in the script and
other features. See Full Text Search 680 in the reference section for details on the
configuration options for Search.
See Editing HTML templates 431 for details on how to edit templates.

Template location
Configuration > Publishing Options > Webhelp > Full Text Search

See also:
Editing HTML templates 431
Variables 439
Conditional output 441
Help Windows 807
6.7.7 The Index template for Webhelp
This HTML template is only used for Webhelp. It generates the keyword index pane within
the frame layout that emulates the appearance and functionality of the HTML Help viewer in

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 439

a normal browser.
The keyword index template is an integral part of the help viewer generated by Help &
Manual for Webhelp. Its code is essential for the proper functioning of the index. Please be
extremely careful when you are editing this template – if you don't understand what a piece
of code is for it's better to leave it alone!
When you publish the actual keyword index is inserted in the Index page by the <%
KEYWORD_INDEX%> variable.
See Editing HTML templates 431 for details on how to edit templates.

Template location
Configuration > Publishing Options > Webhelp > Full Text Search

See also:
Editing HTML templates 431
Variables in HTML templates 439
Conditional output in HTML templates 441
6.7.8 Variables in HTML templates
You can use all global predefined variables and user-defined variables in all HTML
templates. In addition to this there are a number of special HTML template variables, which
are only relevant in HTML templates.
In addition to these variables you can also use predefined and user-defined conditional
switches to include or exclude content on the basis of conditions. This is particularly useful
for variables, which are often only relevant in certain contexts. For details see Conditional
output in HTML templates 441 .

Variables reference
More information on the variables and conditions that you can use in HTML templates
can be found in the following locations:
· List of global predefined variables 774
· List of HTML template variables 778
· Creating user-defined variables 378
· List of HTML template output conditions 782

How to use user-defined variables in HTML templates

You can use all your user-defined variables in HTML templates, including HTML variables
for inserting HTML code. Just type in the variable in the position where you want to use it
in the standard format, complete with the opening <% tag and the closing %> tag.
Example:
...
<br /><br />

© 1997 - 2009 by EC Software, all rights reserved

440 Help & Manual 5 - User Help

</IF_TOPIC_HEADER>
<br /><hr />
By: <%HELPAUTHOR%>
<br /><hr />
<%TOPIC_TEXT%>
</body>
</html>
The above example inserts the contents of the user-defined variable between horizontal
rules above the topic text on every page.

How to use predefined variables in HTML templates

You can use both the global variables and the special HTML template variables. They are
used just in the same way as user-defined variables. Just type them into the template in
the position where you want to use them. Always type the variables exactly as shown in
the variable lists, complete with the opening <% tag and the closing %> tag.
Example:
...
<%TOPIC_TEXT%>
<IF_HTML>
<br><br><hr><center>Page URL:
<a href="http://www.domain.com/help/index.html?
<%HREF_CURRENT_PAGE%>" target="top">http://www.domain.com/help/index.html?
<%HREF_CURRENT_PAGE%></a></center>
</IF_HTML>
...
The above example inserts the web URL of the current page at the bottom of every topic
page in Webhelp. (This makes it easy for support staff to give users the address of
specific help topics in the online version of your help.)

Using editable variables in HTML templates

You can redefine both global and user variables in individual topics, by assigning a new
value to the variable for the topic in the tab behind the editor. This is particularly useful for
HTML templates because it enables you to insert individual code and text in your
templates for on a per-topic basis. For example, you can reference different versions of
JavaScript files in individual topics or insert individual texts in the head section of the
page for search engine optimization.
1. Use your user-defined or global variables normally in your HTML template. (This is
particularly useful for HTML variables!).
2. Select the topic where you want the variable to have a different value. Select the tab
and add the variable and its new value in the Topic Variables section.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 441

See The power of editable variables 395 for more detailed instructions.

See also:
Editing HTML templates 431
Global predefined variables 774 (reference list)
HTML template variables 778 (reference list)
Conditional output in HTML templates 441
The power of editable variables 395
6.7.9 Conditional output in HTML templates
You can use all of Help & Manual's standard conditional output options in HTML templates,
both your user-defined include options 406 and options based on the current output format. In
addition to this there are a few special conditional switches which are only for use in
Webhelp output, because they are only relevant there. See the lists below for details.
These conditions are used to enclose blocks of HTML code in your template that you want to
include in the output only if the condition is fulfilled. The condition tags themselves are never
included in your output code, they are always stripped from the code before publishing.
Conditions based on the output format are only relevant in the HTML topic page templates 433
which are used in HTML Help, Webhelp, Windows Exe and ePub eBooks and Visual Studio
Help / MS Help 2.0. The TOC, search and keyword index templates are only used in
Webhelp so it does not make sense to use format-based conditions there since the output
format is always Webhelp.

Conditional output reference

For more information on the available output conditions, variables and how to use them
see the following topics:
· List of HTML template output conditions 782
· Defining your own include options 406
· List of global predefined variables 774
· List of HTML template variables 778
· Creating user-defined variables 378

How to use include options in HTML templates

Like most HTML tags each condition has an opening tag and a corresponding closing
tag, using the same </ syntax to identify the closing tag as all regular tags. Simply
enclose the code you want to include conditionally between the two tags.
Note that the ELSE condition is not available in HTML templates.
Examples:
<IF_TOPIC_HEADER>
<font size="3">This text only appears in the topic if the topic has a <b>header</
b>.<br><br>
It will not be included in popup topics, which never have a header, or in topics

© 1997 - 2009 by EC Software, all rights reserved

 442 Help & Manual 5 - User Help

assigned
help window types defined without a header.</font>
</IF_TOPIC_HEADER>
<IFNOT_PREVIOUS_PAGE>This text will only be displayed in
the very first topic in your help.</IFNOT_PREVIOUS_PAGE>
<IF_NEXT_PAGE>
<a href="<%HREF_NEXT_PAGE%>">Click here to jump to the next topic</a>
</IF_NEXT_PAGE>
The last example only displays the link if there is a next topic to jump to.

How to use user-defined conditions

Basically this is exactly the same as using the predefined include options, you just have
to use the following syntax rules to create your conditional switches from the names of
your include options in Configuration > Common Properties > Custom Builds 658 :
Syntax:
Opening tag: < + IF_ + OPTION + >
Closing tag: </ + IF_ + OPTION + >
NOT version: < + IFNOT_ + OPTION + >
NOT closing tag: </ + IFNOT_ + OPTION + >

Examples:
This example shows how to use the user-defined include options ALPHABUILD and
BETABUILD :
<IF_ALPHABUILD>
This text will be included if ALPHABUILD is selected in the Include Options in
the
Make Help File & Run dialog.
</IF_ALPHABUILD>
<IFNOT_BETABUILD>
This text will be excluded if BETABUILD is selected in the Include Options in
the
Make Help File & Run dialog.
</IFNOT_BETABUILD>

See also:
HTML template output conditions 782 (reference list)
Editing HTML templates 431
Variables in HTML templates 439
6.7.10 Graphics references in HTML templates
You can reference external graphics in HTML templates – Help & Manual parses the
template code for image references and automatically includes the graphics in your output.
In addition to this you can also embed graphics in your project by adding them to the
Baggage Files. 485 Baggage graphics are always exported automatically when you compile
and they can be referenced without any path information in all HTML-based output formats.
See below for details.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 443

Supported graphics types and how to reference them

Graphics types:
You can use any image types supported in HTML pages – generally JPG, GIF and PNG
images.
Referencing graphics stored in your project folder and search path:
Graphics files stored in your project folder and in folders listed in your project search path
656 can be referenced in the supported tags (see below) without any path information, like

this:
<img src="logo23.jpg" width="200" height="42" />
The files will be located and exported with your published output automatically.
Referencing graphics with other tags:
If you use other tags to reference your graphics you must add the graphics to your
Baggage Files or copy them to your output folder manually to ensure that they are
exported (see below).
Referencing graphics stored in other locations:
If your graphics files are stored elsewhere you must include an absolute or relative path
to the current location of the graphics files in your template code. Here too, this feature is
only supported for certain tags (see further below on this page for details). For example:
<img src="../source files/graphics/logo23.jpg" width="200" height="42" />
If you use absolute paths it is advisable to use UNC path syntax, for example:
<img src="\\?\C:\Users\Robert\Desktop\Source Images\image7.jpg" />
<img src="\\MainServer\HelpStuff\Graphics\image10.jpg" />
When you publish Help & Manual will locate the files using the path you enter and then
strip the path in the published files and export the files with your output. The resulting
code in the three examples above would look like this:
<img src="logo23.jpg" width="200" height="42" />
<img src="image7.jpg" />
<img src="\image10.jpg" />

Where to store your source graphics files:

If you store the referenced external graphic files in the project directory (i.e. in the same
directory as the .hmxz or .hmxp project file) or reference the files with paths to their
location at publish time in your code they will be exported automatically. Alternatively you
can add the files to your project's Baggage Files see below for instructions.

Supported HTML image reference tags

Images referenced in your templates and stored in your project folder will only be found
and exported automatically when they are referenced in the HTML tags listed below.
All other image tags and attributes are ignored. If you reference graphics in your

© 1997 - 2009 by EC Software, all rights reserved

 444 Help & Manual 5 - User Help

templates in any other way you should add the images to the Baggage Files (see below)
or copy them to your output folder manually to ensure that they will be exported. This also
includes the variant images for mouseover buttons as they are not referenced with the
tags listed above!
Automatically Supported Attributes
Parsed Tags
<body> Images referenced with the background="" attribute.
OR
Images referenced within the style="" attribute using the syntax
style="background: #FFFFFF url(image.jpg)"
(this can be combined with other style elements, of course)

<img> Images referenced with the src="" attribute

<table> Images referenced with the background="" attribute

OR
Images referenced within the style="" attribute using the syntax
style="background: #FFFFFF url(image.jpg)"
(this can be combined with other style elements, of course)

Adding graphics to your project's Baggage Files

The easiest way to ensure that graphics files and other files referenced in your HTML
templates are located and exported correctly is to add them to your project's "Baggage"
in Project Files > Baggage Files in the Project Explorer. Then you can use any tag
references you like and you don't need to worry about whether the files will be exported
and integrated in your output.
All files in the Baggage Files section are integrated in your project automatically and can
be referenced in your template code without any path information.
See Using Baggage Files 485 for more information and instructions.

See also:
Graphics in HTML templates 811 (Reference)
Editing HTML templates 431
Variables in HTML templates 439
Conditional output in HTML templates 441
Using Baggage Files 485
6.7.11 Referencing external files
With the exception of a limited number of graphics references 442 external files you reference
in your template code are not automatically exported with your project because Help &
Manual does not know about them. There are two ways to solve this problem:

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 445

Add the files to your project's Baggage

The easiest way to ensure that graphics files and other files referenced in your HTML
templates are located and exported correctly is to add them to your project's "Baggage"
in Project Files > Baggage Files in the Project Explorer. Then you can use any tag
references you like and you don't need to worry about whether the files will be exported
and integrated in your output.
All files in the Baggage Files section are integrated in your project automatically and can
be referenced in your template code without any path information.
See Using Baggage Files 485 for more information and instructions.

Manually integrate the files in your output

In Webhelp you must manually copy the files to your output directory if you have not
added them to the Baggage (see above). The only exception to this are image files
referenced in supported tags, 442 which are exported automatically.
In HTML Help you need to tell the compiler to include the files in the CHM file. Proceed
as follows:
1. Copy the external file(s) to your project directory (the directory containing your .hmxz
or .hmxp project file).
2. In the Project Explorer go to Configuration > Publishing Options > HTML Help
> Extended .HHP Settings 670 .
3. In the Additional Settings editing box add the following entries:
[FILES]
..\functions.js
..\updatelist.txt
Don't add a second [FILES] header if one already exists. Enter each external filename
on its own line below the [FILES] header and precede it with the ..\ relative path
reference. This relative path reference is necessary because the project is compiled from
a temporary subdirectory in the project directory, so files in the project directory are one
level up. If your files are stored elsewhere you need to adjust the path accordingly.

See also:
Using Baggage Files 485
6.7.12 Troubleshooting
When you edit HTML templates manually Help & Manual does not verify the code in any
way. You are entirely responsible for checking and testing the code you write. It is a always
good idea to back up your template in an external text file before editing.

Backing up your template before editing

You can always revert to the standard default template with the Reset Defaults button

© 1997 - 2009 by EC Software, all rights reserved

 446 Help & Manual 5 - User Help

(see below), but you should make backups of working versions of your own edited
templates before you make more changes. Reverting to the default template overwrites
the entire template with the standard version it does not return you to your own previous
version.
Copy the entire contents of the template, paste it to an editor and save it in an external
file. Then if anything goes wrong you can always paste the original version from the
saved file back into the template editing window.

Testing your output regularly

Sooner or later editing your HTML templates will cause errors in your output. This cannot
be avoided and it happens to the best of us.
If you make a lot of different changes before testing your output it can be very difficult to
localize which change is causing the problem. To avoid this kind of frustration you should
always make changes gradually, one step at a time. After each change publish and test
your output before proceeding to the next change. Then you will always know which
change is causing the problem and it will be much easier to correct.

If something goes wrong revert to the default template

You can always restore the default template. Just select Reset in the template editing
screen.
However, this will completely replace your version of the template with the standard
version, so you will also lose any earlier changes you may have made to it. If you have
not already done so, make a backup of your own version before reverting to the default

See also:
Editing HTML templates 431

6.8 Working with Modular Help Systems

A modular help system is a help system that consists of multiple Help & Manual projects that
can be published as a single project. This can make it easier to manage large projects.
In addition to this it may sometimes be practical to break up projects into modules when you
are working in a team, even though it is also possible for all team members to work in the
same project together in Help & Manual Professional. For example, individual team
members may want to work on their parts of the project on their laptops.
See Modular Projects 764 in the Reference section for some more background information on
modular help systems.

See also:
Modular Projects 764 (Reference)

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 447

6.8.1 Support in output formats

Modular projects in Winhelp and HTML Help

In and HTML Help (CHM) and the obsolete Winhelp (HLP) you can create genuinely
modular help systems, in which your output consists of multiple help files that are all
displayed in a single Table of Contents (TOC). In these systems you can create different
versions of your help simply by including or excluding help file modules from your
distribution package: Modules that are not there are excluded from the TOC
automatically.

Modular projects in other output formats

You can also use Help & Manual's modular project features in other output formats.
However, here the advantages of using modular projects is only available during the
editing stage. The output is always a single help system.

6.8.2 Creating a modular project

Creating a modular project is just as easy as adding a topic to a project. Once you have
added the child project its TOC is displayed as part of the current project's TOC and you can
edit it directly if you turn off read-only mode (see below).
When you compile the master project the entire TOC of the child project is inserted in the
master TOC at the point where you insert the child project in the master TOC tree.
See Modular Projects 764 in the Reference section for some more background information on
modular help systems.

Productivity Tip
By default child modules are inserted in
read-only mode. This is recommended for
multi-user editing, otherwise all topics in
child projects will be locked for all users.
You can turn off read-only mode in
Configuration > Common Properties >
Miscellaneous.

How to create a master project

A master project is a normal Help & Manual project. The only thing that makes it a
"master" is the fact that it contains child projects. You can create either an "empty"
master project or a master project with content:
· An empty master project is a project without any topics of its own. It is simply a
framework for handling your child projects, and all the items in its TOC are child
projects.
· A master project with content also has its own topics. Your child projects are inserted
in the TOC along with the master project's own topics.
This distinction is actually a little arbitrary. You can always add topics to the master
project at any time, even if it is empty when you start. The only thing you need to
remember is that the master project's own topics will always be included in the output.

© 1997 - 2009 by EC Software, all rights reserved

448 Help & Manual 5 - User Help

How to add child projects

1. Click at the point in the master project's TOC where you want to insert the child project
(module).
2. Select Add Topic in Project > Managing Topics and then select the Include Help
Project option.

3. In the Project File: field click on the Browse button and select the .hmxz or .hmxp
project file you want to include.
Merge content on publishing: If you select this mode the external project's contents
will be displayed in the TOC of the current project and can be edited directly if you turn
off read-only mode (see below). Merged projects are still stored externally and their
topics are identified by small green icon in the TOC.
Merge content at runtime: This is for HTML Help and Winhelp only and just inserts a
placeholder in the TOC. The projects must be edited and published separately and are
only merged when the user views them if the help files are all present in the same
folder.
4. Click on OK to insert the child project in the TOC.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 449

Display for a project inserted Display for a project inserted

with publish time merging with runtime merging

How to edit the child project

Publish time merging:
If you choose publish merging the project will immediately be displayed as part of your
project's TOC and you can edit its topics directly, as though they were part of the current
project. The topics of merged projects are identified with green icons on the TOC entries.
Read-only mode:
By default the project will be inserted in read-only mode to prevent accidental changes.
You can activate editing in Configuration > Common Properties > Miscellaneous.
If you are using multi-user editing you should leave read-only mode ON, otherwise all the
topics of child projects will be locked for all other users as long as you have the master
project open.
Runtime merging:
If you choose runtime merging a placeholder is inserted in the TOC in the position in
which the child project will be inserted. You can edit the child project by right-clicking on
the placeholder and selecting Edit Child Project.

How to access a child project's files and configuration settings

Even when the TOC of the your child project is visible in the master TOC you cannot see
all of the child's topic files directly. Only the topic files with TOC entries are actually
displayed in the master TOC. You can access topic files without TOC entries and the
child's configuration settings in the Merged Projects section in the Project Explorer:

© 1997 - 2009 by EC Software, all rights reserved

450 Help & Manual 5 - User Help

This section is located right at the bottom of the Configuration section. Note that like the
TOC, the files and settings of merged projects are only shown for projects inserted in
publish-time merging mode. Runtime-merged projects are just placeholders and are not
really part of your project, they must be opened and edited separately.

How to change the merge method

The merge method for HTML Help (CHM) and Winhelp (HLP) is selected when you insert
the child project. To change it you must remove the child project from the TOC and re-
insert it with the other merge method.
1. Select the main module item in the Project Explorer and press DELETE or select Add
Topic > Delete in Project > Manage Topics.
2. Insert the same module again, selecting the other merge method.
Note that merge options are only relevant for HTML Help (CHM) and Winhelp (HLP). In
all other output formats the master and children projects are always published together as
one large help project, which is the equivalent of publish time merging.

Exporting runtime modules to other formats

When you insert a module in runtime mode it will only be exported to HTML Help and
Winhelp. If you want to export the same module to other formats you must insert it in your
TOC a second time in publish-time mode. When you do this you should also set the
include options for each version so that the correct version gets exported automatically
depending on the output format you choose:

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 451

Setting the include options:

Just right-click on the main module "node" (spiky green icon) in the TOC, select Include
in Builds in the context menu and then set the include options appropriately. Make sure
that you set the options so that it is not possible to export both versions together!
You can also access the include options in Manage Topics > Change in the Project tab.
See Conditions and Customized Output 399 for more details on using include options.

See also:
Modular Projects 764 (Reference)
6.8.3 Merge methods for CHM & HLP
In HTML Help and the obsolete Winhelp format you can create genuine modular projects
with separate help files that are displayed in a single TOC. This is called "runtime merging".
Alternatively, you can also combine all your modules to one large help file, just like the
output from a single project. This is called "publish-time merging".
Choosing the merge method is only relevant for Winhelp and HTML Help formats. All other
output formats use publish-time merging only, merging all the modules in your project to
create output that is exactly the same as output generated from a single project.
See Runtime and publish time merging 767 in the Reference section for full details of the
capabilities of these two different output methods for modular projects in HTML Help and
Winhelp.

How to choose and change the merge method

You can set the merge method separately for every child project you insert. You choose
the merge method when you insert the child project.
Important: The project filenames and the output filenames of the HLP or CHM files must
be identical. The references between the child and the master help files are
based on the filenames and if project and output filename don't match the
references will be invalid.

© 1997 - 2009 by EC Software, all rights reserved

452 Help & Manual 5 - User Help

Choosing the merge method while inserting a child project:

· Select Merge content on publishing or Merge content at runtime when you are inserting
the child project 447 in your master project.

Changing the merge method after inserting the child project:

To change the merge method just remove the module from the TOC and re-insert it with
the other merge method. You cannot change the merge method of a module without
removing it from the TOC first.
1. Select the main module item in the Project Explorer and press DELETE or select Add
Topic > Delete in Project > Manage Topics. This does not delete the project on the
disk, it only removes it from the TOC of the master.
2. Insert the same module again, selecting the other merge method.

Exporting runtime modules to other formats

When you insert a module in runtime mode it will only be exported to HTML Help and
Winhelp. If you want to export the same module to other formats you must insert it in your
TOC a second time in publish-time mode. When you do this you should also set the
include options for each version so that the correct version gets exported automatically
depending on the output format you choose:

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 453

Setting the include options:

Just right-click on the main module "node" (spiky green icon) in the TOC, select Include
in Builds in the context menu and then set the include options appropriately. Make sure
that you set the options so that it is not possible to export both versions together!
You can also access the include options in Manage Topics > Change in the Project tab.
See Conditions and Customized Output 399 for more details on using include options.

Additional merge options for HTML Help

In HTML Help you can specify what happens when the user tries to open the child CHM
module directly instead of the master module.
1. Open the Configuration section of the child module in the Project Explorer and
select Publishing Options > HTML Help > Extended .HHP Settings.
2. In the section If this is a child file, merged at run time select the Table of Contents you
want to open when the user opens the file directly.
If you select the master file TOC option opening the child file will be exactly the same as
opening the master file the entire integrated TOC of the master file will be displayed.
Otherwise the child file will open on its own, just like any other HTML Help file.

Additional merge options for Winhelp

If you are using runtime merging in Winhelp you may find that the offset (indentation) of
the child project's TOC within the master project's TOC is not correct. You can adjust this
with the TOC offset setting.
1. Open the Configuration section of the child module in the Project Explorer and
select Publishing Options > Winhelp > Modular Help Options.
2. Adjust the TOC Offset 702 to the value corresponding to the indentation you want to use
for the child module. A value of 1 is one level of indentation, 2 is two levels and so on..

© 1997 - 2009 by EC Software, all rights reserved

 454 Help & Manual 5 - User Help

See also:
Modular Projects 764 (Reference)
6.8.4 Managing modules in the TOC
You can manage module entries in the Table of Contents (TOC) in exactly the same way as
normal TOC items – they are normal TOC items.

Moving module entries

You can move module entries and change their level in exactly the same way as any
other TOC entries.
To move a module entry:
Modules can be moved around in the TOC in the same way as ordinary topics:

Select the main module entry in the TOC with the mouse and drag it, or use the normal
copy and paste methods to move by copying and pasting.
· Select the entry and use cut and paste.
· Use the and buttons in Write > Manage Topics.
To change the level a module entry:
Select the entry and click on the Promote and Demote buttons in Write > Manage
Topics.

To delete a module entry:

Select the entry and press DELETE, or select Add Topic > Delete in Write > Manage
Topics. (This does not delete the module project, it just removes the module entry from
the current TOC.)

Copying modules, second copies of modules

"Copying" modules is not possible because they are really only references to entire help
projects. If you want to insert the same module in a second project you must do this
directly.
You cannot insert a second copy of a module entry within the same project. Please don't
try to do this as it would cause irreconcilable conflicts in your output project because of

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 455

the duplicate topic IDs and context numbers it would create.

Using include options on your modules

You can use conditional output include options on entire modules in the same way as you
can on individual topics. To do this select the main module entry in the TOC and then
select Project > Change > Include in Builds to select the include options for the
module. You can also access the include options by right-clicking on the main module
entry in the TOC. See Modular projects include options 412 for full details.

How to access a child project's files and configuration settings

Even when the TOC of the your child project is visible in the master TOC you cannot see
all of the child's topic files directly. Only the topic files with TOC entries are actually
displayed in the master TOC. You can access topic files without TOC entries and the
child's configuration settings in the Merged Projects section in the Project Explorer:

This section is located right at the bottom of the Configuration section. Note that like the
TOC, the files and settings of merged projects are only shown for projects inserted in
publish-time merging mode. Runtime-merged projects are just placeholders and are not
really part of your project, they must be opened and edited separately.

© 1997 - 2009 by EC Software, all rights reserved

 456 Help & Manual 5 - User Help

See also:
Modular Projects 764 (Reference)
6.8.5 Managing graphics in modules
It's always important to avoid duplicate filenames for your graphics because of the way Help
& Manual manages graphics and locates your graphics files 249 . This applies in particular for
modular projects, because you will often have separate graphics folders for each project.
Duplicate names are OK if you use runtime merging 767 because then each module is
compiled individually and the correct graphics will be used. However, if you use publish time
merging 767 Help & Manual will only find the first instance of any duplicates as it searches
through the graphics folders to locate the correct files.

Use filename prefixes for graphics files in modules

· The simplest solution for this problem is to add a unique prefix to the filenames of
graphics files used in modules, in the same way that you use prefixes for the topic IDs
456 in modules.

· The prefix should be short – two letters and an underline character are usually plenty –
and should identify the module.

See also:
Managing your graphics 249
6.8.6 Managing IDs and context numbers
In modular projects you also have to devote some thought and planning to topic IDs and
context numbers 801 . Modules are completely separate projects and Help & Manual can only
prevent conflicts caused by duplicate IDs and context numbers within a single project. This
means you are responsible for making sure that you do not have duplicates in the modules
you are going to include in your help system.

When you need to avoid duplicates

· It is only really important to prevent duplicates when you use publish time merging 767 .
Duplicate topic IDs and help context numbers in modules merged at publish time will
cause link failures and other errors because they are all in the same output help file.
· Duplicate topic IDs and help context numbers are actually not a problem in projects
merged at runtime. Since the output consists of separate help files there are no
conflicts and all links will work normally. However, it is still a good idea to avoid
duplicates within projects because then you can always switch to publish time merging
without any problems if you need to.

How to avoid duplicate topic IDs

Help & Manual has a feature that makes preventing duplicate topic IDs very easy. In each
project you can automatically add a unique prefix to your topic IDs when you create a

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 457

new topic. Then even topics with the same basic ID will actually be different. For
example, with an auto-prefix the ID Introduction could be Master_Introduction in one
project and Mod1_Introduction in another project.
1. Go to Configuration > Common Properties > Miscellaneous 665 .
2. Enter a prefix for your topic IDs in the Topic ID Prefix: field. It's helpful to add an
underline character after the prefix, this makes the IDs easier to read in the various ID
lists displayed in Help & Manual. For example, the topics in this help file all use the
prefix HM_.
3. Repeat for each project you want to include in your modular help system.
If you assign a unique prefix to each project used in your help system and make sure that
it is used for all modules you won't have any problems with ID conflicts.

How to avoid duplicate help context numbers

Since you can't add prefixes to help context numbers you have to avoid conflicts here by
assigning a predefined range of numbers to each project in your help system this is
effectively the same as a prefix, you just have to make sure the ranges are far enough
apart so that they can never overlap.
1. Choose a range of numbers for each of your modules. Make sure that the range is
large enough to avoid overlaps even if you add a lot more topics to your project than
you initially expect to use! Help context numbers can have a value of 1 – 4294967295
(unsigned 4-byte integer) so this shouldn't be a problem.
2. Go to Project > Project Properties > Common Properties > Miscellaneous 665 .
3. Enter the starting number for the range assigned for the current project in the Start
with: field.
4. Enter a reasonable number for the Increment by: value. This should be large enough
to allow you to add topics between existing topics but small enough so that you won't
go out of your assigned context number range even if you add a lot of topics to your
project.
5. Repeat for every project you want to include in your modular help system.

How to set up existing projects to avoid conflicts

The above methods are fine for new projects. However, when you want to include
existing projects in a modular help system you may already have duplicates conflicts that
you need to deal with.
1. Check your projects to see whether the context number ranges and IDs used have
potential conflicts. The Project Reports 534 tool can be a helpful aid here.
2. Use the Help Context Tool 539 to assign new context numbers to your individual
modules.
Remember that when you change context numbers your programmers must also
change the corresponding calls to your topics made from your application!

© 1997 - 2009 by EC Software, all rights reserved

458 Help & Manual 5 - User Help

3. Edit your topic IDs to eliminate the conflicts. Introduce a prefix naming scheme for IDs
with a different prefix for each module. This must be done manually. You cannot
search and replace topic IDs in the Help & Manual editor.
4. After doing this use the Help Context Tool 539 and the Project Reports 534 tool to export
lists of the new context numbers and topic IDs for your programmers.
5. Check whether any scripts 223 or plain HTML code objects 231 inserted in your project
contain references to the old topic IDs. These are not updated automatically and need
to be checked. The same applies to any links to the old IDs from other projects and
help files.

Changing IDs and context numbers globally

The operations described below are only possible with the Professional version of Help &
Manual and are for advanced users only. If you don't feel comfortable with editing source
code directly you should not try this. Even if you do, please make a backup copy of your
entire project folder before starting!
Note that the risk of damaging your project when you do this is relatively high because it
is easy to make mistakes, particularly if you are performing multiple replaces without a
manual check for every instance. You have been warned!
Adding prefixes to topic IDs globally:
You need a tool that can rename multiple files and a text editor that can perform search
and replace on multiple files for this operation. Without these tools it would be just as fast
to edit your topic IDs manually.
1. If your project is not already saved in uncompressed XML format select Save As... in
the Application Menu and save it in an empty folder with the Help Project
(uncompressed XML) option. This will create a directory of plain-text XML files that
contain all the components of your project.
2. Using your multiple file renaming tool rename the topic files in the Topics folder to add
the prefix you want to have to the filenames – the topic IDs are the topic filenames.
3. Open the table of contents file in the Maps folder and add the prefix to all the topic IDs
in the href= attributes so that the match the new filenames created in step 2 – make
sure that upper and lower case match. This is necessary to make the TOC entries
point to the new topic filenames.
4. Open the .hmxp project file in a text editor and locate the section between the
<helpcontext-numbers> tags. Add the prefix to all the topic IDs in the href=
attributes that assign the help context numbers to specific topics so that the entries
match the filenames created in step 2. (This will only be necessary if help context
numbers are defined in your project.)
5. With your multi-file search and replace tool search all the topic files in the Topics folder
for type="topiclink" href=" and add your prefix after the href=" – you must search
for this entire string, otherwise you will add prefixes to file links, Internet links and
script links as well, and that would break them.
Warning:
Doing this will break links to topics that are not in the current project and you will need

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 459

to repair them afterwards. Broken links are highlighted in red. If you have a lot of
cross-project topic links you may not want to do this.
Changing context numbers globally:
You can also use the same method to change your context numbers globally. Here you
just need to add new number to the beginning of all existing context numbers to "shift"
them into a different range. You can do this by editing the .hmxp project file, which is
where the context numbers are stored:
1. Save in uncompressed XML mode and open the .hmxp project file in a text editor.
2. Locate the section between the <helpcontext-numbers> tags and add the "shift"
number to the beginning of all the context numbers. That's it.

See also:
Modular Projects 764 (Reference)
IDs, Context Numbers and Keywords 801 (Reference)
6.8.7 Creating links between modules
How you create links between modules depends to a great extent on whether you use
runtime or publish time merging. If you use publish time merging all the modules are always
present so you can use normal topic links. If you use runtime merging you should use the A-
link method (see below) for all links to modules which might not be present at runtime.

Basic principles
· Remember that runtime merging is only possible in HTML Help (CHM) and Winhelp
(HLP) help files. All other formats use only publish time merging.
· Even with runtime merging links from child modules to the master module are always
OK because the master module is always present.
· It is better to use A-links for all links from the master to child modules and between
child modules for runtime merging projects. Then you can always be sure that you will
not have problems if you ever need to leave a module out.
· External windows cannot be used across module boundaries in modular help with
HTML Help. You cannot make a link that opens a topic from another help file in an
external window. This is a restriction of HTML Help.

How to create normal links between topics in different modules

In modular projects you can create normal links between topics in different modules in
almost exactly the same way as between topics within a normal project. You just have to
bear in mind that the help file containing the target of the link must be present at runtime
(when the help is viewed), otherwise the link will be dead and the user will get an error
message.
1. Select the topic in which you want to insert the link topics in child modules are
identified in the Project Explorer with spiky green icons on their TOC entries:

© 1997 - 2009 by EC Software, all rights reserved

460 Help & Manual 5 - User Help

Display for a module configured

for publish time merging
If your child module is configured for runtime merging you cannot edit its topics in the
TOC then you must right-click on the module entry and select Edit Child in the
context menu to edit its topics.
2. Proceed as you normally would for inserting a topic hyperlink.
3. In the Hyperlink dialog 617 click on the browse button in the Help File: field and
choose the project or compiled help file containing the topic you want to link to. (It is
always preferable to choose a project rather than a compiled help file if possible.)
Never try to link to Winhelp files from HTML Help projects or to HTML Help files from
Winhelp projects. This will not work!
Links to compiled Winhelp files are extremely limited: You can only link to the default
topic, you cannot display or link to any of the other topics in the hyperlink dialog.
4. If you choose a project (.hmxz, .hmxp) or HTML Help (.chm) file the topic IDs of the
external project or help file will now be displayed in the Topic ID list. Choose the topic
(and anchor 226 if applicable) you want to link to and click on OK.
5. Remember that this link depends on the presence of the target help file. If there is any
chance that the target file may not be there at runtime don't link to it, or use the A-link
method described below.

How to use A-links to create links between modules

Use this method to create links between modules when you are not sure whether the
module containing the link target will be present at runtime or not. It creates a link that
points to both the main target topic and to an alternative topic in the master help module.
If the main target is present the user can select it from the dialog. If it is not present the
alternative topic is displayed automatically.
This method works in both Winhelp and HTML Help (the A-link macro is translated
automatically when you compile to HTML Help). Use it for creating links between the help
files of modular help systems if there is a possibility that the help files containing the
target topics may not be present at runtime. This can happen when you use runtime
merging and choose not to include one or more of the help files in your distribution.
Step 1: Prepare the alternative topic in the master project
The alternative topic should be in the master project because this is the only help file that
is always present in a runtime-merged modular help system.
1. Open the master help project and choose or create the alternative topic that you want
the user to be able to view when the other help file module containing the target topic

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 461

is not available. This can be any topic including a topic in the Topic Files section that
does not have a TOC entry.
2. Select this alternative topic in the Project Explorer, display its tab and enter a unique
A-keyword in its A-Keywords: field.
Step 2: Prepare the target topic in the child project
1. Select the topic you want to link to in the child project.
2. Display the topic's tab and enter the same A-keyword as above in its A-Keywords:
field.
This A-keyword should only be used in these two topics. If you use it in any other topics
in any module these topics will also be displayed in the link list.

Step 3: Create the link

1. Open the module in which you want to create the link. This can be a master module or
another child module.
2. Select the topic where you want to create the link and open the Insert Hyperlink dialog.
3. Select the Script Link option on the left, then select Winhelp macro.
4. Enter Alink() in the Script: field and type the keyword between the parentheses. If your
keyword is "about widgets" the dialog would look like this:

If the target help file is not present when the user clicks on the link the alternative topic
will be displayed automatically. If the target topic is present a dialog will be displayed in
which the user can select either the target topic or the alternative topic.
This is just a very simple example to show you how this solution works in principle. In
practice you can also make more complex solutions, using more alternative topics and
more keywords. If you use multiple keywords remember to separate them with
semicolons, like this:
Alink(about widgets;troubleshooting;widget solutions)

See also:
Using A-keywords 281
About A-keywords 806
Creating a modular project 447
Modular Projects 764 (Reference)
6.8.8 Publishing modular projects
When you are publishing modular projects to HTML Help and the obsolete Winhelp format
the procedure depends on the merging method 451 you are using for your child modules. If
you are using runtime merging you must publish all the child projects separately, they are

© 1997 - 2009 by EC Software, all rights reserved

462 Help & Manual 5 - User Help

not published automatically when you publish the master project.

All other output formats only use publish time merging.

Generating output with publish time merging

When you use publish time merging all the child modules of the master module are
combined. You only need to compile the master file, all child modules are included
automatically in a single compile run.
In Winhelp and HTML Help publish time merging is an option 451 that you can select for
each module in your master project. All other output formats always use publish time
merging.
In all other formats publish time merging is always used for all modules. All modules will
always be compiled together with the main project as one large project.

Generating output with runtime merging

Runtime merging is only possible for Winhelp and HTML Help. It is irrelevant for all other
output formats. Runtime merging is an option 451 that you can select for each module in
your master project.
Important: The project filenames and the output filenames of the HLP or CHM files must
be identical. The references between the child and the master help files are
based on the filenames and if project and output filename don't match the
references will be invalid.
Child modules configured for runtime merging must be published individually,
they are not published automatically when you publish the master module!
1. Check your master project for child projects configured for runtime merging they are
easy to identify because their contents are not displayed as part of the master
project's TOC.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 463

Display for a project inserted

with runtime merging
2. Right-click on the runtime modules, select Edit Child in the context menu, then select
the child projects in the Project Explorer and publish them.
If any of your child modules contain their own child modules configured for runtime
merging these must also be published separately.
3. Compile the master module.
4. Copy all the compiled help files to the same directory if you have not compiled them to
the same directory.

Settings controlled by the master project in publish time merging

When you use publish time merging almost everything is controlled by the master project.
The settings of the child projects are ignored and replaced by the settings of the master
project. However, if settings in the child projects are unique and not duplicated in the
master then they will be used:
Project Project search paths defined in the child projects that are not defined in
search paths: the master project are added to the end of the master project's list of
paths. When inserting a graphic or a snippet file Help & Manual then
searches through all the paths in order and inserts the first file it finds
with a matching name. This means you must be careful not to use files
with duplicate names in your child projects.

User-defined If child projects contain user-defined variables with names that are not
variables: used in the master project the definitions in the child projects will be
used. However, if the master project contains variables with identical
names then the definitions from the master project will be used.

Custom If a child project contains user-defined include options 406 not defined in
include the master project they are available in publish time merging.
options:

HTML topic The HTML topic page templates 433 of the master project replace all
page child project templates that have the same names. For example, this
templates: means that the Default template from the master project template is
always used in all child modules, replacing any template changes that
may have been made in the child projects.
If child projects contain HTML page template definitions with names not
used for templates in the master project then these HTML page
templates will be used in the child projects.
For example, if you have defined an HTML page template called
Secondary in your child module it will be used in the child module if
there is no HTML page template called Secondary in the master
module.
However, if the master module contains a template called Secondary
then the master's version will be used in the child module as well and

© 1997 - 2009 by EC Software, all rights reserved

 464 Help & Manual 5 - User Help

the version defined in the child module will be ignored.

Baggage Baggage files in the master project have priority over Baggage files
files: with the same name in child projects. See Baggage handling 488 for
further details.

See also:
Publishing Your Projects 311
Modular Projects 764 (Reference)
Baggage file handling 488
6.8.9 Multiple Webhelp projects
You cannot use runtime merging for Webhelp – it wouldn't make sense because this output
format always consists of multiple individual files, with one HTML file for each topic. When
you compile a project containing child modules to Webhelp all the child projects are always
compiled to a single HTML directory with a single index file and Table of Contents (TOC).
However, sometimes you may still want to set up a larger Webhelp project with a modular
structure, using a separate directory and index file for each module. When you do this the
Webhelp help systems in the separate output directories are referred to as "collections".

How to set up a "modular" Webhelp project

To do this you must create and edit completely separate projects. Do not use a master-
child structure your project modules must be independent of each other.
Publishing and uploading to your server:
When you publish your "modular" Webhelp projects each project must be published to a
separate folder. In the same way, when you upload the projects to your server you must
store them in separate folders. If you upload them all to the same folder you will probably
overwrite some files, resulting in errors.

Restrictions with "modular" Webhelp projects

There are some important restrictions and also some important points you need to
observe when working with collections and the links between them.
· These are not real modular projects. You cannot insert the child modules in a master
Help & Manual project. If you did this all the modules would automatically be integrated
in a single output folder, which is not what you want here. Separate "modules" must be
opened and compiled as separate projects.
· You can link between collections but you cannot merge their TOCs.
· You cannot create links to the target topics in the project files of the other projects
because Help & Manual cannot manage links between collections across directory
boundaries. You must use Internet links 218 , inserting the correct URLs and/or paths
between your planned directory locations yourself.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 465

Compiling projects to separate HTML directories

· Open each project and compile it separately, to a separate directory. A Webhelp
project like this in its own directory is called a "collection".
· Make sure that you manually enter a different output directory for each project in the
Index Page: field of the Publish 590 dialog. It is good to check this to make absolutely
sure that you are not publishing everything to the same directory.

Creating links between Webhelp projects

Do not try to use normal topic links for hyperlinks between Webhelp projects output to
separate directories. This will not work! Use Internet links 218 (see below for syntax).
In the Target window: field of the Hyperlink dialog 617 select:
Same as Opens the target topic in the current window. The TOC of the current
referring collection will continue to be displayed.
topic:

Top frame: Opens the target topic in the current window with the TOC of the target
collection. The TOC of the current collection will no longer be displayed.

New window: Opens the target topic in a new window together with its own TOC. The
current window remains open.

Syntax for links between collections

The standard syntax for links between collections is as follows:
index.html?topic_id.htm#anchor

Use lower The names and extensions of all the files generated for Webhelp are
case: all lower case, even if the topic IDs used to generate the file names
contain upper case characters (all file names are automatically "down-
cased" when you compile). This is very important – if you use upper-
case characters your links will fail on all Unix and Linux servers and
many other systems!

index.html This is the index file of the target project and it should always be
included in the links. Even though linking directly to the topic file may
seem to work the browser history may not be stored properly, making it
impossible for the user to return to the original topic by using the
browser's Back button.
By default the index file of Webhelp has the extension .html unless
you enter a different extension in the Index Page: field of the Publish
590 dialog.

© 1997 - 2009 by EC Software, all rights reserved

 466 Help & Manual 5 - User Help

?topic_id.htmThe ? character is necessary between the index file and the topic
filename. Each topic is stored in a separate file and the file name is
generated by converting all characters to lower case and adding .htm
to the topic's topic ID. 205 For example, if the topic ID is HM_Intro then
the topic file name would be hm_intro.htm.

#anchor This is optional and links to an anchor 226 in the target topic.

See also:
Webhelp 730

6.9 Command Line Options

Help & Manual supports a number of command line options that make it possible to fully
automate your publication process. If you also generate your documentation automatically
from your application using XML you can produce and publish your documentation without
ever opening Help & Manual manually.
Command line compilation supports Help & Manual's conditional include options 785 . In
combination with INI files and batch files 480 this makes it possible to generate multiple
versions of your project in multiple formats and to multiple destinations in one quick, efficient
process.
In addition to this you can also use command line compilation to apply project skins and
redefine your project's variables with values taken from an external text file.

6.9.1 H&M command line syntax

This syntax guide for the main Help & Manual program is a quick reference for users familiar
with using the command line. For detailed instructions see the other topics in this chapter.

Paths in the command line

The syntax examples all assume that you are entering the command lines in the Help &
Manual program directory, which is normally C:\Program Files\EC
Software\HelpAndManual5.
When you do this you must only enter a path for the project file argument (project.hmxz
in the syntax guide). All the other file name arguments automatically use this path so you
don't need to enter a path for them if they are stored in the project directory. You must
enter path information for all files stored in any other location. You can use relative paths
if you want – they are then relative to the project directory.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 467

Help & Manual (helpman.exe) command line syntax:

helpman.exe "<Path>\project.hmxz" /<format> /<other

switches> ...
Always enclose all paths and filenames containing spaces in quotes.

helpman.exe Single option, use The Help & Manual program file.
once only
<Path> Single option, use The path to the project file, e.g.
once once only "F:\Projects\Help
Project\project.hmx". Always
enclose this and the project file
name in quotes if they contain
spaces. This path is used
automatically for all other file
arguments for which you do not
enter paths.
project.hmxz / Single option, use The project file you want to open.
project.hmxp once only This must always come directly
after the Help & Manual program
file name.
/<format> Multiple option, use The output format switch. This
once per output must always be the first switch
format, followed by entered after the project file
the local options for name. The other switches listed
that output below can be used in any order
but they must come after the
output format switch.
Switches:
/CHM (HTML Help)
/HLP (Winhelp)
/HTML (Webhelp)
/HXS (Visual Studio Help / MS
Help 2.0)
/PDF (Adobe PDF)
/RTF (Word RTF)
/EBOOK (Windows Exe or ePub
eBook)
eBook format:
The eBook format (Windows Exe
or ePub) is determined by the
extension of the output filename.
If you use .epub an ePub file will
be created, if you use .exe a
Windows Exe eBook will be
created.
Examples:

© 1997 - 2009 by EC Software, all rights reserved

468 Help & Manual 5 - User Help

Help & Manual (helpman.exe) command line syntax:

helpman.exe "<Path>\project.hmxz" /<format> /<other

switches> ...
Always enclose all paths and filenames containing spaces in quotes.

/EBOOK=mybook.epub (creates
an ePub eBook)
/EBOOK=yourbook.exe
(creates a Windows Exe eBook)
Output file name and path:
You can also specify the output
file name and path. If you don't
specify it the values used when
you last compiled to the specified
format will be used.
Examples:
/CHM=testproject.chm
/HLP="F:\Final
Build\widgethelp.hlp"
/I=<include Local option, use Corresponds to the include
options> once per output options set in the Make Help File
format option, after & Run 590 dialog. User-defined
the format option. options 406 are also supported. Use
upper case only, separate options
with commas and don't type any
Always use this if
spaces between individual
your project uses
options.
format-based build
options! If you don't specify the /I switch
the program will use the last
include options used when you
last compiled to the specified
format.
Important: These options do not
select the output format!
Format include options:
ALL All builds and user-defined
options "true".
CHM (HTML Help)
HLP (Winhelp)
HTML (Webhelp)
HXS (Visual Studio Help / MS
Help 2.0)
PDF (Adobe PDF)
RTF (Word RTF)
EBOOK (Windows Exe or ePub
eBook)
Examples:

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 469

Help & Manual (helpman.exe) command line syntax:

helpman.exe "<Path>\project.hmxz" /<format> /<other

switches> ...
Always enclose all paths and filenames containing spaces in quotes.
/I=CHM,MYBUILD
/I=HTML,HXS,DEMOVERSION
You should always use this switch
to specify the valid output format
if your project uses format based
build options (conditional text or
TOC include options). Otherwise
the build options may not work
correctly!
For the same reason, when you
use the /I switch you should
also always include the format
you are exporting to.
You can use your user-defined
include options in exactly the
same way as the format include
options.

/V=<filename> Local option, can be Redefines some or all of the

used multiple times variables in your project with a
per output format list of variables in an external text
option, after the file. You can redefine both global
format option. The and user-defined variables. You
last file used has do not need to enter a path if the
priority. file is stored in the project
directory. Use quotes if the path
or filename contain spaces.
File format:
TITLE=Widget Editor V2.8
EDITORS=John and Jane Doe
COPYRIGHT=Widgets Inc., all
rights reserved
One line per definition, no quotes,
no spaces on either side of the =
sign.
Examples:
/V=variables.txt
/V="F:\Data
Sources\variables.txt"

/O=<filename> Local option, can be Apply a project skin 321 to the

used multiple times project when compiling. Enter the
per output format name of the .hmskin file for the
option, after the filename argument. Overwrites all

© 1997 - 2009 by EC Software, all rights reserved

470 Help & Manual 5 - User Help

Help & Manual (helpman.exe) command line syntax:

helpman.exe "<Path>\project.hmxz" /<format> /<other

switches> ...
Always enclose all paths and filenames containing spaces in quotes.

format option. The variables, settings, values and

last file used has styles in the project with those
priority. defined in the skin file. You can
use this switch multiple times,
specifying multiple skins. If the
same attributes are defined in
more than one skin the last skin
in the command line always has
priority.

/S=complete Local option, use Only includes topics and chapters

once per output with the status "complete" in your
format option, after published output. All topics with
the format option any other status are excluded.
Only the status "complete" is
supported for this switch.

/ Local option, use Specifies the name of the PDF

Template=<filenam once per output template file. Include the path
e> format option, after and use quotes if the path or file
the format option name contain spaces. Only
supported for PDF output. You do
not need to enter a path if the file
is stored in the project directory.
If you don't specify this switch
the program uses the template
selected for PDF in Project
Properties 690 .
/noclose Global option, use Leaves Help & Manual open after
once per command compiling is completed (it
line after all the normally exits automatically).
other options
/keeptemp Global option, insert Don't delete the temporary source
after the first format directories and files generated
option for which you when compiling HTML Help,
wish it to apply Winhelp and Visual Studio Help /
MS Help 2.
/L=<compiler log Global option, insert Outputs the compiler log to the
file> after the first format specified text file. If you don't
option for which you enter a path the file is stored in
wish it to apply the project directory. Use quotes
if the path or filename contain

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 471

Help & Manual (helpman.exe) command line syntax:

helpman.exe "<Path>\project.hmxz" /<format> /<other

switches> ...
Always enclose all paths and filenames containing spaces in quotes.

spaces.
If you use multiple output format
476 options or .INI files 480 you can

enter this switch after the last

output format switch to log the
error messages for all output
formats.
/debug Global option, use Display a message window before
once per command outputting showing the batch
line after all the commands and whether they
format options have been recognized properly.
Use for troubleshooting if your
command line doesn't work as
expected.

6.9.2 Project converter syntax

The project converter also has a command line version that you can use manually and in
batch files to convert old Help & Manual 3 and Help & Manual 4 projects. The program file is
called HMXConv.exe and is stored in the Help & Manual program directory.
The syntax of the project converter command line module is displayed automatically if you
open a command line window at the Help & Manual program directory and enter HMXConv.
exe (the version with a graphical user interface is HMC.exe).

Project converter (hmxconv.exe) command line syntax:

HMXConv.exe Inputfile Outputfile [switches]

· Always enclose all paths and filenames containing spaces in quotes.

· Wildcard characters are not supported.
· Switches can be included in any order after the output file argument.
· Relative paths are relative to the current directory – this is either the
current directory of the command prompt or the directory you set with the
CD command in your batch file.

HMXConv.exe The converter application, include a path to

the program if necessary. It is stored in the
Help & Manual program directory.
Inputfile The file to be converted. Include the
extension (.hmx or .hm3) and the path if

© 1997 - 2009 by EC Software, all rights reserved

472 Help & Manual 5 - User Help

Project converter (hmxconv.exe) command line syntax:

HMXConv.exe Inputfile Outputfile [switches]

· Always enclose all paths and filenames containing spaces in quotes.

· Wildcard characters are not supported.
· Switches can be included in any order after the output file argument.
· Relative paths are relative to the current directory – this is either the
current directory of the command prompt or the directory you set with the
CD command in your batch file.

necessary. Wildcards are not supported.

Outputfile The name of the converted project. You
must include the extension, as follows:
If you don't use the /decompress switch
use the extension .hmxz, a compressed .
hmxz file will be generated.
If you do use /decompress use the
extension .hmxp and include a path to an
empty folder.
/decompress Creates a decompressed XML project with
a .hmxp project file and separate XML files
for all topics. Include a path to an empty
folder with the Outputfile parameter
when you use this switch. Only supported
in the Professional version of Help &
Manual.
/noinvisibles Prevents creation of a Former Invisible
Topics folder in the TOC. Your invisible
topics will still be imported to the Topic
Files section in the new project.
By default the converter creates a folder
called Former Invisible Topics in the TOC to
show you the invisible topics that have
been imported from your old project. This
folder's build options are automatically set
to "none" so that it is not included in your
published output. It is a convenience only
and is not really needed.
/maxfolderdepth=x Sets the number of levels of invisible topics
folders in the new Topic Files section. The
default value is 1, the maximum value is
10. Set to a higher number if your old
project contains multiple levels of invisible
topics that you want to preserve.
/log=filename Saves any console messages to the
specified log file. Include a path if you want

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 473

Project converter (hmxconv.exe) command line syntax:

HMXConv.exe Inputfile Outputfile [switches]

· Always enclose all paths and filenames containing spaces in quotes.

· Wildcard characters are not supported.
· Switches can be included in any order after the output file argument.
· Relative paths are relative to the current directory – this is either the
current directory of the command prompt or the directory you set with the
CD command in your batch file.

to specify where the file is to be saved.

/fullreport Generates a detailed conversion report.

This will also be diverted from the console
to the log file if you include the /log
switch.

Options for Help & Manual 3 (.hm3) files

/autosizetables Converts fixed-width tables to autosize
mode.
/autosizelastcol Makes the last column of tables dynamic so
that the table width can adjust
automatically.
/jointables=tolerance Merges tables that are less than tolerance
pixels apart from each other.

/convertstyles Attempts to convert Help & Manual 3 style

names to dynamic styles in the new
project's stylesheet. Text that is not
associated with a clearly-defined style
name will not be converted.

6.9.3 Basic command line options

This topic describes the basic command line options available and how to use them by
entering the commands manually from a command line prompt. See INI and batch files 480 for
details on how to automate the process and for information on using more complex
sequences of commands.
See Syntax reference 466 for details of all the command line switches and arguments
available.

Paths in the command line

The examples all assume that you are entering the command lines in the Help & Manual
program directory, which is normally C:\Program Files\EC
Software\HelpAndManual5. When you do this you must only enter a path for the

© 1997 - 2009 by EC Software, all rights reserved

474 Help & Manual 5 - User Help

project file. All the other file name arguments automatically use this path so you don't
need to enter a path for them if they are stored in the project directory.
However, you must enter path information for all files stored in any other location. You
can use relative paths if you want – they are then relative to the project directory.

Basic syntax – opening a project from the command line

This is the simplest possible command. It just starts Help & Manual and loads the
specified project file. This is rather pointless on its own but it illustrates how the command
line is used.
· Switch to the Help & Manual program directory and enter the following command,
replacing F:\My Projects\ with the path to your project file and projectfile.hmxz
with your project file name, which can be an .hmxp or an .hmxz file:
helpman.exe "F:\My Projects\projectfile.hmxz"
· Note the use of quotes! Since the project path contains a space it must be enclosed in
quotes. The same applies for any file names in the command line that contain spaces.

Compiling a project from the command line

To compile a project from the command you just need to add an additional command
known as a "switch" to specify the output format you want to use. The following example
compiles the project to an HTML Help CHM file, using the last output location and file
name you used when you compiled manually.
See the Syntax reference 466 for details of the available output format switches.
helpman.exe "F:\My Projects\projectfile.hmxz" /CHM
The output format switch must always be the first switch after the project file name. All
the other switches can come in any order but they must be after the output format switch.
Note the use of quotes! All paths and file names that contain spaces must be enclosed in
quotes.

Compiling a project to a different location and file name

To compile a project to a different location and file name just add them to the output
format switch with an equals sign:
helpman.exe "F:\My Projects\projectfile.hmxz" /CHM="F:\My
Projects\Help\WidgetHelp.chm"
Note the use of quotes! All paths and file names that contain spaces must be enclosed in
quotes.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 475

Compiling to PDF with a specific PDF print manual template

The following examples generate PDF files with an explicitly-specified print manual
template. 425 The first example assumes that the print manual template is stored in the
project directory. The second example gets the template from the \Templates\Pdf folder
in the Help & Manual program directory.
Example 1:
helpman.exe "D:\Help Project\MyHelp.hmxz" /PDF=widget.pdf /
Template=a4_template.mnl

Example 2:
helpman.exe "D:\Help Project\MyHelp.hmxz" /PDF=widget.pdf /Template="<%
PROGPATH>Templates\Pdf\widget.mnl"

6.9.4 Using include options

You can use conditional output include options in the command line. These options control
what is included in your published output on the basis of the selected output format or user-
defined include option conditions. Setting them is equivalent to setting the include options in
the Publish 590 dialog when you publish manually.
Specifying include options is optional. If you don't specify this switch Help & Manual will use
the default include options, which are the options you used the last time you published to the
current output format manually.
See the Syntax reference 466 for details on all the available switches and parameters.

Key Information
Note that include options do not select the
output format! Include options only control
what is included in or excluded from your
project, not the output format of your
project.

How to use include options

When you use this switch you should always also specify an include option for the
current output format if you have any items tagged for that format, otherwise items
tagged for that format only will not be included. If you leave out the /I= switch the
include options set the last time you published the project manually will be used.
Add the /I= include options switch after the output format switch. Follow it with all the
include options you want to use, separated by commas. Don't use quotes or spaces (a
space would identify a new switch).
Examples:
helpman.exe D:\Projects\widgethelp.hmxz /CHM /I=CHM,FINALBUILD,USVERSION
helpman.exe D:\Projects\widgethelp.hmxp /CHM /I=CHM,HLP,DEMO

© 1997 - 2009 by EC Software, all rights reserved

 476 Help & Manual 5 - User Help

Both these examples output to HTML Help files (CHM). Note that the CHM include option is
included in both cases, to make sure that anything in the project tagged specifically for
CHM is included (otherwise only the items tagged for All Builds and the other include
options would be included.)
The second example also includes items specifically tagged for Winhelp (HLP) in the
HTML Help output, which would normally only be included when you compile to Winhelp.

Output format and user-defined include options

Output format include options (i.e. for the output formats supported by Help & Manual)
and user-defined include options are both used in exactly the same way. Just type the
options after the /I= switch, separated by commas.

See also:
Conditions and Customized Output 399
6.9.5 Output to multiple formats
You can generate output to more than one format with a single command line. The output
files are then generated one after another, in the order entered. This is OK if you want to do
a single multiple compile quickly but if you want to automate the process it is best to use INI
and batch files 480 so that you don't have to type complex command lines every time.
Basic syntax:
helpman.exe <path>\projectfile.hmxz /<format1> /<switches> /<format2> /
<switches> ...
Each format switch must be directly followed by all the switches you want to apply to that
format. Each format must have its own set of switches, they are not applied to multiple
formats.

Switches reference for multiple format output

Local and Global Switches for Multiple Output

Local switches
The following switches are "local". They must be applied to each output
format individually by inserting them after the format switch for which they
should apply and before the next format switch.
/I=<include options> The include options you want to use for the
output format.
/Template=<template> The PDF template to be used for PDF output
(only for PDF output).
/V=<filename> This switch specifies an external file to
redefine the values of variables in your

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 477

project file. Can be used multiple times per

output format, the last file called has
priority.
/O=<filename> This switch specifies an external .hmskin
HTML skin file to apply to your output. Can
be used multiple times per output format,
the last skin file called has priority.
/S=complete Only output topics with the status
"complete".

Global switches
These switches can only be used once per command line and they apply from
the point in the command line at which they are inserted.
/keeptemp Doesn't delete the temporary directories and
source files generated for Winhelp and HTML
Help output. (Applies to Winhelp and HTML
Help only.)
/E=<compiler log file> Outputs the compiler log to the specified
file.
/debug Displays debug information for each output
format before compiling.
/noclose Leaves Help & Manual open after compiling.
Only use at the end of the command line.
If you have multiple output formats in a single command line you must insert
these switches directly after the first output format to apply them to all output
formats. To apply them only to some output formats insert the switches after
the first output format for which you wish them to apply.
Examples:
1) helpman.exe project.hmxz /CHM /keeptemp /HLP
2) helpman.exe project.hmxp /CHM /HLP /keeptemp
Example 1) above keeps the temporary files for both the CHM and HLP
output. Example 2) only keeps the temporary files for the HLP output. The
same applies for log files and debug information.
The /noclose switch should only be used at the end of the command line,
otherwise you will open multiple instances of Help & Manual.
See Syntax reference 466 for more information on the individual switches and
parameters.

Multiple output format command line examples

Example 1:
The following example compiles a project file to HTML Help and PDF, using conditional

© 1997 - 2009 by EC Software, all rights reserved

 478 Help & Manual 5 - User Help

output include options for the HTML Help file and selecting a specific PDF print manual
template for the PDF output file. The template is assumed to be in the project directory; if
it is stored somewhere else you must include its path.
helpman.exe D:\Projects\widget.hmxz /CHM=widgethelp.chm /I=CHM,DEMO /
PDF=manual.pdf /Template=manual.mnl

Example 2:
The following example compiles to Webhelp and Winhelp using include options. The /
noclose switch at the end of the command line leaves the program open when compiling
is finished.
helpman.exe D:\Projects\widget.hmxp /HLP /I=HLP,FINAL /HTML=D:
\HTML\index.html /I=HLP,FINAL /noclose

See also:
.INI and batch files 480
6.9.6 Skins & redefining variables
You can also apply project skins and redefine some or all of your variables from the
command line. Note that creating user-defined skins is only possible with the Professional
version of Help & Manual. You can use existing skins with the Standard version but you
cannot save or edit your own skins.
Skins are applied with the /O= switch and can completely restyle your entire project,
including the user-defined variables it depends what you store in the skin file. The older
variables file method is applied with the /V= switch and only redefines variables.
When you are outputting to multiple formats you must enter separate /O= and /V=
switches for each output format for which you wish to redefine the variables. See Output to
multiple formats 476 and .INI and batch files 480 for details.

Applying project skins with the /O= switch

The easiest way to redefine user-defined variables in your entire project is with skins,
which can also apply an entirely new design to your project. In addition to user-defined
variables skins can also include your HTML page templates, your Baggage files and your
text and table styles. What is included depends on what you save with the skin file.
1. Save a project skin file (preferably in your project folder) and edit it with the values you
want to use. See Transforming your output with skins 321 for full details.
2. Reference the skin file in your command line with the /O= switch.
If the file is stored in your project directory you don't need to enter a path for the variables
file because the path to the project file is used automatically. If it is stored anywhere else
you must enter a path. (You can enter either absolute paths or relative paths relative to
the project directory.)
Examples:
helpman.exe "D:\Project Files\Widget Help\Myproject.hmxp" /O=demoversion.
hmskin

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 479

helpman.exe "D:\Project Files\Widget Help\Myproject.hmxz" /O="D:\Data

Files\lightversion.hmskin"
Remember, if any paths or file names contain spaces you must enclose them in quotes!
Multiple skins:
You can specify multiple skins for the same output format in a single command line. If the
same attributes are defined in more than one skin the attributes from the last skin in the
command line will always be used.
If you want to specify skins for separate output formats you must do so separately for
each output format.

Redefining variables with the /V= switch

This method only redefines variables. You can also combine the two methods in any order
if the skin file and the variables file both redefine the same variables the last file in the
command line has priority.
Step one: Create a file with the new definitions
1. Create a new plain-text file and enter each variable you want to redefine with its new value
on a separate line using the following syntax. You don't have to redefine all the variables.
Only those included in the file will be affected.
VARIABLENAME1=The new value of variable 1
VARIABLENAME2=<a href="http://www.ec-software.com/">EC Software Website</a>
VARIABLENAME3=The new value of variable 3
Don't enter the <% and %> tags for the variable names in this file and don't insert quotes
around the variable value strings. Don't enter tabs or spaces to the left or right of the =
signs.
Be careful to enter HTML code for HTML variables and text for text variables. If you enter
HTML code for text variables the code will be interpreted as plain text.
2. Save the file with the .txt extension in your project directory.

Step 2: Publish your project with the /V= switch

Add the /V= switch with the name of the variables file created in Step 1 to the command
line. If the file is stored in your project directory you don't need to enter a path for the
variables file because the path to the project file is used automatically. If it is stored
anywhere else you must enter a path. (You can enter either absolute paths or relative paths
relative to the project directory.)
Examples:
helpman.exe "D:\Project Files\Widget Help\Myproject.hmxp" /V=variables.txt
helpman.exe "D:\Project Files\Widget Help\Myproject.hmxz" /V="D:\Data
Files\variables.txt"
Remember, if any paths or file names contain spaces you must enclose them in quotes!

See also:
Using Variables 376

© 1997 - 2009 by EC Software, all rights reserved

 480 Help & Manual 5 - User Help

6.9.7 INI and batch files

As you have probably already realized, command lines can get quite long and complex,
particularly if you use them to generate multiple output formats to different locations
simultaneously. You can solve this problem with configuration files called INI files that
contain all the parameters you want to process, including output to as many different formats
as you want.
If you combine this with a batch file in the Help & Manual program directory and create a
shortcut to this file on your desktop you can automate the entire process and publish to
multiple output formats with complex options for each format with a single mouse click.

How to create an .INI file

Use a text editor to create a plain text file with the extension .ini (for example
batchoutput.ini ) in the project directory of the project you want to publish.
· The INI file contains all the switches and parameters that come after the project file
name, with one switch or parameter per line. They must be entered in exactly the same
order as you would enter them on the command line. That means the output format
switch always comes first, followed by all the other switches.
· The rules for multiple output 476 are also the same as on the command line. First the first
output format switch followed by its switches, then the next output format switch
followed by its switches, and so on.
· The switches you can use in the INI file are exactly the same as the command line
switches. However, they must all be entered on a single line and they are not preceded
by a slash.
· Unlike command lines, you must not use quotes in INI files, even if your arguments
contain spaces! This is very important!
· You can enter comments if you want. Comments must be entered on a single line and
preceded by a ; semicolon character.
Example:
CHM=F:\Project Files\Help Project\Help\WidgetHelp.chm
I=CHM,FINALBUILD
KEEPTEMP
; This line is a comment
PDF=F:\Project Files\Help Project\PDF\WidgetHelp.pdf
I=PDF,FINALBUILD
Template=usletter.mnl
L=F:\Project Files\Help Project\Logs\publishlog.txt

What this example INI file does:

Note that the INI file only includes all the options that would normally come after the Help
& Manual program file name and the project file name in the command line. The program
file and project file must still be included in the command line, or in a batch file.
· The first line publishes to HTML Help with a specific output directory and filename.
Specifying the output explicitly allows you to publish to other destinations manually in
Help & Manual without worrying about changing the destination of the .INI file output.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 481

(Every time you publish manually you automatically reset the default output
destination.)
· The I=CHM,FINALBUILD include options switch includes everything tagged with the
user-defined option FINALBUILD. Since you have specified a user-defined option you
must also specify CHM to ensure that any items specifically tagged for HTML Help are
also included. KEEPTEMP tells Help & Manual not to delete the temporary source files
used to generate the HTML Help output.
· Then the same project is output to PDF, also with a specific output directory and
filename. The include options are the same, but with PDF instead of CHM to include the
appropriate topics in addition to everything tagged with FINALBUILD.
· The Template=usletter.mnl line specifies the PDF print manual template 425 to be
used for the output. Since no path is specified this is assumed to be in the project
directory. If it is stored in any other location you must include a path.
· Finally, the L= parameter stores all the messages associated with the publish
operation in a log file in a specified location. If no path had been included this file would
have been stored in the project directory.

© 1997 - 2009 by EC Software, all rights reserved

482 Help & Manual 5 - User Help

Switches reference for multiple format output

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 483

Local and Global Switches for Multiple Format Output

Local switches:
The following switches are "local". In .INI files They must be applied to each
output format individually by inserting them after the format switch for which
they should apply and before the next format switch.
I=<include options> The include options you want to use for the
output format.
TEMPLATE=<PDF template> The PDF template to be used for PDF
output (only for PDF output).
V=<filename> This switch specifies an external file to redefine
the values of variables in your project file.

Global switches:
These switches can only be used once per .INI file and they apply from the
point in the .INI file at which they are inserted:
KEEPTEMP Doesn't delete the temporary directories and
source files generated for Winhelp and HTML
Help output. (Applies to Winhelp and HTML
Help only.)
L=<log file> Outputs the publication log to the specified
file.
DEBUG Displays debug information for each output
format before publishing.
NOCLOSE Leaves Help & Manual open after compiling.
Only use at the end of the .INI file.
If you have multiple output formats in a single .INI file you must insert these
switches directly after the first output format to apply them to all output
formats. To apply them only to only some output formats insert the switches
after the first output format for which you wish them to apply.
Examples:
1)
CHM=project.chm
KEEPTEMP
HLP=project.hlp

2)
CHM=project.chm
HLP=project.hlp
KEEPTEMP

Example 1) above keeps the temporary files for both the CHM and HLP
output. Example 2) only keeps the temporary files for the HLP output. The
same applies for log files and debug information. The NOCLOSE switch should
only be used at the end of the .INI file, otherwise you will open multiple
instances of Help & Manual.
See
© 1997 - 2009 by EC Syntax
Software, reference
all rights 466
reserved for more information on the individual switches and
parameters.
484 Help & Manual 5 - User Help

How to use the INI file from the command line

To use an INI file just specify it as the first and only parameter after the project file name
in the command line. If it is stored in the project directory you don't need to specify a path
for it. If it is stored anywhere else you must specify a path.
As usual, the example assumes that you are working from the Help & Manual program
directory.
Example:
helpman.exe "D:\Help Project\Widget\WidgetHelp.hmxp" batchoutput.ini
This starts Help & Manual, opens WidgetHelp.hmxp and then executes all the
commands specified by the switches and parameters contained in batchoutput.ini.

How to use the INI file from a batch file

You can take this one step further and automate the process completely by putting the
command line (or lines!) with the reference to the .INI file in a batch file. Then you can
create a shortcut to the batch file and perform the entire complex output process by
double-clicking on the shortcut. Here's how:
· Create a plain text file with the extension .bat or .cmd (for example batchoutput.bat)
and store it in the Help & Manual program directory. Then you only need to enter the
path to the project file, since all other parameters automatically use the path of the
project directory.
· Enter each command line you want to execute on a separate line in the file, as shown
in the example below.
· Finally, create a shortcut to the batch file. The most convenient location for this is
normally on your desktop, but it can be anywhere you like. Then double-clicking on the
shortcut will execute the batch file, which will use the settings in the specified INI file (or
files) to perform all the operations you have specified.
Batch file example:
@ECHO OFF
helpman.exe "D:\Help Project\Widget\WidgetHelp.hmxp" batchoutput.ini
helpman.exe "D:\Help Project\Widget Two\WidgetTwoHelp.hmxz" batchtwo.ini

The @ECHO OFF command suppresses the output to the command console. It is not really
required, it is just customary to use it.
You will normally only want to use one command line with an .INI file per batch file, but
there is nothing to prevent you from including as many as you like. They will all be
processed one after another when you call the batch file.
Remember to store each .INI file in its own project directory – i.e. in the directory in
which its associated .hmxz or .hmxp project file is stored.

See also:
Output to multiple formats 476

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 485

6.9.8 Publishing from your application

If you follow the rules and syntax of the Help & Manual XML Language you can generate
Help & Manual projects directly from your application and publish them to any supported
output format without ever opening Help & Manual.
This can be useful for producing things like automated program code documentation for
which you do not need to edit the project in Help & Manual. Of course, you can also edit the
projects you generate from your application manually with Help & Manual later if you want.
Note that Help & Manual Professional is required for this because the Standard version
cannot read or write uncompressed XML project files.

Generating projects programmatically

To write topics and projects directly, either from your application or manually, you need to
follow the rules and syntax of the Help & Manual XML Language, which are documented
in detail in the file Helpman_XML_ref.chm. This file can be found in the Help & Manual
program directory.
The best way to get started is to work through this tutorial on the Help & Manual User
forum:
Creating Content from Scratch with XML
You need to be a forum member to access this section. Registration is free and without
any obligations, just click on Register in the forum header and follow the instructions
displayed.

Auto-publishing after you generate

After generating your project from your application you can then publish it automatically
with batch commands, following the instructions in the other topics in this chapter. You
don't need to open Help & Manual to do this provided you don't want to edit the content
before publishing the entire process can be fully automated.
Note that this is only possible if you create an entire XML project, including a full, valid .
hmxp project file. You cannot compile individual XML topic files programmatically with this
method.

6.10 Using Baggage Files

The Project Files > Baggage Files section in the Project Explorer enables you to add a
collection of small, frequently-used files to your project. The entries in the Baggage Files
section are not links or references, they become a physical part of your project.
These files are stored together with your project files and they are always accessible, even if
you delete the original source files. If you use the single-file .hmxz format your baggage files
are stored inside your project file. In the uncompressed .hmxp XML format (Professional
version only) they are stored in the Baggage folder inside your project folder.

© 1997 - 2009 by EC Software, all rights reserved

 486 Help & Manual 5 - User Help

6.10.1 Uses for Baggage Files

There are two main uses for the Baggage Files section: For files of your own referenced in
your HTML code and scripts and as a repository for small, frequently-used graphics you
want to keep with your project, particularly those used in your HTML templates (for example
logos, buttons etc).

Integrating files referenced in HTML code and scripts:

There are a number of functions in Help & Manual that allow you to insert your own inline
HTML code in your output or to modify the HTML code generated by the program. These
include HTML Code Object Tool 231 , the HTML code editing function of the Insert Movie
Tool 271 , all the HTML editing functions for HTML templates 430 and the code you enter in
scripts and macros 223 .
If you want to reference graphics files and other files in this code Help & Manual normally
has no way of knowing that these files exist or that you want them to be exported with
your project when you publish. The Baggage Files section provides a quick and elegant
way of solving this problem.
All files that you add to your project as Baggage are automatically exported when you
publish your output and can be referenced in your HTML code by name only, without any
additional path information.

Frequently-used graphics
You can also use the Baggage Files section for storing small, frequently-used graphics
files for example custom icons used for your Table of Contents in Webhelp output or
logo images that you use frequently. Once you have added them to the Baggage you can
delete any graphics files used in your project from other locations. Help & Manual always
looks for files in the Baggage first, so if they are there they will be found, for all output
formats.
This is a useful way of keeping the files associated with your project together but it should
generally only be used for relatively small files. This applies particularly if you are using
the single-file .hmxz format, because all your Baggage files are stored inside the .hmxz
file together with all the other project components. (The Standard version of Help &
Manual only supports the .hmxz format .)

6.10.2 Adding and referencing files

All files you add to the Baggage Files section are automatically included/exported in your
HTML-based output. This is the best way to include files referenced in manually-edited code
in your projects. You can reference all files in the Baggage section directly in your code. You
don't have to add any path information because the files are always available on the same
directory level as the other help files. All necessary copying and references are handled
automatically by Help & Manual.
· Note that non-graphics Baggage files are only exported in HTML-based formats (HTML
Help and Webhelp). They are ignored in all other formats.
You can use Baggage files for files referenced in the code entered with Insert > HTML Code
231 , the HTML code editing function of the Insert Movie Tool 271 , all the HTML editing

functions for HTML templates 430 and the code you enter in scripts and macros 223 .

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 487

Adding files to the Baggage section

Files you place in the Baggage section become part of your project and are always
available. They do not have to be loaded from any external directory – you can even
delete the original files after adding them to your Baggage.
1. In the Project Explorer, select Project Files > Baggage Files.
2. In the Ribbon select Add File > Add New File in Project > Manage Topics.
3. Select the file you want to add and click on OK. The file will be added to the Baggage
list and will become part of your project.
Note that you can use include options 488 for Baggage files!

Referencing Baggage files in your HTML code

Baggage files are always directly accessible for your code and they are always in the
same directory as the other files in your output. This also applies in HTML Help – here
the Baggage files are in the same internal "virtual directory" inside the CHM file as all the
other files in your HTML Help system.
Baggage files can be referenced directly without any path information because they are
always stored on the same directory level as the other help files. Just enter the name of
the file as it is shown in the list in the Baggage section.

See also:
Inserting plain HTML code 231
Flash Animations and Video 271
Using HTML Templates 430
Inserting script and macro links 223
6.10.3 Removing, exporting and importing
Removing and exporting files stored in the Baggage section are generally quite
straightforward operations but there are a couple of points you need to bear in mind. You
can also import the baggage files from other projects.

Removing and exporting Baggage files

Removing Baggage files:
1. Go to Project Files > Baggage Files in the Project Explorer and select the Baggage
file you want to remove.
2. Press DELETE or select Add File > Delete Entry in Project > Manage Topics.
Note that this physically deletes the selected file from your project. If you want to keep a
copy of it export it first before deleting it (see below).
Exporting Baggage files:
This saves a copy of the selected Baggage file in a new location (for example to back up

© 1997 - 2009 by EC Software, all rights reserved

 488 Help & Manual 5 - User Help

the file before removing it from your project).

1. Go to Project Files > Baggage Files in the Project Explorer and select the Baggage
file you want to export.
2. Select Save Baggage File As... button in the lower right corner of the Help & Manual
window.

Importing Baggage files from other projects

You can import all the Baggage files from another Help & Manual project to the current
project. Files with duplicate names will be overwritten when you do this.
1. Select the Baggage Files section in the Project Explorer.
2. Select Add File > Add New File in Project > Manage Topics and select the Help &
Manual you want to import the Baggage files from.
3. You will be asked if you want to import the Baggage files from the selected project.
Confirm to import the files.

Renaming Baggage files

You cannot rename Baggage files directly in Help & Manual. To rename a Baggage file
remove it from the Baggage list (see above), rename the original file and then add it to
the Baggage list again.
Warning: Do not attempt to rename Baggage files on the disk in Windows Explorer,
doing this will cause errors in your project!

6.10.4 Baggage handling

This topic summarizes how Baggage files are handled by Help & Manual. This information
will help you to understand how Baggage works.

Where and how Baggage files are used

Graphics in the Baggage section can be used for all output formats. If you use graphics
formats not directly supported by the output format they will be converted automatically
when you compile, just like the other graphics in your project.
For example, BMP files will be converted to a format compatible with HTML in HTML-
based output formats. References to the BMP files in your topics will be adjusted
automatically but references to BMP files in your own HTML code will fail – they would
have failed anyway because BMP is not supported in HTML.
Non-graphics files in the Baggage section are only relevant for HTML-based formats.
They are ignored in all other formats.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 489

Using include options with Baggage files

You can use conditional output include options on Baggage files just as you can on
topics. This makes it possible to explicitly include or exclude individual Baggage files in or
from specific output formats or builds.
1. Select the Baggage file in the Project Explorer.
2. Right-click on the Baggage file and select Include in Builds in the context menu.
OR: Select Change > Include in Builds in Project > Manage Topics.
3. Select the build options you want to apply to the file.

Baggage graphics files have priority

Baggage graphics files have priority over graphics files stored in the folders in your
project search path 656 . If a graphics file in the Baggage section has the same name as a
file on the project search path the Baggage version will always be used in the output.
This means you must take care to avoid duplicate file names in your graphics folders and
the Baggage section, otherwise the versions in your graphics folders will be "invisible" to
the program when you generate your output. (In any case it is better to use the Image
Shortcuts 251 function for graphics than Baggage.)

Size of the Baggage section

Since Baggage files are physically stored as part of your project they should only be used
for a small collection small files. Use the Image Shortcuts 251 function for frequently-used
graphics files.
This is particularly important when you are saving in the single-file .hmxz format, which is
the only format supported by the Standard version of Help & Manual. Adding a large
number of large files to your Baggage will significantly inflate the size of the .hmxz project
file, which may cause problems on slower computers with less memory.

Baggage files in modular projects

The Baggage files from project modules are also merged in your output when you are
using compile-time merging. If individual modules contain Baggage files with the same
names Help & Manual always uses the first Baggage file encountered and ignores all
other Baggage files. This means that Baggage files in the master module always have
priority, followed by the child modules in the order in which they are processed.
For example, if both the master module and the child modules contain Baggage files
called redarrow.gif and functions.js the versions of the files in the master will
project be used in the entire project, both in the master module's topics and in the child
module's topics. The versions in the child modules will be ignored.
If two child modules contain different versions of a file with the same name the first
version encountered will be used in the topics of both modules and the other version will

© 1997 - 2009 by EC Software, all rights reserved

 490 Help & Manual 5 - User Help

be ignored.
To make sure that Baggage files in child modules are used in the child module you must
make sure that their names are unique and not used in any other modules, including the
master module.

See also:
Working with Modular Help Systems 446

6.11 Visual Studio Help (MS Help 2.0)

Visual Studio Help is also known as MS Help 2.0. Originally this help format was intended to
be the successor of HTML Help. However, Microsoft then postponed its release indefinitely
and it is now clear that it is never going to be released as a help format for normal user
applications.
You cannot view or create Visual Studio Help files unless you have Microsoft Visual Studio
2002 or later installed on your computer. Visual Studio Help is now only used for
documenting add-on components designed to be integrated into the Visual Studio .NET
programming environment.
This section provides a very brief introduction to publishing Visual Studio Help with Help &
Manual. If you want to use Visual Studio Help you need to be experienced in VS.NET
programming, otherwise you shouldn't even think about using this help format. In addition to
this you should also study the relevant Help 2.0 documentation in both VS.NET and the
Visual Studio Help Integration Kit (VSHIK, check the MSDN site for details) very carefully.
Support for Visual Studio Help/MS Help 2.0 is only included in the Professional version of
Help & Manual.

See also:
Visual Studio Help 738 (Help Formats)
Visual Studio Help 694 (Project Configuration)
6.11.1 Requirements and limitations
Visual Studio Help/Help 2.0 is completely irrelevant as a normal help and documentation
format. You cannot use, view or create Visual Studio Help files unless you have Microsoft
Visual Studio 2002 or later installed on your computer. You cannot use Visual Studio Help to
document normal application programs.
In addition to this, Visual Studio Help is severely limited in its capabilities. Generally
speaking, unless you are a Visual Studio .NET programmer it is about as useful as square
wheels on a bicycle or a refrigerator at the North Pole.

Limitations of Visual Studio Help

Surprisingly for a help format that was touted as the best thing since sliced bread, the
features and capabilities of Visual Studio Help are actually considerably more limited than
those of either Winhelp or HTML Help, the formats it was originally supposed to replace.
Many common features of Microsoft's earlier help formats are not available in Visual
Studio Help. For example, window types 121 are not supported at all, nor are links to

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 491

external files. Links to external videos are also taboo in Visual Studio Help. The only
external links that are permitted are web URLs with absolute addresses.

What you need to publish and view Visual Studio Help

To publish Help 2.0 you need Visual Studio 2002 or later and the Visual Studio Help
Integration Kit (VSHIK), which can be downloaded from the Microsoft website (check the
MSDN site for details). Both these packages must be installed to publish Help 2.0 with
Help & Manual.
After installing the Help 2.0 compiler go to View > Program Options > Compilers 649
in Help & Manual and make sure that the correct path is entered to the compiler
executable.
To view Help 2.0 documentation you only need Microsoft Visual Studio 2002 or later, the
VSHIK does not have to be installed. Unlike HTML Help there is no stand-alone version
of the Help 2.0 viewer. If you don't have MS Visual Studio installed you can't view Help
2.0.
The MS Help 2.0 compiler:
The MS Help 2.0 compiler is part of the Visual Studio Help Integration Kit (VSHIK), which
you must download from the Microsoft website in the correct version for your version of
Visual Studio .NET. Unlike the HTML Help and Winhelp compilers it is not a stand-alone
compiler system. It can only be used in combination with Visual Studio .NET, which you
will have if you are programming Visual Studio .NET components. If you are not
programming Visual Studio .NET components you don't need it. Got it?
The Visual Studio Help Integration Kit:
This package is available directly from the Microsoft website. Unfortunately, the download
location has been changing quite frequently recently so you will need to search for it on
the MSDN site yourself – any download link we could provide here would probably be
obsolete again by the time you read this.

See also:
Visual Studio Help 738 (Reference)
6.11.2 About compiling VS Help
If you are not familiar with Visual Studio .NET you shouldn't really even think about working
with Visual Studio Help (Help 2.0). It is an extremely complex help system and the Help 2.0
compiler is both tricky and picky.

Required settings
The Help 2.0 compiler requires a "Namespace" and a "Unique Identifier" (also referred to
as a "Unique Title ID" in the documentation). Both must be entered otherwise the
compiler will quit with an error message. (The Namespace is used to call the help viewer,
the Unique Identifier is like a Topic ID for the entire help file.)
In Help & Manual you can enter these settings in Configuration > Publishing Options
> Visual Studio Help > Namespace & Options 694 .

© 1997 - 2009 by EC Software, all rights reserved

492 Help & Manual 5 - User Help

Registration is required for HXS help files

Unlike HTML Help CHM files you cannot just copy a Visual Studio Help HXS file to your
disk and then click on it to start it. It must be installed and registered with the MS Installer
first.
When you compile HXS files with Help & Manual they are installed and registered
automatically on your development machine so that you can view them there. However,
when you distribute your files you must configure the MS Installer to do this. See the
documentation of the installer and your Microsoft Visual Studio package for details.

Referencing files in your HTML topic templates

If you reference any additional files in your HTML topic templates 433 you must add them
to the Baggage Section 485 in the Project Files section of the Project Explorer. MS Help 2
does not have anything like an .HHP file with which you can tell the compiler to include
additional files. (Yet another surprising limitation compared to Microsoft's other earlier
help formats.)
If you add files to the Baggage Section they will be included in your compiled output
automatically.

"Do not compile" option for debugging

Help & Manual supports two different compile options for Visual Studio Help. Normally
you will compile a finished HXS file, which will then be automatically registered on your
local development computer and opened. If this does not work properly there is also a
debugging option called Do not compile, open with VStudio in the Publish 313 dialog.
· If you select the Do not compile option Help & Manual generates a Visual Studio Help
Project file with the extension .HWProj in the temporary output directory. This is a small
XML file that acts as a wrapper for Visual Studio.
· When you select this option the temporary output directory (in your project directory) is
not deleted after you compile the project. After compiling you can then use the .HWProj
file to open and compile the project file directly in VS.Net, using the debugging options
available there.

Calls to register and view .HXS files

The following two calls are just brief examples. For full details please refer to the
documentation of VS.NET and the VSHIK!
Manual registration of an .HXS file:
"C:\Program Files\Microsoft Help 2.0 SDK\hxreg" -n Namespace -i UniqueID
-c MyHelpfile.HXS

Call to view an .HXS file:

"C:\Program Files\Common Files\Microsoft Shared\Help\dexplore.exe" /

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 493

helpcol ms-help://ECSoftware
As you can see there is no file name in the call. In the above example ECSoftware is the
Namespace. The viewer will only find the file if it has been registered correctly.

See also:
Visual Studio Help 738 (Reference)
Publishing Your Projects 311

6.12 XML and XML editing

XML is only relevant at all if you are using the Professional version of Help & Manual. The
Standard version does not have an XML editing tab in the Editor window and can only save
in the compressed, single-file .hmxz format in which you do not have access to the XML
source files of your project.
Working with the XML source code is something for advanced users only. You do not have
to know anything at all about XML to work with Help & Manual.

Editing the XML source files

To access the XML source files you need to save in the uncompressed .hmxp format.
You can then edit all the source files with any normal text editor or a dedicated XML
editor.
If you want to make any changes to the code you must observer the rules and syntax of
the Help & Manual XML Language. Documentation of the updated version of the Help &
Manual XML Language used in Help & Manual 5 is going to be released as soon as
possible.

Editing in the XML Source tab

You can edit the source code of the current topic directly in the XML Source tab behind
the main editor window. This tab contains a simple code editor with syntax highlighting,
word wrap and search and replace features. The code you enter is automatically parsed
and checked for syntax and well-formedness. It will only be accepted if it does not contain
any errors.
Note that you can only edit one topic at a time in the XML Source tab. If you want to edit
multiple topics you must use an external editor with multi-topic capabilities and edit the
source files directly.
Search and spell checking are both available in the XML editor – just right-click in the
editor to access these features.

Complex search and replace with XML

Once you have gained an understanding of the basic principles of the XML syntax you
can perform complex search and replace operations on the XML source code that would
not be possible in the Help & Manual editor.

© 1997 - 2009 by EC Software, all rights reserved

 494 Help & Manual 5 - User Help

To do this you will need an editor that can perform search and replace operations on
multiple files in multiple folders. If you are not using a dedicated XML editor a very good
and inexpensive tool for this is FAR HTML from Helpware, which also has an excellent
complex search and replace tool that is easier to use than regular expressions.

Creating XML topic files and projects yourself

If you follow the rules of the Help & Manual XML Language you can also create topics,
chapters and entire projects directly yourself, either manually or programmatically from
your application. For example you can set up your application to generate documentation
automatically, which you can than either edit in Help & Manual or compile directly 485 from
the command line without ever having to open Help & Manual yourself.

6.13 Using OLE Objects

OLE (Object Linking and Embedding) objects are active links in your project to documents
created and edited in other applications. This enables you to insert formatted objects that
you cannot create directly in the Help & Manual editor, such as formulas created in the MS
Equation Editor.
OLE objects can be inserted as links to external files (recommended) or as links to objects
that are actually embedded in your project file. Embedded objects are stored with your
project and will increase its size.
When your help file is compiled, OLE objects are converted into static bitmap graphics. The
advantage of OLE over screenshots is that the objects remain editable – double-clicking on
an OLE object in the Help & Manual editor opens it for editing in its associated program.
Please see About using OLE objects 757 in the Reference section for some important
additional information.

See also:
Insert OLE Object 635
About using OLE objects 757
6.13.1 Inserting OLE objects
OLE stands for "Object Linking and Embedding". It is a Windows technology that allows you
to link or embed documents and files from other programs into your current document.
Instead of importing the external document you just link to it, enabling you to update the
external document if necessary without making a new copy.
Note that OLE objects are actually controlled by the OLE server of the associated
application, not by Help & Manual. Whether and how the object is editable depends on the
server and if the function fails it is due to the server, not to Help & Manual.
When you publish your content all OLE objects are converted to bitmap graphics. This
means that you can only use document types that can be converted to static graphics.

Key Information
OLE objects are only "live" while you are

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 495

working in the Help & Manual editor! When

you publish your output they are always
converted to bitmap graphics. This is
necessary because the output formats do
not support live OLE objects.

How to insert an external file as an OLE object

Linking is always preferable to embedding. Embedded OLE objects inflate your project
files and cannot be edited outside Help & Manual. Linked objects are normal documents
and can be edited directly with the associated application.
Inserting a OLE link to an external file:
1. Select the OLE Object Tool in Write > Insert Object.
2. Select the Create from File option in the dialog displayed.

3. Use the Browse button to select the file you want to insert. The file does not have to
be in your project directory. Remember that only objects that can be displayed as
static graphics are supported.
4. Select the Link check box. This inserts a link to the external file instead of embedding
the file in your project.
5. Select Display as Icon if you only want to display a placeholder icon for the object in
the Help & Manual editor. If you deselect this option you can preview and size the
object in the editor.
6. Click on OK to insert the OLE object.

Embedding an OLE copy of an external file in your project:

· Proceed exactly as described above but deselect the Link check box in Step 4. This will
make a copy of the external file and physically embed it in your Help & Manual project.
Note that when an OLE object is embedded editing the external file will not change the
copy in your project! To edit the embedded OLE object you must double-click on the
object in the Help & Manual editor.

How to embed a new OLE object in your project

The Create New option always embeds the resulting object in your project. It is preferable

© 1997 - 2009 by EC Software, all rights reserved

496 Help & Manual 5 - User Help

to use Create from File to ensure that the OLE object is stored as an external file.
1. Select the OLE Object Tool in Write > Insert Object.

2. Select Create New in the dialog displayed, then select the application in the Object
Type list.
Remember that only OLE objects that can be displayed as static graphics are
supported.
3. Select Display as Icon to display the OLE object as a small icon link. Otherwise a
graphical image of the object will be inserted in your topic.
4. Click on OK to open the external application to create the object.
Important:
When you create an OLE object in this way the file you create with your external
application is physically embedded in your Help & Manual project, it is not stored as an
external file. This type of OLE object can only be edited from within your Help & Manual
project.

How to edit OLE objects

All OLE objects:
To edit an OLE object with the application that created it just double-click on the object in
the Help & Manual editor. Or right-click on the object and select Edit or Open.This
method works both for OLE objects that are embedded in your project file and OLE
objects inserted as links to external files.
OLE objects inserted as links:
When you insert an OLE object as a link (see above for details) you can also edit it by
editing the external file with the application associated with it directly.
Deleting OLE objects:
Place the cursor before or after the OLE object and press Backspace or Delete.

See also:
Insert OLE Object 635
About using OLE objects 757

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 497

6.13.2 OLE examples

Example 1 – a Word file:

This example was created by pasting text to Word and saving it as a .DOC file. This file
was then inserted as an OLE object. Note that in the output this is actually a graphic, not
text!
The object has been inserted in a single-cell table with a border and centered to
distinguish it from the rest of the text.

A Word file inserted as an OLE object:

Example 2 – an equation:
This example shows an equation created with the MS Equation Editor:
x+ y
n
Z

6.14 Replacing Formatting and Styles

The Styles > Replace Styles function in the Write tab is a simple global search and replace
function for replacing either font attributes or paragraph attributes. This can be quite a
useful aid when you are importing formatted text from external sources like RTF and CHM
files.
Help & Manual imports formatted text from external sources as "manual formatting" and if
you want to use styles on imported formatted text you must first create Help & Manual styles
on the basis of the imported formatting and then apply the styles to your text either
manually or with Replace Styles.

© 1997 - 2009 by EC Software, all rights reserved

 498 Help & Manual 5 - User Help

See also:
Importing Data 99
Text Formatting and Styles 155
Dynamic Styles 711
6.14.1 Introduction to style replacement
Before you start using this function, please read through the following explanations carefully.
They will make it much easier to use this function effectively.
If you are an experienced computer user you will probably find that you will be able to use
the function after reading this section only. If you require more information continue to the
next chapters and follow the instructions provided there.

Font and paragraph attributes are separate

The first important thing to understand when you are using this function is that font
attributes and paragraph attributes are internally separate. In Help & Manual the two sets
of attributes are combined in paragraph styles. However, every paragraph style actually
has two sets of attributes with the same name: one set of font attributes and one set of
paragraph attributes.
For this reason the Replace Styles dialog has two modes, which must be used
separately: One mode for the font attributes and one mode for the paragraph attributes.
Since paragraph styles consist of both font and paragraph attributes this means that you
must always perform two passes with Replace Styles to apply paragraph styles: One to
replace the font attributes and one to replace the paragraph attributes. Since paragraph
attributes are sometimes not "unique" many different paragraph styles may share the
same paragraph settings you may find it easier to apply paragraph styles manually in
some cases.

ALL the search attributes must match

The search is performed for all the attributes in the left column (Search for Format/Style:).
All the replacement or removal operations are only performed on text that returns a
perfect match for all the options in the left column.
This also applies for the operations defined by the Inline Formatting replacement settings
in the right column (Remove inline formatting etc). The operations will only be performed
on text that matches the search arguments in the left column perfectly!

Current formatting is preselected automatically

When you open the Replace Styles dialog the search settings in the left column are set to
the attributes of the text at the current cursor position. If you perform your search without
changing anything in the left column, any operations you choose in the right column will
only be performed on text that precisely matches the text attributes at the current cursor
position. This includes both the style name (which is just one attribute among many) and
all the other attributes.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 499

For example, if the cursor is in the normal text of a paragraph styled with StyleA, any
operations will only be performed on text styled with StyleA. Text within StyleA text with
different formatting will be ignored and will remain unchanged, unless you use a "fuzzy"
search (see below).

The style name is just one attribute among many

Remember that the name of a style is just one attribute among many setting the style
name in the search column on the left just searches for text associated with that style
name. It too can be switched to (Any) to create a fuzzy search, and doing this does not
change any of the other attributes.
Changing the style name at the top of the column does not change any of the other
attributes, it only changes the style name.
So you can search for the same attributes in combination with the style name (to find a
style that has already been applied) or without the style name (to find text that you want
to restyle or integrate in an existing style).

Explicit searches and fuzzy searches

The search is precise for attributes in the left column that are specified explicitly. The
search is "fuzzy" for attributes that are specified as (Any).
For example, if you want to include inline-formatted text that has a different font in your
search you must set the Font Face setting in the left column to (Any). Then the search
will find both text matching the main style and text with a different font.
The same applies in the same way to all other attributes.

Inline formatting is only changed if it matches

The Remove inline formatting options in the right column are only performed on inline
formatted text that precisely matches the settings in the left column.
Example:
For example, suppose you want to remove all manually-applied italics from your body
text, which is Arial 11 points. You use several different body text styles and you want to
remove manually-applied italics from all of them. You need the following settings:
Left Column Right Column
Font Style (any text) (keep style name)
Name:
Remove inline
formatting
Font Face: Arial (Use style attributes)
Font Size: 11 (Use style attributes)
Font Style Italic

© 1997 - 2009 by EC Software, all rights reserved

 500 Help & Manual 5 - User Help

All other (any) (Use style attributes)

settings
This will remove all manually-applied Italic formatting on any Arial 11 text with any style,
but it will not remove any other inline formatting because only Arial 11 Italic matches the
search.
If you change (any text) to Normal for the Font Style Name in the left column then only
formatting in paragraphs formatted with Normal will be changed.

See also:
Importing Data 99
Text Formatting and Styles 155
Dynamic Styles 711
6.14.2 Font attributes - styled text
The methods described below only work for text already formatted with Help & Manual
styles. See the topic on unstyled text 500 for instructions on how to deal with texts that do not
yet have styles applied.
Before you try to follow these instructions, please study the Introduction to style replacement
498 for an explanation of how the Replace Styles function works. This will make it much

easier for you to use this feature.

Replacing one existing font style with another – exact search

This is the most straightforward operation. It simply takes texts formatted with one style
and applies a different style to them. The exact search replaces only text formatted with
the named style. Any inline-formatted text within text formatted with the target style will be
protected, as will any text formatted with other styles.
1. Select multiple topics if you want to replace only in some topics
If you only want to replace styles in specific topics select those topics in the Project
Explorer first, using Shift+Click or Ctrl+Click. Select the topic containing the example
of the style you want to replace last, so that you can select the style example in the
next step.

2. Click in styled text in the editor, then select Replace Styles and Font Styles
Click inside some text formatted with the style you want to replace, then select Styles
> Replace Styles in the Write tab. Then select the Font Styles mode at the top of the
dialog that appears.

3. Leave all left column attributes unchanged

All the formatting attributes of the current style are displayed in the left column and the
style name is displayed at the top of the left column. Don't change any of the left-
column font attribute settings – the attributes must all match exactly for an exact
search.

4. Select the new style in the right column

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 501

Select the new style you want to apply from the drop-down list directly below the
Change to Format/Style: heading on the right. If you need to create the style first,
select Edit Styles.

5. Leave inline formatting settings unchanged

Leave the option Remove inline formatting activated. This will only replace inline
formatting matching the settings in the left column, so any manually-formatted text
with different attributes will be protected. When you are performing an exact search
this option is effectively inactive.

6. Click on Replace Styles to execute

A dialog will be displayed allowing you to choose where you want to replace: In the
entire project, the main topics, the invisible topics or selected topics only. You can also
perform a test run to check how many styles would be found and replaced before
actually applying the changes.
Note that any changes in the current topic will only be visible in the editor after you
close the Replace Styles dialog.

Replacing one existing font style with another - fuzzy search

This method allows you to extend the scope of your search, so that in addition to finding
text that exactly matches your style you can also apply the target style to other texts. For
example, it allows you to also reset inline-formatted texts within your search text.
Fuzzy searches only seem complicated at first, they are actually quite simple. If you have
trouble try out the examples at the bottom of the instructions, they will help demonstrate
how it works.
1. Select multiple topics if you want to replace only in some topics
If you only want to replace styles in specific topics select those topics in the Project
Explorer first, using Shift+Click or Ctrl+Click. Select the topic containing the example
of the style you want to replace last, so that you can select the style example in the
next step.

2. Select a style in the editor, then select Replace Styles and Font mode
Click inside some text formatted with the style you want to replace, then select
Format > Replace Styles. Then select the Font Styles mode at the top of the dialog
that appears.

3. Set selected left-column attributes to (Any)

All the formatting attributes of the current style are displayed in the left column and the
style name is displayed at the top of the left column.
Examples:
Suppose you know that the text whose styles you want to replace contains sub-texts
formatted with a different font that you want to reset. To do this you need to set the

© 1997 - 2009 by EC Software, all rights reserved

502 Help & Manual 5 - User Help

Font Face attribute to (Any).

If you also want to reset text formatted with a different size you must also set the Font
Size attribute to (Any).
If you also want to reset text formatted with bold or italics you must set the Font Styles
attribute to (Any).
The same principle applies to all the attributes in the list. To match any differences
from the standard style settings you need to set the attributes for those differences to
(Any). You can even do this for the style name, but be careful – this may reset more
texts than you expect!

4. Select the new style in the right column

Select the new style you want to apply from the drop-down list directly below the
Change to Format/Style: heading on the right. If you need to create the style first,
select Edit Styles.

5. Adjust the inline formatting settings for the desired result

As soon as you have activated fuzzy options in the search with (Any) settings you can
also start to find manually-applied formatting within your texts, i.e. formatting that does
not match the standard style settings. This makes the Inline Formatting: options
relevant.
"Remove inline formatting" resets all matching texts:
This option will reset all inline-formatted texts that match the search settings in the left-
hand column to the settings of the target style selected.
Any texts that don't match the search settings will not be reset. This means that you
can "protect" texts formatted in certain ways by choosing your search settings
carefully. The best way to learn how to do this is to experiment with some test texts.
"Remove except B/I/U/Color" protects these attributes:
The second option "protects" bold, italic, underlined and colored text. This allows you
to be a little less careful with your left column settings and still protect these formatting
styles, which are very frequently applied manually.
"Custom Settings" lets you choose for yourself
This option gives you full control over the target formatting, in the same way that the
individual settings in the left hand column let you control the search settings.
By default all the attributes are set to Use style attributes. To change the output
formatting just change any of the settings.
Important: Note that using this option will create new inline formatting within the styled
text!

6. Click on Replace Styles to execute

A dialog will be displayed allowing you to choose where you want to replace: In the
entire project, the main topics, the invisible topics or selected topics only. You can also
perform a test run to check how many styles would be found and replaced before

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 503

actually applying the changes.

Note that any changes in the current topic will only be visible in the editor after you
close the Replace Styles dialog.

Examples of fuzzy searches

Objective: Search for settings: Change to settings:

Replace one style with · Font Style Name · Font Style Name
another. Leave manually- set to the name of the set to target style
applied bold, italics, and source style
underlining within the text · Inline Formatting
· Font Styles and set to Remove except
intact.
Underline set to B/I/U/Color
(Any)
· All other attributes
unchanged

Replace one style with · Font Style Name · Font Style Name
another. Change set to the name of the set to target style.
manually-formatted text source style
with a different font to the · Inline Formatting
· Font Face, Font set to Remove except
target font, leaving all
Styles, Underline B/I/U/Color
manually-applied bold,
italics, underlining and text and Text Color set
color within the target text to (Any)
intact. · All other attributes
unchanged

Replace one style with · Font Style Name · Font Style Name
another and reset all set to the name of the set to target style
manually-applied source style
formatting, including bold, · Inline Formatting
italics, underlining and · All other attributes set set to Remove inline
color. to (Any) formatting

See also:
Importing Data 99
Text Formatting and Styles 155
Dynamic Styles 711
6.14.3 Font attributes - unstyled text
The instructions below explain how to use Replace Styles to apply formatting to text that
does not have any Help & Manual styles applied to it. See the topic on styled text 500 for
information on how to reformat text that already has Help & Manual styles applied to it.
Before you try to follow these instructions, please study the Introduction to style replacement
498 for an explanation of how the Replace Styles function works. This will make it much

© 1997 - 2009 by EC Software, all rights reserved

504 Help & Manual 5 - User Help

easier for you to use this feature.

Applying font attribute styles to unstyled text

Unstyled text is text that does not have any Help & Manual style applied to it. This is
visible in the style selector in the Write > Font section of the Ribbon – when it is blank
instead of displaying a style the text at the current cursor position is unstyled.

The style selector looks like this when

the cursor is on unstyled text
Basically you proceed exactly as you would for performing an exact or fuzzy search for
styled text. 500 When you click in unstyled text before selecting the Replace Styles function
the Font Style Name field in the left column of the Replace Styles dialog automatically
displays (Unstyled text only).
All the other settings and procedures are exactly the same. This is because the only
difference between styled and unstyled text is that styled text has a style name assigned
to it. Remember: the style name is just one attribute among many.
For more details see the example in Styling imported text 513 .

Reformatting manually-formatted text with styles

Frequently you will format certain texts in a different way to highlight them or make them
easier to identify. For example, you might format the names of menu items using a
different font and italics. The objective here is to apply named styles to these texts, so
that you can later change the formatting of all of them just by changing the style
definition.
You will most frequently need to do this with imported formatted text for example from
RTF, CHM or HTML files where all the formatting is always imported as manual
formatting.
This is a two-step process: First you need to create a style on the basis of the manual
formatting, then you need to use Replace Styles to apply this style to all the examples of
that formatting in your project. After you do this you can then change the formatting of all
these texts just by editing the style definition.
Step 1: Create a new style on the basis of the formatting
1. Select an example of the text you want to use as the model for the style (click in the
text or select it).
2. Select Styles > Create Style from Selection in the Write tab and create a new text
style 161 on the basis of the formatting.
This example creates a text style because it is assumed you are applying style to text
within paragraphs. You can also use the same approach for creating paragraph styles,
but then you must also apply the paragraph format 507 to the text as well in a second

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 505

operation.
Step 2: Apply the style to all the texts with matching formatting
1. Select multiple topics if you want to replace only in some topics
If you only want to replace styles in specific topics select those topics in the Project
Explorer first, using Shift+Click or Ctrl+Click. Select the topic containing the example
of the style you want to replace last, so that you can select the style example in the
next step.

2. Click in the formatted text in the editor, then select Replace Styles and Font
mode
Click inside the example of the text you want to style, then select Styles > Replace
Styles in the Write tab. Then select the Font Styles mode at the top of the dialog that
appears.

3. Select (Any text) for the Font Style Name

If a style name is displayed in the Font Style Name: field in the left column change it
to (Any text). This is particularly important if you have selected the text with which you
just created the new style: Since the text you want to style does not yet have the style
name it will not be found unless you make this change.
Leave all other settings in the left column unchanged!

4. Select the name of the style you created in the right column
Select the name of the new style you just created in the Change to Format/Style
column. Leave all other settings in this column unchanged. The inline formatting
settings are irrelevant because you are performing an exact search.

5. Click on Replace Styles to execute

A dialog will be displayed allowing you to choose where you want to replace: In the
entire project, the main topics, the invisible topics or selected topics only. You can also
perform a test run to check how many styles would be found and replaced before
actually applying the changes.
Note that any changes in the current topic will only be visible in the editor after you
close the Replace Styles dialog.

Reformatting manually-formatted text without using styles

Sometimes you may just want to quickly replace one kind of formatting in your document
with another kind of formatting, without using styles at all. You do this by switching off the
style names in the search and target fields and then replacing the formatting.
1. Select multiple topics if you want to replace only in some topics
If you only want to reformat text in specific topics select those topics in the Project
Explorer first, using Shift+Click or Ctrl+Click. Select the topic containing the example
of the formatting you want to replace last, so that you can select the style example in

© 1997 - 2009 by EC Software, all rights reserved

506 Help & Manual 5 - User Help

the next step.

2. Click in the formatted text in the editor, then select Replace Styles and Font
mode
Click inside some text with the formatting you want to change, then select Styles >
Replace Styles in the Write tab. Then select the Font Styles mode at the top of the
dialog that appears.
Leave the settings in the left column as they are or change them, depending on the
formatting you want to change.

3. Change the Font Style Name: setting in the left column to (Any text)
This will find all instances of the text formatted in exactly this way, no matter whether it
has a style or not. You can also use the option (Unstyled text only) if you only want to
find text that has no style applied to it. You may need to perform the search twice,
once with each option, to get all the matching text.)

4. Select the target style name setting

In the Font Style Name: field in the right column select either (Keep style name) or
(Remove style name). The first option will keep any style name explicitly assigned to
the reformatted text, applying the new formatting as manual (inline) formatting. The
second option will remove any explicit style name, so that the text is manually
formatted only – it will then have the style name of the paragraph surrounding it.

5. Select Custom Settings: in the right column

Then manually select all the attributes that you want to apply to the text. All the
settings you leave set to (Use style attributes) in the right column will remain
unchanged.

6. Click on Replace Styles to execute

A dialog will be displayed allowing you to choose where you want to replace: In the
entire project, the main topics, the invisible topics or selected topics only. You can also
perform a test run to check how many styles would be found and replaced before
actually applying the changes.
Note that any changes in the current topic will only be visible in the editor after you
close the Replace Styles dialog.

Turning styles into manually-formatted text

This is just a variation on reformatting manually-formatted text without using styles.
Basically all you need to do is follow the instructions for reformatting manually formatted
text (see above) with the following two changes:
1. Select the name of the style you want to remove in the left column.
2. Select (Remove style name) in the right column.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 507

6.14.4 Paragraph attributes - styled text

The methods described below only work for paragraphs already formatted with Help &
Manual styles. See the topic on unstyled paragraphs 510 for instructions on how to deal with
paragraphs that do not yet have styles applied.
Before you try to follow these instructions, please study the Introduction to style replacement
498 for an explanation of how the Replace Styles function works. This will make it much

easier for you to use this feature.

Replacing one paragraph style with another – exact search

This is the most straightforward operation. It simply takes paragraphs formatted with one
style and applies a different style to them. Exact search replaces only the styles of
paragraphs formatted with the named style. Any inline-formatted text within text formatted
with the target style will be protected, as will any text formatted with other styles.
1. Select multiple topics if you want to replace only in some topics
If you only want to replace styles in specific topics select those topics in the Project
Explorer first, using Shift+Click or Ctrl+Click. Select the topic containing the example
of the style you want to replace last, so that you can select the style example in the
next step.

2. Click in a styled paragraph in the editor, then select Replace Styles and
Paragraph mode
Click inside a paragraph formatted with the style you want to replace, then select
Styles > Replace Styles in the Write tab. Then select the Paragraph Styles mode at
the top of the dialog that appears.

3. Leave all left column attributes unchanged

All the formatting attributes of the current style are displayed in the left column (Search
for Format/Style)and the style name is displayed at the top of the left column. Don't
change any of the left-column paragraph attribute settings – the attributes must all
match exactly for an exact search.

4. Select the new style in the right column

Select the new style you want to apply from the drop-down list directly below the
Change to Format/Style: heading on the right. If you need to create the style first,
select Edit Styles.

5. Leave the inline formatting settings unchanged

Leave the option Remove inline formatting activated. This will only replace inline
paragraph formatting matching the settings in the left column, so any manually-applied
paragraph attributes will be protected. When you are performing an exact search this
option is effectively inactive.
Important: The target style will not be applied at all to paragraphs that do not have
precisely matching attributes. If you also want the style to be applied to "modified"
versions of the paragraphs you must use a "fuzzy" search (see below).

© 1997 - 2009 by EC Software, all rights reserved

508 Help & Manual 5 - User Help

6. Click on Replace Styles to execute

A dialog will be displayed allowing you to choose where you want to replace: In the
entire project, the main topics, the invisible topics or selected topics only. You can also
perform a test run to check how many styles would be found and replaced before
actually applying the changes.
Note that any changes in the current topic will only be visible in the editor after you
close the Replace Styles dialog.

Replacing one paragraph style with another - fuzzy search

This method allows you to extend the scope of your search, so that in addition to finding
paragraphs that exactly match your style you can also apply the target style to other
paragraphs. You will probably want to do this, because most texts will contain paragraphs
with additional manual indents and so on.
Fuzzy searches only seem complicated at first, they are actually quite simple. If you have
trouble try the examples at the bottom of the instructions, they will help demonstrate how
it works.
1. Select multiple topics if you want to replace only in some topics
If you only want to replace styles in specific topics select those topics in the Project
Explorer first, using Shift+Click or Ctrl+Click. Select the topic containing the example
of the style you want to replace last, so that you can select the style example in the
next step.

2. Click in a styled paragraph the editor, then select Replace Styles and Paragraph
mode
Click inside some text formatted with the style you want to replace, then select Styles
> Replace Styles in the Write tab. Then select the Paragraph Styles mode at the top
of the dialog that appears.

3. Set selected left-column attributes to (Any)

All the formatting attributes of the current style are displayed in the left column and the
style name is displayed at the top of the left column.
For example, suppose you know that you have manually changed the indent of some
of the paragraphs formatted with the current style. To include these paragraphs in the
search set the Left Indent and/or Right Indent attributes to (Any).
The same applies for all the other settings. It is the same principle: If you know that
you have manually changed any settings in paragraphs formatted with the current
style you must set those settings to (Any) to include the manually-altered paragraphs
in the search.

4. Select the new style in the right column

Select the new paragraph style you want to apply from the drop-down list directly
below the Change to Format/Style: heading on the right. If you need to create the style

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 509

first, select Edit Styles.

5. Adjust the inline formatting settings for the desired result

As soon as you have activated fuzzy options in the search by including (Any) for
search options can also start to find manually-applied paragraph formatting that does
not match the standard style settings. This makes the Inline Formatting: options
relevant.
"Remove inline formatting" resets all matching paragraph settings
This option will reset all manually-applied paragraph settings that match the search
settings in the left-hand column to the settings of the target style selected.
Any texts that don't match the search settings will not be reset. This means that the
target style will not be applied to paragraphs with settings that don't match your
combination of exact and fuzzy search options.
"Remove except Alignment+Indent" protects these attributes
The second option "protects" alignment and indenting from being reset by the target
style. This allows you to be a little less careful with your left column settings and still
protect these formatting styles.
"Custom Settings" lets you choose for yourself
This option gives you full control over the target formatting, in the same way that the
individual settings in the left hand column let you control the search settings.
By default all the attributes are set to Use style attributes. To change the output
formatting just change any of the settings.
Note that using this option will result in paragraphs with additional manually-applied
formatting

6. Click on Replace Styles to execute

A dialog will be displayed allowing you to choose where you want to replace: In the
entire project, the main topics, the invisible topics or selected topics only. You can also
perform a test run to check how many styles would be found and replaced before
actually applying the changes.
Note that any changes in the current topic will only be visible in the editor after you
close the Replace Styles dialog.

Examples of fuzzy searches

Objective: Search for settings: Change to settings:

Replace one paragraph · Left Indent and/or · Para Style Name

style with another. Include Right Indent set to set to target
paragraphs with manually- (Any) or (Any value paragraph style name
modified indents in the <> 0)
search. · Inline Formatting
· All other attributes set to Remove except

© 1997 - 2009 by EC Software, all rights reserved

 510 Help & Manual 5 - User Help

unchanged, including Alignment+Indent

Para Style Name

Replace one paragraph · Left Indent and/or · Para Style Name

style with another. Include Right Indent set to set to target
paragraphs with manually- (Any) or (Any value paragraph style name
modified indents and <> 0), Alignment
manually-modified · Inline Formatting
set to (Any).
alignment in the search. set to Remove except
· All other attributes Alignment+Indent
unchanged, including
Para Style Name

Replace one paragraph · All attributes · Para Style Name

style with another and unchanged, including set to target style.
reset all manually-applied the style name.
paragraph formatting, · Inline Formatting
including alignments and set to Remove inline
formatting
indents.

See also:
Importing Data 99
Text Formatting and Styles 155
Dynamic Styles 711
6.14.5 Paragraph attributes - unstyled text
The instructions below explain how to use Replace Styles to apply formatting to paragraphs
that do not have any Help & Manual styles applied to them. See the topic on styled
paragraphs 507 for information on how to reformat paragraphs that already have Help &
Manual styles applied to them.
Before you try to follow these instructions, please study the Introduction to style replacement
498 for an explanation of how the Replace Styles function works. This will make it much

easier for you to use this feature.

Applying paragraph styles to imported and other unstyled text

Unstyled paragraphs are paragraphs that do not have any Help & Manual styles applied
to them. This is visible in the style selector in the Ribbon – when it is blank instead of
displaying a style the text at the current cursor position is unstyled.

The style selector looks like this when

the cursor is on unstyled text
Basically you proceed exactly as you would for performing an exact or fuzzy search for
styled paragraphs. When you click in an unstyled paragraph before selecting the Replace

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 511

Styles function the Para Style Name field in the left column of the Replace Styles dialog
displays (Unstyled text only).
If the Para Style Name field is not set to (Unstyled text only) already you must change it
to this setting to make sure that the search finds paragraphs with no styles applied. All
the other settings and procedures are exactly the same. This is because the only
difference between styled and unstyled text is that styled text has a style name assigned
to it. Remember: the style name is just one attribute among many.
For more details see the example in Styling imported text 513 .

Reformatting manually-formatted paragraphs with styles

Frequently you will manually format some paragraphs in a different way from other
paragraphs in your project. After a while you may decide that there are enough of these
paragraphs to define a style for them. The following instructions explain how to use
Replace Styles to achieve this.
This is a two-step process: First you need to create a style on the basis of the manual
formatting, then you need to use Replace Styles to apply this style to all the matching
paragraphs in your project. After you do this you can then change the formatting of all
these paragraphs just by editing the style definition.
Step 1: Create a new style on the basis of the formatting
1. Click in the paragraph that you want to use as the model for the style.
2. Select Styles > Create Style from Selection in the Write tab and create a new
paragraph style 161 on the basis of the formatting.
The font attributes of the new paragraph style will be set automatically. You can then
use Font Styles mode in a second pass to apply the font styles to your target text.
Step 2: Apply the style to all the texts with matching formatting
1. Select multiple topics if you want to replace only in some topics.
If you only want to replace styles in specific topics select those topics in the Project
Explorer first, using Shift+Click or Ctrl+Click. Select the topic containing the example
of the style you want to replace last, so that you can select the style example in the
next step.

2. Select a paragraph in the editor, then select Replace Styles and Paragraph
mode.
Click inside the example of the paragraph you want to style, then select Styles >
Replace Styles in the Write tab. Then select the Paragraph Styles mode at the top of
the dialog that appears.

3. Select (Any text) for the Para Style Name.

If a style name is displayed in the Para Style Name: field in the left column change it
to (Any text). This will ensure that all paragraphs with matching attributes will be found.
Leave all other settings in the left column unchanged!

© 1997 - 2009 by EC Software, all rights reserved

512 Help & Manual 5 - User Help

4. Select the name of the paragraph style you just created in the right column.
Select the name of the new style you just created in the Change to Format/Style
column. Leave all other settings in this column unchanged. The inline formatting
settings are irrelevant because you are performing an exact search.

5. Click on Replace Styles to execute.

A dialog will be displayed allowing you to choose where you want to replace: In the
entire project, the main topics, the invisible topics or selected topics only. You can also
perform a test run to check how many styles would be found and replaced before
actually applying the changes.
Note that any changes in the current topic will only be visible in the editor after you
close the Replace Styles dialog.

Reformatting manually-formatted paragraphs without styles

Sometimes you may just want to quickly replace one kind of paragraph formatting in your
document with another kind of formatting, without using styles at all. You do this by
switching off the style names in the search and target fields and then replacing the
formatting.
1. Select multiple topics if you want to replace only in some topics.
If you only want to reformat paragraphs in specific topics select those topics in the
Project Explorer first, using Shift+Click or Ctrl+Click. Select the topic containing the
example of the formatting you want to replace last, so that you can select the style
example in the next step.

2. Select a paragraph in the editor, then select Replace Styles and Paragraph
mode.
Click inside a paragraph with the formatting you want to change, then select Styles >
Replace Styles in the Write tab. Then select the Paragraph Styles mode at the top of
the dialog that appears.
Leave the settings in the left column as they are or change them, depending on the
formatting you want to change.

3. Change the Para Style Name: setting in the left column to (Any text).
This will find all instances of the paragraph formatted in exactly this way. You can also
use the option (Unstyled text only) if you only want to find paragraphs that has no style
applied to it. (You may need to perform the search twice, once with each option, to get
all the matching paragraphs.)

4. Select the target style name setting.

In the Para Style Name: field in the right column select either (Keep style name) or
(Remove style name). The first option will keep any style name explicitly assigned to
the reformatted paragraph. The second option will remove any explicit style name, so
that the resulting paragraph is manually formatted only.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 513

5. Select Custom Settings: in the right column.

Then manually select all the attributes that you want to apply to the text. All the
attributes you leave set to (Use style attributes) will remain unchanged.

6. Click on Replace Styles to execute.

A dialog will be displayed allowing you to choose where you want to replace: In the
entire project, the main topics, the invisible topics or selected topics only. You can also
perform a test run to check how many styles would be found and replaced before
actually applying the changes.
Note that any changes in the current topic will only be visible in the editor after you
close the Replace Styles dialog.

Turning styled paragraphs into manually-formatted paragraphs

This is just a variation on reformatting manually-formatted paragraphs without using
styles. Basically all you need to do is follow the instructions for reformatting manually
formatted paragraphs 507 with the following two changes:
1. Select the name of the style you want to remove in the left column.
2. Select (Remove style name) in the right column.

6.14.6 Styling imported formatted text

When you import formatted text from other sources the formatting is retained but the text
does not have any styles. Effectively, it is all manually formatted. You can use the Replace
Styles function to integrate this formatting into the stylesheet of your project, either by
applying existing styles or by creating new styles and applying them.
This topic illustrates this by walking you through the steps of a typical example. For details
on how to perform the individual operations see the topics in this chapter on replacing font
and paragraph styles and formatting.

Example: Applying the Normal style to imported body text

Let's assume that you want to apply the Normal style to all your imported unstyled body
text. At the same time you also want to apply named styles to inline-formatted text within
your body text, some of which has different font settings to that of the body text (for
example menu names and other items formatted with different fonts etc).

Step 1: Setting up the styles

If you want to use the style of the imported text in your project you first need to use
formatting from your imported text as a model to update your project's style definitions.
1. Update the Normal style on the basis of the imported text.
Click in a plain area of the imported body text and select Styles> Create Style from
Selection in the Write tab. Then select Change existing style, select Normal in the
style list and activate Assign paragraph attributes.

© 1997 - 2009 by EC Software, all rights reserved

514 Help & Manual 5 - User Help

2. Update or create text styles for additional formatting.

If special formatting is used for text within other paragraphs click in examples of this
formatting in your imported text. Then use Styles> Create Style from Selection in the
Write tab to update or create a new text styles for this formatting. Repeat for all
different formatting types used within paragraphs.
See Defining styles 161 for more details on using the Create Style from Selection
function.

Step 2: Apply the Normal font attributes to the main body text
Next you want to apply the modified Normal font style attributes to the text of the body
paragraphs in your imported text.
1. Select multiple topics if you want to replace only in some topics
If you only want to replace styles in specific topics select those topics in the Project
Explorer first, using Shift+Click or Ctrl+Click. Select the topic containing the example
of the style you want to replace last, so that you can select the style example in the
next step.

2. Select an example of the body text in the editor, then select Replace Styles and
Font mode
Click inside some text formatted with the style you want to replace, then select Styles
> Replace Styles in the Write tab. Then select the Font Styles mode at the top of the
dialog that appears.

3. In the left column, set the Font Style Name to (Unstyled text only)
Set Font Style Name in the left column to (Unstyled text only) and leave all other
attributes unchanged. This will find all text with the attributes of the current paragraph
and will make sure that any paragraphs in your project that already have named styles
remain unaffected.

4. Select Normal in the right column

Select Normal in the drop-down list directly below the Change to Format/Style:
heading on the right. This will apply the Normal style to all matching text.

5. Leave the inline formatting settings unchanged

The exact settings in the left column will only match the unchanged body text, so any
text within paragraphs with different formatting will be ignored. This makes the Inline
Formatting: options irrelevant – you can leave the default setting of Remove inline
formatting as it is.

6. Click on Replace Styles to execute

A dialog will be displayed allowing you to choose where you want to replace: In the
entire project, the main topics, the invisible topics or selected topics only. You can also
perform a test run to check how many styles would be found and replaced before
actually applying the changes.

© 1997 - 2009 by EC Software, all rights reserved

 More Advanced Procedures 515

Note that any changes in the current topic will only be visible in the editor after you
close the Replace Styles dialog.

Step 3: Apply text styles to sub-texts within the body text

Now you want to apply the text styles created in step 1 to the differently formatted sub-
texts within the body text. This must be repeated for each sub-text type.
1. Select multiple topics if you want to replace only in some topics
If you only want to replace styles in specific topics select those topics in the Project
Explorer first, using Shift+Click or Ctrl+Click. Select the topic containing the example
of the style you want to replace last, so that you can select the style example in the
next step.

2. Click in an example of the sub-text in the editor, then select Replace Styles and
Font mode
Click inside one of the formatted texts that you want to style, then select Styles >
Replace Styles in the Write tab. Then select the Font Styles mode at the top of the
dialog that appears.

3. Select (Unstyled text only) or (Any text) in the left column

If you know that none of the sub-texts have styles applied to them select (Unstyled text
only), otherwise select (Any text) to make sure that you find all of them.

4. Select the target style in the right column and execute

In the right column select the appropriate text style in the Change to Format/Style list
and then click on Replace Styles to replace all the styles.

Repeat the above procedure for every text style in your project.

Step 4: Apply the Normal paragraph attributes to your body text

Finally, you also want to apply the paragraph attributes of the Normal style to your
imported body text so that it is fully integrated in your stylesheet.
1. Select multiple topics if you want to replace only in some topics
If you only want to replace styles in specific topics select those topics in the Project
Explorer first, using Shift+Click or Ctrl+Click. Select the topic containing the example
of the style you want to replace last, so that you can select the style example in the
next step.

2. Click in a body paragraph editor, then select Replace Styles and Paragraph
mode
Click in one of your body text paragraphs, then select Styles > Replace Styles in the
Write tab. Then select the Paragraph Styles mode at the top of the dialog that
appears.

© 1997 - 2009 by EC Software, all rights reserved

516 Help & Manual 5 - User Help

3. Select (Unstyled text only) for the Para Style Name

If a style name is displayed in the Para Style Name: field in the left column change it
to (Unstyled text only). This will ensure that only paragraphs that do not yet have
styles applied to them will be found. This will reduce the possibility of errors and will
protect any styled paragraphs in your project with the same settings. Leave all other
settings in the left column unchanged!

4. Select Normal in the right column

Select the Normal style in the Change to Format/Style column. Leave all other settings
in this column unchanged. The inline formatting settings are irrelevant because you
are performing an exact search.

5. Click on Replace Styles to execute

A dialog will be displayed allowing you to choose where you want to replace: In the
entire project, the main topics, the invisible topics or selected topics only. You can also
perform a test run to check how many styles would be found and replaced before
actually applying the changes.
Note that any changes in the current topic will only be visible in the editor after you
close the Replace Styles dialog.

See also:
Importing Data 99
Text Formatting and Styles 155
Dynamic Styles 711

© 1997 - 2009 by EC Software, all rights reserved

Part

VII
 518 Help & Manual 5 - User Help

7 Multi-User Editing & Translation

The Professional version of Help & Manual has full support for team editing and project
translation and localization. These features are not available in the Standard version, which
cannot save or read projects in uncompressed XML and does not include the Project
Synchronizer and other features required for multi-user editing and translation.

7.1 Multi-User Editing

Help & Manual allows multiple users to edit the same project at the same time. The only
restriction is that it is not possible for two authors to edit the same topic simultaneously.
When one author is editing a topic a second author will get a message telling him or her that
the topic is not available for editing because it is in use.
Concurrent multi-user editing works directly "out of the box". You do not need to do any
server configuration, there are no special settings and you don't need a database. You just
need to store your project in uncompressed XML (.hmxp) format on a drive that all your
authors can access and start editing.

Productivity Tip
Refresh your project regularly! While
working on a project in a team always click
on Refresh Project in the Project menu
whenever you switch to a new topic to
make sure that you see the current version
of the Table of Contents and Project Files.

Requirements for multi-user editing

· Professional version only:
Multi-user editing is only supported in the Professional version of Help & Manual. All
users accessing the project must be using the Professional version of Help & Manual.
· Uncompressed XML save format only:
Projects must be saved in the uncompressed XML (.hmxp) format for multi-user editing
to be possible. The compressed .hmxz format cannot be used because it is stored in a
single file and it is necessary to access individual topic files for multi-user editing.
· All project files must be saved as uncompressed XML:
If the project has any merged sub-projects they must all also be saved as
uncompressed .hmxp projects. You cannot have any .hmxz sub-projects if you are
going to use multi-user editing.

Multi-user editing and version control systems

Multi-user editing is also supported when your project is linked to a version control system
335 . When your project is linked to a VCS repository all the multi-user access capabilities

© 1997 - 2009 by EC Software, all rights reserved

 Multi-User Editing & Translation 519

are then handled by your VCS, but this will not make any difference to the way you work
on your project. All the topic and project editing and access features work in exactly the
same way as with normal multi-user editing as described in this chapter.
Improved remote editing capabilities:
Remote editing – i.e. working on projects stored on a remote server – is considerably
better and more robust when you use a VCS, both for single-user access and for multi-
user access. When your project is linked to a VCS you work on a local copy that is linked
to the copy in the VCS repository on the server. This means that only the changes need
to be transferred between your location and the server, and that only when you open your
project (changes on server are transferred to you) and save your own work (your
changes are transferred to the server). Everything else is local.
Link your project to the VCS before you begin remote editing:
If you know you are going to need to edit your project remotely it is best to create your
local linked copy from the VCS repository before you go on the road, if possible. This will
avoid the need to download the entire project over a slower connection before you can
start editing. See the chapter on using version control systems 335 for more information.

The Refresh Project tool in the Project tab

This is the most important tool when you are working in multi-user editing mode. It
updates the display of the project and the TOC on your screen so that you can be sure
that you are seeing the current version, including any changes made to the TOC by other
users who may have moved, deleted or renamed TOC items.
Refresh also updates the contents and lock state (read-only or read-write) of the current
topic displayed in the editor.
Always use Refresh Project before making any changes that affect the TOC (renaming,
moving, deleting and creating topics).
Always save your project directly after making changes that affect the TOC to make
sure that there are no conflicts with other users' edits that you need to resolve.
See Creating, renaming, moving and deleting topics below for more details.

Editing topics
Just store the project on a network or server drive where all authors have read/write
access and start editing as normal.
You will only notice a difference if you try to edit a topic that someone else has open
then you will get a message telling you that the topic is open and is not currently
available. Help & Manual will never allow two different versions of the same topic to be

© 1997 - 2009 by EC Software, all rights reserved

520 Help & Manual 5 - User Help

created and it will never allow two users to edit the same topic at the same time. This
applies even if you have not saved your project.

When you select a topic that another user is already working on you will see a red bar
with a READ ONLY warning at the top of the editor screen and the topic will be grayed
out in the TOC.
If another user starts editing the topic while you are viewing it you will not see the READ
ONLY bar immediately. However, if you then try to edit the topic you will get a message
telling you that the topic is now being worked on and then the READ ONLY bar will be
displayed.
Custom display color for read-only topics:
You can set a custom color for displaying read-only topics in the TOC to make them
easier to identify for you. Go to View > Program Options > Editor and change the
setting for Display color for read-only TOC items.

Creating, renaming, moving and deleting topics

Help & Manual never allows you to edit the content of topics being worked on by other
users under any circumstances, even if you have not saved or refreshed your project.
However, when you make changes in the TOC in multi-user mode you are working on a
local copy of the TOC. The changes are only written to the actual project file when you
save the project. If another user has made changes to the same TOC entries you will
have a conflict and a dialog will be displayed asking you to resolve the conflict you must
then decide which version of the changes to keep and which to discard.
User Refresh Project to avoid TOC conflicts:
To avoid conflicts you should always select Refresh Project in the Project tab before
making any changes to the TOC. This will update your local copy of the TOC with the
current main version.
Refresh also updates the contents and lock state (read-only or read-write) of the current
topic displayed in the editor.
Creating new topics:
You can create new topics just as you would when you are working on a project on your
own. New topics cannot conflict with changes made by other users so you can always

© 1997 - 2009 by EC Software, all rights reserved

 Multi-User Editing & Translation 521

create them. Of course, if you choose a topic ID/topic file name that conflicts with an
existing topic you will not be allowed to create the topic.
Renaming, moving and deleting topics:
Always select Refresh Project before moving or deleting topics or renaming them in the
TOC. This ensures that you are viewing the current version of the TOC in the main
project file and prevents you having to resolve conflicts with your co-workers.
Once you have done this you can move and delete topics just as you would when you are
working in single-user mode.
Even so, it is generally advisable to check with your colleagues before moving or deleting
topics that others have also worked on! If in doubt make a copy of the topic with File >
Save Topic to File in Project > Manage Topics before deleting it.

Global search and replace

You can perform global search and replace operations normally when other users are
working on the same project as you. You will be able to find terms in topics that other
users are working on but you will not be able to replace them there until the other users
save their work and stop editing the topics.

Editing your project configuration

Your settings in the Configuration section of your project are not managed in the same
way as your project content. Any changes you make here are made without warnings or
locking. Anyone who makes changes here and saves the project will overwrite the current
settings with the new settings.
When you are working in a team the Configuration section should be the responsibility of
the project manager. Always check with your project manager or co-workers before
changing anything in your project configuration!

7.2 Translating Your Projects

Full support for translation and localization is only included in the Professional version of
Help & Manual. Although both the Standard and Professional versions support Unicode and
can thus produce projects in all languages except right-to-left languages, the Standard
version does not include the Project Synchronization Tool 556 and does not support saving in
the uncompressed XML format required for translation with tools like SDL Trados or Nero
Across.
The topics in this chapter provide an introduction to Help & Manual's translation and
localization features and show you where to find the information you need to use them.

See also:
Translating in Help & Manual 525
Translating with external editors 522
The Project Synchronization Tool 556

© 1997 - 2009 by EC Software, all rights reserved

 522 Help & Manual 5 - User Help

7.2.1 About translation support

Your uncompressed XML project files (.hmxp save mode) can be edited and translated
directly with an XML editor or with an XML-aware professional translation tool like SDL
Trados or Across. A customized INI file 81 for SDL Trados is included with Help & Manual
for proper display and editing of the XML output in Trados.
You can also translate your projects in Help & Manual itself. This can be done either in-
house using your own copy of the program or by an outside translator working with Help &
Manual as a translation editor. In this case only the Standard version of Help & Manual is
required. The Standard version can edit all features of projects created with the Professional
version provided they are saved in the single-file .hmxz format you cannot create some
features with the Standard version, but this is not something the translator should be doing
anyway.
In addition to this the Project Synchronization Tool 556 makes it easy to identify topics
containing changes in the next version of your documentation so that you can provide the
translator with a new version of the project file to update.

7.2.2 Translating with external editors

A growing number of professional translators use industry-grade translation assistance and
translation memory programs like SDL Trados or Nero Across that can edit XML files
directly. Help & Manual's uncompressed XML project files can be edited and translated
directly by these tools.
No conversion, export or import is necessary you only need to use the uncompressed .
hmxp save format so that the translators can access all the project files. Once the project
has been translated you can open it directly and continue editing it in Help & Manual. Here
too, no conversion or import is necessary.
It is also possible to edit and translate the XML files in your project with any XML editor,
along with WYSIWYG previews if the editor supports that feature. However, some editors do
not provide "protection" for XML tags and when translators work with these editors they have
to be very careful not to delete or change any tags while they are working.

Productivity Tip
An INI file for SDL Trados is included
with Help & Manual Pro. This makes
editing and translating your projects in
Trados much easier. See here 81 for
details.

Protecting text against changes and translation

You can explicitly protect text against translation and editing changes. To do this select
the text in the editor and then select the "padlock" tool in Write > Font. The text will
then be displayed shaded in the Help & Manual editor and it will be tagged with the
attribute translate="false" in the XML topic file.

© 1997 - 2009 by EC Software, all rights reserved

 Multi-User Editing & Translation 523

Procedure for translating in an external editor

Translating in external editors is only possible with the Professional version of Help &
Manual. The Standard version cannot read or write the uncompressed XML format
required for access by other editors and translation tools.
1. Save your project in .hmxp mode
Your project needs to be saved in uncompressed XML format for the translator to be
able to access the contents. If you are not already working in this mode click on the
Application Button in the top left corner of the Ribbon, select Save As... and save in
uncompressed XML mode (.hmxp uncompressed, Professional version only).

2. Make a "sibling copy" for the translator to work on

Select Synchronize in Project > Tools and make a sibling copy of the original
project. This copy will have exactly the same internal IDs as the original, which will
make it possible to identify changes and update the translated version with the
Synchronize tool later. See The Project Synchronization Tool 556 for more details.
It is best to perform this step after consolidating all your graphics and external files in
the project folder (see above).

3. Set up the language settings in the sibling copy for the new language
This is very important and can lead to unexpected errors in your output if you forget it.
For details on the settings you need to make and the issues you need to consider
study International languages setup 94 .

4. Update your graphics and export your Impict image texts for the translator
Check through all your graphics and make sure that they will make sense in the target
language. Texts stored in your Impict IPP images can be exported to XML files 528 for
the translator.

5. Make sure all graphics and external files are accessible

Check the locations of your graphics files in Configuration > Common Properties
> Project Search Path. Make sure that all these graphics will be available to the
translator for reference. It is generally best to place all graphics and external files in
folders inside the project folder, then you can send everything to the translator in a
single package. If you move your graphics you will need to update your project search
path so that Help & Manual can find them. See Managing your graphics 249 for details.
If you have separate source graphics, for example Impict IPP graphics containing
editable text objects, remember to include those too, preferably in a separate folder.
Check for any other relevant external files that you are referring to in your project as
well.

6. Check whether you need to include any snippet files for the translator
If your files contain linked snippets 149 from external sources you may need to include
copies of these embedded files for the translator.

© 1997 - 2009 by EC Software, all rights reserved

524 Help & Manual 5 - User Help

7. Translate the project with your external tool

The physical procedure for translating will depend on the tool you use to edit the XML
files. However, there are some important instructions for translators that should always
be observed. See Instructions for translators and editors 528 for full details.

8. Check through the Configuration to make sure that everything is OK.

When the translation is complete load it in Help & Manual and check through it
carefully make sure that all the relevant texts 525 in the project's Configuration section in
the Project Explorer have been translated to the new language. Also check things like
the index keywords etc.

9. Publish your project in the new language.

You will be able to generate the new version of your output in the target language
directly. What you get back from the translator is already a fully-functional Help &
Manual project since they have been working directly on the project source files.
Here too, of course, you should check things like special characters in your output
before distributing the finished product.

Procedure for updating translations

When your original project is updated you can use the Project Synchronization Tool to
make an updated version of the old translated project for the translator.
These instructions assume that you used the Project Synchronization tool to create a
sibling copy for the translator to work on when you sent the project for translation. If you
did not do this you may need to use a special feature of the Synch tool to link the two
projects. See Synching existing projects 565 for details.
1. Create an updated version of translated project for the translator
Follow the instructions in The Project Synchronization Tool 556 for synchronizing the
new version of your documentation with the old translated version. This will create a
new version of the translated project for the translator. Deleted topics will be removed,
new topics will be inserted and changed topics will be marked as changed. You can
also choose to insert full copies of the new content of all new and changed topics for
the translator to work with.

2. Translate the new material

This is the same procedure as above. The translator just translates the new material in
the updated XML package.

3. Generate your output from the updated project.

You don't need to check your language settings because you are already using a
project set up for the target language. After checking that everything has been
translated correctly you can generate your output with Help & Manual normally.

© 1997 - 2009 by EC Software, all rights reserved

 Multi-User Editing & Translation 525

Translating individual topics

Since all your topics are stored as individual XML files you can also send copies of
individual files out for translation as well.
In addition to copying individual topic files from your project folder you can also export
topic files with the File > Save Topic to File function in Project > Manage Topics.

7.2.3 Translating in Help & Manual

Translating projects in Help & Manual is basically exactly the same as working on a project
in your own language. You just make a sibling copy of the project with the Project
Synchronization Tool 556 , set up the language settings appropriately for the target language
and work you way through the project, translating as you go. When a new version of your
project becomes available you can then use the Project Synchronization tool to create an
updated version of the translated project containing all the topics with new material to be
translated.

Protecting text against changes and translation

You can explicitly protect text against translation and editing changes. To do this select
the text in the editor and then select the "padlock" tool in Write > Font. The text will
then be displayed shaded in the Help & Manual editor and it will be tagged with the
attribute translate="false" in the XML topic file.

Procedure for translating projects in Help & Manual

When you are using Help & Manual as the translation editor you can use either the
compressed .hmxz format or the uncompressed XML .hmxp format which you use is up
to you. However, both the original project and the translated version must be saved in the
same format, otherwise you will not be able to use the Project Synchronization tool later
to update your translations.
1. Make a copy of your original project for the translator
If you have the Standard version of Help & Manual you must just make a copy with
Save As... in the Application Menu. The Project Synchronization tool is not included
with the Standard version.
In the Professional version select Synchronize in Project > Tools and make a sibling
copy of the original project. This copy will have exactly the same internal IDs as the
original, which will make it possible to identify changes and update the translated
version with the Synchronize tool later.
See The Project Synchronization Tool 556 for more details.

2. Set up the language settings for the target language in the translation version
This is very important and can lead to unexpected errors in your output if you forget it.
For details on the settings you need to make and the issues you need to consider

© 1997 - 2009 by EC Software, all rights reserved

526 Help & Manual 5 - User Help

study International languages setup 94 .

3. Update your graphics and export your Impict image texts for the translator
Check through all your graphics and make sure that they will make sense in the target
language. Texts stored in your Impict IPP images can be exported to XML files 528 for
the translator.

4. Make sure all graphics and external files are accessible

In the translator's copy, check the locations of your graphics files in Configuration >
Common Properties > Project Search Path. Make sure that all these graphics will
be available to the translator for reference. It is generally best to place all graphics and
external files in folders inside the project folder, then you can send everything to the
translator in a single package. If you move your graphics you will need to update the
project search path so that Help & Manual can find them. See Managing your graphics
249 for details.

If you have separate source graphics, for example Impict IPP graphics containing
editable text objects, remember to include those too, preferably in a separate folder.
Check for any other relevant external files that you are referring to in your project as
well.

5. Check whether you need to include any snippet files for the translator
If your files contain linked snippets 149 from external sources you may need to include
copies of these embedded files for the translator.
If you include the files with the translation package you should add an entry to
Configuration > Common Properties > Project Search Path 656 pointing to the
folder containing the snippet files so that Help & Manual will find them.

6. Translate the project in Help & Manual.

Obviously, the first thing you will translate will be the texts of your topics. But there are
also a number of other things that you should not forget, and a few things that you
should not translate:
· Remember to translate all the normal index keywords in the tab and the Index Tool.
See Keywords and Indexes 273 for details on working with index entries.
· Don't translate any A-keywords 806 in the tab. These keywords are never seen by the
user and they will work best if you leave them unchanged.
· Check through all the sections of Project Configuration 652 and translate any texts
that will be visible to the user, including the values of text variables 376 .
· Don't translate the names of variables or include options 406 (build conditions). You
can translate the display texts for include options if you want but you don't have to,
they are never seen by the user.
See Instructions for translators and editors 528 for a full list of guidelines.

7. Publish your output, check and distribute.

© 1997 - 2009 by EC Software, all rights reserved

 Multi-User Editing & Translation 527

Publish your output as normal. Before distributing it check it to make sure that
everything is OK for the target language. For example, if your language settings are
not correct special characters in the target language may not be displayed correctly.

Procedure for updating translated projects

Translating the first version of your project is straightforward, you just make a copy and
translate it. The next challenge is to produce an updated version of the translation when a
new version of your original documentation is released.
If you are using the Standard version of Help & Manual you must make notes of all your
changes and tell the translator where they are.
If you have Help & Manual Professional you can use the Project Synchronization Tool 556
to make an updated version of the translated project. Project Synch will delete removed
topics, add new topics and mark changed topics as changed. Full copies of the original
text of all new and changed topics, topic titles in the TOC and topic headings can be
inserted for the translator if you want. (Otherwise you must provide a copy of the original
version for the translator to refer to.)
1. Create an updated version of the project for the translator
Standard version:
If you have the Standard version of Help & Manual you must send the translator a
copy of the new version of the original project with annotations showing where the
changes are located. The translator must then use Help & Manual to update the old
version of the translation.
Professional version:
Follow the instructions in The Project Synchronization Tool 560 for synchronizing the
new version of your documentation with the translated version. This will create a new
version of the old translated project for the translator, with deleted topics removed,
new topics inserted and changed topics marked as changed. You can also choose to
insert full copies of the new content of all new and changed topics for the translator to
work with.

2. Make copies of all new and changed graphics and other external files.
Before sending the updated project to the translator, make sure that you also include
all new and modified graphics in the translation package, along with any new and
changed external files. Here too, keeping everything in one project folder makes things
a lot easier.
Also check whether there are any changes in linked snippets 149 – if there are you will
probably need to include copies of the new versions of the source files for the
translator.

3. Translate the changes and generate your output.

Once the translator has produced the new version you can generate your output as
normal. Don't forget to check through the Configuration settings in the Project Explorer
to make sure that all relevant texts visible to the user have been translated.

© 1997 - 2009 by EC Software, all rights reserved

 528 Help & Manual 5 - User Help

After generating your output check the finished product carefully to make sure that
everything is OK in the target language. For example, make sure that special
characters are rendered correctly – if they are not you may need to adjust the
language settings for your project.

See also:
The Project Synchronization Tool 556
International languages setup 94
7.2.4 Translating texts in images
If you create images with Impict 536 that contain text objects you will also need to translate the
texts in the images. If the translator is working in Help & Manual they can edit the texts
directly in Impict – you just need to remember to give them copies of all the images in
Impict's own IPP format so that the texts remain editable.

Translating image texts in Impict

If possible it is probably better for the translator to work directly in Impict to translate the
image texts. Text lengths often change when they are translated and this will generally
make it necessary to move and modify the text objects in the images. Some languages
will also require a different layout because of the different structure and logic of the
language.
If the translator works in Impict they can do this work directly, eliminating the need for you
to have to do it later.

Exporting image texts to XML for translation

Translators using XML editors or translation tools will not have access to Impict. You can
export the texts in your Impict IPP images to external XML files that these translators can
edit. Later, you can import the translated texts from the XML files to the IPP images with
Impict and make any necessary modifications.
For details see the chapter on Translating Texts in Images in the Impict help.

7.2.5 Instructions for translators and editors

When you are working on the XML files it is important that you should only translate or edit
those parts of the file that are "editable". This topic provides basic instructions for translators
and editors of Help & Manual project, particularly those working on the XML files rather than
in Help & Manual itself. How important these instructions are will depend on the XML editing
tool you are using. Some XML editors will protect attributes and tags, making it difficult or
impossible to accidentally damage them, others don't provide this protection and must be
used with more care.

What you are NOT allowed to translate or edit

Do not translate:
· Anything inside tags (XML elements)

© 1997 - 2009 by EC Software, all rights reserved

 Multi-User Editing & Translation 529

· Text identified as translate="false"

· Tag/element attributes
Anything inside tags (XML elements)
The first and most important principle is that you are never allowed to edit anything inside
tags. All text in tags and tag attributes – i.e. anything between the < and > characters
marking the beginning and end of a tag – is strictly off limits for translators and editors.
Don't even think about editing anything inside tags, this information doesn't even exist for
you. Just ignore it.
Nothing inside tags is ever seen by the user so nothing inside tags ever needs to be
translated or edited. For example, even though many of the words inside the following tag
(in blue) are in English you are not allowed to translate them because they are inside the
tag:

<config-value name="title" translate="true">Help &amp; Manual

XML Language Reference</config-value>

You are only allowed to translate the text shown in red, because it is plain text between
tags (and because the tag has a translate="true" attribute, see below).

Text tagged as translate="false"

This should be fairly obvious: In Help & Manual text can be protected against changing
and this applies the attribute translate="false" to the text tag. Any text tagged with this
attribute should be left unchanged unless the author specifically provides other
instructions.
Element attributes
Element attributes are also inside tags so that is already a very good reason not to
translate them. However, this point is so important we would like to repeat it. Don't even
think about translating or editing the attributes of any XML elements. Again, none of
these attributes are ever seen by the user so they don't need to be translated. If you do
translate them you will create syntax errors and make it impossible for Help & Manual to
open the project correctly.
In the following example too, you can only translate or edit the text shown in red.
Everything else is strictly off limits. All the texts shown in green are element attributes.
Editing or translating them will make it impossible to re-import the XML files because of
the strictness of XML syntax.

<para styleclass="Heading2"><text styleclass="Heading2">What

you are </text><text styleclass="Heading2" style="text-
decoration:underline;">not</text><text styleclass="Heading2">
allowed to translate or edit: </text></para>

Of course, sometimes you will have to use your own judgment a little. In the example
above you will have to move around the underline tags around the word "not" because
the structure of the sentence will probably be quite different in another language. This is
generally OK provided you do it carefully and don't move these tags outside any other
tags enclosing them. Just be careful and if you are not entirely sure what you are doing
leave it alone or get help from someone with more experience.

© 1997 - 2009 by EC Software, all rights reserved

530 Help & Manual 5 - User Help

Ultimately, you will save a lot of time and frustration if you use a proper translation tool
that hides the tags from you so you don't need to worry about them at all.

What you are allowed to translate or edit

Text data between tags with the translate="true" attribute
What you may translate is very clearly defined. Every element containing translatable
data is identified with the translate="true" attribute in the opening tag. This means that
you don't even need to look at any elements that don't have this tag. If a tag has the
attribute translate="false" just ignore its content.
Here too, of course, you are only allowed to translate or edit the text data between the
tags. You are still not permitted to touch anything inside the tags themselves, even in the
tags with translate="true".

Translatable elements

Element Translatable
text Text is always translatable if its translate attribute is set to "true". Do not
translate if translate="false" is set.

link The captions of hyperlinks (topic links, web links, file links, script/macro
links) are translatable if their translate attribute is set to true.

caption Image captions are translatable if their translate attribute is set to true.

keyword Keywords are always translatable. They always have a translate

attribute and the setting is always "true".
Note that this does not apply to a-keywords! A-keywords are never seen by
the user and should never be translated because this can break help
functionality!

html-code The translate attribute of html-code elements is always set to "true".

However, whether a translation is really required will depend on the nature
of the code. If in doubt, ask!

config- Only some config-value elements are translatable. If they have a translate
value attribute and it is set to true they can be translated. If not they should be
left alone.

See also:
Project Synchronization 556
Editing XML source code 154

© 1997 - 2009 by EC Software, all rights reserved

Part

VIII
 532 Help & Manual 5 - User Help

8 Tools included with Help & Manual

In addition to the main program Help & Manual also includes a number of tools that make
producing help and documentation easier and more efficient. Some of these tools are
separate programs and some are integrated in Help & Manual itself, but they are all
available from within the main program.
This chapter provides descriptions of the tools and instructions on how to use them. In some
cases the instructions here are very basic because some of the tools have their own
separate help and documentation.

8.1 The Screen Capture Tool

Help & Manual has an integrated screen capture tool that includes all the functions you need
to make attractive screenshots quickly and efficiently. The tool will automatically select
windows, controls and menus and you can also select freely-defined rectangular regions of
applications or the desktop and fixed size regions.
In addition to simple screenshots you can also make screenshots with a wide variety of
different shapes, add shadows and background colors and automatically resize your
screenshots with a choice of high-quality scaling filters.
For more control over effects and appearance you can create and edit your screenshot with
Impict 244 , the screenshot editing and enhancement program included with Help & Manual. In
Impict edits are non-destructive, which means you can always go back and change
something if you need to.

Productivity Tip
If you have a dual-monitor display the
window you are capturing and Help &
Manual must both be in the same monitor
for captures to work. On some systems
captures may only work correctly in the
primary monitor.

How to capture a window, control or menu

1. Make sure that the program containing the element you want to copy is on the screen,
then click in the editor in the place where you want to insert the captured image.
2. Select Screen Capture in Project > Tools.
3. Select A Window, Control or Menu option and click on Start Capture.
4. Help & Manual minimizes and now you can move the mouse to select what you want
to capture. The selected element is indicated by a red outline.
You can also click to select and deselect windows and elements and open menus and
dialogs, this will not activate the capture.
5. When you are ready to capture hold down Ctrl and click. This will display the Save
Image dialog, in which you can choose where you want to save the graphic, the

© 1997 - 2009 by EC Software, all rights reserved

 Tools included with Help & Manual 533

filename and the color depth (or grayscale).

When you select Save the screenshot file will be saved and simultaneously inserted in
your topic.

How to capture a free region

You cannot click on elements to activate them while capturing with this method so
arrange everything as you want to have it for the capture before you start. If you want to
capture something in a program select it briefly and then return to Help & Manual, this will
ensure that its window is active when you capture.
1. Click in the editor in the position where you want to insert the screenshot.
2. Select Screen Capture in Project > Tools.
3. Select A free region of the desktop and click on Start Capture. Help & Manual
minimizes and a cross-hair pointer is displayed along with a lens window that helps
you to see exactly what you are selecting.
4. Position the cross-hair pointer at the top left corner of the area you want to select.
Press the left mouse button and drag down and to the right to define the area to
select.
5. Release the mouse button and then click inside the selected area. This will display the
Save Image dialog, in which you can choose where you want to save the graphic, the
filename and the color depth (or grayscale).
When you select Save the screenshot file will be saved and simultaneously inserted in
your topic.

Capturing a fixed-size region

Capturing a fixed-size region is very similar to capturing a window or control. However,
instead of automatically selecting elements on the screen the red outline remains the
same predefined size. This can be useful for selecting elements that are otherwise
difficult to "grab" and elements that all need to be exactly the same size (like icons).
1. Make sure that the program containing the element you want to copy is on the screen,
then click in the editor in the position where you want to insert the screenshot.
2. Select Screen Capture in Project > Tools.
3. Select A fixed-size region option set the size of the region you want to capture (in
pixels). Then click on Start Capture.
4. Help & Manual minimizes and now you can move the mouse to select what you want
to capture. A fixed-size red rectangle showing the area to be captured is displayed.
You can also click to select and deselect windows and elements and open menus and
dialogs, this will not activate the capture.
5. When you are ready to capture hold down Ctrl and click. This will display the Save
Image dialog, in which you can choose where you want to save the graphic, the
filename and the color depth.

© 1997 - 2009 by EC Software, all rights reserved

 534 Help & Manual 5 - User Help

When you select Save the screenshot file will be saved and simultaneously inserted in
your topic.

Using extended options for more effects

All three capture methods can be combined with a selection of options to automatically
resize your screenshots and enhance them by adding shadows, applying shapes and
other effects while the capture is being made. See Screen Capture 595 in the Reference
section for explanations of the individual options. Experiment!
· Before making your screenshot click on the Extended >> button to display the available
options. All the options you select here are applied automatically when the screenshot
is made.
· For even more screenshot power try TNT, the combined screen capture and graphics
editor tool from EC Software: TNT Screen Capture Page

See also:
Screen Capture 595 (dialog reference)
About Graphics in Help & Manual 753
The Impict Screenshot Editor 536

8.2 The Project Reports Tool

This tool generates detailed reports on your project that can be used for a wide range of
purposes, including documentation, providing your programmers with lists of topic IDs for
their help calls, checking project status, locating dead links, finding missing images and
unused images and so on. Reports are displayed immediately in a special viewer but you
can also save them in HTML files for documentation and other purposes.
See the report dialog reference 596 in the Reference > Menus and Dialogs > Tools
chapter for details on the dialog options and the available report types 596 .

How to generate a project report

1. Select Report Tool in Project > Tools.

© 1997 - 2009 by EC Software, all rights reserved

 Tools included with Help & Manual 535

2. Select the report type in the Report Type: field.

3. Select the other options to change the sort order of your report and which topics you
wish to include or exclude (see the dialog reference 596 for details).
4. Click on OK to display the report in your default browser.

Report types
Short report: Simple list of all topics in your project with status, caption (i.e. the TOC
title), topic IDs, help context numbers, builds in which the topics are
included and date last edited. The report also includes a summary of the
number of topics and keywords in your project.
This is a practical format for providing your programmers with a list of topic
IDs and context numbers for their calls.

Extended Also includes each topic's keywords and help window and a more detailed
report: project summary with a list of the images used in the project.
Missing images are shown in red.

Long report: Also includes lists of the images used in each topic, lists of the links in
each topic with their targets (including topic links, Internet links, file links
and script links) and the first lines of the text with which the topic begins.
Missing images and dead links are shown in red.

Full report Same as the Long Report but also includes an additional full list of images
including used in the project with a lists of the topics in which each image is used. In
image addition to this there is also a list of images in the project's graphics
references: folders that are not used in the project (useful for tidying up your project
folders).
Missing images and dead links are shown in red. Unused images are

© 1997 - 2009 by EC Software, all rights reserved

 536 Help & Manual 5 - User Help

listed at the end of the report.

See also:
Reports 596 (dialog reference)

8.3 The Impict Screenshot Editor

Help & Manual comes with a fully-featured graphics editing program called Impict. This
program is designed specifically for editing and enhancing screenshots and other graphics
used in help and documentation projects. Since Impict comes with its own comprehensive
help this topic only explains how to start the program and how to open graphics files for
editing in Impict from the Help & Manual editor.
For full details on editing images with Impict see the program's own help.

Setting Impict as your default image editor

Several of the functions described below only open Impict if it is set as your default image
editor. This is the default setting when Help & Manual is installed.
1. Select Program Options in the View tab and then select the General tab in the dialog
displayed.
2. Check that impict.exe is selected in the Default Image Editor: field. If it isn't use the
browse button to select this file in the Help & Manual program directory, which is
normally C:\Program Files\EC Software\HelpAndManual5.
Alternatively you can also select any other graphics editing program. Then most of the
functions described below will open this program instead of Impict.

How to start Impict

There are several different ways to start Impict:
· Select the Image Editor tool in Project > Tools.
· Select Impict in the Help & Manual program group in the Windows Start menu.
· Right-click on an image in the Help & Manual editor and select the option for editing the
image in Impict.

How to open an image in Impict from the editor

1. Click once on the image you want to edit in the Help & Manual editor to select it.

2. Select Image Editor in Project > Tools or right-click on the image and select the

© 1997 - 2009 by EC Software, all rights reserved

 Tools included with Help & Manual 537

option for editing the image in Impict.

Note that these options will open the image in a different image editor if Impict is not
defined as your default image editor (see above).

See also:
Using Graphics 238
Screen Capture 532

8.4 The Print Manual Designer

The Print Manual Designer is a separate program used for editing the print manual template
files that define the layout and appearance of your published PDF files and printed
manuals.
In addition to defining the layout of your PDF pages you can also add additional pages and
content not included in your project, including cover and back cover pages, an introduction,
a formatted table of contents, title pages for individual chapters, headers and footers, a
formatted index and multiple endnotes pages. You can also add your own custom pages
and insert topics from your project and external Help & Manual XML files.
The Print Manual Designer has its own help so this topic only describes the basic
procedures for opening templates for editing and selecting them in your projects. Print
manual template files have the extension .mnl.

How to edit the current print manual template

You can open the print manual template assigned to the current project directly for
editing.
Opening the template for Adobe PDF output:
1. Open your project and go to Configuration > Publishing Options > Adobe PDF
> PDF Layout 690 .

2. Click on the Design... button to the right of the Print Manual Template: field. This
opens the Print Manual Designer and loads the current template for editing.
Opening the template for printed manuals:
1. Open your project, click on the Application Button and select Print Manual 575 .

© 1997 - 2009 by EC Software, all rights reserved

538 Help & Manual 5 - User Help

2. Click on the Design... button to the right of the Print Manual Template: field. This
opens the Print Manual Designer and loads the current template.
Note that you can set different templates for PDF and print manual output. Both settings
are stored automatically after being selected.

How to select a print manual template for your project

You must select a print manual template in your Project Configuration settings to use it
for your project. You can select separate templates for printed manuals and Adobe PDF
output.
Selecting a template for Adobe PDF output:
1. Open your project and go to Configuration > Publishing Options > Adobe PDF
> PDF Layout 690 .

2. Enter the path and name of the template you want to use in the Print Manual
Template: field. Use the browse button to locate and select the template you want to
use.
Selecting a template for printed manuals:
1. Open your project, click on the Application Button and select Print Manual.

2. Enter the path and name of the template you want to use in the Print Manual
Template: field. Use the browse button to locate and select the template you want to

© 1997 - 2009 by EC Software, all rights reserved

 Tools included with Help & Manual 539

use.

How to open the Print Manual Designer on its own

· Select the Manual Designer tool in Project > Tools.

This opens the Print Manual Designer with a new empty template file. It is generally
easier to edit an existing template, particularly when you are using the program for the
first time. You can find a collection of sample templates in the \Templates\pdf folder in
the Help & Manual program directory, which is normally C:\Program Files\EC
Software\HelpAndManual5.
It is a good idea to make a copy of the sample template instead of working on the
original. If you are using Windows Vista you will generally be unable to save template
files in the template directory you must save a copy in a directory for which your user
account has full read and write permissions.
It is a good idea to store the working copy of your print manual template in your project
directory if you want to keep all the files used by your project in one place.

See also:
PDF and Printed Manuals 325
PDF and print manual templates 425
Adobe PDF 737
Printed manuals 738

8.5 The Help Context Tool

The Help Context Tool helps to manage the help context numbers 205 in your project and it
can also be used to generate topic files automatically from map files supplied by your
programmers.
You can assign, delete, import and export help context numbers in batch mode for your
entire project. In addition to this you can also use the tool to automatically generate missing
help topics from a map file containing a list of topic IDs and context numbers.

Supported context number range:

Help & Manual stores context numbers as an unsigned 4-byte integer, which means you
can enter values between 1 and 4294967295. This is nearly 4.3 billion, so it should
provide you with just about enough numbers for most normal applications.

Key Information
Note that you cannot import help context
numbers to anchors, even though you can
export help context map files with anchor
information. Note also that you can only

© 1997 - 2009 by EC Software, all rights reserved

540 Help & Manual 5 - User Help

import one help context number per topic

with the context tool. Multiple numbers
must be added manually.

Assigning context numbers to all topics without them

This function only assigns context numbers to topics that do not yet have them, existing
context numbers are protected. If you want to renumber all the topics in your project first
use the Delete function (see below) to clear all the numbers in your entire project.
1. Select your project in the Project Explorer, then select Context Tool in Project >
Tools.
2. Click on Create Numbers. A dialog will be displayed informing you of the starting
number an the increments that will be used between numbers.
3. Click on Create Numbers to assign the numbers. Numbers will be added to all topics in
your project that do not yet have context numbers.
Changing the increment:
This function uses the increment set in your project configuration for assigning context
numbers to new topics. You can change the setting in the Project Explorer in
Configuration > Common Properties > Miscellaneous.

Editing and adding context numbers for single topics

1. Select your project and open the Context Tool (see above).
2. Select List all Topics to make sure that all topics are listed, including those that do not
have context numbers yet.
3. Select a topic from the list, click on the topic you want to edit and select Edit Number.
4. You can then add a new context number or edit the existing number.
You can't add multiple context numbers with this method. To add multiple numbers to a
topic you must use the tab behind the main editor.
Adding new numbers and topics:
The Add New Number function is for creating new topics with new numbers. Enter a new
topic ID followed by a new number. The new topic ID and context number will be added to
the list and a new topic file will be created when you click on OK.
An error will be displayed if you enter the ID of an existing topic.

Deleting help context numbers

1. Open your project and select Tools > Help Context Tool.
2. Select the context numbers you want to delete in the list displayed. Use Ctrl+Click and
Shift+Click to select multiple numbers.
3. Click on Delete Selected to delete the context numbers from the selected topics.

© 1997 - 2009 by EC Software, all rights reserved

 Tools included with Help & Manual 541

Note that if selected topics have multiple context numbers all the numbers will be
deleted, even though only the first number is shown for the topic in the list.

Importing context numbers and auto-generating topics from a map file

Software development tools can generate "map" files with lists of context IDs and
matching help context numbers. Programmers often provide these lists to inform the help
authors of the topic IDs and context numbers needed for context-sensitive help calls.
In addition to importing missing context numbers to existing topics this function can also
auto-generate missing topics from a map file. Since context-sensitive help often consists
of hundreds of very short topics this capability can save you many hours of boring and
frustrating work. It creates the basic framework for your context help in seconds.
Importing context numbers:
1. Obtain the map file from the programmers and make sure that it only contains the
topics you want to use. These files have a standard syntax – you can create an
example by using the Help Context Tool's export function (see below).
2. Open your project (you might want to make a backup first) and select Tools > Help
Context Tool.
3. Select Import Map File and select the map file you want to import. A dialog will be
displayed asking you whether you want to merge or replace the existing numbers
Replace:
This deletes ALL context numbers in the current project and replaces them with the
numbers from the map file.
Merge:
This only replaces the context numbers for topics with matching IDs. All other topics
are left unchanged.
Auto-generating topics:
When you import a map file any topic IDs in the file that don't exist in your project will be
listed in red in the Context Tool editing box. When you click on OK the tool will ask you if
you want to create topic files for these IDs.
If you say yes the files will be created in the Topic Files section, without TOC entries. If
you want to create TOC entries for the new topics you must do this manually. 112

Exporting IDs and context numbers to a map file

You can also use the Help Context Tool to export the topic IDs and help context numbers
from your project to a map file that the application programmers can use for writing their
context help calls (and also to obtain an example of the map file syntax).
1. Open your project (you might want to make a backup first) and select the Context
Tool in the Tools > Help Context Tool section.
2. If you only want to export some of the help context numbers select them in the list
with Ctrl+Click and Shift+Click. Then select Export Map File:

© 1997 - 2009 by EC Software, all rights reserved

542 Help & Manual 5 - User Help

3. Select Export selected numbers only if you don't want to export the entire list, then
choose the Map File Syntax:
· #Define is the default and selects the standard #define syntax used in most map
files.
· INI Style selects the standard INI file format.
· Custom allows you to define your syntax yourself. To do this you can combine the
three map file variables displayed (see below) with any text or additional characters
of your own.
4. Enter a filename and click on Save to export the map file.

Variable syntax for custom map file output

You can use the following three variables in your map files:
<%TOPICID%> Inserts the Topic ID of the current topic. Unlike <%
HREF_CURRENT_PAGE%> this variable inserts the
Topic ID exactly as it is displayed in the tab, including
upper and lower case characters.

<%ANCHORID%> Inserts the anchor ID of an anchor that has a help

context number.

<%TOPIC_HELPCONTEXT Inserts the help context number of the current topic or

%> anchor.
Just inserting the variable on its own generates a decimal
number. You can also export the context numbers in
hexadecimal by adding a hex prefix:

&<% Exports to hex in the format &000000FF

TOPIC_HELPCONTEXT%>
0x<% Exports to hex in the format 0x000000FF
TOPIC_HELPCONTEXT%>

See also:
Topic IDs and context numbers 205
IDs, Context Numbers and Keywords 801

© 1997 - 2009 by EC Software, all rights reserved

 Tools included with Help & Manual 543

8.6 The Spell Checker

The spell checker included with Help & Manual supports both manual spell checking (check
topics or the entire project in a single session) and "live" spell checking, which highlights
incorrectly spelled words as you type.
See Spell checking 145 in the Creating and Editing Topics chapter for instructions on using
both manual and live spell checking functions.

Productivity Tip
Spell checking is supported almost
everywhere in Help & Manual where you
can enter text. Just right-click to display the
context menu or click on the upper half of
the Spelling tool in the Project tab to
access.

The Spelling tool

The Spelling tool in the Project tab is available almost everywhere in Help & Manual
where you can enter text, including the HTML editors for HTML templates and code
objects, the XML editor, the TOC captions in text entry mode and all of the text entry
fields in the Configuration section of your project.

· Clicking on the top half of the Spelling tool checks selected text (if any is selected) OR
the current topic or text entry field or window (if no text is selected).
· Clicking the bottom half of the Spelling tool displays the spell-check menu.

Spell checker Options

Select Tools > Spelling > Configure Spell Checker, then configure your options in
the User Preferences tab.

© 1997 - 2009 by EC Software, all rights reserved

544 Help & Manual 5 - User Help

Most of the settings here are self-explanatory. Here are a couple of notes on special
functions:
Live spelling:
Identifies incorrect words with squiggly red underlines while you are working. Right-click
on words with these underlines to display a spell-check menu. Does not support repeated
words and dual capitals (see below)
Main dictionary only:
When this is active suggested corrections will be taken from the main dictionary for the
current language only. No suggestions will be taken from your own user dictionaries.
Prompt on repeated word, correct Dual capitals:
These functions are not active for live spell checking. They are only supported in the
interactive spell check started from with the Spelling tool in the Ribbon.

Selecting the language and adding main dictionaries

Select Tools > Spelling > Configure Spell Checker, then select the dictionary for the
language of your project in the Dictionaries tab.
To add dictionaries for more languages click on Download dictionaries... These dictionary
files must be saved in the \dictionaries folder in the Help & Manual program directory.

© 1997 - 2009 by EC Software, all rights reserved

 Tools included with Help & Manual 545

Selecting and adding custom (user) dictionaries

The main dictionaries are not editable. However, you can create custom user dictionaries
to store your own additional terms. These dictionaries can also store auto-correct word
pairs and "excluded" words that you want to always identify as incorrect even if they are
in the main dictionary.
See Using custom dictionaries 548 and Creating and editing custom dictionaries 546 for full
details on this subject.

· The standard user dictionary is stored in your My Documents folder (called Documents
in Windows Vista). To use this just select it in the When adding words, use this
dictionary list at the bottom of the dialog.

© 1997 - 2009 by EC Software, all rights reserved

 546 Help & Manual 5 - User Help

· Click on Add/New to create a new user dictionary or to select an existing dictionary.

You can store your dictionary anywhere you like.
· If you only want to use the selected dictionaries for the current project activate Selected
dictionaries are used for this help project only. Otherwise your selections will be stored
for all projects.

Disabling spell checking for specific styles

The settings in the Ignore List tab exclude text formatted with specific styles from spell
checking. This makes it possible to prevent spell checking for text where it would not
make sense, for example in quoted text in other languages.
1. Select Tools > Spelling > Configure Spell Checker and click on the Ignore List
tab.

2. Select the check boxes of all the styles you want to exclude from checking.
All text formatted with the selected styles will be ignored by the spell checker. These
settings are always global unlike the other spell checker options you cannot apply them
on a per-project basis.

See also:
Using custom user dictionaries 548
Creating and editing custom user dictionaries 546
Spell checking 145
8.6.1 Creating and editing custom dictionaries
You can store your custom user dictionaries in any location, including network drives. and
multiple users working on the same or different projects can use them simultaneously. In
addition to storing your own terms user dictionaries can also store auto-correct pairs for
terms you always want to correct and "excluded" words that you always want to mark as

© 1997 - 2009 by EC Software, all rights reserved

 Tools included with Help & Manual 547

incorrect, even if they may be in one of the main dictionaries.

Creating a custom user dictionary

1. Select Tools > Spelling > Configure Spell Checker, then select the Dictionaries
tab.

2. Click Add/New and choose a name and storage location for the dictionary. Dictionaries
can be stored anywhere you like, also on network drives. They can also be used
simultaneously by other users working on the same project or different projects.
You can also use the Add button to select existing user dictionaries. This adds them to
the Custom Dictionaries list so that they are used by the spell checker.

Using dictionaries for the current project only

Normally your dictionary setup will be stored with your Help & Manual program settings
and will be activated for all your projects. If you only want to use your dictionary settings
for the current project select the option Selected options are used for this help project
only in the Dictionaries tab.

How to edit custom user dictionaries

In addition to adding incorrect words to your user dictionaries while spell checking you
can also edit the dictionaries to remove words added accidentally or add new words.
1. Select Tools > Spelling > Configure Spell Checker, then select the Dictionaries
tab and click the dictionary you want to edit in the Custom Dictionaries box.

© 1997 - 2009 by EC Software, all rights reserved

 548 Help & Manual 5 - User Help

2. Enter a word and click on Add to add, select a word and click on Delete to remove.

Auto-Correct Pairs and Excluded Words

The Auto-Correct Pairs and Excluded Words tabs in the edit user dictionary dialog (see
above) have the following functions:
Auto-Correct Pairs:
The first word in each pair in this list will be automatically replaced by the second word
during manual spell checks. (This function is not supported in live spell checking.) You
cannot enter words that are already included in the Excluded Words list.
Excluded Words:
All the words in this list are identified as incorrect by the spell checker, even if they are
contained in the main dictionary. You cannot enter words that are already included in the
Auto-Correct Pairs list.
See Spell checking 145 for instructions on using these functions while spell checking.

See also:
Using custom dictionaries 548
Spell checking 145
8.6.2 Using custom dictionaries
You can define and use as many custom user dictionaries as you want. In addition to the
standard function of storing words not contained in your main dictionaries these dictionaries
also have two more very useful functions:
Auto-Correct for frequent errors and abbreviations:
The Auto-Correct function automatically replaces common typing errors and
abbreviations with the correct words or entire phrases. See Spell checking 145 in the
Creating and Editing Topics chapter for details on using this function. This function is

© 1997 - 2009 by EC Software, all rights reserved

 Tools included with Help & Manual 549

not available in live spell check mode!

Excluded Words for exception handling:
The Excluded Words function allows you to enter words that will always be marked as
incorrect, even if they would normally be considered correct. This allows you to enter
exceptions for words contained in the standard main dictionaries that you want to handle
differently.

Selecting the user dictionary for the Add Word function

The spell checker uses the words from all user dictionaries listed in the Dictionaries tab
but new words can only be added to one selected user dictionary. This dictionary is used
for the Add function in both live and manual spell checking.
This dictionary is also used when you select AutoCorrect in the manual spell checker. For
more details see Spell checking 145 in the Creating and Editing Topics chapter.
1. Select Tools > Spelling > Configure Spell Checker, then select the Dictionaries
tab.

2. Select the custom dictionary you want to use in the Custom Dictionaries: box. Click
Add/New if you want to add a new dictionary or select a dictionary stored in a different
location. (Custom dictionaries can be stored anywhere and can be shared by multiple
users working simultaneously.)
3. Select the dictionary you want to use from the list in the Custom Dictionary: field.

Activating and deactivating custom user dictionaries

Although words are always added to the same custom user dictionary (see above) you
can define and use as many custom dictionaries as you like. New words will be added to
the standard custom dictionary, but the spell checker will use all the activated dictionaries
for checking spelling and for the Auto-Correct 543 and Excluded Words functions.

© 1997 - 2009 by EC Software, all rights reserved

 550 Help & Manual 5 - User Help

Activating user dictionaries:

1. Select Tools > Spelling > Configure Spell Checker and click on the Dictionaries
tab.

2. Click on the Add/New button to add dictionaries to the Custom Dictionaries list. You
can then create a new dictionary or select an existing dictionary.
All the listed dictionaries will be used for spell checking. These dictionaries can be
stored in any location, also on network drives, and they can be used simultaneously by
multiple users.
Deactivating user dictionaries:
To deactivate a user dictionary just select it in the list and click on Remove. This will not
delete the dictionary, it will just remove it from the dictionaries list.

Using dictionaries for the current project only

Normally your dictionary setup will be stored with your Help & Manual program settings
and will be activated for all your projects. If you only want to use your dictionary settings
for the current project select the option Selected options are used for this help project
only in the Dictionaries tab.

See also:
Creating and editing custom user dictionaries 546
Spell checking 145

8.7 The Project Converter

This tool converts old project files created with Help & Manual 3 (.hm3) and 4 (.hmx) to the
current Help & Manual formats.
Normally you will convert old projects directly by opening them. Just click on the Application

© 1997 - 2009 by EC Software, all rights reserved

 Tools included with Help & Manual 551

Button, select Open, choose the project type you want to open and follow the instructions
displayed. This will also give you the option of opening the external converter program.
You can also open the Project Converter manually by selecting it in the Help & Manual
program group in the windows Start menu.

How to convert projects

1. Click on the Application Button and select Open.
2. Select the project or help file type you want to convert, then navigate to the file and
select it.
3. The following dialog is displayed:

Convert and open:

Converts the project to the compressed, single-file .hmxz format, storing it in the same
directory as the original file. If you choose this option no additional options are displayed.
Start external converter:
Opens the external Project Converter program providing additional options (see below). If
you are converting Help & Manual 3 projects it is better to choose this option.
You can also start the Project Converter directly by selecting it in the Help & Manual
program group in the Windows Start menu.

Using the external Project Converter

When you use the external converter you can choose the project file format (compressed
single-file format or uncompressed XML) and configure the Help & Manual 3 conversion
settings.
Project file format:
First you must choose whether you want to export to the compressed .hmxz single-file
format (default) or uncompressed XML (a directory of individual XML project files).

© 1997 - 2009 by EC Software, all rights reserved

552 Help & Manual 5 - User Help

· Uncompressed XML is only available in the Professional version of Help & Manual. This
format is required for multi-user editing.
· If you choose uncompressed XML you must choose an empty directory for the output
files. This is necessary because this format consists of several folders with individual
files for all topics and other project components.
Help & Manual 3 conversion settings
If you are converting a Help & Manual 3 project the following additional options will be
displayed in the next screen of the conversion wizard:

© 1997 - 2009 by EC Software, all rights reserved

 Tools included with Help & Manual 553

Convert tables to This converts the fixed-size Version 3 tables to dynamic tables
auto-size: that will automatically resize to fit the help viewer window.
Note that this option makes the widths of all columns in your
tables variable – they will adjust automatically on the basis of their
content.
Don't activate this option if your project contains tables with
explicitly defined column widths as it may cause formatting
problems! (For example if you use tables as a formatting tool.)

Convert only last This has the same effect as the previous option but it only makes
column to auto- the last (rightmost) column in the table variable. This is the most
size: flexible table conversion option.

Concatenate In Help & Manual 3 it was often necessary to split tables to control
similar tables: formatting properly. In PDF and printed manuals Help & Manual
now splits tables automatically at page boundaries and can also
automatically generate headers on each page so manual table
splitting is no longer necessary.
This option can identify similar tables in your topics and
automatically join them together to create a single table that is
more easy to handle.

Tolerance for Defines how closely matched the columns of tables have to be to
column width be combined with the Concatenate function. Two tables will only
differences: be combined if all the widths of all their columns are within this
tolerance.
Increase this value if your tables contain manually-adjusted
column widths with slight variances.

Try to recognize If this is selected the Converter will attempt to identify styles
styles and format applied to the text in your .hm3 project. It will create new style
converted text definitions for these styles and apply them to paragraphs
with styles: formatted with these styles in the old project.
Please note that this process cannot be perfect because style
names in Help & Manual 3 projects did not have a very close
association with text and paragraphs. All the formatting of your
text will be converted correctly but you may find that some
paragraphs are associated with the Normal style instead of a
newly-defined style matching the old formatting.

Invisible topics from old Help & Manual projects

If your old HMX or HM3 project contains "invisible topics" they will be moved to a sub-
folder called Topics\Invisible in the Topic Files section in the Project Explorer.

© 1997 - 2009 by EC Software, all rights reserved

554 Help & Manual 5 - User Help

Automatic Converter:

When you use the automatic converter a folder called

(Former Invisible Topics) will also be created at the
bottom of the converted project's Table of Contents
(TOC) section.
These TOC entries are linked to the topic files of the
former invisible topics but they will still not be included in
your published output because their include options are
automatically set to "None".

You can delete the (Former

Invisible Topics) folder by
selecting it and pressing
DELETE. Before confirming,
deselect the option Also delete
referred topic files to keep the
actual topic files.

External Converter:
When you use the external converter program you can decide what you want to do with
your old invisible topics:

Add invisible topics to TOC creates the (Former Invisible Topics) folder described
above.
Keep organization structure creates sub-folders in the Topic Files section to match
your folder structure in your old project. You can create a maximum of 10 levels but the
converter will not create more levels than the original project contained.

© 1997 - 2009 by EC Software, all rights reserved

 Tools included with Help & Manual 555

About converting Help & Manual 4 projects

Help & Manual 4 .hmx projects are converted 1:1 without any restrictions or limitations. All
version 4 features are supported in the current version of Help & Manual you will not
see any formatting or functional changes.

About converting Help & Manual 3 projects

Help & Manual 3 did not have dynamic styles and its table formatting options were quite
limited. In addition to this the code of the HTML templates used for HTML-based output
formats has changed considerably and if you have made any additions of your own you
will have to add them again manually after converting.
Styles:
If you select Convert Styles in the options (see below 550 ) the Project Converter will try to
identify the styles used in your HM3 project and replace them with dynamic styles. This is
only possible with text explicitly formatted with styles in the HM3 project – the formatting
of manually-formatted text will be converted but it will not be associated with a defined
style.
If the style of a paragraph cannot be identified uniquely it will be assigned the Normal
style. Its text formatting will converted correctly but it will be applied manually. The result
will be a paragraph with the Normal style containing manually-formatted text.
Tables:
Tables in Help & Manual 3 were fixed-width only and they were often split into multiple
tables to handle page break problems in PDF and printed manuals. The Project
Converter has options for dealing with both of these issues (see below 550 ) but because of
the differences between the two table formats you may need to make some manual
corrections to your tables after importing.
Customized HTML templates:
The HTML templates 427 have changed considerably since version 3, so it is not possible
to transfer custom code from your .hm3 projects when they are imported – the risk of
mangling the resulting code would be too great.
If you have entered custom code in your templates you will need to re-enter it manually in
the templates of your project after conversion.

See also:
Creating Projects 83
Importing Data 99
Text Formatting and Styles 155
Dynamic Styles 711
Working with Tables 253

© 1997 - 2009 by EC Software, all rights reserved

 556 Help & Manual 5 - User Help

8.8 The Project Synchronization Tool

The Project Synchronization Tool is used to update translated versions of your projects,
identifying new and changed topics so that the translator can translate the new material. The
tool compares the latest original version of your project with the last translated version and
updates the translated version. It inserts new topics, moves moved topics, deletes deleted
topics and identifies topics with changes. All new and changed topics are highlighted and the
complete new version of the topic content is inserted above the old translated version.
The Project Synchronization Tool is only available in the Professional version of Help &
Manual.

8.8.1 About Project Synchronization

Project synchronization helps you produce and maintain translated versions of your projects.
Producing the initial translation is easy – you just make a "sibling copy" of your original
project with Project Synch and give it to the translator, who translates all the text in the
project into a different language, using either Help & Manual or an external tool like SDL
Trados or Nero Across that can edit the XML project files directly (Professional version of
H&M only).
The real job of Project Synch begins when you need to update your documentation. When
the new version of the original project is ready you use Project Synch to compare the new
version of the original with the last translated version of the project delivered by the
translator.
The old translated version is then updated: New versions of modified topics are inserted for
translation, completely new topics are inserted, deleted topics are removed, stylesheets and
project properties are updated and so on.
You then send the updated version to the translator, who translates the changes and new
content and returns it to you.

What project synchronization does and does not do:

Project synchronization compares differences in project structure, not in topic content.
This makes it possible to compare two projects written in completely different languages
the original version and the translated version – and to update the structural changes in
the translated version.
Project Synch is not a "track changes" or "compare by content" function.
It does not show you where changed text is in individual topics or what specific changes
each topic contains. It only tracks which topics have changed and updates the project
structure to the latest version.
It just shows you that topics contain changes. These changes can be topic content,
keywords, settings in the topic's tab or changes in the topic caption in the TOC.
Project Synch is not suitable for monitoring ongoing changes in two projects.
Project Synch assumes that nothing in the translated version is ever changed
independently. It only checks for changes in the original version and updates the
structure of the translation version to reflect those changes.

© 1997 - 2009 by EC Software, all rights reserved

 Tools included with Help & Manual 557

If independent structural changes (new topics, moved topics etc.) are made in
the translated version Project Synch will eliminate them!
It is extremely important to understand this. The translator is not permitted to make any
structural changes to the project! They must just produce a 1:1 translation of the project
structure as you deliver it to them.
Because of this you shouldn't try to use Project Synch to compare and synchronize
ongoing changes made in two different versions of the same project in the same
language. If you do, all the changes in the target version (equivalent to the translation
version) will be eliminated when you synchronize!

How changes are synchronized:

The original project and the translated project are linked as a "translation pair" which we
refer to as "siblings". When you compare the two Project Synch can then identify all items
in the original project that have changed since a specified date. This is achieved with
internal ID codes and timestamps that are assigned to the entire project, topics and other
elements of your project.
· New topics: These are inserted in the translated version in the correct positions so that
they can be translated. They are highlighted in the TOC.
· Changed topics: These are highlighted in the translated version. The complete new
version of the content of the changed topic is inserted in the translated version. This
can either replace the old translated text or be inserted above the old translated text.
· Deleted topics: These are removed from the TOC of the translated version.
· Moved topics: If their content has not changed they are simply moved to their new
positions in the translated project. They are not highlighted in the TOC unless their
content is also changed.
· Topics with changed : Project Synch treats these as changed topics and also
highlights them in the TOC.

See also:
Identifying changes 563
Interim updates 564
Problems and troubleshooting 565
8.8.2 Synchronization Steps
8.8.2.1 Step 1: Create a translation sibling

The first step of using Project Synch is creating a copy of your original project for the
translator to translate. If you want you can do this in Windows Explorer or any other file
manager. However, if you do this you must then link the two projects as a "language pair"
manually later. It is easier to use Project Synch to create a "sibling", then the two projects
are "paired" automatically.

Project format:
If the project is going to be translated using an XML-based tool like SD Trados or Across
you must save the project and generate the sibling in uncompressed XML format. This
format is only supported by the Professional version of Help & Manual.

© 1997 - 2009 by EC Software, all rights reserved

558 Help & Manual 5 - User Help

The compressed single-file .hmxz format can only be translated using Help & Manual as
the translation editor. Project Synch is also not available in the Standard version of Help
& Manual, the tool is only included with the Professional version.

Synchronizing existing translations:

You can also synchronize projects that have already been translated without using the
Project Synch function. However there are a few points you need to bear in mind when
doing this. Please see the Problems and Troubleshooting 565 topic for details.

1: Save the project and create the new sibling

Before you perform this step you should be as certain as possible that your original
project is finished and will not be changed again while the translator is working. You can
synchronize more changes 564 later if necessary but it will make the process more
complicated.
1. Save your original project. It doesn't hurt to use this as an opportunity create a backup
in a safe place as well! From now on this project will be referred to as the Master.
2. Select Tools > Synchronize... and select the New tab in the dialog displayed.

3. Select the language and character set of your target project (see International
languages setup 94 for details) and choose a file name and the location where you
want to save it. By default Help & Manual will suggest a project name with the
language code of the new language added to the old project name you can change
this to something more descriptive if you like. The select OK to save the new sibling.
The sibling will automatically be saved in the format of the current project: .hmxz for
single-file projects, .hmxp for uncompressed XML projects (H&M Pro only).

2: Send the sibling to the translator

Now all you need to do is pack the new project folder and all its contents in a ZIP file and
send it to the translator for translation. Before doing so you should check that you have
included everything the translator will need.

© 1997 - 2009 by EC Software, all rights reserved

 Tools included with Help & Manual 559

Graphics files:
Make sure that all the graphics files used in your project are included. It is best to put all
the graphics files in one or more folders inside the project folder.
Snippets files:
If you are using linked snippets 149 from other locations you may need to include copies of
the snippet files for the translator. It is best to put all the snippet files in one or more
folders inside the project folder.
Project Search Path:
Update the Project Search Path 656 if necessary, adding entries at the top of the list for
any folders you have added to the project folder for the snippets and graphics files. Then
everything will display correctly when the translator opens the project from the folder
relative paths are used in the Project Search Path, so if the additional folders are inside
the folder containing the project file the paths will be "portable".
It's also a good idea to compile the translation copy once before sending it off to make
sure that it's working correctly then you won't have to waste time answering questions
from the translator.
Make sure that the translator reads and understands the translation guidelines 559
before starting work!

8.8.2.2 Step 2: Translate the original project

In this step the translator just works through his or her copy of the project in Help & Manual
or their translation tool and translates it into the target language. There is nothing special
about this, but the translator must observe the guidelines listed below.
Once the translation is finished it can be compiled and distributed with the translated version
of your application. This is the end of this step of the process. The real work comes when
you need to synchronize and the next version of the help and translate the changes.

Guidelines for the translator

The translator's job is only to translate. Making any structural changes to the project is
strictly forbidden for the translator! For example, if the translator adds, moves or deletes
topics these changes will be deleted the next time the language pair is synchronized!
Configuration: Check and translate all the texts used in Title & Copyright, Text
Variables (see below), HTML Page Templates (the translator may
need information from you here), Help Windows (window titles but not
window names) and any text fields used in the relevant publishing
options sections (HTML Help, Winhelp, PDF etc).
: Never under any circumstances make any changes to anything in the
tab except the Keywords. Everything else in this tab is off limits for the
translator!
The TOC: Only translate the captions. No other changes here are permitted. In
particular, never make any changes to the structure of the TOC. Do not
move or delete topics.
When working in Help & Manual always translate the TOC captions

© 1997 - 2009 by EC Software, all rights reserved

 560 Help & Manual 5 - User Help

before translating the topic header above the topic text. The header is
normally linked to the caption and will only need to be translated if it is
different. Translating the header first would break this link.
Topic Headers: Only translate topic headers if they do not get translated automatically
when you translate the TOC captions. (This is only the case if the
header and the caption are different.)
Topic Text: Translate everything here that is not protected (shaded text, cannot be
edited without unprotecting). Be careful not to delete any hyperlinks and
only translate the captions of hyperlinks, not their targets, which are the
untranslatable topic IDs and anchor IDs.
Text Variables: If the text contains variables go to Configuration > Common
Properties > Text Variables and translate their definitions. Do not
translate the variable names!
Hyperlinks: Only translate the captions of hyperlinks. Do not make any changes to
the links themselves or their targets.
Keywords / Only translate the keywords in the Keywords: editing box in the tab.
Index: Use the Index Tool in the Project tab to help you find the other topics
where the same keywords are used.
Do not translate the A-Keywords. These are never visible to the user
and should remain in the original language because they are used in
special links that must reference the original keyword names!

8.8.2.3 Step 3: Update the original project

This step must be performed on the original project file used to create the translation sibling
in Step 1. Only this file will have the correct Project GUID 556 that can be used for
synchronization in the next step.
That is all you need to know about this step. Simply work on your project normally, making
any necessary changes, deletions and additions. There are no restrictions on the changes
you can make.

Mark the changes with comments while you are working!

To make the translator's work easier use the comments and bookmarks 143 features to
identify the text that has been changed. You can write comments to explain where the
changes are, particularly if they are only in the – otherwise the translator may waste a lot
of time trying to find changes in the text that are not there!

8.8.2.4 Step 4: Synchronize the new version

This step is where the real work of the Project Synch function comes in. Now you want to
synchronize the new version of the original help with the translation of the original version.
The result will be an updated translation version in which all the topics containing changes
are marked, with the new versions of the updated topic contents inserted for translation.
For this step you need the updated version of the original project edited in Step 3 and the
original translation delivered by the translator in Step 2.

© 1997 - 2009 by EC Software, all rights reserved

 Tools included with Help & Manual 561

Key Information
The Synch procedure has reversed since
Help & Manual 4! Now you open the
Master (original) project and synchronize
with the old translation.

Synchronize the old translation with the updated original

The synchronization is performed by opening the latest version of the original project then
selecting the old translated version to be updated.
1. Open the updated original project in Help & Manual.
2. Select Tools > Synchronize and select the Compare tab. Then select the old
translated project in the Select OLD sibling... field:

3. Select your synchronization options. Recommended settings:

· Keep old and new text in TOC and topics
· Highlight changed topics
DON'T select Compare TOC by Topic ID when you are comparing a sibling! This is a
special setting for comparing existing translations 565 that are not siblings.
4. Click on OK to update the translated version.
This will update the old translated project with the changes in the new version of the
original. After the conversion you can check the updated translation to make sure that
everything has gone OK and then send it to the translator so that they can translate the
changes and the new material.
Before the translator starts work make sure that he or she has studied the instructions
for identifying changes 562 and the original translation guidelines 559 .

Project synchronization settings

Keep old and Selecting this will insert the complete new version of topics
new text in containing changes above the old translated version. The old and

© 1997 - 2009 by EC Software, all rights reserved

 562 Help & Manual 5 - User Help

TOC and new versions will be separated by a header saying -----OLD

topics: TEXT-----.
The same procedure is used for the TOC captions, the headers and
the keywords in the tab.
This is the best mode for normal synchronization.

Simply The content of changed topics, headers, topic captions etc. will be
overwrite with completely overwritten with the new versions in the original
new content: language.
The translator must then use a copy of the original version of the
translation for comparison.

Do not This option only highlights changed topics in the TOC and does
overwrite, just overwrite the translated version or insert a new version.
flag changes:
The translator must then use a copy of the new version of the original
to obtain the new versions of the topics and their keywords etc.
Note that even when this option is selected the following changes will
still be updated:
· Context numbers
· Topic IDs
· Help window settings
· TOC structure (new, moved and deleted topics)

Highlight Selecting this identifies changed topics with colored highlights

changed ("Needs Review") in the TOC.
topics:
This should always be on. If you turn it off it will be very difficult to
identify where changes are located.

Compare TOC WARNING: Do not use this option for synchronizing siblings!
by Topic ID:
This is a special setting for synchronizing two versions of a project
that were not created by making a sibling copy of the original. In
normal synch mode the Project Synch tool compares topics on the
basis of their hidden internal ID, which never changes this makes it
possible to compare topics even when their visible IDs have been
edited.
If you independently create two projects that have the same structure
and Topic IDs they will look identical but their invisible internal IDs
will not match. The first time you synch such projects you need to
use this option to compare by topic ID. After this the internal IDs will
by synchronized and the projects will then be siblings.

8.8.2.5 Step 5: Translate the changes

Synchronizing the new version of the original with the old translated version updates the
translated version with the changes that need to be made. You can then give the updated

© 1997 - 2009 by EC Software, all rights reserved

 Tools included with Help & Manual 563

translated version to the translator for review and translation of the changes.
The translator then needs to go through the project, locate the changes and translate them.
The actual translation work here is pretty much the same as the original translation, and the
same guidelines should be followed. The main problem is identifying where the changes
are.

See also:
Guidelines for translators 559
Identifying changes in the synch project 563
8.8.3 Identifying changes
Remember that Project Synch doesn't compare content, it only identifies changed, new and
deleted topics and updates the structure of the translation project to match the new version
of the original project.
If possible, you should thus always document and explain your changes with comments 143
while you are working on the new version of the original project.
This is particularly important if you only make changes in the tab, because then the
translator may waste a lot of time looking for changes in the text that are not there. It is also
very helpful for the translator if you systematically tag text changes with comments as well,
however.

How to identify changes in the synched project

New topics: New topics are inserted in the translation project in the
correct position in the TOC. If you have selected highlighting
in the synchronization options, every new topic in the TOC
will be highlighted with the Needs Review status, which will
be light green unless you have changed it.
In addition to this, the new topic will not be in the same
language as the translated version, of course.
Deleted topics: Deleted topics are simply removed from the project. They are
no longer there.
Changed topics: Changed topics are highlighted with the Needs Review
status in the TOC and the new version of the topic in the
original language is inserted above the old translated version
unless you have turned this off in the synch settings.
Remember that changes can be in the as well as in the topic
content!
Moved topics: Moved topics are simply moved to their new position in the
TOC. They are not highlighted as changed unless they
contain other changes in their text or .
Topic captions in the If topic captions have changed the new version of the caption
TOC: will be inserted and the old version will be enclosed between
<OLD> and </OLD> tags, like this:
Getting Started with Widget Confabulator

© 1997 - 2009 by EC Software, all rights reserved

 564 Help & Manual 5 - User Help

<OLD>Einführung</OLD>
In this example the author has edited the topic caption to
make it longer. You can see the old translated version
between the OLD tags – the original caption was probably
just Introduction.
When only the topic caption is changed no new text is
inserted in the topic body or header.
Keywords: When a topic is flagged as changed you should always also
check the Keywords in the tab, as this can also be the cause
for the change flag.
If you have selected Keep old and new text in the
synchronization options the old and new keywords are
separated by an --OLD KEYWORDS-- divider, with the new
keywords above.
Topic IDs and other : It is important to understand that changes in the can also
cause the topic to be flagged as changed, even if nothing
has actually changed in the topic text. So if you can't find any
changes in the text the change is probably in the .

See also:
Guidelines for translators 559
8.8.4 Interim updates
It happens: You thought your project was finished but after the translator has started work
on the new translation you discover that you need to make some more changes and/or
additions to the original project. Can the translator synchronize these changes into his/her
project, even though the actual translation is not yet finished?
This is possible because of the way Project Synch works. Instead of comparing the dates
and timestamps of the project files it synchronizes all changes made since the last
synchronization of the language pair. So even if the translator has worked on the changed
topics after the new changes have been made, the project will still be synchronized
correctly.

Synchronizing interim updates

Just open the updated original (even if the translation of the original changes is not yet
completely finished) and perform the project synchronization 560 step on the translated
version of the project again. You can do this even if the translator has already started
work on some of the changes added the first time you synchronized the two projects.
Always select the "Keep old and new text" option in the synchronization options!
If you select Simply overwrite with new content the work that the translator has done in
the meantime may be lost!

See also:
Project synchronization settings 560
Identifying changes 563

© 1997 - 2009 by EC Software, all rights reserved

 Tools included with Help & Manual 565

8.8.5 Synching existing projects

You may already have versions of your project in different languages. The question is, can
you synchronize these projects? The answer is yes as long as the structure and topic IDs
are identical if they are then Project Synch has a special function that will turn the two
projects into siblings.

About matching project siblings:

Projects are synchronized using the hidden internal numerical IDs of your topics and the
topic captions in the Table of Contents (TOC). Each topic and each topic caption has a
unique internal numerical ID that is assigned when the topic is created and it is normally
never changed – not even if you change the Topic ID 801 . It is part of the topic forever,
until it is deleted. These IDs are not editable and not visible to the user.
Matching project siblings are projects with identical internal numerical IDs for all topics
and all TOC entries. Only matching project pairs can be synchronized directly with the
normal Project Synch settings.
In the case of a translated version this is only the case if you created the translated
version by making a copy of the original project and then translated its text. If you built
the translated version from scratch the internal numerical IDs may not match and you will
have a problem. You can correct this with the Compare by Topic ID option.

Synchronizing existing projects that are not matching siblings

If the internal IDs of your projects do not match you need to use the Compare by Topic ID
option the first time you compare. Project Synch will then synchronize the internal
numerical IDs of the two projects. After this you can synchronize the projects normally.
1. Make absolutely sure that the structure and topic IDs of the two versions of your
project match. Then save both projects in the same format (single-file compressed or
uncompressed XML) and open the original version.
2. Select Synchronize in Project > Tools and click on the Compare tab.
3. Choose the translated project in the Select OLD sibling... field, then activate the
Compare TOC by Topic ID option. You will be warned that this is only for special
purposes.
4. Set your other options and synchronize the two projects.
You only need to do this once. After this the internal numerical IDs are synchronized and
the two projects are real siblings that can be synchronized normally.

See also:
Problems and troubleshooting 565
8.8.6 Problems and troubleshooting
If you work within its capabilities, remembering that it cannot be used to highlight changes in
topic text, Project Synch will work very reliably. However, you may still encounter some
problems in certain situations, particularly if you don't follow the instructions.

© 1997 - 2009 by EC Software, all rights reserved

566 Help & Manual 5 - User Help

Always create backups before synchronizing

Since project synch automatically modifies your translated version of the project you
should always create backups before synchronizing. This is simply good security policy,
and it is particularly important if you are synchronizing existing translations that were not
created with the help of project synch (see below). Then you can re-insert text from the
backup to

Comparisons with changes in both projects

Structural changes made in the translated version will be deleted!
Please always remember that this function is only for updating translated versions to
reflect changes made in the original project. It is assumed that the translator does not
make any structural changes to the project. If the translator makes structural changes like
adding new topics, moving or deleting topics etc. these changes will be deleted when you
synchronize the translated project with the master!
Again: The translator is not allowed to make any structural changes to the project or to
alter anything in the Project Properties or (except translation of the keywords).
Translating the content is fine, but structural changes made by the translator will probably
be deleted during synchronization and may also cause problems!

Comparisons with existing translations

Can you compare an existing translation with the original master project?
You can do this even if the language pair was not created with the Project Synch tool,
provided that the structure and Topic IDs of the two project versions match precisely. If
this is the case you can use the Compare by Topic ID option to turn the two projects into
real siblings that can be synchronized normally.
For full details see Synching existing projects 565 .

See also:
Synching existing projects 565
Translation guidelines 559

© 1997 - 2009 by EC Software, all rights reserved

Part

IX
 568 Help & Manual 5 - User Help

9 Reference
This section contains documentation of all Help & Manual's menu options and the
associated dialogs (in Menus and Dialogs 573 ).
The other sections in Reference contain more detailed background information on a number
of key subjects that will help you to gain a better understanding of how Help & Manual
works. Studying these sections is not absolutely essential but it will make it much easier for
you to use Help & Manual efficiently and effectively.
There are extensive cross-references and links to the Procedures sections so that you can
always find the instructions you need to show you how to do what is being described in the
reference topics.

9.1 FAQ for HM4 Upgraders

The user interface of Help & Manual 5 is very different from that in version 4 and earlier. In
addition to this a number of changes have been made to the way the program works. The
list below will help upgraders to find their way around in the new version.
Even if you are an experienced Help & Manual user we recommend that you work through
the Introduction 16 and Quick Start Tutorials 41 chapters of the new help briefly before you
start working with the new version. This will help you to familiarize yourself with the new
features.

User Interface – Where is Everything?!

What's the Project Explorer?
The Project Explorer is completely new and it allows you to access the contents of your
project just as you would browse the contents of your hard disk with Windows Explorer.
See the Introduction 16 and Quick Start Tutorials 41 sections for an introduction to the
Project Explorer.

Where are my Project Properties?

All the settings that used to be located in Project Properties are now accessed in the
Configuration 652 section in the Project Explorer.

Where's the File menu?

The File menu has now been replaced by the Application Button, which opens the
Application Menu. Look for all your basic file, input and output functions here.
Remember its name, this is one of the most important controls in the new interface and
it is referred to constantly in the help.

The Quick Access Toolbar next to the Application Button navigates in your editing
history like a browser and provides direct access to the most frequently-used functions.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 569

Configure it with the drop-down menu at its right-hand end.

See The User Interface 23 for more details.

Where is Tools > Customize?

This is now called Program Options 643 you can access it both in the Application Menu
and in the View tab.

Where are the Next/Previous project navigation buttons?

These are now in the Quick Access Toolbar next to the Application Button and they are
blue instead of green.

Where are all the other menus and the editor tabs?
The menus have been replaced by tabs. You will find your editing and text formatting
tools in the Write tab. The tools that used to be located in the Insert menu are also
located there.
The editor tabs are still there, they're now below the main editor window instead of
above it.

What happened to the Index tab behind the Table of Contents?

The Index tab has been replaced by the new Index Tool 275 , which you can access in
the Project menu.

Where is the Invisible Topics section?

This section no longer exists. Instead, you have the Table of Contents section with
all your TOC entries and the Project Files section where all your topic files are stored.
The TOC entries are only links to your topic files.
You can still create topics without TOC entries. To do this you just create a new topic in
the Topic Files section instead of in the Table of Contents section.

I can't find the "Compile" dialog!

We now refer to generating your output as "publishing". The old term "compile" is a
hangover from the time when Help & Manual only produced Winhelp and HTML Help
files, which are generated with the Microsoft help compilers. Help & Manual is now a
multi-format tool for technical writers and we felt that the term "publishing" was more
appropriate. We still refer to compiling occasionally, but only when we are really talking
about the Microsoft help compilers.

Where are my Baggage Files?

The Baggage Files 485 section is now located in Project Files > Baggage Files in the
Project Explorer.

How can I undock Help & Manual windows?

The mechanisms for undocking and redocking Help & Manual components have
changed. You can now undock and redock just by double-clicking on a window title bar.
You can't undock components of the Ribbon interface or the Editor window. However,

© 1997 - 2009 by EC Software, all rights reserved

570 Help & Manual 5 - User Help

you can change the position of the tab by dragging it. See Explorer Tips 46 for more
details.
You can also undock and redock windows by dragging them to the borders of the
Editor window – you can dock components to any side of the editor: top, bottom, left or
right.

I can't assign a help window in Topic Options!

Help windows are now only relevant for HTML Help (CHM) and Winhelp (HLP). It is no
longer possible or necessary to associate a help window definition with individual
topics. Help window definitions are now only used for defining the appearance and
behavior of the HTML Help and Winhelp help viewers and for displaying topics in
external windows with hyperlinks.
To configure the help viewers you just need to edit the definition of the Main help
window in Configuration > Common Properties > Help Windows.
Displaying topics in external windows is now achieved exclusively with hyperlinks. You
define an additional help window type and then select the help window type in the
Insert Hyperlink dialog when you create the hyperlink. It is no longer possible to define
a topic that automatically opens in an external window when it is selected in the TOC
(this never made sense anyway).

I can't find the settings for the background colors of the topic and header!
These are no longer defined by the help windows except for the obsolete Winhelp
format. Background colors for all HTML-based output formats are now defined in the
HTML page template which you can find in Configuration > HTML Topic Page
Templates.

What happened to the Repair and Recover tool?

This is no longer needed in Help & Manual 5 because there is no longer any internal
database that needs to be reorganized. If you save in the uncompressed XML format
everything is saved in plain-text files and there is nothing hidden that needs to be
repaired. The single-file HMXZ format is really just a ZIP archive and if it ever needs
repair you can fix it with any of a large number of ZIP repair and recovery tools just
change the file extension to .zip to perform the repair, then change it back to .hmxz to
be able to open it in Help & Manual.

New and Different – Major Changes

New terminology: Publishing and Webhelp
What used to be referred to as "compiling" is now known generically as "publishing".
This is more accurate because not all output formats are really run through compilers.
We still sometimes talk about compiling when referring specifically to the Microsoft help
compilers.
"Browser-based Help" is now known as "Webhelp", which as established itself as the
standard term for help viewed in a normal web browser. The old term was always a bit
of a mouthful and it was annoying to have to write the entire term whenever we wanted
to discuss it.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 571

Two save formats – single-file compressed and uncompressed XML

If you have the Professional version you can now save in two different formats: A
single-file compressed format with the extension .hmxz and an uncompressed XML
format that saves your project in a directory of uncompressed XML files with a project
file with the extension .hmxp.
The Standard version of Help & Manual can only read and write the single-file
compressed format.
Uncompressed XML is required for multi-user editing.

New additional eBook Format: ePub

The ePub eBook format is an open, universal eBook standard that is rapidly being
adopted all over the world. It is supported by many software readers on all computer
platforms and a growing number of hardware devices, including the Sony Reader and
the Apple iPhone and iPod Touch.
Please check the eBook sections in Configuring Your Output and Help Formats before
getting started with ePub eBooks. You will also need to install the free Adobe Digital
Editions reader software so that you can display your ePub eBooks.

Multi-project editing / Multi-user editing

You can load and edit multiple projects in the new Project Explorer, which supports
Copy & Paste and Drag & Drop between projects. You can also display split views of
projects or parts of projects with Explore > Split Explorer in Project > Manage
Topics.
If you have the Professional version multiple users can work on the same project at the
same time. All users must be using the Professional version and the project must be
saved in the uncompressed XML (HMXP) format.

Table styles are now available

Table styles are available in Write > Styles > Edit Styles. To apply them to a table
click in the table and then select Properties in the Table tab. Table styles are
dynamic, just like text styles – updating the style automatically updates all the tables
formatted with the styles.

Embedded topics are now called snippets and can do more

Embedded topics are now called snippets and are much more powerful. In addition to
topics in the current project you can also insert snippets from external XML files and
topics in other projects (provided they are saved in uncompressed XML). You can save
both selected text and entire topics to snippet files to create libraries of reusable
content.
See Re-using content with snippets 149 for more information and instructions.

Child modules must be inserted separately for runtime merging

When you are working with modular projects you now set the merge method (runtime
or compile-time) separately for each child module. This means that you can mix
runtime and compile-time (now referred to as "publish-time") merging. In addition to

© 1997 - 2009 by EC Software, all rights reserved

572 Help & Manual 5 - User Help

this, child modules inserted in publish-time mode can be edited directly inside the
master project.
However, this also means that child modules inserted in runtime mode are only
exported to CHM and HLP because only these formats support runtime merging. If you
want to export the same modules to other formats you must now insert them a second
time and apply suitable build conditions to ensure that they are not exported when you
publish to CHM or HLP.
See Exporting runtime modules to other formats in Merge methods for CHM & HLP 451
for details on how to do this.

Help Windows are much less important

Help windows are now only relevant for HTML Help (CHM) and Winhelp (HLP). They
no longer define background colors for any format except the obsolete Winhelp.
Background colors for all other formats are defined in the HTML Page Templates 666
(these colors are also displayed in the editor).
It is no longer possible or necessary to associate a help window definition with
individual topics. Help window definitions are now only used for defining the
appearance and behavior of the HTML Help and Winhelp help viewers and for
displaying topics in external windows with hyperlinks.
To configure the help viewers you just need to edit the definition of the Main help
window in Configuration > Common Properties > Help Windows.
Displaying topics in external windows is now achieved exclusively with hyperlinks. You
define an additional help window type and then select the help window type in the
Insert Hyperlink dialog when you create the hyperlink. It is no longer possible to define
a topic that automatically opens in an external window when it is selected in the TOC
(this never made sense anyway).

External windows in CHM and HLP are handled differently

Displaying topics in external windows is now achieved exclusively with hyperlinks. You
define an additional help window type and then select the help window type in the
Insert Hyperlink dialog when you create the hyperlink. It is no longer possible to define
a topic that automatically opens in an external window when it is selected in the TOC
(this never made sense anyway).

HTML page templates are defined separately

HTML page templates are now defined separately in the Project Explorer, in
Configuration > HTML Page Templates. They can be assigned to topics when you
create new topics and in .
Background colors for topics and headers are now defined in the HTML page
templates and displayed in the Help & Manual editor. The only exception is the
obsolete Winhelp format – the background colors for Winhelp are still set in the help
window definition in Configuration > Common Properties > Help Windows.

Project Synch works in the opposite direction

In the new Project Synchronizer tool you open the updated original project and then
select Synchronize in the Project tab to perform the conversion.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 573

Popups are now defined with the new "Topic Class" attribute
Popup topics are now defined with the Topic Class attribute in or when you are creating
the topic file. Popup topics can only be created in the Topic Files section of the Project
Explorer.
You cannot create a popup topic in the Table of Contents section and you cannot
switch the Topic Class to Popup in the Table of Contents section. (The Topic Class
attribute is currently only used for popups but it may be used for other new features in
later updates.)

Bookmarks and comments are now separate

In Help & Manual 4 bookmarks and comments were the same thing. In Help & Manual
5 they are now two separate functions.
Bookmarks are set and used with the Bookmark tool in the Project tab. You can only
set one bookmark per topic and they always link to the top of the topic. They are also
managed and accessed with the Bookmark tool. Bookmarked topics are identified in
the TOC by red "pin" icons.
Comments are inserted with the Comment tool in Write > Insert Object. You can
insert multiple comments in a topic but you cannot jump to comments like bookmarks.

Create sections and use external files in the Manual Designer

The print manual designer for PDF templates has been updated with some major new
functions:
· You can now create your own sections for additional pages. Just select Insert Page
in the new Pages menu. You can also move your custom pages around in the
manual template with the tools in this menu (the standard pages are fixed).
· You can insert topics from your current project and external Help & Manual XML
topic and snippet files into your template pages with the new Snippet tool.

9.2 Ribbon Tabs and Dialogs

This section provides a reference to the individual controls in the dialogs accessed in the
Ribbon Toolbar.

Only dialogs that need explaining are documented

Please note that although this reference is quite complete, only dialogs that really need
explaining are documented. For example, we assume that you can figure out what menu
entries like Save and Save As do for yourself.
This also applies to simple dialogs whose functions are explained elsewhere. Some of
these dialogs are listed, but only with references to the relevant topics in the Procedures
sections.

You can create keyboard shortcuts for most Ribbon tools

Most of the tools in the Ribbon can also be accessed with keyboard shortcuts. To view,
assign and change your keyboard shortcuts select Customize in the View tab.

© 1997 - 2009 by EC Software, all rights reserved

 574 Help & Manual 5 - User Help

9.2.1 The Workspace

The Help & Manual workspace has four main components: The Application Menu at the top
of the screen, the Ribbon Toolbar where you access all program functions, the Project
Explorer for navigating and managing your projects and the Editor where you edit the
content of your projects.

The Application Menu and Quick Access Toolbar

The Application Button in the top left corner of the Help & Manual window is one of the
most important controls. It provides access to the functions normally accessed in the File
menu in menu-based programs. This is where you open existing projects, create new
projects, publish and print your projects, save your projects under other names and so
on.
The Quick Access Toolbar next to the Application Button is a place for your most
frequently-used tools. It is fully configurable just click on the drop-down icon to the right
of it to add or remove functions.
By default the QAT includes the New, Open and Save tools and also the Back and
Forward tools that navigate through the topic files and other Project Explorer items you
have visited in your current editing session.

The Ribbon Toolbar

The Ribbon Toolbar is the control center where you access virtually all of Help & Manual's
functions. If you use Microsoft Office 2007 you will already be familiar with the Ribbon
interface. It is context-sensitive, automatically displaying functions relevant to what you
are currently doing.
Tip: The Ribbon can also be operated almost entirely via the keyboard. To display the
accelerator keys just press and release the ALT key once the keys will be displayed in
icons superimposed on the Ribbon.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 575

The Project Explorer and Editor

The Project Explorer is like Windows Explorer for Help & Manual projects. When you
load or create a project all its contents are displayed here, including both the topic files it
contains and all the settings and configuration options. You can load multiple projects in
the Project Explorer and copy and paste between them.
The Editor is where you edit your topic content, and project settings dialogs. To edit a
topic you just select the topic in the Project Explorer and start editing in the Editor, which
works very much like a normal word processor. To edit project settings you just select the
settings in the Configuration section of the Project Explorer.

See also:
The User Interface 23
Using the Project Explorer 41
Editing Topics 58
9.2.1.1 Print Manual

This dialog is used for generating a printed user manual from your project. In addition to
normal printing it also supports booklet printing with multiple pages per sheet and fold/cut
options.
The dialog consists of two screens.

© 1997 - 2009 by EC Software, all rights reserved

576 Help & Manual 5 - User Help

Print options

Printer: The printer you want to use.

Print Manual The Print Manual function uses the same templates 425 as the PDF
Template: output function. Select to choose an .mnl print manual template file
and Design... to open the selected template in the Print Manual
Designer. (This program has its own separate help.)

Colored text: Options for controlling how colored text and hyperlinks are to be
displayed in your output. Set accordingly for monochrome or color
printers.

Page Prints hyperlinks with "page referrers" – little icons showing the page
referrers: number of the referenced topic.

Include These options can be used in combination with Help & Manual's
Options: conditional output features. Topics and content that don't match the
selections you make here will be excluded from your output. Please
study Conditions and Customized Output 399 before using!
If no options are selected the Include Options list is highlighted in red
to indicate that no output will be generated.
Current format:
By default the include option for the selected output format is
preselected. If you also select other options you must leave the current
format option selected, otherwise content tagged for the current format
will be excluded!

Selected Selecting this special option in the Include Options only outputs the
Topics: topics currently selected in the TOC. This function is designed for
testing only. Links to excluded topics are converted to plain text. The
Include Options section is highlighted in yellow as a warning.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 577

Print options screen 2:

Print Style: Options for normal or booklet printing. Select Normal (1:1) for best
quality in normal printouts.

Print cut Prints professional printer-style cut marks for trimming your output.
marks:

Page Range: Options for printing only individual pages or a range of pages.
Select page numbers:
Enter the numbers of the pages you want to print separated by
commas (example: 12,42,49).
Note that all page range numbers refer to the sequential numbers of
the sheets of paper in your output, not to the numbers shown on the
pages, which may be different. Use Print Preview 577 to check the
numbers of the pages to output.

From Print all pages, only odd pages or only even pages. Use for printing on
selected both sides of the paper on printers without duplex printing (both sides of
range, print: the sheet).

See also:
Print Preview 577
Conditions and Customized Output 399
9.2.1.2 Print Preview

The Print Preview function previews your printout on the computer screen. The options are
exactly the same as in the first screen of the normal Print Dialog. 575 Print Preview is
extremely fast, you can use it for a quick preview of your project layout.
For more details please see Print Manual 575 (Screen 1 options only).

© 1997 - 2009 by EC Software, all rights reserved

 578 Help & Manual 5 - User Help

The Print Preview dialog:

Unsupported functions:
· Selection by page number and booklet printing options are not supported in Print
Preview mode. Selected Topics in the Include Options section works, however.
· Page numbers are not displayed in the page referrers in Print Preview mode. The page
referrer icons are shown, but they are empty. This is not an error. The referrer numbers
can only be generated when you actually output to a printer.

See also:
Print User Manual 575
9.2.1.3 Version Control System

This entry in the Application Menu is only shown in the Professional version of Help &
Manual and if access to a version control system (VCS) database is installed on your
system. Currently only Microsoft Visual SourceSafe and 100% clones are supported. If you
are not using Visual SourceSafe your VCS must support the Microsoft SCCAPI 1.1, 1.2 or
1.3 with an implementation that matches Visual SourceSafe in every detail.
For full details please see Using Version Control Systems 335 .

Version Control System Options

Connect local project to VCS Uploads a copy of the current project to your VCS
database and links the database version to your local
version. The current project thus becomes the local
working copy for the new VCS project. Topics you work
on will be checked out of the VCS database and locked
for other users automatically. They are checked back in
when you save and move on to another topic.
If additional users want to work on the project they must
use Load VCS project to local system to download a

© 1997 - 2009 by EC Software, all rights reserved

 Reference 579

local copy to their own computers.

Load VCS project to local Downloads a copy of a Help & Manual project stored in a
system VCS database to your local computer and links the two.
When you open your local copy it will be automatically
updated with any changes made on the VCS version by
other users. When you work on topics they will be
automatically checked out of the VCS database and
locked for other users until you save and move on to
another topic.
Save as VCS project This is used for single-file HMXZ projects. It first saves
the project as in uncompressed XML format (required for
version control and multi-user editing), then it uploads a
copy to the VCS database and links the two.
The second step is exactly the same as Connect local
project to VCS.

See also:
Using Version Control Systems 335
9.2.2 The Project Tab
This tab contains all the tools used for managing topic files and managing and publishing
projects. In addition to this it includes a copy of the clipboard tools available in the Write tab
and links to the external tools external tools included with Help & Manual.
Note that the standard file functions (Open, Close, New etc.) are accessed in the Application
Menu 574 .

See also:
Publishing Your Projects 311
9.2.2.1 Clipboard

The Clipboard group contains a standard set of tools for using the Windows clipboard
(Copy, Cut, Paste, Paste as Text). You can use the clipboard tools for copying both content
in topics and for topics and chapters in the Project Explorer.
Remember that Drag & Drop also work both in the editor and in the Project Explorer, also
between different projects.

What Paste as Text does:

· Paste as Text or Ctrl+Shift+V pastes copied text as plain text, without any formatting
(bold, underline, graphics etc).
· Use if you want to copy text without any formatting from other topics, projects or other
programs such as MS Word or a web browser.
· This feature is also useful for pasting text into paragraphs formatted with styles without
transferring the style of the copied text into the target paragraph.

© 1997 - 2009 by EC Software, all rights reserved

 580 Help & Manual 5 - User Help

See also:
Copying, cutting and pasting text 139
Moving cutting and pasting topics 199
9.2.2.2 Manage Topics

The Manage Topics group contains all the main functions for creating topics and
manipulating them in the Table of Contents (TOC) and Project Files sections of the Project
Explorer.
Several of the options in this menu already have keyboard shortcuts. You can assign
shortcuts to the other options yourself in Tools > Customize > Shortcuts.

Topic group options:

Add Topic / Add Name changes depending on whether you are in the TOC or
File: 581 Project Files.
· Create new topics, chapters and topic files.
· Delete topics, chapters and topic files
Explore · Expand and collapse branches in the Project Explorer
· Filter Explorer display by build options
· "Split" the Explorer to display topics and branches in a separate
window.
Change: · Set build options for topics and chapters
· Change the item status (colored highlight in the TOC)
· Change the icon displayed for the item (not supported in all output
formats)
· Edit the item caption

Find: · Locate topics by ID and help context numbers

· Locate topics containing links to the current topic
File: · Convert a topic to a chapter without text and vice-versa
· Load topics from external XML file, and from RTF, RVF, HTML
and TXT files
· Save topics as XML files or reusable snippets 149 (text blocks in
external files).
· Move selected topics around in the TOC (up/down)
· Promote and demote topics in the TOC (left/right)
· Edit topic caption
· Print topic

See also:
Creating and Editing Topics 108
Managing the TOC and Topic Files 199
Options & Keyboard Shortcuts 31

© 1997 - 2009 by EC Software, all rights reserved

 Reference 581

9.2.2.2.1 Add Topic/File

Creates a new topic file in the Table of Contents (TOC) or the Project Files section. See
Creating new topics 110 .for more details.

Insert New Topic or Chapter dialog:

This dialog is displayed when you select one of Add Topic options. It creates a new topic,
a new chapter or a TOC item linked to web page or another help file.

Topic /Chapter:
Creates a new topic with a TOC entry (in the TOC) or a new topic file without a TOC
entry (in Project Files). The topic automatically becomes a "chapter" as soon as it has
sub-topics.
When you select the function in the Project Files section you can only add topic files, no
other options are available.
Position: Position of the new topic in the TOC relative to the current topic.

Topic The title of the topic in the TOC. This text is also entered as the topic
heading: header (in the box above the editor).

Topic ID: This is the "address" of the topic. It is never seen by the user and must
be unique. Use only English ASCII characters and numbers. Foreign
characters, spaces and special characters will cause problems in some
output formats.

HTML The HTML page template 123 to be linked to the topic. This will usually
template: be Default unless you have created additional templates.

Topic Class: Whether the topic is a normal topic or a popup topic. You can only
select the Popup class in the Topic Files section of the Project
Explorer. You cannot create popup topics in the Table of Contents

© 1997 - 2009 by EC Software, all rights reserved

582 Help & Manual 5 - User Help

section.

Create in : The folder in the Project Files section where you want to store the new
topic file.

Topic Normally new topics are empty. If you wish, you can specify a template
template: file 423 here containing standard text, tables, images and any other
content. You must create template files first, otherwise nothing will be
displayed here.

Chapter without text:

This creates a "chapter" node in the TOC only. There is no topic file and when the user
clicks on it nothing is displayed.
Winhelp restriction:
Note that chapters with text are not supported in Winhelp. If you create a chapter with
text in Winhelp its contents will be copied to a sub-topic with the same name as the
chapter.
Position: Position of the chapter node in the TOC relative to the current topic.

Chapter The title of the chapter in the TOC.

heading:

Multiple topics:
Allows you to enter multiple topics at the same time, for example by pasting a list of topic
titles that you want to use as captions. Each line of text entered in the Item Captions: field
will create a new topic with that text as the caption in the TOC. The topic IDs 205 are
generated automatically from the caption texts.
Position: Position of the first new topic in the TOC relative to the current topic.

Headings: Each line of text you enter here creates a new topic.
Press Enter to create a new topic line.
Press Tab or use the indent buttons on the right to create sub-topics.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 583

Create In: The folder in the Project Files section where you want to store the new
topic file.

Topic Normally new topics are empty. If you wish, you can specify a template
Template: file 423 here containing standard text, tables, images and any other
content.

Link to External Help:

Instead of creating a new topic file this creates a TOC item that is a link to a topic in
another help file. When the user clicks on the TOC entry the topic from the other help file
is displayed.
This only works in HTML Help and Winhelp!
The target topic must be the same format as the main help file you can't link between
HTML Help and Winhelp files.
Position: Position of the chapter node in the TOC relative to the current topic.

Heading in The title of the item in the TOC.

Table of
Contents:

Help file: The Help & Manual project file (.hmxp, .hmxz) or the help file (.chm, .
hlp) containing the topic you want to link to.

Target topic: The topic you want to link to.

Web Link:
Creates a topic that references a web page on the Internet:

© 1997 - 2009 by EC Software, all rights reserved

584 Help & Manual 5 - User Help

· In Winhelp and eBooks selecting the topic in the TOC opens the referenced web
page in an external browser window.
· In HTML Help and Webhelp selecting the topic the page can be opened inside the
help viewer, as part of the help, or in an external window.
· In PDF and Word RTF the topic is ignored and is not included in the output.
Position: Position of the item in the TOC relative to the current topic.

Heading: The title of the item in the TOC.

Target The URL of the HTML page you want to link to. If this is not a local file
address: you must enter the fully-qualified URL, including the http:// prefix.

Include Help Project:

Inserts a placeholder for another Help & Manual project, turning the current project into a
master/parent project. When you compile the master project the TOC of the child project
will be added to that of the master project.
Position: Position of the first topic of the external project in the TOC relative to
the current topic.

Project file: The the .hmxp or .hmxz project file that you want to include

Merge These settings are only relevant for HTML Help (CHM) and Winhelp
content on (HLP) output. All other formats are always merged when they are
publishing / compiled.
runtime:
For more details see Working with Modular Help Systems 446 .
Merge content on publishing:
This merges the selected project with the project you are inserting it.
The result is one large CHM or HLP file. You do not have to compile
your child projects separately when you use this method. However, you
must take steps 456 to ensure that you do not have duplicate topic IDs
and help context numbers in your projects, otherwise you will
experience unexpected errors in your help.
Merge content at runtime:
This merges the child help file modules into the TOC of the master
when the help is opened on the user's computer. The child help files
must be published separately. If these help file modules (CHM or HLP)
are present in the same folder as the master help file their TOCs will be
merged with the master TOC and the effect is the same as one help
file containing all modules. If the modules are not present on the user's
computer they will not be included in the TOC.

See also:
Creating new topics 110

© 1997 - 2009 by EC Software, all rights reserved

 Reference 585

Content templates for topics 423

9.2.2.2.2 Explore

This sub-menu contains options that control the behavior of the Project Explorer.

Expand / Collapse
These options expand and collapse the Table of Contents and Topic Files display in the
Project Explorer.

Filter
This allows you to filter the Table of Contents display on the basis of your build options/
include options. It will only have any effect if you have actually assigned build options to
your topics. See Conditions and Customized Output 399 for more details.
Note that this function only filters topics in the TOC, it does not filter content in your topics
tagged with build options using the Conditional Text tool.

Disable Drag & Drop in Explorer

This protects your TOC against accidental changes with the mouse. This can be useful
when you are just editing your project and are no longer making any changes to the TOC.

Split Explorer
Opens up a new view of the selected project or project branch in the Project Explorer.
This can be useful for copying and pasting between different parts of large projects or
separate projects.
You can also undock the split Explorer view (just double-click on its title bar, double-click
again to redock) to make copying and pasting even easier.

9.2.2.2.3 Change

The options in this sub-menu are for changing the properties and functions of selected TOC
items and topic files (some functions are only available for TOC items).

Include in Builds
Sets or clears conditional build/include options for the selected TOC items or topic files.
This feature is used to include or exclude topics from your published output. You can do
the same for content inside your topics with the Conditional Text 628 tool. See Conditions
and Customized Output 350 for details.

Topic Status
This is an editing aid. It allows you to "flag" topics in the TOC with colors associated with
"status" name as a reminder of the current editing status of the topic -- for example
"Needs Review" or "Out of Date". You can define your own status options with Define
Custom Status and you can edit your status definitions in Configuration > Common
Properties > Topic Status.
Topic status is not exported when you publish, it is an editing aid only.

© 1997 - 2009 by EC Software, all rights reserved

 586 Help & Manual 5 - User Help

You can also use topic status to exclude unfinished topics from your output. Just select
the option "Complete Only" in the Publish 590 dialog and all topics with a status other than
Complete will not be exported when you publish.
You can also sort and group the display of your files by topic status in the Topic Files file
viewer see Managing topic files in the Explorer 211 for details.

Change Icon
Allows you to change the TOC icon of the selected topics in the TOC. Only the displayed
icons are available in HTML Help (CHM) and Windows Exe eBooks. Topic icons are not
supported at all in ePub eBooks. Icon changes will not be reflected at all in the obsolete
Winhelp format, which only supports the standard icons.
If you want chapter icons to switch automatically between the "open" and "closed"
versions you must use one of the first eight icons and make sure that "Automatic" is
activated in the Change Icon menu.
In Webhelp you can also use your own custom icons, which you can set in
Configuration > Publishing Options > Webhelp > Navigation.

Convert to Chapter without/with Text

Converts the selected chapter topic to a chapter with or without text. A chapter topic
without text is just an empty node in the Table of Contents and does not have any content
of its own or any properties. If you convert a chapter topic with text to a chapter topic
without text the text in the deleted topic will be moved to a new sub-topic.
The obsolete Winhelp format does not support chapter topics with text. When you publish
to Winhelp the content of chapters with text will be moved to a new sub-topic with the
same name as the chapter.

9.2.2.2.4 Find

This sub-menu contains options for locating topics in your project and links to and from
selected topics.

The Find Topic dialog:

· Typing text in the Select Topic: field automatically takes you to the first topic in the list
matching the text you type. (This does not work for help context numbers.)
· The topic IDs and help context numbers of modular child projects in your TOC are not

© 1997 - 2009 by EC Software, all rights reserved

 Reference 587

shown in the list.

Find Referrers:
This option displays a list of all links to and from one or more selected topics. It is
normally displayed in the main program window but you can undock it by double-clicking
on its title bar. To redock just double-click again.
The Find Referrers report includes both normal links and links in graphics hotspots 246 .
However, please note that the report does not include any references to topics that may
be contained in scripts, macros or plain HTML code 231 that you have entered yourself.

Dialog options
Topic: The link address of the current topic.
Tip: All the links are active! You can navigate to all the topics and back to
the current topic by clicking on the links in the dialog.

Is referred All the topics in the current project that refer to the selected topic. Links to
by: the topic from other projects are not included, even if the projects are
included in the TOC of the current project as child modules.

Links to: All the topics in the current project linked to by the current topic. Links to
topics in other projects are not listed, even if the projects are included in
the TOC of the current project as child modules.
This list also includes references to any topics in which the current topic is
used as a snippet 149 .
You can click on the topic ID links in the list to visit the topics and edit
them without closing the Find Referrers report.

Dialog toolbar
Returns you to the original topic after visiting other topics in the reports list.
Inactive for reports including results for more than one topic.

© 1997 - 2009 by EC Software, all rights reserved

 588 Help & Manual 5 - User Help

Simple search function for finding text in the report window.

Copies text from the report window to the clipboard. (This does not select all the
text in the report - you must select text with the mouse first.)

Prints the report.

Saves the report to a file. The file is saved in HTML format.

See also:
Searching for text, topics and referrers 141
Find Topic 585
Find & Replace Text 602
9.2.2.2.5 File

This sub-menu contains options for saving and loading selected text and topics to and from
external files. You can save topics and selected text to Help & Manual XML files. You can
load topics from Help & Manual XML files and also from RTF, RVF, HTML and TXT files.
The Reload Topic command refreshes the current topic – this can be useful when you have
changed a graphics file on the hard disk and also when multiple users are working on the
same project (use together with Refresh Project in the Project tab).

Dialog options:
Load Topic from Create an empty topic before using! Overwrites the current topic with
file: the contents of an RTF, RVF, TXT, HTML or Help & Manual XML
file.
Save Topic to Saves the entire topic to a Help & Manual XML file that you can use
File: as a snippet or load with Load Topic from File. Saves and loads the
topic's keywords with the topic file.
Save Snippet: Text in topic selected:
Saves only the selected text to a simple Help & Manual XML file
without any keywords.
No text selected:
Saves the entire topic to a Help & Manual XML file along with
keywords (same as Save Topic to File).
Reload Topic Reloads the current topic file in the editor. Refreshes graphics if the
graphic file has been changed and can also be used to refresh topic
lock status for multi-user editing.

Version control system options:

These options are only displayed in Help & Manual Professional if you have Microsoft
Visual SourceSafe or a 100% compatible version control system installed. In addition to
this the current project must be linked to a VCS database. See Using Version Control
Systems 335 for full details.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 589

Get Latest VCS Get the latest version of the file from the VCS database – use to
Version: make sure that you have updated the latest changes when you have
activated manual check-out 346 for the current project.
Check Out: Checks the current topic out of the VCS database so that you can
edit it. Only active if you have set manual check-out for the current
project.
Check In: Checks the current topic back in to the VCS database so that other
users can edit it. Only active if you have set manual check-out for the
current project.
Undo Check Out: Use to 'reset' topics that are already checked out when you open a
project set for manual check-out. This can happen if you or another
user forgets to check their topics back in after editing them. Only
active if you have set manual check-out for the current project.
Show History / Opens the interface of your VCS so that you can view the history of
Show the current topic and the differences between versions. These
Differences: functions are provided by your VCS, not by Help & Manual – see your
VCS documentation for instructions.

See also:
Reusing content with snippets 149
Multi-User Editing 518
Using Version Control Systems 335
9.2.2.2.6 Mini Toolbar

The "mini toolbar" in the Manage Topics group is mainly for editing the
structure of your Table of Contents. You can move topics up and down
and also change the "level" of topics in the TOC this is done by
"demoting" or "promoting" topics. In addition to this the mini toolbar
contains functions for printing the current topic and editing the topic
caption.

Mini toolbar functions

Move the selected topic up or down in the TOC. This doesn't change the
current level of the topic, it just moves it.
Promote or demote the selected topic in the TOC hierarchy. "Promoting" (left
arrow) a topic moves it up to a higher level for example it moves a topic out of
a chapter onto the same level as the main chapter topic. "Demoting" (right
arrow) moves the topic down to a lower level for example making it the sub-
topic of a chapter.
Edit the TOC caption (title) of the topic. You can also edit the caption by clicking
in the TOC and pressing F2 and by clicking twice slowly in the TOC.
Print the current topic. Displays the standard Windows Print dialog.

© 1997 - 2009 by EC Software, all rights reserved

 590 Help & Manual 5 - User Help

You cannot choose a print range because the function always prints the entire
current topic.
The topic is printed with all the formatting from the editor, including links,
graphics etc, but without any of the layout options provided by the print manual
templates used for printing PDF files and user manuals 325 . Headers and page
numbers are not included in the printout.

9.2.2.3 Project

The Project group contains functions for publishing your project, jumping to bookmarks and
accessing your Project Configuration settings.

Project group options:

Publish: · Displays the same Publish 593 dialog available in the Application menu
· Clicking on the lower part of the icon executes a "Quick Publish" to the
selected output format, applying the last settings used.
Bookmark: Displays a list of the bookmarks 143 defined in your project. Selecting a
bookmark in the list jumps to the topic containing the bookmark.

Options: Links to the different sections of the Configuration 652 section of your
project that is also available directly in the Project Explorer.

Refresh Reloads the project and updates the TOC and editor display. This is
Project: particularly useful for multi-user editing but you can also used it to refresh
the display when image files have been changed on the disk etc.

See also:
Project Configuration 652
Comments and Bookmarks 143
9.2.2.3.1 Publish

This option outputs or "publishes" the current project to any of the help and documentation
formats supported by Help & Manual. Some of the features of the Publish dialog change
depending on the output format you select.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 591

The Publish Help Project dialog:

Common features:
Output file Where you want to generate your output and the name of the output
and path: file. By default Help & Manual uses your project directory and the
project name. You can change this here whenever you like, however.
When you do this the program makes all necessary internal changes
automatically.
You can use the browse button to navigate to a different output
directory.

Compile with Only available for HTML-based output formats.

skin:
Allows you to select a .hmskin skin file 321 to replace the entire design
of a project while compiling. This allows you to apply a completely
different layout and "branding" to your project with a single click. You
can save the current project as a skin with Save As in the Application
Menu.
In PDF you can also select the .mnl print manual template 330 file that
defines the layout of the PDF output.

Include These options are used in combination with Help & Manual's
Options: conditional output features. Topics and content that are "tagged" with
the options you select here will be included in your output, those that
don't match will be excluded from your output. Please study Conditions
and Customized Output 399 before using!
The Selected Topics option:
Selecting this only outputs the topics currently selected in the TOC.
This function is designed for testing only. Links to excluded topics are
converted to plain text.

© 1997 - 2009 by EC Software, all rights reserved

592 Help & Manual 5 - User Help

When Selected Topics is activated the Include Options list is

highlighted in yellow as a warning and reminder.
Links have priority over include options!
If included topics contain hyperlinks to excluded topics the topics will
always be included to prevent dead links. This has absolute priority –
the only way you can prevent it from happening is to make sure that
there are no links to your excluded topics. (Use Find Referrers in
the File menu.)
Current format:
By default the include option for the selected output format is
preselected. If you also select other options you must leave the current
format option selected, otherwise only the content matching the other
options will be included.

Topic Status: Only exports topics with the status 585 "complete" to your published
Complete output. This enables you to prevent topics that are not yet finished from
Only being included in your output.

Display file: Automatically displays the output file as soon as it has been generated,
using the appropriate viewer.

HTML Help settings:

Delete temp Selected by default. Normally all the source files generated to compile
files: HTML Help are deleted. If you deselect this you can view the source
files in the \~tmphtml directory, which you can find in your project
directory.

Webhelp settings:
Index page: The default index page for Webhelp is index.html. You can change
this here, along with the output path. Help & Manual remembers your
setting for the current project.

Enable local This setting allows you to test your Webhelp in Internet Explorer on
testing for your local machine without having to click away the annoying yellow
MS Internet security warning bar. Click here for further details.
Explorer:

Delete all Clears all the files in the output folder before compiling. Use this when
files in target you are producing a distribution build to ensure that the folder only
folder: contains the files related to the current version of your project.
Otherwise the directory may contain HTML files for topics that you have
already deleted in your project, left over from previous compiles. These
files take up unnecessary space and are also indexed by the indexer
and included in the full-text search function, which is something you
want to avoid.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 593

Always use this function if you change the title of your project as this
also changes the names of all the output files associated with the full-
text search 680 function. If the old files are present the indexer may
attempt to index them, which can cause errors.

Adobe PDF settings:

Print manual Selects the .mnl print manual template 330 file to be used to generate
template: the PDF file. This template file defines the PDF layout, generates the
print-style table of contents and the index and adds a number of
additional pages and other features like headers, footers, page
numbers etc.

Highlight Displays outlines around the hotspots and links in your PDF output.
hotspots: Dead links and hotspots to missing targets are also highlighted.

Visual Studio Help / Help 2.0 settings:

Do not This is a special debugging option for Visual Studio Help. Instead of
compile: compiling a finished .HXS file it generates a .HWProj project file that
you can open and compile manually in Visual Studio .NET. For details
see About compiling VS Help 491 .

Delete temp Selected by default. Normally all the source files generated to compile
files: Visual Studio Help are deleted. If you deselect this you can view the
source files in the \~tmphxs directory, which you can find in your
project directory.

Winhelp settings:
Delete temp Selected by default. Normally all the source files generated to compile
files: Winhelp are deleted. If you deselect this you can view the source files
in the \~tmprtf directory, which you can find in your project directory.

Microsoft Word RTF and eBooks

These formats have no special settings in the Publish dialog.

See also:
Conditions and Customized Output 399
9.2.2.3.2 Bookmark

This option displays a list of the bookmarks in your current project and allows you to add
new bookmarks. Bookmarks mark topics, not positions within topics. You can only add one

© 1997 - 2009 by EC Software, all rights reserved

 594 Help & Manual 5 - User Help

bookmark to any one topic.

You can jump to the bookmarks by selecting them in the list.
To create a new bookmark just select Bookmark Current Topic. By default the topic title is
used as the bookmark title but you can change this if you want.

See also:
Comments and bookmarks 143
9.2.2.3.3 Options

This provides links to the main configuration sections for your project in the Project Explorer.
These links are just a convenience, all the sections can be accessed directly in the
Configuration section of the Project Explorer. For full details on the settings dialogs
contained in this section see Project Configuration 652 .

See also:
Project Configuration 652
9.2.2.4 Tools

The Tools group provides direct access to a variety of tools included with Help & Manual,
including a full-featured graphics editing program, a powerful screenshot capture program
and a separate editor for designing the layout templates for your PDF files and printed
manuals.
These tools are covered in more detail in the Tools Included with Help & Manual 532 chapter,
and some of them also have their own help files.

See also:
Tools included with Help & Manual 532
9.2.2.4.1 Spelling

The Spell Check option in the Tools menu provides access to Help & Manual's spell
checker and its configuration options. Full details of these options and the configuration
settings are can be found in The Spell Checker 543 in the chapter on the tools included with
the program.
Note that Help & Manual supports live spell checking that marks incorrectly-spelled words as
you type. Just select Spelling > Configure Spell Checker and activate the Check spelling as
you type option.

Productivity Tip
Spell checking is supported almost
everywhere in Help & Manual where you
can enter text. Just right-click to display the
context menu or click on the upper half of
the Spelling tool in the Project tab to
access.

See also:
The Spell Checker 543

© 1997 - 2009 by EC Software, all rights reserved

 Reference 595

9.2.2.4.2 Screen Capture

This option starts Help & Manual 's integrated screenshot program, with which you can take
snapshots of your screen and program components for using in your help. Captures
windows, controls, menus, the entire screen and free areas and can also apply a variety of
effects.
For details on using this tool see Screen Capture 532 in Tools Included with Help & Manual.

The Screen Capture dialog:

Click on the Extended >> button to display all the options shown in the screenshot
above.

Dialog options
Window, Automatically identifies and captures windows, buttons and other
control or program elements and controls.
menu:

A free region Captures all the contents of a selected rectangular region of the
of the desktop.
desktop:

A fixed size Captures a region of a predefined size. Define size with Width: and
region: Height: .

Zoom factor: Resizes the screenshot automatically if you select a value other than
100%.

Zoom filter: A collection of different high-quality resizing filters. The default is

Lancos, which works very well for most images, but you may obtain
better results with the other filters on some types of images.

© 1997 - 2009 by EC Software, all rights reserved

 596 Help & Manual 5 - User Help

Image shape:The shape of the captured image. Some of these shapes apply effects,
Automatic Shape finds fills the background of the image with the
background color (see below) to create a fake transparency effect.
Experiment!

Fade out: Applies gradient fade effects to the captured image.

Background The color of the background around the captured image. You will
color: normally want to match to the color of your topic pages (usually white).

Include Includes the mouse pointer in the captured image.

cursor:

Add sparkle: Inserts a starburst effect at the mouse pointer tip. You can also apply
this without including the mouse pointer if you want.

Image has Applies a drop shadow to the captured image.

shadow:

Cursor has Applies a drop shadow to the mouse pointer.

shadow:

Shadow The color of the drop shadow. Black creates a normal grey shadow,
Color: any other color will generally look pretty strange, but be our guest...

Shadow These three controls adjust the width, direction and blur intensity of the
properties: shadow. Again, this is easier to see than to describe. Try it out and
you'll see what we mean.

See also:
Screen Capture 532 (Instructions)
9.2.2.4.3 Image Editor

By default the Image Editor tool in Project > Tools starts the Impict graphics editing
program included with Help & Manual. You can change this to a different graphics editing
program in View > Program Options > General.
The Impict program has its own separate help and documentation.
If you select an image in the Help & Manual editor before selecting Image Editor the
corresponding graphics file will be loaded into the graphics editing program automatically.

See also:
The Impict Screenshot Editor 536
9.2.2.4.4 Report Tool

This tool generates detailed reports on your project that can be used for a wide range of
purposes, including documentation, providing your programmers with lists of topic IDs for
their help calls, checking project status, locating dead links, finding missing images and
unused images and so on.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 597

See the Report Tool 534 for full details on how to generate reports.

The Project Report dialog:

Note that all options that exclude topics will reduce the accuracy of link reporting (links to
topics that are not included in the report will not be checked).

Dialog options
Report type: You can generate five different report types, with increasing levels of
detail. See below for more detailed descriptions.

Sort order: How you want your topics to be sorted in the report. Note that only the
Table of Contents sort option also includes chapters without text. All
the other options (Topic ID, Context Number, Modification Date)
only include topics that actually have contents.
If you sort by context number only those topics that actually have
context numbers will be included in the report!

Modified Only include topics edited between two specified dates.

between:

Topics with Include only topics with specific help window types 121 in the report.
window:

Topics with Include only topics with a specific editing status 209 in the report.
status:

Include Include topics on the basis of predefined and user-defined include

options: options. This works in the same way as include options in conditional
output 402 .

File name: Name and location of the HTML file for saving the report. Use the

© 1997 - 2009 by EC Software, all rights reserved

 598 Help & Manual 5 - User Help

browse button to choose the location.

Reset Options Resets all the dialog options to their default settings.

Report types
Short project Simple list of all topics in your project with status, caption (i.e. the TOC
report: title), topic IDs, help context numbers, builds in which the topics are
included and date last edited. The report also includes a summary of
the number of topics and keywords in your project.
This is a practical format for providing your programmers with a list of
topic IDs and context numbers for their calls.

Extended Also includes each topic's keywords and help window and a more
project detailed project summary at the end with a list of all the images used in
report: the project.
Missing images are shown in red.

Long project Also includes lists of the images used in each topic, lists of the links in
report: each topic with their targets (including topic links, Internet links, file
links and script links) and the first lines of the text with which the topic
begins. As in the extended report the summary includes a list of all the
images used in the project
Missing images and dead links are shown in red.

Full project Same as the Long Report but also includes an additional full list of
report images used in the project with references to the topics in which each
including image is used. In addition to this there is also a list of images found in
image the project's image folders that are not used in the project (useful for
references: tidying up your project folders).
Missing images and dead links are shown in red.

Missing Special report that only locates topics that do not have any index
keywords keywords.
report:

See also:
Report Tool 534 (Instructions)
9.2.2.4.5 Index Tool

This tool displays an editable and fully-functional version of the finished index of your
project. This enables you to polish and tidy your index very easily. For example you can
quickly correct multiple index entries that are similar, and you can test your index links to
make sure that they point to the right places. You can also use the integrated editing tools to
assign existing and new keywords to multiple topics in a single operation.
The Index Tool can be used most effectively in combination with the index keyword entry

© 1997 - 2009 by EC Software, all rights reserved

 Reference 599

functions for individual topics in the tab.

The Index Tool window:

Editing tools
Edit keyword Edit the selected keyword simultaneously in all the topics where the
keyword occurs. You can also add the keyword to additional topics by
including them in the list on the left side of the dialog displayed.

New Add a new keyword to one or more topics simultaneously.

keyword:

Delete Delete the selected keyword from all the topics where it is used. Use
keyword: the tab behind the main editor window to delete keywords from
individual topics.

Display: Display the topic(s) the current keyword links to.

Reload: Reload the finished index to refresh editing changes.

See also:
Editing the index directly 275
9.2.2.4.6 Manual Designer

The Print Manual Designer is another separate program included with Help & Manual. It is
used for editing the template files that define the layout and appearance of the PDF files
and printed manuals generated from your projects.
The Print Manual Designer program has its own separate help and documentation.

See also:
Print Manual Designer 537
Using PDF templates 330

© 1997 - 2009 by EC Software, all rights reserved

 600 Help & Manual 5 - User Help

9.2.2.4.7 Context Tool

The Help Context Tool is a wizard integrated in the main Help & Manual program for
managing the context numbers 205 in your project. You can use it to assign, delete, import
and export help context numbers in batch mode for your entire project. In addition to this you
can also use the tool to automatically generate context help topics from a map file containing
a list of topic IDs and context numbers.
The screens in the Help Context Tool are documented in detail in The Help Context Tool 539
in the Tools Included with Help & Manual chapter.

See also:
The Help Context Tool 539
9.2.2.4.8 Synchronize

The Project Synchronization tool is used for updating translated versions of your project.
When your original project has been updated you use Project Synch to compare the
updated original project with the old translated project. Project Synch then creates a new
version for the translator containing the changed and new material that needs to be
translated.

See also:
The Project Synchronization Tool 556
9.2.3 The Write Tab
This is the tab where you will probably be spending most of your time while actually writing
the content of your projects. It contains all your text formatting and editing tools and also all
the tools for inserting special help features like toggles (expanding sections and images),
snippets (reusable text blocks), HTML code objects and so on.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 601

9.2.3.1 Clipboard

The Clipboard group contains a standard set of tools for using the Windows clipboard
(Copy, Cut, Paste, Paste as Text). You can use the clipboard tools for copying both content
in topics and for topics and chapters in the Project Explorer, both within the same project
and between multiple projects.
Remember that Drag & Drop also work both in the editor and in the Project Explorer.

What Paste as Text does:

· Paste as Text or Ctrl+Shift+V pastes copied text as plain text, without any formatting
(bold, underline, graphics etc).
· Use if you want to copy text without any formatting from other topics, projects or other
programs such as MS Word or a web browser.
· This feature is also useful for pasting text into paragraphs formatted with styles without
transferring the style of the copied text into the target paragraph.

See also:
Copying, cutting and pasting text 139
Moving cutting and pasting topics 199
9.2.3.2 Editing

The Editing group contains basic editing commands for finding, replacing and selecting text
and for undoing your editing operations. All these commands are also available via keyboard
shortcuts. You can view and edit the shortcuts in View > Program Options > Shortcuts.

Editing group functions:

Find and Search for and replace text, graphics file names and keywords.
Replace:

Undo: Undo the last editing action. Note that this must be selected repeatedly for
some more complex actions.
Undo is not available for operations in the TOC!

Redo: Reverse the last Undo operation.

Redo is not available for operations in the TOC!

Select All: Selects the entire contents of the current topic or the current table cell.

See also:
Creating and Editing Topics 108
The Project Explorer 41
Options & Keyboard Shortcuts 31

© 1997 - 2009 by EC Software, all rights reserved

 602 Help & Manual 5 - User Help

9.2.3.2.1 Find & Replace Text

This is a standard find and replace function but with a couple of extra features for finding
and replacing in Help & Manual projects. The dialog can be used both for simple searches
and for replacing text. Deselecting the Replace with: check box turns off the replace
function.
Note that you cannot search for or replace text in the topic captions in the Table of Contents
(TOC).

The Find & Replace dialog:

Note that some of the buttons on the right will be disabled depending on where and how
you are searching. For example, you cannot replace in the Table of Contents, but you
can in Captions (TOC captions, topic titles). Wildcard characters are not supported.
Dialog options:
Find in: Search in the current topic (default), all topics from here or all Topics.

Find Where: · Topic text and header searches the content of your topics.
· Topic keywords searches the keywords stored in the tab.
· Table of Contents locates topics in the TOC by their title. Replace is
not supported in this mode.
· Captions searches the TOC captions (topic title) stored in the tab.
Replace is supported in this mode.
· Image filenames searches for references to graphics files. You can
use this mode to "replace" images in your project by making image
references point to different graphics files.

Find what: Enter the text you want to find here.

Replace with: Enter the replacement text here.

Only active if the check box next to it is selected, otherwise the dialog
functions as a simple search function.

Find Next: Starts or continues the search.

Find All: Finds all occurrences of the search term and displays them in a report
screen with links to the topics.

Replace: Replaces the current instance.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 603

Replace All: Replaces all instances of the search text. A prompt is displayed to
make sure that you want to do this before proceeding.
Note that the scope of Replace All is also defined by the selections you
make in Search Options!

See also:
Searching for text, topics and referrers 141
Find Topic 585
Find Referrers 586
9.2.3.3 Styles

The Styles group contains the main functions for editing and manipulating text, paragraph
and table styles. Using styles effectively can radically speed up your work and will also make
your projects look more uniform and professional. They will also save you a lot of time
once you have got styles set up you can change the fonts and formatting in your entire
project in a couple of minutes just by changing your style definitions.

Styles group functions:

Edit Styles: Display the dialog for creating and editing text, paragraph and table
styles.

Create Style Uses the text and paragraph settings at the cursor position to create a
from new style or redefine an existing style.
Selection:

Replace Global search and replace operation to replace formatting and styles in
Styles: your entire project. Searches for text attributes and paragraph attributes
separately.

9.2.3.3.1 Create Style from Selection

This option turns the current selection into a dynamic style that you can reuse. Formatting
text manually and then turning it into a style is often easier than designing a style "from
scratch" in the styles definition dialogs.
If no text is selected the function uses the attributes of the paragraph in which the cursor is
currently located, including the paragraph attributes and the text attributes at the current
cursor position.

© 1997 - 2009 by EC Software, all rights reserved

 604 Help & Manual 5 - User Help

Dialog options
Create a new Define a completely new style using the current selection as a model.
style:

Change Redefine an existing style. The style assigned to the current selection
existing or cursor position is the default but you can select another style to
style: redefine.

New style Enter a new name or accept the name of the style you want to redefine.
name:

Based on Select a "parent" child to make the new or redefined style the child of
style: another style. If you select a paragraph style as the parent the new
style will also be a paragraph style.

Assign Assigns both the text and paragraph attributes of the current selection
paragraph to the new or redefined style.
attributes:

Edit Styles: Opens the Edit Styles dialog for more detailed styles editing.

See also:
Text Formatting and Styles 155
Defining styles 161
9.2.3.3.2 Edit Styles

This dialog contains all the settings for creating and editing text, paragraph and table styles.
For full details on creating, editing and using styles please see Text Formatting and Styles 155
.

Table styles and text/paragraph styles

To display the options for table styles just click on one of the entries in the Table Styles
section on the left. In the same way, display the options for text and paragraph styles by
clicking on one of the entries in the Text & Paragraph Styles section.

Dialog options
Style name: Name of the current style.

Based on style: The "parent" style of the current style. Styles inherit all attributes that
you do not explicitly change from their parent style. You can change
the parent style by selecting a different style in this field.

Shortcut: The keyboard shortcut for selecting the style. To add a shortcut just
click in this field and press the key combination for the shortcut.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 605

Add Style Creates a new style definition.

Remove Style Deletes the current style. If the style has any sub-styles (child styles)
they will also be deleted (a warning is displayed). Not active for Help
& Manual's standard styles, which cannot be deleted.

Copy Styles Copies the styles definition set from another Help & Manual project.
From...
This completely overwrites the current style definition set, replacing
it with the definitions of the other project.

Screen View / You can define two sets of different settings for each style: Screen
Print Manual View is for electronic help formats (HTML Help, Winhelp, Webhelp
View and Windows Exe and ePub eBooks), Print View is for page-style
formats (PDF, Print User Manual, Word RTF).
You can switch between the Screen and Print View style settings in
the Help & Manual editor by clicking on the Screen/Print button in
the status bar at the bottom of the main program window.

Font, These buttons display the dialogs for formatting the Font, Paragraph
Paragraph, and Borders & Backgrounds attributes of the current style. The
Borders (Text & dialogs are exactly the same as the standard Format Font 606 ,
Paragraph Format Paragraph 609 and Format Borders & Backgrounds 611
Styles) dialogs.

Modify Layout Displays the layout settings for table styles. These settings are a
(Table Styles) subset of the normal Table Properties dialog.

Reset Style Resets the current styles to the default settings. Always use this
before defining a text-only style 161 to make sure that you do not
accidentally include paragraph or border attributes.

See also:
Text Formatting and Styles 155
Dynamic Styles 711
9.2.3.3.3 Replace Styles

This is quite a complex and powerful tool for replacing formatting and styles globally
throughout your entire project. It replaces font and paragraph styles and settings separately,
in two separate operations, and requires a little planning to use. See Replacing Formatting
and Styles 497 for details.

See also:
Replacing Formatting and Styles 497
9.2.3.4 Font

Most of the formatting tools in the Font group should be self-explanatory, they are exactly
the same as in any word processor. There are just a couple that deserve extra mention and
explanation.

© 1997 - 2009 by EC Software, all rights reserved

 606 Help & Manual 5 - User Help

Font formatting tools

Font Dialog:
Clicking on the Font Dialog icon at the bottom right
corner of the Font group opens the full font formatting
dialog. See Format Font 606 for more details.

Protect Text: Protects text from change and translation. Select text
and click to apply. Protected text is displayed with a
shaded background and is tagged with the attribute
translate="false" in the XML source code of your topic
file.

Style selector: Shows the style applied to the current text at the
cursor and can be used to select a new style. Used
for both text and paragraph styles. If text is manually
formatted or imported you must select it first to apply
a style, otherwise the style will be applied to the entire
current paragraph.

Syntax highlighting: Tool for applying standardized syntax highlighting to

program code in a number of different languages.

See also:
Text Formatting & Styles 155
Formatting Program Source Code 195
9.2.3.4.1 Format Font

This is a standard font formatting dialog. Everything

should be familiar from word processing programs and
pretty self-explanatory. Exactly the same dialogs are
displayed for formatting text manually 155 and for defining
styles 161 . The only difference when you define a style is
Click the dialog icon in the Font that your formatting is stored in the style for reuse. All
group to display the Font dialog font attributes can either be used directly or for defining
styles.

The Format Font dialog:

This dialog is displayed by clicking on the little Dialog icon

© 1997 - 2009 by EC Software, all rights reserved

 Reference 607

Font formatting principles:

· When formatting text manually select text before selecting the Font dialog to apply
formatting to text.
· If you apply font attributes without selecting text they will only be applied to new text
typed at the current cursor position.
· Remember that only standard fonts will be present on most user's computers for most
output formats!
Font tab options:
The only option here that is not self-explanatory is Script:, which is important for texts in
non-English languages. If you are having problems with displaying special characters in
these languages always check the Script setting, particularly if you have imported your
text from RTF, HTML or CHM files.
Character Spacing tab options:
Character These options increase or decrease the spaces ("leading") between
spacing: individual characters. The effects are shown directly in the preview box.

Horizontal This "stretches" or "compresses" the text horizontally. The effects are
scaling: shown directly in the preview box.

See also:
Text Formatting and Styles 155
9.2.3.4.2 Syntax Highlighting

This menu option applies highlights program code text to make it easier to read. A number
of programming languages are supported, and you can customize the highlighting styles for
each program language.
For more details see Formatting program source code 195 .

© 1997 - 2009 by EC Software, all rights reserved

 608 Help & Manual 5 - User Help

Customize dialog options:

This dialog is displayed when you select Format > Syntax Highlighting >
Customize.

Format with The basic appearance of all text formatted with the Syntax Highlighting
style: function is controlled by the standard Code Example style. This is the
currently only style you can use for syntax highlighting.

Opens the Edit Styles dialog to edit the Code Example style.

Elements: Settings for defining the color and font styles of the various elements
highlighted by the function.

Load Loads your own list of reserved words to be used by the highlighter for
reserved the current language. Load the words from a plain ASCII file with one
words: reserved word per line.

Add list to If you select this your list of reserved words will be added to the
predefined: program's list. Otherwise your list will replace the program's list.

Reset Resets all settings for the current language to the default values. This
defaults: also replaces any reserved words you have loaded.

See also:
Formatting program source code 195
9.2.3.5 Paragraph

The Paragraph group contains the tools for formatting paragraphs manually. In addition to
justification, line spacing and indents this also includes tools for creating bulleted and
numbered lists and applying borders and background colors to paragraphs.
The following reference only shows the Paragraph group tools that are not entirely self-
explanatory.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 609

Paragraph group tools:

Paragraph
dialog:
Clicking on the small dialog icon in the bottom right corner opens the
normal paragraph formatting dialog in which you can apply all
available paragraph formatting settings.

Lists: Tools for bulleted and numbered lists. List definitions are separate
from styles. Click on the arrows next to the list tools to display a list
style gallery and the options for opening the list dialogs.

Indents: Increase and decrease paragraph indents. These tools are disabled
in single-level bulleted and numbered lists. In multi-level outline-style
lists they change the level of the current list element.

Borders and Displays a menu in which you can apply individual simple borders or
Shading: open the full Borders and Backgrounds dialog to set more complex
options for the current paragraph.

Text marks: Clicking this tool displays paragraph end markers and tab characters
in your text so that you can see them more easily. You can turn this
on permanently with the settings in View > Program Options >
Editor.

See also:
Text Formatting and Styles 155
Numbered and bulleted lists 180
9.2.3.5.1 Format Paragraph

This is the manual paragraph formatting dialog displayed when you

select the Dialog icon 608 in the Paragraph group. Most of its features
should be familiar from word processing programs and pretty self-
explanatory. Exactly the same dialogs are displayed for formatting text
The dialog icons manually 155 and for defining styles 161 .
opens When formatting text manually paragraph attributes are applied to all
the Paragraph
paragraphs that are at least partially selected, or to the paragraph in
dialog
which the cursor is currently located.

Internally, Help & Manual handles all measurements in pixels. For maximum precision
working in pixels rather than inches or centimeters is recommended. You can change your
measurement units setting globally in View > Program Options > Editor > Ruler Units
647 .

The Indents and Spacing and Tab Stops tabs:

All the settings in these tabs are exactly the same as in a normal word processor and

© 1997 - 2009 by EC Software, all rights reserved

610 Help & Manual 5 - User Help

should be self-explanatory. Note that tab stops are not supported in HTML-based formats
and should generally only be used in hanging indents, where they are automatically
converted in HTML output. Please see Using indents 172 for details on using indents in
help files.

The Line and Page breaks tab:

The first two settings in this tab are only used for printing manuals and generating PDF
output. They are ignored in all other output formats.

Keep lines Applying this attribute to a paragraph or a style will keep all of the lines
together: of a paragraph together at a page break. Don't use for body text – if
your paragraphs are large this setting will bump the entire paragraph
onto the next page, leaving an ugly gap!

Keep Keeps the paragraph with the next paragraph at a page break.
paragraph Generally only used for headings. If you use empty paragraphs after

© 1997 - 2009 by EC Software, all rights reserved

 Reference 611

with next: headings remember that you must apply this setting to both the
heading and the empty paragraph, otherwise it won't work.

Word wrap: If you disable this setting the lines of paragraphs will no longer
automatically wrap to the next line. It is normally only used for
formatting program code and other text where the ends of each line is
defined with a paragraph end mark. If you disable this in normal text
everything except the first line will disappear off the right margin of the
page.
In HTML-based output formats turning off word wrap is achieved by
converting all spaces to non-breaking spaces. You can then also use
leading spaces for indenting text.

See also:
Text Formatting and Styles 155
Using indents 172
Tabs, indents and HTML 722
9.2.3.5.2 Format Borders and Background

This dialog is displayed by clicking on the Borders tool in the Write > Paragraph group
and the selecting Borders and Shading.
These settings allow you to apply borders and colored backgrounds to paragraphs. Most of
its features should be familiar from word processing programs and pretty self-explanatory.
Exactly the same dialogs are displayed for formatting text manually 155 and for defining styles
161 .

The Format Borders & Background tab:

When you format text manually border and background attributes are applied to all
paragraphs that are at least partially selected, or to the paragraph in which the cursor is
currently located.
Multiple paragraphs with a background color may have white space between them.
Multiple paragraphs with borders will have individual borders around each paragraph

© 1997 - 2009 by EC Software, all rights reserved

 612 Help & Manual 5 - User Help

instead of one border around all paragraphs. To avoid these problems press SHIFT-
ENTER instead of ENTER between paragraphs with borders and backgrounds.
Dialog options:
Settings: These settings define the color and dimensions of the border and the
background. The Offset is the distance between the border and the
paragraph.

Preview: The buttons around the Preview window activate or deactivate the
border display for top / bottom / left / right.

Border style: You must select one of these styles to display borders. If None (the
default) is selected no borders will be displayed!

See also:
Text Formatting and Styles 155
9.2.3.5.3 Format Bullets and Numbering

This dialog is displayed when you click on the Bulleted or Numbered List tool in Write >
Paragraph and then select the Bullets and Numbering option displayed below the list styles
displayed.
To apply a bulleted or numbered list select paragraphs in the editor, display this dialog and
then select one of the list styles.
Although selecting numbered and bulleted lists is very simple using them properly in Help &
Manual requires a little more information. Please see Numbered and bulleted lists 180 for
details.

The Format Bullets & Numbering dialogs:

Restart Select to restart the numbering of the current item or list with a
numbering / different number. You can also use this to reset the numbering of a
Start at: list to begin at 1.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 613

Customize: Select to modify the currently selected bullet or numbering style.

Reset: Select to reset the current bullet or numbering style to its default
settings.

The Customize dialog (Bullets):

Displayed by selecting Customize in the Bulleted tab. Edits the properties for the bullets
style selected in the main tab.

Levels: Number of levels in the list. This is not active for bulleted lists, which
always only have one level.

Level Formatting and style for the current level. Bulleted lists always only have
Format: one level.

Number Selecting anything except Bullet here switches to a numbered list.

style:

Select Select a different character to use for the bullet in the bulleted list. The
Bullet: selected character will be displayed in the preview box on the right.

The Customize dialog (Numbered List):

Displayed by selecting Customize in the Numbered tab. Edits the properties for the
numbered list style selected in the main tab.

© 1997 - 2009 by EC Software, all rights reserved

614 Help & Manual 5 - User Help

Levels: Number of levels in the list. This is not active for ordinary lists, which
always only have one level.

Level Format: Formatting and style for the current level. Ordinary numbered lists
always only have one level.

Number style: You can choose a variety of styles for your numbered list.
Experiment!

Number The format of the number displayed in the list. The variable <L1>
format: displays the list number and should not be deleted. Any other
characters you enter will be added to the number. The result is
displayed in the preview box on the right.

Start Only active for lower levels of outline numbered lists (see below).
numbering at:

Legal Activates legal numbering style for outline numbered lists, with all the
numbering list numbers at the left margin (see below).
style:

Level reset: When this is selected the numbering of sub-levels in outline

numbered lists always re-starts with 1 or the equivalent (see below).

The Customize dialog (Outline Numbered List):

Displayed by selecting Customize in the Outline Numbered tab. Edits the properties for
the outline numbered list style selected in the main tab.

Levels / Count: Number of levels in the outline numbered list style. You can change
the number of levels by adjusting the Count: value.

Level Format: Formatting and style for the current level. Select the level to modify by
clicking in the Levels box.

Number style: You can choose a variety of styles for your numbered list.
Experiment!

Number The format of the number displayed in the list. The variables <L1>,

© 1997 - 2009 by EC Software, all rights reserved

 Reference 615

format: <L2> etc. (for the levels) display the list numbers and should not be
deleted. Any other characters you enter will be added to the number.
The result is displayed in the preview box on the right.

Start Resets the starting number of the current level. Only active for lower
numbering at: levels of outline numbered lists.

Legal Activates legal numbering style for outline numbered lists, with all the
numbering list numbers at the left margin. This setting must be set separately for
style: each level of an outline numbered list!

Level reset: When this is selected the numbering of sub-levels in outline

numbered lists always re-starts with 1 or the equivalent. Otherwise
the numbering continues from one sub-level to the next. Must be
selected separately for each level of the outline numbered list.

See also:
Text Formatting and Styles 155
Numbered and bulleted lists 180
9.2.3.6 Insert / Insert Object

The Insert and Insert Object groups in the Write tab are particularly important. They
contains options for inserting different kinds of hyperlinks and all the objects that you can
use in Help & Manual topics in addition to text. You can also insert tables here so that you
don't have to switch to the Table tab while you are working.

Insert group:
Link: Displays the dialog for inserting hyperlinks in your topic. You can
insert topic links, file links, internet/email links and links that run
scripts or macros. Select text first to create

Image: Displays the dialog for inserting a graphic in your topic.

Table: A graphical tool for inserting tables quickly and a link to the
standard Insert Table dialog.

© 1997 - 2009 by EC Software, all rights reserved

616 Help & Manual 5 - User Help

Insert Object group

Movie: Displays the dialog for inserting a video or flash animation file in
your topic.

Topic Displays the dialog for inserting an anchor in your topic as a target
Anchor: for topic links and other references. (Anchors can also be used as
targets for HTML links in Webhelp.)

Text Displays the dialog for inserting a text variable in your topic.
Variable: Includes both the program's predefined variables and any variables
you have defined for your project.

Conditional Displays the dialog for inserting conditional text to include or

Text: exclude text and other content from your output on the basis of
conditions.

Toggle: Insert expanding sections, expanding inline text and expanding

images. These items "grow" when the user clicks on them in the
help. Only supported in HTML-based output formats with
JavaScript.

HTML Code Displays the dialog for inserting inline HTML code in your topics for
Object: adding features and functionality in HTML-based output formats.
This code is ignored in all non-HTML based output formats.

Manual Page Inserts a hard page break at the cursor position. Page breaks are
Break: only used in PDF, Printed Manuals and Word RTF. They are
ignored in all other formats

Snippet: Inserts a topic or an external Help & Manual XML file as a snippet
which can be either linked or pasted. Linked snippets are dynamic
and update automatically when the linked file is changed. Pasted
snippets are like ordinary cut and paste.

Comment/ Opens the dialog for entering a comment for yourself or others
Bookmark: working on the project. Comments can also be used as
bookmarks, with which you can find and jump to places in your
project quickly with Bookmark in Project > Project. Comments
and bookmarks are not included in your output.

OLE Object: Displays the standard Windows dialog for inserting OLE (Object
Linking and Embedding) objects in your topics. OLE objects are
converted to graphics in your output.

Horizontal Inserts a horizontal line in the topic at the cursor position.

line:

Special Displays the character map dialog for inserting special characters
Character: that are not available on the keyboard in your topic.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 617

See also:
Using Graphics 238
Adding video files 269
Re-using content with snippets 149
Using OLE Objects 494
Using Context-Sensitive Help 369
Using Variables 376
Conditions and Customized Output 399
9.2.3.6.1 Link

This dialog contains all the options for inserting hyperlinks in your topics. For detailed
instructions see the Links, Anchors, Macros Scripts and HTML 214 chapter. The appearance
of the dialog changes depending on the kind of link you are inserting.

The Insert Hyperlink dialog:

Common options for all link types:

Caption / The caption displayed in the text for the link if you are creating a text
Picture: link. If you select text in the editor before invoking the Insert Link
function the selected text is displayed here.
If you select Picture in the Style section (see below) Picture: is
displayed above this field instead of Caption:. The browse button to
the right of the entry field is then activated so that you can select a
picture to use.

Tooltip: Adds text for a tooltip that is displayed on mouseover in HTML-based

output formats.

Style:
Link: The standard link format: text link, displayed in blue with an underline.

Text: Displays the link as plain text that you must format yourself in the

© 1997 - 2009 by EC Software, all rights reserved

618 Help & Manual 5 - User Help

editor. If you don't format the link it will be active but it will not look any
different from the text around it, i.e. it will not be identifiable as a link.

Button: Displays the link as a standard Windows button. The caption in the
Caption: field is used as the label text on the button.

Picture: Uses a graphic as the link instead of a text caption. The supported
graphics types are indicated by file extensions are displayed in the
dialog displayed when you click on the Browse button to select a file.

Topic link dialog options:

Help file: The file containing the topic you want to link to. By default this is the
current project file but you can also create links to other project files
and compiled Winhelp HLP and HTML Help CHM files.
Click on the browse button to select a different help file. Its topics will
then be displayed in the Topic ID list. (Topics are not displayed for
compiled Winhelp files.)
The target help file must be present in the same directory as the file
containing the link at runtime (i.e. on the user's computer). Also, the
target help file must have the same format as the help file containing
the link. You cannot create links between CHM and HLP files.
Links to compiled Winhelp files are very limited – you can only link to
the default topic of a Winhelp file, not to any selected topic within the
file.

Window: Only relevant in HTML Help and Winhelp. If you have defined
secondary window types for your project you can select a different help
window type for opening the target topic.
In Winhelp selecting a secondary help window here always opens the
topic in an external window, with all the properties of the help window
type (background colors, position, size, viewer buttons and controls).
In HTML Help selecting a secondary help window here only opens an

© 1997 - 2009 by EC Software, all rights reserved

 Reference 619

external window if secondary HTML Help windows are activated in the

Help Windows 661 configuration. If they are not activated this setting has
no effect in HTML Help.
Topics in HTML Help do not change their background colors when you
specify a secondary help window in a hyperlink. Their colors are
defined by the HTML template of their own window type definition and
this cannot be changed by a link. Even when they are displayed in an
external window the secondary window type only controls the
appearance of the window, not of the topic itself.

Target: The topic ID of the topic you want to link to. Select the ID from the list
or type its name in the entry field. Each letter you type will automatically
display the first topic matching that letter.

Anchor: Use to link to an anchor inside the selected topic, so that clicking on the
(drop-down list link takes the user directly to the position of the anchor. Anchors are
next to Target:) only displayed here if the target topic already contains anchors. If you
have just inserted an anchor in the target topic it is not displayed until
you save your project.

Internet link dialog options:

Address: The website URL or email address you want to link to. Always enter a
complete URL for websites, including the http:// protocol prefix. Links
without this prefix sometimes don't work in HTML Help.

Test Test the URL. Opens your browser or email program.

Links to an Select to enter a website URL.

Internet
address:

Sends an Select to enter an email address.

email:

© 1997 - 2009 by EC Software, all rights reserved

620 Help & Manual 5 - User Help

Target Same as referring topic

window: Opens the web page in the current browser window or the help viewer if
possible. (The Winhelp and Windows Exe eBook viewers cannot
display web pages, ePub readers will only open a browser if possible
and available.)
Use this option instead of Top frame when loading web pages into
Webhelp topics if you want the Table of Contents to remain visible
when the web page is loaded.
New window:
Opens the web page in a new browser window.
Top frame:
This option is designed for Webhelp output. It loads the web page into
the topmost frame in the current frame structure, completely overwriting
the Table of Contents so that the web page fills the entire browser
window.

File link dialog options:

File links link to external files located in the same directory as the help file containing the
link. When the user selects the link it is like double-clicking on a file in the Windows
Explorer.
See Inserting file links 220 for details and compatibility with various output formats.

File name: The name of the file you want to link to. You can use the browse
button to select a file but this will not enter any path information
because it is assumed that the file will be in the same directory as the
help file containing the link.
If you enter the file name manually always type the complete name of
the file, including the extension.

Execution Any parameters you want to add to the file link, for example switches or
parameters: a file name to follow an executable program.

Test Tests the file link with the execution parameters. If you use the button

© 1997 - 2009 by EC Software, all rights reserved

 Reference 621

in the File name: field to select the file this will access the file
wherever it is located.
Note that this doesn't test whether the file link is compatible with your
output format! It only tests how executing the external file behaves with
the execution parameters entered.

Script link dialog options:

This option enters a link that executes a Winhelp macro or some JavaScript code. Please
see Inserting script and macro links 223 for information on how to use this function.

HTML Select this to enter JavaScript code. Only supported in HTML Help and
JavaScript: Webhelp output.

Winhelp Select to enter a Winhelp macro. Only supported in Winhelp output.

macro: However, four special Winhelp macros are automatically converted to
their ActiveX equivalents in HTML Help. See Inserting script and macro
links 223 for details.

Script: Enter your script or Winhelp macro here. See the documentation of
Microsoft Help Workshop for details on Winhelp macros.

Note on JavaScript:
JavaScript links are generated as follows:
<a href=" contents of Script window ">
If you are familiar with JavaScript you can use this information to enter
complex scripts. (See the links under See also: below for full details on
this.)

Load from These buttons allow you to save and load blocks of script and macro
File: code that you want to reuse.
Save to File:
Load from file.. loads a text file to the current cursor position in the
script window.
Save to file.. saves the entire contents of the script window to a text

© 1997 - 2009 by EC Software, all rights reserved

 622 Help & Manual 5 - User Help

file.

See also:
Inserting script and macro links 223
Scripts, HTML and Macros 758 (Reference)
9.2.3.6.2 Image

This dialog contains all the options for inserting graphics in your topics. For detailed
instructions see the Working with Graphics 238 chapter. In addition to this also see the The
Impict Screenshot Editor 536 information on the screenshot enhancement and graphics
editing program included with Help & Manual.

The Insert / Open Image dialog:

Dialog options:
Open file The upper part of the window is a standard Windows file open dialog.
options:

File name: The image file you want to insert. You can select a file from the
directory above with the mouse or type the filename here. You can also
use wildcard characters (? and *) to filter the directory. For example
typing *.jpg will only display the JPG files in the current folder and
???.gif will only display GIF files with 3-character names.

Files of type: This drop-down list filters all the graphics file formats supported by Help
& Manual. You can display all the supported files or only files of specific

© 1997 - 2009 by EC Software, all rights reserved

 Reference 623

types.

Picture: This box displays a thumbnail preview of the currently selected

graphics file and the dimensions of the file. Click on the thumbnail to
display a full-size preview of the selected graphics file.

Picture ID: Text you add here is inserted in the <img> tag as an ID attribute in
HTML-based output formats. This is only relevant if you want to
manipulate your HTML code manually and need to reference your
images with ID attributes.

Tooltip: Text you enter here is added to the <img> tag as the ALT attribute in
HTML-based output formats so that it will be displayed as a tooltip
when the user positions the mouse over the image.
Note: If you leave this field blank the image filename will be exported
as the tooltip unless you turn this off in Configuration > Publishing
Options > Webhelp / HTML Help > HTML Export Options.

Alignment: These options define how the graphic will be aligned in your output.
With text
The default setting. Treats the graphic as though it is a character in the
text. It flows with the text without any wrapping.
Left of text
Positions the graphic to the left of the text and wraps the text around it
to the right.
Right of text
Positions the graphic to the right of the text and wraps the text around it
to the left.
Note that the left/right of text formatting is not displayed in the editor. It
is only shown in the output.
Left/right of text is an electronic help format feature. It is not supported
in PDF or Word RTF. Use tables to position graphics in these formats.

Spacing: This defines an invisible margin around the edge of the graphic,
between the graphic and text and any other objects on the page. Enter
a value in pixels.

Zoom %: This setting allows you to resize graphics 242 precisely by percent. It has
the same effect as selecting the graphic in the editor and resizing it by
dragging with the mouse.
Graphics resized with this method are not physically altered until you
compile. When you compile to PDF the full original format is used so
that you get better quality printing. In all other formats the graphics are
physically scaled to the displayed size when you compile.

Caption: Text displayed as a caption beneath the graphic. This text is always
centered and automatically uses the standard style Image Caption. You

© 1997 - 2009 by EC Software, all rights reserved

 624 Help & Manual 5 - User Help

can format it manually by selecting the graphic in the editor window and
then selecting text formatting options.

Opens the Hotspot Editor 624 , with which you can add clickable areas
with hyperlinks to your graphics.

9.2.3.6.3 Hotspot editor

The hotspot editor enables you to define "clickable areas" in your graphics and associate all
the different types of hyperlinks with them that are supported by H&M. When the user clicks
on the hotspot area in the graphic it is exactly the same as clicking on a hyperlink of the
same type in the topic text.
The parameters of the different kinds of hotspot hyperlinks are exactly the same as those for
normal hyperlinks. For details see Links, Anchors, Macros, Scripts and HTML 214 and
Graphics with hotspots, macros and scripts 246 .

The Picture Hotspot Editor:

Dialog options:
Toolbar options:
Inserts a topic link hotspot.

Inserts an Internet link hotspot.

Inserts a file link hotspot.

Inserts a script link hotspot.

Aligns the hotspots in a vertical row with the first hotspot selected.

Aligns the hotspots in a horizontal row with the first hotspot selected.

Deletes the hotspot (same as pressing the Delete key).

© 1997 - 2009 by EC Software, all rights reserved

 Reference 625

Selected Shows the properties of the selected hotspot. You can adjust the size and
hotspot: position of the hotspot by dragging with the mouse or by entering values
here.

Rectangl Choose a rectangular or an elliptical hotspot.

e/
Ellipse:

Title: Adds a title attribute text to the hotspot link.

Hyperlink settings:
The settings of the various hyperlink types are exactly the same as those for normal
hyperlinks in the topic text. For details see Links, Anchors, Macros, Scripts and HTML 214
and Graphics with hotspots, macros and scripts 246 .

See also:
Graphics with hotspots, macros and scripts 246
Links, Anchors, Macros, Scripts and HTML 214
9.2.3.6.4 Movie

This option is used to insert movies in your topics for the output formats that support them.
See Flash Animations and Video 269 for details.

Insert Movie / Movie File tab:

File name: Name and path of the movie file. Use the browse button to select a
movie file to insert.

Placeholder Preview of the graphic image that will be displayed in your topic to
image: represent the movie file.

Select Click here to insert a placeholder image. You can take a snapshot from
Placeholder: the movie or insert a an image from a graphics file or the Windows
clipboard.

© 1997 - 2009 by EC Software, all rights reserved

626 Help & Manual 5 - User Help

Width / Shows the dimensions of the movie as found by Help & Manual.
Height: Sometimes movie files report these values incorrectly. If this happens
you can adjust the values here so that they match the real dimensions.
Don't try to adjust these values to scale movies! The results will
generally be terrible! Only use them to correct dimensions to the actual
values.

Start Play the movie automatically as soon as the page is displayed. If you
automatically do not select this the movie may not play properly in the case of some
: video formats and/or browsers.

Loop Repeat the movie indefinitely.

playback:

Show Display simple player controls for the user. You may need to activate
controls: this option in the case of some video formats and/or browsers. This
option is not displayed for Flash movies, which must have their own
embedded controls.

Requires Enter the version of the Flash plugin or player required to play your
Flash: Flash movie. If the user has the incorrect version they will be prompted
to upgrade before playing.

Insert Movie / HTML Code tab:

This tab displays the HTML code used to embed the movie in HTML-based output
formats (HTML Help and Webhelp) and allows you to edit it if you want to. Requires
advanced HTML knowledge and familiarity with the relevant ActiveX controls.
Selecting I want to enter the embedded HTML code displays the code and allows you to
edit it.

See also:
Adding Video Files 269

© 1997 - 2009 by EC Software, all rights reserved

 Reference 627

9.2.3.6.5 Anchor

Inserts and anchor in your topic. An anchor is a "jump target" within a topic that enables you
to define hyperlinks that jump to specific positions in topics.

The Insert Anchor dialog:

Dialog options:
Anchor ID: An alphanumeric ID that is used as the address of the anchor. Use a
descriptive ID that is easy to identify. These IDs are displayed in the
tab and in the Insert Hyperlink dialog.
You cannot use spaces or special characters. A warning will be
displayed if you try to use illegal characters.

Help Context: You can assign help context numbers to anchors so that you can make
context-sensitive calls to specific positions inside topics. If you have
activated the automatic generation 205 of context numbers for anchors a
number will be displayed here automatically.

Keywords: You can also assign index keywords to anchors (normal K-keywords
only, A-keywords 281 are not supported here). If you do this selecting the
keyword in the index will jump to the anchor instead of the top of the
topic.

See also:
Anchors - jump targets 226
9.2.3.6.6 Text Variable

This simple dialog displays the list of available text variables for insertion in your topic. The
list includes both Help & Manual's predefined variables and any variables you have defined
for your project.
When you insert variables with this dialog they are highlighted in green in the editor, which
makes them easier to identify. This is only a convenience, however. You can also enter
variables by typing them directly in the editor. When you compile your output Help & Manual
will still identify them.

© 1997 - 2009 by EC Software, all rights reserved

 628 Help & Manual 5 - User Help

The Insert Text Variable dialog:

Selecting More... displays the Text Variables section in your Project Configuration so that
you can edit existing variables or add new ones.

See also:
Using Variables 376
9.2.3.6.7 Conditional Text

This dialog is used to insert include option conditions in your topics to control what is
included and excluded from your output on the text level. See Conditions and Customized
Output 399 for more details.
Note that conditions set in the text work in combination with the options you select in the
Compile Help File 590 dialog when you compile your project.

The Insert Text Condition dialog:

Dialog options:
IF Marks the beginning of a positive include option condition for all the
options selected in the list on the right (tagged content is included if the
condition evaluates TRUE). You can select multiple conditions.
The text and other content enclosed by the condition will be included in
your output if one or more of the selected conditions are fulfilled (OR
logic).

© 1997 - 2009 by EC Software, all rights reserved

 Reference 629

IFNOT Sets the beginning of a negative include option condition for all the options
selected in the list (tagged content is included if the condition evaluates
FALSE). Here too, you can select multiple conditions.
The text and other content enclosed by the condition will only be included
in your output if none of the selected conditions are fulfilled (OR logic).

ELSE Marks the beginning of text to be included if the previous condition is not
fulfilled. This tag must be inserted between a pair of IF/ENDIF or
IFNOT/ENDIF condition tags.
For example, if the output format is HTML Help (CHM) the following
condition will output TEXT 1, otherwise it will output TEXT 2:

ENDIF Marks the end of an IF or IFNOT condition. If you select text in the editor
before invoking this function the ENDIF tag is added automatically at the
end of the selected text.

Opens the dialog for defining and editing user-defined include options.

See also:
Conditions and Customized Output 399
Compile Help File 590
Publishing Your Projects 311
9.2.3.6.8 Toggle

This dialog is used to insert expanding sections, text and images, known as Toggles 350 , in
your topics. There are two versions of the dialog, depending on whether you choose the
Expanding Text or Screenshot Toggle option a the top of the dialog.

The Insert Toggle dialog – Expanding Text mode:

© 1997 - 2009 by EC Software, all rights reserved

630 Help & Manual 5 - User Help

Insert Toggle dialog options for expanding text:

Export These options control whether the toggle is expanded or collapsed in
Options: your output. Normally, toggles are expanded in print formats (PDF,
printed manuals and Word RTF) and collapsed by default in supported
electronic formats.
Note that toggle switching is not supported in Winhelp and Windows
Exe or ePub eBooks and so toggles are always displayed expanded in
these formats.
Optional ID: This is optional and we recommend that you leave it blank. You
only need to enter an ID here if you plan to access the toggle IDs in the
HTML code of your output for any reason.
If you leave this field blank Help & Manual will give each toggle a unique
internal ID. If you enter your own ID you must make sure that each ID in
the current topic is unique and you must also edit your IDs manually if
you copy your toggles, otherwise you will have ID conflicts.
Caption: This is the "header" of your expanding section. It is also the active link
that the user clicks on to expand or collapse the section. (If you select
text before inserting the toggle the text will automatically be displayed
here).
Link style: Selecting this displays the toggle header formatted as a normal
hyperlink, deselecting it displays the header as plain text (it is still an
active link).
For more details on formatting toggle links see below and in the
Formatting toggle links 361 topic.
Tooltip: Text you enter here is displayed as a mouseover tooltip when the user
positions the mouse pointer over the toggle header.
Icon: This option allows you to choose the image to be displayed to the left of
the toggle header. You can choose no icon, one of the three standard
icons or use your own icons.
If you choose a standard icon the icon files (one for each state) will be
copied to your project or graphics directory the first time you select the
function.
If you choose to use your own icons you can then select the graphics
for the two icon states in the Collapsed: and Expanded: fields. We
recommend storing the icons in your standard graphics folder 249 or your
project folder. See below 351 for more details on using your own icons for
expanding sections.
Toggle a Table: This option creates an expanding section toggle.
Create a new table:
This is the standard option. It automatically creates a new, single-cell
table for the text that you want to expand. This table is inserted directly
after the toggle header (caption). The table and the header are both
automatically indented by the same amount from the icon.
Toggle the table below this link:

© 1997 - 2009 by EC Software, all rights reserved

 Reference 631

This option is displayed if there is a table directly below the current

position and it allows you to toggle an existing table. There can be a
maximum of one paragraph of empty space between the toggle header
and the table.
Toggle Inline This option creates an expanding inline text toggle.
Text:
Enter your text in the editing box. You cannot enter any formatting in
this box. You can enter hard returns with enter for easier editing but
they will be ignored in the generated toggle.
Format text Applies a style to the expanding inline text, for example to make it stand
with Style: out against the rest of the text in the paragraph.

The Insert Toggle dialog – Screenshot Toggle mode:

Insert Toggle dialog options for expanding images

Export These options control whether the toggle is expanded or collapsed in
Options: your output. Normally, toggles are expanded in print formats (PDF,
printed manuals and Word RTF) and collapsed by default in supported
electronic formats.
Note that toggle switching is not supported in Winhelp and Windows
Exe or ePub eBooks and so toggles are always displayed expanded in
these formats.
Optional ID: This is optional and we recommend that you leave this field blank.
You only need to enter an ID here if you plan to access the toggle IDs in
the HTML code of your output for any reason.
If you leave this field blank Help & Manual will give each toggle a unique
internal ID. If you enter your own ID you must make sure that each ID in
the current topic is unique and you must also edit your IDs manually if
you copy your toggles, otherwise you will have ID conflicts.
Picture file This is the full-size image to be used in your toggle. Click on the
name: Browse button to select an image file directly.

© 1997 - 2009 by EC Software, all rights reserved

 632 Help & Manual 5 - User Help

Spacing: Inserts spacing around the image. The value is in pixels.

Tooltip: The tooltip and caption you enter here are normally displayed in both
Caption: the expanded and the collapsed states. The texts are automatically
copied to the When Collapsed: fields, which are grayed out unless you
select them to enter different texts there.
The tooltip is displayed when the user positions the mouse pointer over
the image. The caption is displayed beneath the image using the
standard image caption style 176 .
When Normally, the toggle will use the same image, tooltip and caption for
collapsed use both the expanded and the collapsed states. You can select the options
different here to use a different image and enter a different tooltip or caption.
settings:
Picture: Select this option to use a different image 357 in the collapsed state.
Alternatively you can use your own image for the thumbnail version. If
you do this you must create this version yourself with Impict 536 or your
favorite graphics program. You must create the image with the correct
size you want to display – Help & Manual will not zoom the image for
you.
Tooltip: Select these options to enter a different tooltip and/or caption for the
Caption: collapsed state.

See also:
Toggles: Expanding Text and Images 350
9.2.3.6.9 HTML Code Object

This function is designed for advanced users with a good knowledge of HTML. It is used to
insert your own inline HTML code to be included in HTML Help and Webhelp output. Code
you insert with this function is ignored in all other output formats.
The code you enter here is inserted directly in the output page at the point in the text where
you insert it. Your code will not be checked or parsed in any way by Help & Manual – you
are entirely responsible for making sure that it works yourself. If you include references to
files you must also make sure that they are accessible.

The Insert HTML Code dialog:

You don't need to insert any normal page tags like <HEAD> or <BODY> and so on. these
tags already exist in the output pages.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 633

Dialog options:
Just type the code you want to insert in the editing window. You can increase the window
size by dragging the lower right corner.
Load from Saves the contents of the editing window to a text file so that you can
File: reuse it.

Save to File: Loads the contents of a text file to the current cursor position in the
editing window.

See also:
Inserting plain HTML code 231
9.2.3.6.10 Comment

This function inserts a comment in the current topic with information, reminders or questions
for the authors or reviewers of the project. Note that comments are an editing aid only – they
are not included in your published output!

The Insert Comment/Bookmark dialog:

· Just type your comment in the editing box and click on OK to insert it at the cursor
position.
· Show comment as icon only displays the comment as a red "pin" icon in the editor.

See also:
Comments and bookmarks 143
Image caption and comment styles 176
9.2.3.6.11 Snippets

This option inserts a topic from the current project or an external Help & Manual XML topic
or snippet file in the current topic at the cursor position. You can insert snippets in two
modes: Paste and Linked. Pasted snippets are just like normal pasted text from any other
source. Linked snippets are dynamically linked to the source topics or files and will updated
automatically when the sources are edited.
When you compile your project a copy of the linked snippets is inserted in the output
linked snippets are only dynamic while you are editing.

© 1997 - 2009 by EC Software, all rights reserved

634 Help & Manual 5 - User Help

The Insert Snippet Dialog From Topic

This dialog inserts topics from the current project as snippets. Just select the topic ID of
the topic you want to embed from the list and click on OK to insert it.
You may want to exclude the source topics from your output (for example for HTML Help
or Winhelp). If you do not do this the source topics will also be included in the help file
and the user will be able to find them with Search, which may not be what you want.

Dialog options:
Select Select the topic ID of the topic you want to insert as a snippet.
topic:

Copy & Pastes the contents of the snippet file at the cursor position. After this you
Paste can edit it normally, just like any other text. Pasted snippets are not linked
to the source file.

Snippet is Creates a link to the original topic. The contents of the snippet cannot be
linked edited in the editor but they will update automatically when the original
topic is changed.

The Insert Snippet dialog From File:

This option is for inserting snippets from external XML topic files. You can create these
files from topics and from selected text in topics with File > Save Snippet in Project >
Manage Topics.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 635

Dialog options:
Snippet The snippet file you want to insert. This must be a valid Help & Manual
file: XML topic file or snippet file. You can create snippet files from topics and
selected text with File > Save Snippet in Project > Manage Topics.
Help & Manual Professional only:
If you are using Help & Manual Professional you can save your projects in
the uncompressed XML format (.hmxp option). When you do this you can
load any topic file from another project directly as a snippet.

Copy & Pastes the contents of the snippet file at the cursor position. After this you
Paste can edit it normally, just like any other text. Pasted snippets are not linked
to the source file.

Snippet is Creates a link to the snippet file. The contents of the snippet cannot be
linked edited in the editor but they will update automatically when the original
snippet file is changed.

Use project Select this to add the path to the snippet file to your Project Search Path 656
search in Configuration > Common Properties in the Project Explorer. If you
path do not select this option the path to the snippet will be stored in the topic
with the snippet and the link to the snippet will be dead if the snippet is
ever moved.
It is a good idea to use this option and to keep your snippet files organized
in easily-accessible directories. You can then move your snippets and
Help & Manual will still be able to find them if you update the Project
Search Path. This will make it easier to transport your entire project and to
send out all the components of your project for translation if this ever
becomes necessary.

See also:
Using embedded topics 149
9.2.3.6.12 OLE Object

This function inserts an OLE (Object Linking & Embedding) object in the editor screen. An
OLE object is a document created by another program. If you double-click on the object in
the Help & Manual editor the document will be opened with its associated program so that
you can edit it.
Depending on how you create them, OLE objects are either embedded in your topic file or
inserted as links. We recommend using the link method, this generates fewer overheads
and allows you to edit the files without opening Help & Manual.
Important: OLE objects are only linked in the Help & Manual editor. In your compiled output
they are just bitmap graphics. This is necessary because the documentation formats do not
support live OLE objects.

© 1997 - 2009 by EC Software, all rights reserved

636 Help & Manual 5 - User Help

The Insert OLE Object dialog:

When you compile your output OLE objects are converted to bitmap graphics. They are not
exported to your published files as active links – this is impossible in the Help & Manual's
output formats. This means that you cannot use all types of OLE objects supported by your
Windows installation. For example, you can't insert movies as OLE objects because they
would be converted to static bitmap images.
Create from File mode dialog options:
Create from Insert an existing file as an OLE object.
File:

Create New: Open an OLE-enabled program to create a new OLE object. See
below.

File: Click on Browse to select the file to insert. This file does not have to be
in your project folder.

Link: Inserts a link to the file instead of embedding it in your project.

Recommended – this reduces system overheads and makes it possible
to edit the linked file without opening Help & Manual.
If you deselect this option a copy of the file will be embedded in your
project and you can only edit it by double-clicking on it in the Help &
Manual editor.

Display as Displays an icon to represent the object in the editor instead of the
icon: contents of the OLE object file.

Create New mode dialog options:

Create New: Opens the associated program to create an OLE object and embed it in
your project file. This method is not recommended. It creates
considerable system overheads and you cannot edit the object as an
external file. Create from File (see above) in Link mode is always
preferable.

Create from Switches to Create from File mode. See above.

File:

© 1997 - 2009 by EC Software, all rights reserved

 Reference 637

Object Type: Select the program with which you wish to create the document for the
OLE link. Only use programs that generate documents that can be
converted to a single bitmap graphic, such as Word or Excel.

Display as Displays an icon to represent the object in the editor instead of the
icon: contents of the OLE object file.

See also:
Using OLE Objects 494
About using OLE objects 757
9.2.3.6.13 Special Characters

This function allows you to insert special characters not available directly via the keyboard. A
number of common special characters are available from the menu. Clicking on More
Symbols... displays the following dialog:

The Insert Special Character dialog:

· Just select the font you want to use, then select the character and click on Insert to
insert it in the editor at the current cursor position.
· You can increase the size of the character map for easier viewing by dragging the
bottom right corner of the dialog window.
· Note that in most output formats the font you use must be installed on the user's
computer for special characters to be displayed properly! This is particularly important
for help formats like HTML Help and Winhelp. If you need characters from special fonts
here it is better to use small graphics.

See also:
Special characters, lines and breaks 143

© 1997 - 2009 by EC Software, all rights reserved

 638 Help & Manual 5 - User Help

9.2.4 The Table Tab

This menu contains the options for inserting and manipulating tables in your topics. Most of
these options will only be active when the cursor is actually in a table or when you have
selected all or part of the table.
Table styles:
Note that you must select Properties to select a style for the current table. To define
table styles go to Write > Styles > Edit Styles.

Table tab options:

Select: Selection options for selecting all or part of the current table.

Properties: Opens the Table Properties dialog to edit the properties of an existing
table. You must select this if you want to set or change the style for the
current table.

New Table: Opens the dialog for defining and inserting a new table at the current
cursor position. Same options as in the Write tab.

Rows and Insert and delete table rows and columns.

Columns

Merge Options for merging, splitting and unmerging table cells and rows. Only
works on selected cells.

Lock Column: Locks or unlocks the width of the selected column or columns. When
column width is locked the column will not become wider or narrower
when the user resizes the viewer window on the screen. Tables with a
percentage width must have at least one unlocked column.

Alignment: Sets the alignment of text within cells.

See also:
Working with Tables 253
9.2.4.1 Table Properties

This dialog is displayed by clicking in a table and selecting Properties in the Table tab. It
defines or changes the formatting, layout and appearance of entire tables and selected parts
of tables. It is also displayed automatically when you create a new table. See Working with
Tables 253 for details on creating and using tables.

The Table Properties Tab:

The properties in this tab are applied to the entire table.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 639

Table Size
Rows: If you are creating a new table these values define the total number of
Columns: rows and columns in the table.
In an existing table increasing the values adds rows and columns in the
last row and column and decreasing the values deletes rows and
columns from the last row and column (i.e. rightmost column and
bottom row).
For more precise control over adding and deleting rows and columns
use the Insert and Delete functions 259 in the Table menu.

Table ID: This setting is optional. It assigns an ID attribute to the <table> tag
that you can reference in your own HTML code.
Most users should leave this blank. Only use it if you really plan to
reference your tables by ID with your own HTML and CSS code.
If you assign your own IDs to the tables used in toggles 351 you must be
very careful not to use the same ID more than once in any topic If you
do your toggles will not work properly.

Layout
Table Style: Selecting this applies the selected table style 263 to the table. Any
attributes you change after applying a style will not be under the control
of the style they are like manual formatting in a paragraph formatted
with a style.

Table can Tables can now split automatically at page boundaries for PDFs and
split to next printed manuals generated with Application Button > Print User
page: Manual 575 .
Page breaks are possible inside table rows but not in rows containing
nested tables 266 .

Number of The heading rows option repeats the first x rows of the table at the top
heading of the table when it is continued on the following page.
rows:
If you enter 0 for the heading rows the table will not have a heading.

Head row The background color for the heading row

color:

Alternating Background color for alternating table rows. The main background
row color: color is set by the Table has solid color: setting (see below). This
setting defines the color for every other row.

Autosize Creates a table that calculates its size on the basis of the contents of its
table: cells. The absolute width of the table in your output will depend on how
you adjust the width of the cells and the table itself and the content you
put in them.
In the editor an autosized table initially occupies the full available width

© 1997 - 2009 by EC Software, all rights reserved

640 Help & Manual 5 - User Help

of the current paragraph (if the paragraph has indents the table will be
narrower than the page). You can adjust column widths with the mouse
after adding content (note that this locks the width 256 of the columns).
In PDF, printed manuals and RTF autosized tables appear exactly as
the are displayed in the editor, filling the entire width of the paragraph/
page.
In HTML-based output formats autosized tables are only as wide as
their content. If all columns contain full paragraphs the table will be as
wide as the page but if the columns only contain small amounts of text
the table will be narrower than the page.

Size table to Creates a table that is permanently maximized to the width of the
fit on page: current paragraph (if the paragraph has indents the table will be
narrower than the page). This is exactly the same as setting a width of
100% with the Size manually option.
Tables sized with this option always occupy the entire available width of
the current paragraph or page. They can only be made narrower by
increasing the left and/or right indents of the paragraph.
The same applies for tables inside other tables: If paragraph containing
the table is indented the 100% value is the width of the indented
paragraph, otherwise it is the width of the cell containing the table.

Size table Creates a table with a fixed width in percent or pixels, relative to the
manually: width of the current paragraph. Setting a value of 100% is exactly the
same as Size table to fit on page.
Here too, percentage values are always relative to the paragraph
containing the table. If the paragraph is indented the value is a
percentage of the width of the indented paragraph; otherwise the value
is a percentage of the page width or the table cell width, if the table is
inserted inside another table.
Note that as in HTML tables, pixel values are "preferred values" rather
than being absolute. If you insert graphics or other objects that are
larger than these values the cell widths will be adjusted automatically
so that the objects fit, and the other cells will be made narrower
accordingly.

· Note that all automatic width adjustment features can only work if the width of at least
one of the table's columns is dynamic (i.e. has no set width).
· To set/reset click in a table column or select one or more columns. Then select Table
> Lock Column Width or right-click and select Table > Lock Column Width.

Background and Borders

These settings define the background for the entire table. You can define the background
color for individual cells in the Selected Cells 638 tab.
Table is This makes the background of the page visible through the table.
transparent:

© 1997 - 2009 by EC Software, all rights reserved

 Reference 641

Table has This selects an opaque background color. If you also set a color for
solid color: alternating rows (see above) this color is only used for the alternating
rows of the table.

Background This allows you to use a graphics file as the background for your table.
picture: See Using background graphics 267 in the Working with Tables
chapter for details.
Select Tile to repeat the background picture, Center to center it in the
table.

Cell Borders
These settings work just like the formatting parameters for borders and cell spacing in
HTML tables. In all settings a value of zero turns the property off (i.e. no borders).
Cell borders: This defines the width of borders around the cells inside the table.

Border This defines the border around the edges of the table.
around table:

Border color: This defines the color of all borders

Border style: This defines the appearance of the border. This is easier to see than to
describe – just try it out!

You can’t define different colors for individual cell borders. However, you can achieve this
by inserting a second table inside your main table. See Nested tables 266 for details.
Cell Padding and Spacing
Cell padding: This is the space between the edge of the cell contents and the border
of the cell.

Cell spacing: This is the space between the border of one cell and the border of the
next cell. This is effectively like making a broader border between the
cells but it doesn't affect the width of any border lines you define
between the cells.

You can only define padding and spacing for the entire table. If you need different
settings for individual rows, columns or cells you can achieve this by using nested tables
266 .

The Selected Cells tab:

The properties in this tab are applied to selected cells only. If no cells are selected the
Selected Cells properties are applied to the cell in which the cursor is located.
To apply these options to a single cell just click in the cell you want to format before
selecting Table Properties. You don’t need to drag to select a single cell.
Cell Options
Note that adjusting the size of cells manually with the mouse automatically resets the
settings configured in this section.

© 1997 - 2009 by EC Software, all rights reserved

 642 Help & Manual 5 - User Help

Preferred This sets the target width of the selected cells/columns in pixels or
width: percent. Percent values are relative to the width of the table. If this is
set to 0 the automatic width is calculated as the table width divided by
the number of columns, unless graphics or other objects force different
widths for individual columns.
If you set the preferred width to a non-zero percent or pixel value the
editor will attempt to achieve the specified value but the widths will be
adjusted if it is not possible. The width of content such as graphics or
other objects always has priority. If you insert an image wider than the
preferred width the cell will be made wider so that the image fits, for
example.

Height at This is the minimum height of the cell/row. If it is 0 the height is

least: calculated automatically on the basis of the cell contents. If it has any
non-zero value the cell/row will be at least that high, and higher if
necessary to accommodate the content.

Background Sets a different background color for individual cells.

color:

Vertical alignment
Top / Center: These options control the vertical positioning of text and other content
Bottom / within the selected cells. They are pretty self-explanatory.
Default:

See also:
Working with Tables 253
9.2.5 The View Tab
The View menu contains options for changing Help & Manual's appearance and behavior.
In addition to changing the color and style of the program window you can also access the
Program Options 643 dialog with extensive configuration options for all aspects of the
program.
Most of the settings in these dialogs are self-explanatory. For more details see Options &
Keyboard Shortcuts 31 .

Productivity Tip
We have left extra room in this tab to allow
you to customize it for your own needs.
You can use it for storing your own set of
Help & Manual functions and controls
use the Ribbon customization options in
Program Options.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 643

View menu options:

Program Options Customize the way Help & Manual works, see Program
Options 643 for full details.
Also available in the Application Menu 574 .

Appearance Change the program appearance and reset default settings.

Defaults The Appearance settings are also available in Program
Options - Ribbon.

See also:
Customize 643
Customizing Help & Manual 31
9.2.5.1 Program Options

This menu contains the settings for configuring how Help & Manual itself works. These
settings are all saved with the program, as opposed to the settings in Project Configuration
652 which are all saved with individual projects.

It is a good idea to check through these settings before you start working with Help &
Manual. You may be surprised at all the things you can adjust and configure!

See also:
Project Properties 652
Options & Keyboard Shortcuts 31
9.2.5.1.1 Program Options - General

These options control how Help & Manual starts up, automatic backups, automatic update
checking and some other general features.

© 1997 - 2009 by EC Software, all rights reserved

644 Help & Manual 5 - User Help

Automatically Checks for the availability of a more recent version of Help & Manual.
check for New versions are published regularly, both to provide new and
updates: improved functions and to correct issues reported by users.
Note that this only works if you are connected to the Internet. Also, if
you are behind a firewall you may need to configure your firewall
settings give the Help & Manual program helpman.exe permission to
access the Internet.
What does checking "now and then" mean in this option? Here's what
the programmer has to say about it:
It means that it checks for updates not every time you start it, but
more frequently than once a month. It will check more often in the
beginning and less often if it gets frustrated because it hasn't
successfully detected an update for a while. That could be once a
week or so. But it never checks for updates on Sundays and
occasionally does on weekdays, except if the day is a holiday in
Austria. It only checks for updates when it is idle and there are no
other urgent tasks to process and it stops checking when it finds
that you are on lunch break (it figures you will not read the
message while you are away).
Note: The above is not entirely serious...

Visual effects Turn this on if the user interface display in the Project Explorer
are seems to be too slow on your system.
performance-
optimized:

Show Recommended! When this is activated little tooltip popups are

mouseover displayed when you position the mouse cursor over toolbar buttons
hints for and objects in the editor. These popups contain a lot of useful
buttons and information for your project. They are like an extra status bar for
objects in text: links, graphics etc.

Automatically Also recommended, particularly if you are one of those authors who
back up project concentrate so much on their project that they forget to save their
file every xx work regularly! This function creates a backup copy of your project
minutes: file in the project directory at the specified intervals.
The backup files are saved in single-file compressed mode with the
extension .hmxz~~ to make them readable Help & Manual projects
just delete the ~~ characters from the file extension.

Open last help Automatically loads the last project(s) you had open when you start
project on Help & Manual.
start:

Empty Automatically clears the Windows Clipboard when you exit the
Clipboard when program.
Help & Manual
closes:

© 1997 - 2009 by EC Software, all rights reserved

 Reference 645

Default image By default Help & Manual starts the integrated Impict graphics editing
editor: program when you click on graphic in the Help & Manual editor and
then select the Image Editor tool in the Project tab. This setting
allows you to change this to a different graphics editing program.

See also:
Options & Keyboard Shortcuts 31
9.2.5.1.2 Program Options - Ribbon

You are free to configure the Ribbon toolbar to suit your own preferences. If you wish, you
can completely rearrange all the tools in all the Ribbon tabs. However, be warned that if you
do this referring to the help will become difficult, because the documentation always refers to
the standard layout.
Tip: You can use the View tab as your own personal tab. We have intentionally left this tab
almost empty and all the standard functions can be removed because they are also
available elsewhere. The Quick Access Toolbar can be customized directly and the
Program Options are also available in the Application Menu.

© 1997 - 2009 by EC Software, all rights reserved

 646 Help & Manual 5 - User Help

Ribbon color Change the colors of the Ribbon and the entire program interface.
scheme:

Ribbon tab: Selects the Ribbon tab you want to customize.

Groups in this The function groups included in the selected tab. Select and use
tab: Remove>>, Move Up and Move Down to edit.

Available Shows all the available function groups. To add a group to the current
groups: tab select it and then click on <<Add.

Reset Returns all the Ribbon settings to the default configuration.

defaults:

See also:
Project Properties 652
Options & Keyboard Shortcuts 31
9.2.5.1.3 Program Options - Shortcuts

You can use these options to assign keyboard shortcuts to most program functions. You can
also change the standard keyboard shortcuts that are already assigned if you want, although
this is generally not recommended.
Just click on the option you want to assign a new or different shortcut to, then select the
shortcut in the Current Shortcut: fields.

Current These two fields select the letter (right) and the control key (left). Select
shortcut: the letter key first for options that do not yet have a shortcut assigned.

Resets all the shortcuts to the default settings that Help & Manual has
when it is freshly installed.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 647

See also:
Project Properties 652
Options & Keyboard Shortcuts 31
9.2.5.1.4 Program Options - Editor

These options adjust the appearance and behavior of the Help & Manual editor.

© 1997 - 2009 by EC Software, all rights reserved

648 Help & Manual 5 - User Help

Ruler units: You can select pixels, inches, centimeters or points. Pixels are
recommended for maximum accuracy – Help & Manual handles all
sizes internally in pixels and all other units must be converted.

Display a vertical Display a vertical ruler to the left of the editor as well as a
ruler: horizontal ruler.

Show paragraph Makes tabs, paragraph end marks and spaces visible in the editor.
and text marks in This can be useful for identifying formatting problems. Can also be
editor: switched on and off with in Write > Paragraph .
Show spaces:

Custom DPI Changes the font size used to display text in the editor pane. This
settings for text does not affect your output, it is only to make text easier to read
editor: while you are working. It can also help you to get an idea of what
your text will look like on computers with larger fonts set in
Windows.
This setting can also be changed with the DPI setting in the status
bar at the bottom of the main Help & Manual program window.

Font settings for Allows you to select a different font for the XML source code editor
XML and HTML and the HTML code editors used for HTML templates, HTML code
editors: objects etc.
Only fixed-space console fonts like Courier New or Lucida Console
will look good in these editors.

Show strong Uses darker and slightly thicker grid lines to show the borders of
table grid lines in tables. Can be useful to make tables more visible on some
edit mode: monitors.

Automatically When this setting is active Internet URLs and email addresses will
detect URLs while automatically be turned into Internet links 218 as you type.
typing text:

Auto-correct Topic IDs containing blanks are invalid in many output formats so
blanks in topic we strongly recommend leaving this option active.
IDs:

Apply status to Choose a status (highlight color and name) to be applied to new
new topics: topics automatically. Note that only the standard status settings
(Needs Review, Out of Date, Under Construction) can be used for
this. User-defined status settings are stored with your project, not
with your program settings, and are thus not available here.

After changes set Automatically change the topic status to the value you specify after
status to: editing changes have been made.

Display color for Sets a custom color for highlighting read-only topics and other
read-only TOC items in the TOC. This is mainly relevant for multi-user editing and
items: can make locked topics easier to identify in the TOC.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 649

See also:
Project Properties 652
Options & Keyboard Shortcuts 31
9.2.5.1.5 Program Options - Compilers

These options configure the paths to the Microsoft compilers used to generate HTML Help,
the obsolete Winhelp format and Visual Studio Help / MS Help 2.0. You can also select the
compiler messages to display during compilation. The paths to these compilers will usually
be found automatically during installation. Only change them if you really need to.

© 1997 - 2009 by EC Software, all rights reserved

 650 Help & Manual 5 - User Help

Compiler It is a good idea to leave all these messages activated as they make it
messages: much easier to identify problems when you are compiling.

Export This setting is used to prevent dead links if when you are excluding
excluded topics from your output with Help & Manual's conditional output tools.
topics if When this is selected excluded topics will be exported anyway if they
referenced: are referenced in links in other topics in your project. If it is not
selected you will have dead links in your project.
Topics exported in this way do not have TOC entries they are
exported "invisibly" and will only be displayed when the user clicks on
the links referencing them.

Remove dead This is an alternative method for dealing with dead links to excluded
links to topics. If you select this option Help & Manual will simply delete dead
excluded links to excluded topics when you publish.
topics:
This is really only recommended for testing purposes because the
deleted links may leave gaps in your text!

Tolerant Allows you to compile projects in Asian languages on Windows

handling of systems whose language does not match the language of the help
Asian project. Some features in the help generated may not work properly
languages: (Search, Index) to test these features properly you need a matching
version of Windows.

Help The paths to the Microsoft compilers for Winhelp, HTML Help and
Compilers: Visual Studio Help / MS Help 2.0. You must have these compilers
installed to be able to output your projects to these formats!
Note that the MS Help 2.0 compiler (Visual Studio Help) support is
only relevant for programmers documenting Visual Studio .NET
components. It is irrelevant for all other purposes and cannot be used
as a general help or documentation format for application programs.

Resets all the settings and paths to the default values.

Search for Attempts to locate the necessary compiler executable files in your
compilers: Program Files directory.

See also:
Project Properties 652
Options & Keyboard Shortcuts 31
9.2.5.1.6 Program Options - PDF Export

This tab can be used to set a different "reference printer driver" for generating PDF output.
The PDF engine must have a printer driver to generate PDF files – if you don't have any
printer installed on your computer the screen driver will be used to generate PDFs.
PDF output anomalies are often caused by bugs in proprietary drivers from printer
manufacturers. If you experience problems try installing a standard driver for a common
printer from the Windows CD and selecting it here. This doesn't have to be a driver for a

© 1997 - 2009 by EC Software, all rights reserved

 Reference 651

printer that is physically connected to your computer.

Problems with the reference driver used for generating PDF output can also result in
incorrect displays for special characters and international languages. However, if you
experience problems like this first check the language settings 654 of your project to make
sure that everything is set up correctly. If you still have problems in your PDF output after
making sure that your language settings are correct you can try using a different reference
printer driver.
If you are not using WMF or EMF graphics it is generally best to use the screen device to
generate PDFs. A proper printer driver is needed to mange EMF and WMF graphics,
however otherwise these graphics may be clipped in your PDF output.

Use screen as Uses the computer's screen driver as the reference device for PDF
reference output. Help & Manual defaults to this setting if you have no printer
device: installed. This option is generally preferable unless your projects
contain EMF or WMF graphics. If you use EMF or WMF graphics
you should choose a printer driver, otherwise the graphics may not
display or may be clipped.

Use default Uses the default printer driver for PDF output. Leave this setting
reference selected if your PDF output is OK.
device:

Use this printer Use this to select an alternative printer driver to use for PDF output.
driver as a Click on the browse button to select the printer.
reference
device:

See also:
Project Properties 652
Options & Keyboard Shortcuts 31

© 1997 - 2009 by EC Software, all rights reserved

 652 Help & Manual 5 - User Help

9.2.6 The Help Tab

The Help tab provides access to this help file (Online Help), which can also be accessed at
any time by pressing the F1 key. In addition, this menu also contains a number of links to
specific important information and how-to topics in the help and some useful links to the EC
Software website.
You can also check whether you are using the latest version of Help & Manual with the
Check for Update function and send a mail to support with the Customer Support link.

Help Tab options:

Come on, you can figure out the rest yourself, you're a help author!

9.3 Project Configuration Settings

The Configuration section in the Project Explorer menu is the control center for your project.
Unlike the settings in View > Program Options (which are program settings), all the
settings you enter here are stored in your current project and are only available to the
project in which they are stored. They define all the basic parameters for your help project
and how it is output to the formats supported by the program.

Productivity Tip
You can use both user-defined variables
and global variables in the text fields in
your configuration settings. For example
you could use © <%\YEAR%> by <%
AUTHOR%> for your copyright message.

There are three groups of settings in Project Properties: Common Properties, HTML Page
Templates and Publishing Options. In addition to this the

Common Properties:
These settings define things like the name of your project displayed in help window title
bars, copyright messages, language settings, where images and snippet files used in the
project are stored, text variables used in the project and so on. This is also where you will
find the help window definitions used to configure the help viewers used to display
Microsoft HTML Help (CHM) and Winhelp (HLP) formats.
It is always a good idea to check all the settings in this section when you create a new
project.

HTML Page Templates:

HTML-based documentation formats are now predominant and this makes these
templates very important. They define the background colors for the topic pages and their
headers, which are also displayed in the Help & Manual editor. In addition to this they
also define the entire layout of your topic pages in all HTML-based publishing formats:
HTML Help (CHM), Webhelp (HTML), Windows Exe and ePub eBooks and Visual Studio
Help/Help 2.0.
The HTML page templates are combined with the contents of your topic pages when you
publish. The template provides everything above and below <body> </body> tags, the

© 1997 - 2009 by EC Software, all rights reserved

 Reference 653

content from the editor provides everything that goes between the body tags.
Advanced users can edit the source code of the HTML page templates directly to
customize their output in any way they like.

Publishing Options:
These settings are organized in sections by output format. They allow you to control how
each output format is handled, providing a high degree of customization. For example, in
the Webhelp section you can directly edit all the additional HTML templates that define
the frameset and the Contents, Index and Search pages of your Webhelp output. In
HTML Help you can configure different modes for popup topics, in PDF you can choose
between interactive and static PDF files and so on.

9.3.1 Common Properties

Most of these settings are "housekeeping" for your project. They include things like the title
of your project, language settings, customized topic status settings and the locations of
images and snippet files used in the project.
In addition to this section also includes settings for some of Help & Manual's special
features:

Text Variables:
This section allows you to define and store any number of variables for use in your
project. You can use both plain text variables for inserting text anywhere in your project
(also in the TOC, keywords and Configuration) and HTML variables for inserting HTML
code in your HTML templates and HTML code objects.
This is very useful for texts that may change after you create your project, such as
program names and so on. You can then change the texts in your entire project just by
editing the variables, and you are always sure that all instances have been changed.

Custom Builds:
This section allows you to define your own include options 406 . Include options are like
tags that you use to include or exclude text, topics, chapters or entire modules from your
help output. You simply tag content with your include options in your project and then
select or deselect the corresponding options in the Compile Help File 590 dialog when you
compile.

Help Windows:
Help Window definitions are only used in the Microsoft HTML Help (CHM) and Winhelp
(HLP) formats. They control the appearance and features of the Windows help viewers
used to display these formats. In addition to this they can also be used to display
individual topics in external windows when you link to them from your topics.

© 1997 - 2009 by EC Software, all rights reserved

 654 Help & Manual 5 - User Help

9.3.1.1 Title & Copyright

Help title: The title of your help project. The text you enter here can be inserted
anywhere in your project with the <%TITLE%> variable.
For example, in HTML Help and Winhelp you can display it in the title
bar of the help viewers by inserting the <%TITLE%> variable in the Title
bar text: field for the Main help window definition in the Help Windows 660
section (this is the default setting).
In Webhelp this text is inserted in the title bar of the web browser by
using the <%TITLE%> variable in the <title> tag of the frameset file in
the Layout 674 section (this is the default setting).

Author: The author of your help project. This text is not used automatically by
Help & Manual. You can insert it yourself anywhere in your project with
the <%AUTHOR%> variable.

Summary: A short text describing your project. This text is not used automatically
by Help & Manual. You can insert it yourself anywhere in your project
with the <%SUMMARY%> variable.

Copyright: The copyright notice for your project. This text is not used automatically
by Help & Manual. You can insert it yourself anywhere in your project
with the <%COPYRIGHT%> variable.

Comment: Space for a comment about your project. This text is for internal
information and documentation only. There is no corresponding variable
so you cannot insert it in topics in your project.

Major These fields have four corresponding variables that can be used to
Version: generate three-part version numbers.
Minor
Version:
The variables corresponding to the individual components are <%
Build VERSION_MAJOR%>, <%VERSION_MINOR%> and <%VERSION_BUILD%>.
Version: The fourth variable, <\%VERSION%>, combines the contents of the three
fields with dots between them, like this:
6.5.456

See also:
Creating Projects 83
Using Variables 376
9.3.1.2 Language Settings

These settings are very important for correct handling of languages and character sets in
your output. Before making any changes here please study the International Languages and
Unicode 819 chapter in the Reference section carefully. For more detailed instructions for
individual languages please also refer to International languages setup 94 in the Creating
Projects chapter.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 655

Language of Defines the language of the help file. This option controls sorting in the
help file: keyword index and full-text search in the published help file. In addition
to this it also identifies the language to the system for proper handling
of languages with special character sets and languages requiring
Unicode 820 for proper processing.
· The default setting (English United States) works correctly for all
Western European languages and should not be changed unless
really necessary.
· The language setting should be changed for Eastern European
languages (including Greek and Turkish) and the Font character set
setting (see below) should then be set to match.
· This setting must be changed for all Asian languages and other
languages requiring Unicode 820 support (all languages with more
than 255 characters that store characters as two bytes). Here too,
the Font character set must also be set to match. Correct Unicode
support for these languages is not possible without a correct
language setting and a matching font character set setting.

Bi-directional This setting is for activating support for right-to-left languages like
Language Arabic, Hebrew and Farsi. The default is Left to Right and it should
Mode: only be changed if you are working with a right-to-left language like
Hebrew, Farsi or Arabic.
Right-to-left support is only available in HTML Help (CHM). It is not
supported in any other output format.
The setting makes radical changes in the way Help & Manual operates,
switching the direction of all the texts in the editor, TOC and
everywhere else, both in Help & Manual itself and in the compiled
output.

Font Defines the character set to be used both in your compiled help file
character set: and in the Help & Manual editor.
· The default setting (ANSI_CHARSET) should be used for English
and all other Western European languages.
· This option must be set to the correct, specific character set for all
Eastern European languages (including Greek and Turkish).
Furthermore, this setting must match the Language of the help file
setting.
· This option must also be set to the correct, specific character set for
all languages requiring Unicode 820 support (most Asian languages
and other languages with more than 255 characters). In these
languages too it is essential to set both this option and the help file
language option to the correct, matching settings for the language
you are using.

Default font: This is not the default font for your help file! This option only sets the

© 1997 - 2009 by EC Software, all rights reserved

 656 Help & Manual 5 - User Help

font used by Microsoft Winhelp and HTML Help for their dialog boxes
and table of contents entries. The default is MS Sans Serif,8,0 and
both Winhelp and HTML Help are optimized for this font. If you change
this font always test thoroughly before publishing your help.
The value 8 defines the font size and should generally not be changed.
The value 0 defines the character set. You do not need to change the
character set value – if it is necessary Help & Manual will do this for
you automatically when you compile your project.

Default This setting specifies the topic that is automatically displayed when an
("Home") electronic help file is opened (Winhelp, HTML Help, Webhelp,
topic: Windows Exe eBooks). This setting is not supported in ePub eBooks.

See also:
International Languages Setup 94 (Procedures)
International Languages and Unicode 819 (Reference)
Test-compiling Asian languages on non-Asian Windows 313
9.3.1.3 Project Search Path

This section contains the relative paths to folders where you store the graphics and external
snippet files 149 used in your project.

Key Information
The project search paths are all relative to
the project directory the full path is only
shown for information. This makes it easier
to move your project and your graphics
and snippets folders.

How Help & Manual locates graphics and snippet files:

When you insert an image or snippet file in your project Help & Manual only stores the file
name, it does not store the path to the file. It finds the file by searching all the folders
listed in the Project Search Path, in the order in which they are listed.
This makes it easy to move project and graphics folders to other locations. However, it
also means you must be careful to avoid duplicate graphics file names in different folders.
See Managing your graphics 249 for more information.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 657

Controls:
To insert a new entry click on Add Entry and navigate to the folder you
want to add.

To delete an entry click on the entry to select it, then click on Remove
Entry.

The Move Up and Move Down buttons move entries up and down in the
list. This controls the order in which Help & Manual searches folders to
locate graphics files.
Remember that Help & Manual always inserts the first file with a
matching name that it finds with a matching name. If two folders in the
search list contain files with the same name the first file will always be
inserted. The second file will never be found.

See also:
Using Graphics 238
Reusing content with snippets 149
Managing your graphics 249
9.3.1.4 Text Variables

This section allows you to define and store any number of variables for use in your project.
This is very useful for texts that may change after you create your project, such as program
names and so on. You can then change the texts in your entire project just by editing the
variables, and you are always sure that all instances have been changed.

Plain text variables and HTML variables

You can define variables as either plain text variables or HTML variables.
Plain text variables can be used anywhere and everything they contain will be rendered
as plain text, including HTML code.
HTML variables can contain HTML code. If they are used in topics only the plain text part
of the code will be inserted, for example the text portion of a hyperlink. The HTML code is
only used when the variables are used in HTML templates and HTML code objects. If you
insert an HTML variable in locations where HTML code is not supported (for example the
main editor) only the plain-text portion of the variable value will be used. If there is no
plain-text portion nothing will be inserted.

© 1997 - 2009 by EC Software, all rights reserved

 658 Help & Manual 5 - User Help

Controls:
Add a new variable to the list. Variable names can contain spaces.
Variable names are converted to all upper case characters automatically.
After creating a variable select the Type (HTML or Text), then enter the
value in the Value column. There is no effective limit on the amount of text
you can enter. The theoretical limit is 2 gigabytes...

Select to delete variables from the list. Does not check whether the
variable is in use in your project.
Undefined variables will be output to your project as the variable name.
You can search for them and remove them as normal text with Find &
Replace in the Write tab.

Imports a list of variables and corresponding values from a plain text file,
adding them to the project's variable list. You must set the variable type
(HTML or Text) manually after importing the list the type cannot be
stored with the list.
Syntax: VARIABLENAME=Variable value
Enter one variable per line without spaces on either side of the = sign and
with a hard carriage return at the end of each line.
Example:
PRODNAME=Widget Confabulator 3
PRODUCT PATH=\Application\Widget\Program
WEBSITE=<a href="http://www.acmecoyote.com/">Acme Coyote Products</
a>
CURRENT LOCATION=Bombay, India

This function exports the current variable list to a text file, using the same
format as shown above. (You can use this to get a full example of the
format if you like.)
This only includes user-defined variables. Help & Manual's own
predefined variables are not exported.

See also:
Using Variables 376
9.3.1.5 Custom Builds

This section allows you to define your own include options, which are also referred to as
build options. These options s are like tags that you use to include or exclude text, topics,
chapters or entire modules from your help output. You simply tag content with your include
options in your project and then select or deselect the corresponding options in the Publish
590 dialog when you compile.

See Conditions and Customized Output 399 for details on using this function in your projects.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 659

Controls:
Select to add a new user-defined build option.
Spaces and a number of special characters are not allowed in build option
names. They will simply be removed if you enter them. It is best just to use
A..Z and 0..9. All the characters you enter will also be converted to upper
case.
The Display Text is displayed in the lists of build options used in the
program to help you identify the individual options. By default it is the same
as the build option name but you can change it if you want. Just click in the
text in the Display Text column and edit.

Deletes the current build option from the list.

Note that Help & Manual does not check whether you have used the include
option in your project when you do this!
Undefined include option tags used in your topics will still be functional and
since you cannot select them in the Compile Help File 590 dialog they will
always exclude the text they enclose.

See also:
Conditions and Customized Output 399
9.3.1.6 Topic Status

This section allows you to modify the standard "topic status" colors and names that you can
use to identify topics in the Table of Contents while you are working. You can also define as
many custom status types as you like. When you publish your project you can select Export
"complete" only to exclude unfinished topics from your published output.
Controls:
Define a new custom status. You will first be able to define the new status
name then the color picker will be displayed so that you can define the
highlight color. Choose a light color that will not obscure the black text in
the Table of Contents!

Deletes the current status definition from the list. You can only delete
user-defined status definitions. The three standard definitions cannot be
deleted.

Edit the name and color of the current status definition.

See also:
Topic icon, status and timestamps 209

© 1997 - 2009 by EC Software, all rights reserved

 660 Help & Manual 5 - User Help

9.3.1.7 Help Windows

These settings define the appearance and behavior of the help viewers used to display the
Microsoft HTML Help and Winhelp formats. They are completely irrelevant for all other
formats.
These help viewers are components of Microsoft Windows. The settings in the help window
definitions can only control the features provided by the viewers. For more information see
Help Windows 807 in the Reference section.

See also:
Using help windows 121
Configuring Your Output 292
Templates and Secondary Windows 416
Help Windows 807 (Reference)
9.3.1.7.1 General Options

These common properties are displayed at the top of the editing screen and are always
available no matter which tab is selected.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 661

Select Select a help window definition for editing. By default only the
window: standard Main window is defined. Click on Add to create additional
secondary help windows. Remove deletes the current secondary help
window (Main cannot be deleted).

Window This is the identifying name of your help window type, which is
name: displayed in the Help Window: field in each topic's tab. It is
restricted to a maximum length of 8 characters. No spaces or non-
alphanumeric characters are allowed.
You cannot rename a secondary help window once you have created
it.

Title bar text: This is the text displayed in the title bar of the help viewer in HTML
Help and Winhelp. You can enter different texts for secondary window
definitions to display different titles in the title bars of external
windows.
By default this field contains the <%TITLE%> variable, which
automatically displays the text entered in Help Title: field in the Title &
Copyright 654 section, so you only need to change this if you want to
display a different text.

Size and Defines the size and position of the main help viewer for Main and for
position: external windows for secondary help window definitions.
Note that in HTML Help these settings are only used the first time the
help is opened for the main help viewer. After that Windows stores the
user's own settings and re-uses them the next time the help is
opened. The settings will always be used for external windows,
however.

Position The Position Wizard displays a dummy window that you can position
Wizard and resize on the screen to set the size and position values.
If you have a dual monitor system use the position wizard in the
primary monitor and make sure that the primary monitor is on the left:
On dual-monitor systems the 0,0 position is defined as the top left
corner of the primary monitor, so doing this will make sure that the
resulting values also work on single-monitor computers.

See also:
Using help windows 121
9.3.1.7.2 HTML Help Options

The options in this tab only apply when you compile your project to HTML Help. They control
the appearance and behavior of the main HTML Help viewer (Main help window) and the
viewer windows for external windows 429 (user-defined secondary windows).
Specifying a secondary help window in a hyperlink to a topic will only have any effect in
HTML Help if the option Links to secondary help windows open a new help window is
activated here. If not all the secondary window settings will be ignored and the settings for

© 1997 - 2009 by EC Software, all rights reserved

662 Help & Manual 5 - User Help

Main will be used.

Productivity Tip
Note that there is no Keep window on top
setting for HTML Help. This can only be
activated by the programmer in the call to
the HTML Help see the HTML Help API
documentation for details.

Controls:
Links to Activates external windows. When you specify a secondary help
secondary window in the Insert Hyperlink dialog (with the Window: option) the
help windows target window will be opened in an external window with the settings
open a new for the specified secondary window.
help window:
If this option is not activated links to secondary windows will open in
the main help viewer.

Visible These options are used to choose which control buttons are displayed
buttons: in the help viewer. You may want to switch them all off for external
windows 429 .

Window has This option activates or deactivates display of the help viewer's
a navigation navigation panel containing the Table of Contents, keyword index and
panel: other tabs. You may want to disable this for external windows 429 . Note
that if you also disable the Hide/Show button in the Visible Buttons
section the user will not be able to activate the navigation panel at all!

Search tab: These options activate or deactivate the display of the Search and
Favorites tab: Favorites tabs in the navigation panel. Note that if they are disabled it
will not be possible for the user to enable them.

User-defined Allows you to define two HTML URLs as targets for the Home button
buttons: and two user-defined buttons. (These buttons must also be activated
in Visible buttons: to be displayed.)
You cannot enter links to topics in the help here. Note that you must
enter fully-qualified URLs including the protocol (i.e. http://, ftp://
etc). Simple URLs without the protocol (e.g. www.domainname.com) will
not work.
You can edit the names of the Jump 1 and Jump 2 buttons but you
cannot change the name of the Home button.
The icons displayed for these buttons are hard-wired into the Microsoft
HTML Help viewer and cannot be changed.

See also:
Secondary windows 429

© 1997 - 2009 by EC Software, all rights reserved

 Reference 663

9.3.1.7.3 Winhelp Options Tab

The options in this tab control the appearance and behavior of the main Winhelp viewer
window (Main help window type definition) and the viewer window for secondary windows 429
(user-defined secondary help window type definitions).

© 1997 - 2009 by EC Software, all rights reserved

664 Help & Manual 5 - User Help

Controls:
Background The background colors of the topic and topic header. These colors are
colors: only displayed in the compiled Winhelp file, not in the Help & Manual
editor. If you open a topic in an external window with a link specifying a
secondary help window the target topic will be displayed using the
background colors defined for the secondary help window.

Auto-size Automatically adjusts the height of secondary windows on the basis of

window their contents. This option is only available for secondary (user-
height: defined) windows, not for the Main window.

Maximize Automatically maximizes the help viewer when it is opened to fill the
window: user's entire screen. Not recommended the majority of users hate it
when help windows do this!

Keep window Keeps the help window on top of all other windows on the user's
on top: screen. Also not recommended. Many users still use small monitors
with relatively low resolution and on these systems keeping the help
window on top makes it impossible to see the application without
closing the help, which is extremely annoying!

Window The Winhelp help viewer normally adjusts window sizes and positions
position and you enter interactively on the basis of the user's monitor size and
size are screen resolution. If you activate this option the values you enter for
absolute: window position and size will be taken as absolute and will not be
adjusted by the help viewer on the user's computer.
It is better to leave this unchecked unless you have a very good reason
for using absolute values.

Visible These options define the help viewer control buttons to be displayed in
buttons: the window.
Defaults displays the standard set of controls in the main help viewer. It
does not have any effect in secondary (user-defined) windows.
The Browse option which displays Previous/Next browse buttons is
only available in secondary (user-defined) windows, not for the Main
window. This is because these buttons cannot be disabled for the main
help viewer window.

User-defined This section allows you to define and display additional buttons of your
buttons: own, which execute Winhelp macros when the user clicks on them.
You must type the macros manually in the Winhelp Macro field.
See the documentation of Microsoft Help Workshop for details of
Winhelp macros and how to use them.

See also:
Secondary windows 429

© 1997 - 2009 by EC Software, all rights reserved

 Reference 665

9.3.1.8 Miscellaneous Options

The settings in this section set the read-only attribute for merged child projects and allow
you to automatically generate help context numbers and prefixes for topic IDs for new
topics.
Help context numbers are sometimes used to make direct calls to help topics from
application programs. Topic ID prefixes are useful for preventing duplicate IDs in modular
help systems.
Open child This protects child projects merged into the TOC of the current project
projects against accidental editing. This is the default setting.
read-only:
See Working with Modular Help Systems 446 for more information on
editing merged child projects.

Topic ID Any text you enter here is automatically added as a prefix to the
Prefix: suggested topic ID when you create a new topic. Note that this function
can only be used for new topics; you cannot automatically change
existing topic IDs.

Automatically If you activate this function help context numbers will be assigned to
create: / new topics automatically, starting with the Start with number. Each new
Start with: / number will be generated by incrementing the last number assigned by
Increment the Increment by setting.
by:
This function can only be used for new topics. You can add, delete and
change the context numbers of existing topics with the Help Context
Tool 539 .

Apply to topic This setting will also automatically generate help context numbers for
anchors: new topic anchors 226 so that anchors can also be used for calls to help
topics from applications.

Version This option is only relevant if you have a version control system like
Control Microsoft Visual SourceSafe installed on your computer.
System:
Manually check
By default file check-out and check-in is handled automatically for
out and check projects linked to a VCS – Help & Manual automatically checks topics
in topics out of the VCS database when you edit them and checks them back in
when you save your project and move on to a different topic.
Setting manual check-out/check-in switches this automatic feature off
and sets all the topics in your project to read-only. To edit a topic you
must then first check it out manually, either with Project > File >
Check Out in the Ribbon, or with Version Control System > Check
Out in the context menu displayed when you right-click on the topic in
the Project Explorer.
After editing a topic you must also check it in manually with the Check
In menu options in the same locations. Other users will not be able to
edit the topic until you do this – even if you close your project. (This
allows you to leave a topic checked out even when you are not working
on a project.)

© 1997 - 2009 by EC Software, all rights reserved

 666 Help & Manual 5 - User Help

See also:
Topic IDs and context numbers 205
IDs and context numbers in modular help 456
Working with Modular Help Systems 446
Anchors - jump targets 226
Auto and manual check-in/check-out 346
9.3.2 HTML Page Templates
This section allows you to edit the HTML templates that define the layout and general
appearance of your topic pages in all HTML-based output formats. See Using HTML
Templates 430 for full details.
HTML page templates are shared:
Note that the same HTML templates are used for all HTML-based output formats (HTML
Help, Webhelp, Windows Exe and ePub eBooks and MS Help 2.0).

Simple Template Layout tab:

The Simple Template Layout tab hides the HTML code of the page template and allows
you to make some simple changes and additions. This mode is recommended if you do
not have experience with editing HTML code.

Create new HTML templates and delete existing ones. You can
assign page templates to individual topics when you create them
and in the tab behind the main editor window.

Resets the current page template to the default settings.

Header /Text Defines the background colors of the topic header and text.
background color:

Text above topic: Any text you enter in these two editing boxes will be inserted on
Text below topic: every page above and below the main text of your topic.
HTML code is permitted but you are responsible for the correct
syntax.

Topics with Activating this option adds additional navigation links to the
headers have headers of your topic. These links always point to the Top topic
<Top>, (the home topic defined in Configuration > Common
<Previous> and Properties > Language Settings) and the Next and Previous
<Next> links: topics in your help.
You can edit the captions of the links in the Caption column but
you cannot change their functionality.
By default the links are text-only. You can create button links by
selecting graphics files for your buttons in the Image File
column. Use the browse button to locate the graphics files.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 667

HTML Source Code tab:

In this mode you can edit all the code of the HTML templates for your help window
definitions manually with a basic HTML code editor with syntax highlighting. Experience
with editing HTML code is needed please don't change or delete anything here unless
you really understand what you are doing!

See also:
Templates and Secondary Windows 416
Using HTML Templates 430
9.3.3 Publishing Options
The options in this section configure how your project is published to the supported output
formats. You should always check through all the settings in the relevant section before you
output to a new format.

See also:
Publishing 288
Configuring Your Output 292
9.3.3.1 HTML Help

The settings in this section control how your project is exported to HTML Help. Since HTML
Help is an HTML-based format it shares some settings with the other HTML-based output
formats supported by Help & Manual.

Shared settings:
The options in the HTML Export Options section are shared by all HTML-based output
formats (HTML Help, Webhelp, Windows Exe and ePub eBooks and Visual Studio Help/
MS Help 2.0). These settings are accessible in the Webhelp 684 and HTML Help 671
sections of your project configuration.
These are the general settings for all HTML output formats, including image conversion
and export options and the options for the CSS style sheet used to export the style
formatting information from your project. Here too, there is only one CSS style sheet and
one set of HTML Export Options for all these output formats. You cannot enter different
settings for each output format.

See also:
HTML Help 727 (Help Formats)
HTML Help Options 661 (Help Windows)
HTML Page Templates 666
9.3.3.1.1 Popup Topics

These options define how popup topics are exported in HTML Help. For full details see
Creating popup topics 125 and Using JavaScript popups 129 .

© 1997 - 2009 by EC Software, all rights reserved

668 Help & Manual 5 - User Help

Options:
Text-only This activates HTML Help's native popup mode. You cannot use
popups: formatted text (bold, italics etc.), images, hyperlinks, tables or any
other non-text features. When this mode is activated hyperlinks to
popup topics in your help will display as popups automatically.
HTML Help's text-only popups are stored in an internal text file in the
output CHM help file. By default this file is called CSHelp.txt. You can
change this here but since this is the default name of this file you
should only change it if the programmer specifically asks you to.
This mode can be used for field-level popups called from applications.
The calls are made to the plain text file inside the CHM file using the
HTML Help API.

HTML- Selecting this option turns your popups into normal topics without
encoded headers. When this mode is activated links to popup topics will display
topics: the topics in the main help viewer.
This mode cannot be used for field-level popups called from
applications.

JavaScript This mode outputs popup topics using JavaScript code that allows you
popups: to use formatted text (bold, italics etc.), images, Internet and topic
hyperlinks, tables (with grid lines and borders) and even video files in
your popups.
The popups are stored inside the main CHM help file so you only need
to distribute one file with your application.
This mode cannot be used for field-level popups called from
applications. If you want to use both JavaScript popups and field-level
popups called from your application you must create a separate project
for your context popups.

Customizing JavaScript popups:

JavaScript popups are highly-customizable. Click on to display the
configuration dialog:

© 1997 - 2009 by EC Software, all rights reserved

 Reference 669

Click/ Displays the popup on user click or mouseover (i.e. as soon as the user
mouseover: moves the mouse pointer over the link). Be careful with using the
mouseover option as many users find this intrusive and it may also
trigger popup blockers in some browsers.

Minimum Setting this to 0 makes the popup width automatic, on the basis of the
width: amount of text and/or other content.
Setting it to any other value (in pixels) explicitly defines the width of the
popup. If the popup only contains text it will have the width you specify.
If it contains other content (graphics, videos) it will be at least as wide
as the specified width and wider if required by the content.

Border width: Enter 0 for no border, any value above 0 (in pixels) to draw a border
around the popup box.

Border The distance between the popup content and the border or edge of the
padding: popup (if there is no border) in pixels.

Background: The background color of the popup box.

Border color: The color of the border, if there is one.

Visual These effects are only supported by MS Internet Explorer. This means
effects: that they are available in HTML Help (which uses MSIE) and in
Webhelp when the user is using Internet Explorer. They are ignored by
all other browsers.
These effects are easier to see than to describe. Experiment! (Note
that the transition effects are only for opening the popup box. The
popups always close in the same way, no matter what effect you
select.)

See also:
Creating popup topics 125

© 1997 - 2009 by EC Software, all rights reserved

 670 Help & Manual 5 - User Help

Using JavaScript popups 129

Using Context-Sensitive Help 369
HTML Help 727 (Help Formats)
HTML Help Options 661 (Help Windows)
9.3.3.1.2 Extended .HHP Settings

This section enables you to add or overwrite sections of the HHP project file used to
generate your HTML Help output. (See HTML Help project files 728 for details). Normally you
will never need to use this feature but there may be situations where you want or need to
make changes to your HTML Help output by making changes or additions to the HHP file.
Please only use these feature if you understand HHP files and how to edit them. You can
find information on the settings in the documentation distributed with Microsoft HTML Help
Workshop.

Adding entries to the HHP file:

To add entries to the HHP file enter the section heading name in upper case and
enclosed in square brackets, followed by the settings you want to add or change, entering
one setting per line with a hard line break (ENTER) at the end of each line. Don't enter
any section heading more than once.
Note that merging files into your CHM file is much easier with the Baggage Files section
in the Project Explorer. See Using Baggage Files 485 for details.
Example:

This example shows some of the Extended .HHP settings we used for the old Help &
Manual 3 help, before the Baggage section was available. It is now much easier to add
About paths to referenced files:
When Help & Manual compiles your project all the HTML Help project files 728 , including
the HHP file, are generated in a temporary directory called \~tmpchm and then fed to
the Microsoft HTML Help compiler. This directory is created in your project directory,
which is the directory containing your .hmxp or .hmxz project file.
This means that all file paths entered in the Extended HHP Settings must be relative to
this directory, because that is where the .hhp file is located. In the example above, for
instance, the files referenced are located in the project directory, which is one directory
up from \~tmpchm. This is why ..\ must be prefixed to each file reference so that the
compiler can find the files.
If your files are stored in other locations you must adjust the relative paths accordingly.
Storing them in the project directory is usually the simplest solution, however.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 671

HTML Help TOC options:

Below the Extended HHP Settings editing window are some additional options with which
you can adjust the appearance and behavior of the TOC in the Microsoft HTML Help
viewer:
Display plus/minus icons:
Activates or deactivates the +/- icons displayed to the left of closed/open chapter icons
("books") in the HTML Help viewer's TOC.
Draw lines between items:
When this is activated fine dotted lines are displayed between related items in the TOC,
making it easier see which topic belongs to which chapter in complex TOCs.
Track selection (mouseover effect):
When this is activated an underline is displayed below topic entries in the TOC when the
user moves the mouse over them. This makes it easier to be sure which topic you are
going to click on.
Only expand a single heading:
When the user selects a new chapter any other chapters on the same level in the TOC
that are open will be closed automatically. This is useful for complex help documents with
lots of chapters, because it is easier to navigate in the TOC if you do not have multiple
chapters open.

Child file TOC settings

This setting is only relevant if the current project is a child project in your modular help
system. It controls what happens when the user tries to open the child .chm module
directly.
Its own table of contents
This makes the child file open with its own table of contents as a separate help file in its
own right.
Table of contents of the master file
This automatically opens the master .chm and loads the child .chm into its TOC when the
child file is opened. This is effectively the same as opening the master .chm directly. Use
the browse button to select the master .chm file (this must be present in the same
directory on the user's computer at runtime).

See also:
Working with Modular Help Systems 446
Using Baggage Files 485
Using HTML Templates 430
Inserting HTML Code 231
HTML Help 727 (Help Formats)
HTML Help Options 661 (Help Windows)
9.3.3.1.3 HTML Export Options

These options control many key aspects of how your project content is converted to HTML
code for all the HTML-based output formats, including how the styles used in your project
are exported to a CSS cascading style sheet file, how graphic images are converted and

© 1997 - 2009 by EC Software, all rights reserved

672 Help & Manual 5 - User Help

exported and a number of other important settings.

This is a shared section:

Note that these options are shared by all HTML-based output formats (HTML Help, Visual
Studio Help (MS Help 2.0), Webhelp and Windows Exe and ePub eBooks). They are
accessible in several locations in your project Configuration but no matter where you edit
them you are always editing the same settings. You cannot save different HTML Export
settings for the individual HTML-based output formats.
With a couple of small exceptions (noted in the descriptions of the individual settings) all
the options are used by all output formats.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 673

Extension for By default all HTML topic files are exported with the extension .
HTML topic files: htm. You can change this to .html, .asp, .php or a manually-
entered extension but these extensions are only supported in
Webhelp.
The .htm extension is always used for topic files in HTML Help,
and MS Help 2.0.
This setting is irrelevant for eBooks.

CSS stylesheet This setting allows you to change the name of the stylesheet file
file name: exported with the CSS style information. The default file name is
default.css.

Font size This setting allows you to choose how font sizes are defined in your
encoding: output. You can choose pt (points), px (pixels), % (percent) or
ems (where 1 em = 100%). Which setting you choose controls
how fonts are displayed on the user's screen and whether or not
the user can change the font size.
Choose Pixels to lock your font size and layout, Percent to
allow the user to change the font size.
Points:
When you export the font size in points the user cannot adjust the
font size. However, the size of the fonts displayed on the user's
computer screen will vary depending on the Windows screen DPI
setting and/or font size settings. For example, if you develop your
help on a machine with Windows set to 96dpi (the standard) your
text layout may be incorrect on computers set to 120dpi (fonts look
much too big, text in hanging indents may be wider than the indent
etc). This is because the size of the fonts changes but the size of
the other layout elements (indents, locked table cells etc.) doesn't.
Pixels:
This is the only setting that ensures that the fonts and your layout
will always be displayed exactly as you see them on your
development machine. The font size is always uses the same
number of pixels, so it is always the same size relative to other
elements of your layout like indents, graphics and so on.
Percent or Ems:
If you select percent or Ems the user will be able to adjust the font
size in the help, for example by holding down Ctrl and turning the
mouse scroll wheel. This may or may not be a good thing, because
the size of other layout elements (graphics, indents, locked table
cells etc.) will not change, so the user adjustments may "break"
your layout.

Font size of If you choose percent or ems for font size encoding (see above)
Normal style: you can also use this setting to define the size of the Normal style
in relation to the default font of the user's browser. The value is
expressed in percent and the default is 100%. This is normally
preferable because most users will have set the default font in their
browsers to the size of font they prefer.
© 1997 - 2009 by EC Software, all rights reserved
Export XHTML If you select this Help & Manual will generate HTML code that is
1.1 compliant compliant with the XHTML 1.1 specification.
HTML:
This is only used in Webhelp. The HTML Help compiler cannot
 674 Help & Manual 5 - User Help

See also:
Configuring Your Output 292
Publishing Your Projects 292
HTML Help 727 (Help Formats)
HTML Help Options 661 (Help Windows)
9.3.3.2 Webhelp

The settings in this section control how your project is exported to Webhelp, which can be
displayed with any modern web browser. Help & Manual's Webhelp provides a close
approximation of the HTML Help viewer layout so that it can be used intuitively by all
Windows users. In addition to a Table of Contents with expanding and collapsing chapter
entries it also includes a keyword index and full-text search and supports JavaScript popups
129 that will also work transparently on all modern browsers.

Since Webhelp is an HTML-based format it shares several groups of settings with the other
HTML-based output formats supported by Help & Manual.

Shared settings:
The options in the HTML Export Options section are shared by all HTML-based output
formats (HTML Help, Webhelp, Windows Exe and ePub eBooks and Visual Studio Help/
MS Help 2.0). These settings are accessible in the Webhelp 684 and HTML Help 671
sections of your project configuration.
These are the general settings for all HTML output formats, including image conversion
and export options and the options for the CSS style sheet used to export the style
formatting information from your project. Here too, there is only one CSS style sheet and
one set of HTML Export Options for all these output formats. You cannot enter different
settings for each output format.

See also:
Webhelp 730 (Help Formats)
Webhelp 296 (Configuring Your Output)
9.3.3.2.1 Layout

These settings define the layout of your Webhelp output. The default setting is Two
Frames and you should leave this unchanged for most projects.
· For more background information see Webhelp 296 in the Configuring Your Output
chapter and Webhelp 730 and Browser compatibility 731 in the Reference > Help
Formats chapter.
· There are also some special variables you can use in the layout page's HTML template.
For details see HTML template variables 782 in the Reference section.
Controls:
Simple Options / Only select the HTML Code tab if you have a thorough
Edit HTML Code: understanding of editing HTML frameset files. Otherwise you can
select all the layout options you need in the Simple Options tab.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 675

Two frames: Default, choose for stand-alone help:

Two frames is the default layout. It creates a stand-alone help
project that is effectively a website in its own right. Navigation is
dynamic with an expanding and collapsing contents tree if the
user's browser supports it and static if it doesn't.
The output is fully compatible with all modern browsers, even if
they have features like JavaScript turned off, and it will also
display and work correctly in older browsers, just with fewer
features.

Three frames: Choose for integration in an existing website

This is the same as two frames but with an additional frame above
for integration in your website – you can use the top frame to
insert your standard website header components. Navigation is
dynamic with an expanding and collapsing contents tree if the
user's browser supports it and static if it doesn't.
Here too, the output is fully compatible with all modern browsers,
even if they have features like JavaScript turned off, and it will
also display and work correctly in older browsers, just with fewer
features.

No frames, no Choose for fully-manual website integration

scripts:
This completely turns off the dynamic TOC and outputs your help
as simple HTML pages without frames, without any scripting and
with a single separate TOC page containing all the links to your
individual topics.

Show borders Displays border lines between the two or three frames of your
between frames: layout. Turn off for a "seamless" look.

Width of the left Defines the width of the navigation frame containing your project's
frame: TOC. Only displayed if a frame mode is activated. You can enter
the values as either pixels or percent:
· Values under 100 are interpreted as percent.
· Values above 100 are interpreted as pixels.

Height of head Only displayed if the Three Frame option is selected. Defines the
frame: height of the head frame in pixels. The height of this frame is
always fixed so you must choose the right height to match the
layout of the file you are loading into the head frame.
Head frame has Only displayed if the Three Frame option is selected. If you
scrollbars: deselect this no scrollbars will be displayed, even if the content
does not fit in the head frame. Deactivate for a seamless
appearance (you must plan the height of your head frame content
precisely for this to work properly).

© 1997 - 2009 by EC Software, all rights reserved

 676 Help & Manual 5 - User Help

Head frame loadsSelect to load an existing HTML file into the top frame. Only
external file: displayed if the Three Frame option is selected.
Enter the name of the HTML file you want to load into your top
frame here. Filenames are case sensitive in most web servers so
be careful to enter the entire name correctly.
Enter the absolute or relative path to the file if is not going to be in
the same directory as your help (for example if you are going to
use the standard header file for your website).
Important: Help & Manual will not copy this file or any files that it
references to your output folder for you! You are responsible for
ensuring that the file and any files it references (graphics etc.) are
stored in the correct location.
Examples:
File will be in help directory:
headframe.html
File will be in another directory two levels up from your help on the
server:
././headframe.htm
File will be on a different server:
http://www.servername.com/general/headframe.htm

Edit head frame Choose this option to create and edit the HTML code to be loaded
HTML code: into the head frame directly. Only displayed if the Three Frame
option is selected.
When you choose this option the head frame file is generated
automatically using the code you enter here when you compile
your help. You can reference graphics and other files in it in the
same way that you would in all other HTML template files.
Please study Using HTML Templates 430 first.

See also:
Webhelp 296 (Configuring your Output)
Webhelp 730 (Help Formats)
HTML template variables 782 (Reference)
Browser compatibility 731
9.3.3.2.2 Navigation

These settings control how the navigation is handled in your Webhelp output. Like the
settings in the Layout section they are essential for the functioning of your help. You should
always check them very carefully before publishing your Webhelp to make absolutely sure
that the help will behave as you want.
For more information see Webhelp 296 in the Configuring Your Output chapter and Webhelp
730 and Browser compatibility 731 in the Reference > Help Formats chapter.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 677

Include Keyword These features should be self-explanatory. They simply switch

Index individual features in your Webhelp on and off.
Include Full-text
Search
Note that Full Text Search is only available in the Professional
version of Help & Manual and will only work if the user has
JavaScript enabled.
If you activate search you should also configure the search
options in the Full Text Search 680 section.

Add ordering Adds topic/chapter numbering to the TOC in your output, using
numbers to Table the standard legal format (1, 1.1, 1.2, 1.2.1 etc).
of Contents:

Lazy content This is a specialized setting for advanced users that should be left
synchronization: turned off for all normal output. Activating it may slightly slow
down synchronization between topics and the TOC, particularly in
menus with many entries.
Lazy synchronization activates a different method for
"synchronizing" the item highlighted in the TOC pane with the
topic displayed in the topic pane.
In normal mode, when lazy synchronization is deactivated, all
topics include information about where their entries are in the
TOC. When the user clicks on a topic hyperlink the entry for the
target topic in the TOC will be highlighted as soon as the topic is
displayed.
Activating lazy synchronization removes this TOC address
information from the individual topics. When the user clicks on a
link the browser must first search for the matching entry in the
TOC, and this can cause a small delay.

Single click on By default, the user must double-click on chapters to expand them
caption in Table in the TOC. This option allows you to change this to expand on a
of Contents single click.
expands chapter:
Note:
We recommend leaving this option off. The default mode allows
you to select chapters without expanding them automatically and
you can still expand chapters with a single click on the chapter
icon.

Automatically When you set this option all chapters except the chapter in which
collapse the user is currently browsing collapse (close) automatically. This
unfocused can make navigation easier in large help projects because you do
entries: not have a large number of chapters open at the same time.
Note:
Selecting this option will disable On load, expand... All Entries
(see below)

© 1997 - 2009 by EC Software, all rights reserved

 678 Help & Manual 5 - User Help

On load, expand: Allows you to expand the TOC automatically when the user opens
the help. You can expand either all entries or just top-level entries
(main chapters).
Note:
Expand All Entries is disabled when Automatically collapse
unfocused entries is selected (see above).

Icons in the TOC: If you want you can select your own icons to be used in the Table
of Contents here. If you select custom icons stored in folders
listed in your Image Folders 656 they will be copied to your output
directory automatically.

See also:
Webhelp 296 (Configuring your Output)
Webhelp 730 (Help Formats)
Browser compatibility 731
9.3.3.2.3 Table of Contents

This section allows you to edit the HTML template 427 that defines the layout and appearance
of the Table of Contents pane in your Webhelp output. See Using HTML Templates 430 for
full details.

Simple Template Layout tab:

This mode is recommended if you do not have experience with editing HTML code!
Text above TOC Any text you enter in these two editing boxes will be inserted
headings: above and below the TOC tree with the topic entries. For
Text below TOC
example, you might want to enter the title of your project above
headings: the tree and a copyright notice below the tree. HTML tags are
allowed.
The default code inserts the title of your project and links to the
Keyword Index and Full-text Search panes (if activated in your
settings). Please do not change this code unless you really
understand how it works.

Format of TOC These settings define the formatting styles to be used for the
headings: headings in your TOC. You can use up to six levels. However,
note that users will normally find anything more than a maximum
of three levels generally and four in exceptional cases confusing
and difficult to navigate.

This button automatically clears the HTML template and reloads

the default template. Use with caution – this function completely
overwrites all your editing changes!

© 1997 - 2009 by EC Software, all rights reserved

 Reference 679

HTML Source Code tab:

This tab allows you to see and edit all the code of the TOC template manually.
Experience in editing HTML code is necessary for using this mode!
Please note that the code in this template is essential for the proper functioning of the
TOC. Please don't change or delete anything that you don't understand!
Editing window: The editor provides full HTML syntax highlighting to make editing
easier. To enlarge the window for easier editing just resize the
Project Properties window.

Here too, this button automatically clears the HTML template and
reloads the default template. Use with caution – this function
completely overwrites all your editing changes!

See also:
Webhelp 730 (Help Formats)
Using HTML Templates 430
HTML Templates 810 (Reference)
9.3.3.2.4 Keyword Index

This section allows you to edit the HTML template 427 that defines the layout and appearance
of the Keyword Index pane in your Webhelp output. See Using HTML Templates 430 for full
details.

Simple Template Layout tab:

This mode is recommended if you do not have experience with editing HTML code!
Text above Keyword Any text you enter in this editing box will be inserted above the
Index: Keyword Index. HTML tags are allowed.
The default code inserts the title of the Keyword Index and links
to the TOC and Full-text Search (if activated in your settings)
panes. Please do not change this code unless you really
understand how it works.

Keyword Index These settings define the font styles to be used for the
Font: components of your Keyword Index.

Index Separators: These entries generate the headings for each letter group in
the Keyword Index. If your help is not in English you can add
appropriate letters for your language.

This button automatically clears the HTML template and

reloads the default template. Use with caution – this function
completely overwrites all your editing changes!

© 1997 - 2009 by EC Software, all rights reserved

 680 Help & Manual 5 - User Help

HTML Source Code tab:

This tab allows you to see and edit all the code of the Keyword Index template manually.
Experience in editing HTML code is necessary for using this mode!
Please note that the code in this template is essential for the proper functioning of the
Keyword Index. Please don't change or delete anything that you don't understand!
Editing window: The editor provides full HTML syntax highlighting to make
editing easier. To enlarge the window for easier editing just
resize the Project Properties window.

Index Separators: These entries generate the headings for each letter group in
the Keyword Index. If your help is not in English you can add
appropriate letters for your language.

Here too, this button automatically clears the HTML template

and reloads the default template. Use with caution – this
function completely overwrites all your editing changes!

See also:
Using HTML Templates 430
HTML Templates 810 (Reference)
Webhelp 730 (Help Formats)
9.3.3.2.5 Full Text Search

This section configures the Full-text Search function for Webhelp output. It includes both the
options for configuring the behavior of the search function and the HTML template 427 that
defines the layout and appearance of the Search pane in your Webhelp output. See Using
HTML Templates 430 for full details.
· Professional version feature only:
Please note that the support for full-text search in Webhelp is only included in the
Professional version of Help & Manual.

How full-text search works in Webhelp

Full-text search uses an index of words found in the project, together with the locations
where the words are found. This means that it is not possible to search for phrases
because the index only knows about the locations of the individual words.
Searching for exact words:
You can use quotes to search for exact words. For example, cat will find cat, catalog and
advocate, but "cat" will only find cat. This can be combined with wildcard characters –
"cat*" will find catalog but not advocate.

Configuration options:
The configuration options for Full-text Search are quite simple but they are important
because they make a major difference to how search functions. The Accent and Single-
case options are particularly important for some languages.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 681

String Constants / The String Constants table is a list of the texts that are used in
Translation: the user interface of the Search function. You can edit the
default texts in the Text column directly. HTML tags are not
permitted here, you can only enter plain text.

In addition to editing the string constants yourself you can also

(Load / Save load sets of constants for a variety of different languages, and
Constants): save your own constants to external files.
The constants are stored in Unicode text files, so you can
store your texts in any language. The files have the extension
*.zlang and are stored in the \Templates\html folder in the
Help & Manual program directory, which is normally C:
\Program Files\EC Software\HelpAndManual5. You will
find files for most common languages in this directory.

Exclude these words This list defines common words you don't want to include in
from search: the full-text search index to save space. This is an important
point because the JavaScript full-text index has to be
completely downloaded from your server by the user's browser
before a search can be executed.
You can add your own words and delete existing words. Just
click in the list and edit, and only enter one word per line. Copy
and paste is supported.
Note that this list must contain at least one word. If you delete
all the entries it will default to the standard entries when you
save your project.

Skip words with less This is another function that decreases the size of the index.
than ... characters: Words with less then 3 characters are usually not very
meaningful and excluding them from the search is generally
recommended.

Word-joining The indexing function automatically treats words linked with

characters: the characters you specify here as single words. For example,
if the "-" character is included here ready-mix and readymix
would both be treated as the same single word.
You can edit the list to add your own characters or delete
existing characters.

Enable "Sort results When this is activated users can sort the search results by
by date": score (relevance of the topic found) or date.

Search is accent- This converts accents and umlauts to their base characters so
insensitive: that the search doesn't make a difference between base
characters and their accented versions.
This is strongly recommended for highly-accented languages
like French and German, as it will make the searches much

© 1997 - 2009 by EC Software, all rights reserved

 682 Help & Manual 5 - User Help

more effective for the user.

Support for single- This creates a case-insensitive search index. You don't need
case languages: this for western languages but it is a requirement for Asian
languages. It is also helpful for languages like German in
which all common nouns are capitalized.

Simple Template Layout tab:

This mode is recommended if you do not have experience with editing HTML code!
This button automatically clears all your settings and the HTML
template and reloads the default template. Use with caution –
this function completely overwrites all your editing changes!

Text on top of The text here defines what appears at the top of the Search
Search page: pane in the Webhelp shown in the user's browser. HTML tags
are allowed.
The default code inserts the title of the Full-text Search and
links to TOC and Index. Please do not change this code unless
you really understand how it works.

HTML Source Code tab:

This tab allows you to see and edit all the code of the Keyword Index template manually.
Experience in editing HTML code is necessary for using this mode!
Please note that the code in this template is essential for the proper functioning of the
Search function. Please don't change or delete anything that you don't understand!
Here too, this button automatically clears the HTML template
and reloads the default template. Use with caution – this
function completely overwrites all your editing changes!

Editing window: The editor provides full HTML syntax highlighting to make
editing easier. To enlarge the window for easier editing just
resize the Project Properties window.

See also:
Webhelp 730 (Help Formats)
Using HTML Templates 430
HTML Templates 810 (Reference)
9.3.3.2.6 Popup Topics

These options define how popup topics are handled in Webhelp. Note that only the
JavaScript popups option will export popup topics that really function as popups.
For full details see Creating popup topics 125 and Using JavaScript popups 129 .

© 1997 - 2009 by EC Software, all rights reserved

 Reference 683

Popup mode:
HTML-encoded Selecting this option generates popup topics as normal topics
topics: without headers – i.e. they are no longer popup topics. When this
mode is activated links to popup topics will display the topics in
the main browser window in the topic pane.

JavaScript This mode outputs popup topics using JavaScript code that allows
popups: you to use formatted text (bold, italics etc.), images, topic
hyperlinks, Internet links, tables (with grid lines and borders) and
even video files in your popups.

Customizing JavaScript popups:

JavaScript popups are highly-customizable. Click on Customize to display the
configuration dialog:

Click/ Displays the popup on user click or mouseover (i.e. as soon as the user
mouseover: moves the mouse pointer over the link). Be careful with using the
mouseover option as many users find this intrusive and it may also
trigger popup blockers in some browsers.

Minimum Setting this to 0 makes the popup width automatic, on the basis of the
width: amount of text and/or other content.
Setting it to any other value (in pixels) explicitly defines the width of the
popup. If the popup only contains text it will have the width you specify.
If it contains other content (graphics, videos) it will be at least as wide
as the specified width and wider if required by the content.

Border width: Enter 0 for no border, any value above 0 (in pixels) to draw a border
around the popup box.

Border The distance between the popup content and the border or edge of the

© 1997 - 2009 by EC Software, all rights reserved

 684 Help & Manual 5 - User Help

padding: popup (if there is no border) in pixels.

Background: The background color of the popup box.

Border color: The color of the border, if there is one.

Visual These effects are only supported by MS Internet Explorer. This means
effects: that they are available in HTML Help (which uses MSIE) and in
Webhelp when the user is using Internet Explorer. They are ignored by
all other browsers.
These effects are easier to see than to describe. Experiment! (Note
that the transition effects are only for opening the popup box. The
popups always close in the same way, no matter what effect you
select.)

See also:
Creating popup topics 125
Using JavaScript popups 129
9.3.3.2.7 HTML Export Options

These options control many key aspects of how your project content is converted to HTML
code for all the HTML-based output formats, including how the styles used in your project
are exported to a CSS cascading style sheet file, how graphic images are converted and
exported and a number of other important settings.

This is a shared section:

Note that these options are shared by all HTML-based output formats (HTML Help, Visual
Studio Help (MS Help 2.0), Webhelp and Windows Exe and ePub eBooks). They are
accessible in several locations in your project Configuration but no matter where you edit
them you are always editing the same settings. You cannot save different HTML Export
settings for the individual HTML-based output formats.
With a couple of small exceptions (noted in the descriptions of the individual settings) all
the options are used by all output formats.
Extension for By default all HTML topic files are exported with the extension .
HTML topic files: htm. You can change this to .html, .asp, .php or a manually-
entered extension but these extensions are only supported in
Webhelp.
The .htm extension is always used for topic files in HTML Help,
and MS Help 2.0.
This setting is irrelevant for eBooks.

CSS stylesheet This setting allows you to change the name of the stylesheet file
file name: exported with the CSS style information. The default file name is
default.css.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 685

Font size This setting allows you to choose how font sizes are defined in your
encoding: output. You can choose pt (points), px (pixels), % (percent) or
ems (where 1 em = 100%). Which setting you choose controls
how fonts are displayed on the user's screen and whether or not
the user can change the font size.
Choose Pixels to lock your font size and layout, Percent to
allow the user to change the font size.
Points:
When you export the font size in points the user cannot adjust the
font size. However, the size of the fonts displayed on the user's
computer screen will vary depending on the Windows screen DPI
setting and/or font size settings. For example, if you develop your
help on a machine with Windows set to 96dpi (the standard) your
text layout may be incorrect on computers set to 120dpi (fonts look
much too big, text in hanging indents may be wider than the indent
etc). This is because the size of the fonts changes but the size of
the other layout elements (indents, locked table cells etc.) doesn't.
Pixels:
This is the only setting that ensures that the fonts and your layout
will always be displayed exactly as you see them on your
development machine. The font size is always uses the same
number of pixels, so it is always the same size relative to other
elements of your layout like indents, graphics and so on.
Percent or Ems:
If you select percent or Ems the user will be able to adjust the font
size in the help, for example by holding down Ctrl and turning the
mouse scroll wheel. This may or may not be a good thing, because
the size of other layout elements (graphics, indents, locked table
cells etc.) will not change, so the user adjustments may "break"
your layout.

Font size of If you choose percent or ems for font size encoding (see above)
Normal style: you can also use this setting to define the size of the Normal style
in relation to the default font of the user's browser. The value is
expressed in percent and the default is 100%. This is normally
preferable because most users will have set the default font in their
browsers to the size of font they prefer.

Export XHTML If you select this Help & Manual will generate HTML code that is
1.1 compliant compliant with the XHTML 1.1 specification.
HTML:
This is only used in Webhelp. The HTML Help compiler cannot
handle XHTML-compliant code and it is also not relevant for
eBooks.
Note that XHTML code is fine for modern browsers but the
specification contains a number of features that older browsers
cannot handle correctly. If you believe you have a significant
number of users still using old browsers it is better to deselect this.

© 1997 - 2009 by EC Software, all rights reserved

686 Help & Manual 5 - User Help

New browsers will not have a problem with this because they can
also handle code that is not fully XHTML-compliant .

Export Webhelp Only switch this off if you are using PHP code in your project and
with UTF-8 BOM: your server's PHP system is having trouble with the BOM at the
beginning of your webhelp files. If you don't know what PHP is you
don't need to turn this off!
All Help & Manual webhelp files are stored in UTF-8 Unicode. The
UTF-8 BOM (Byte Order Mark) is a special character code at the
beginning of the file that identifies it as UTF-8 Unicode. It is
generally better to leave this in because it will prevent old and
badly-configured servers from misinterpreting the UTF-8 Unicode
formatting. However, the PHP installations on almost all servers
still have trouble with the BOM and so it is better to switch the BOM
off if you are using PHP.

Apply date and When this is on (default setting) the timestamps of your HTML
time stamp of topic files will be set to the date and time of the topic in your
topic to HTML project, which is equivalent to the time of the last change. This
topic files: makes it easier to synchronize your output folder with an old
version on your web server, for example. This is only really relevant
for Webhelp output – in CHM help the topic files are all hidden
inside the CHM.
If you turn this off the timestamps of all HTML files will always be
the date and time at which your entire project was compiled.
Do not turn this setting off unless you have a specific reason to do
so.

Modify archive Turning this on will automatically switch the archive bits of all
bit of topic files modified files in your Webhelp output folder. Use this if you have
depending on an FTP program like Second Copy that can synchronize your
changes: output folder with your web server folder using archive bits.
The advantage of this is that it automatically flags all modified files,
even if their timestamps have not changed. This is important
because the timestamps of your topic files are only changed if the
topics have actually been edited. For example, if you change your
HTML templates this will change all your topic files but it will not
change the timestamps of topic files that have not been edited,
even though their contents change because of the template
changes. Using archive bits guarantees that all modified files are
identified.
Using this option only makes sense if you have an FTP program
that supports folder synchronization on the basis of archive bits,
however...

Export style When this is selected Help & Manual uses the full names of your
names: styles in the stylesheet. This makes the sheet much easier to read
if you ever want to view or edit it manually.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 687

If you deselect this option the style names are converted to brief,
alphanumeric codes that are not so "human-friendly". This can
make your project a little bit smaller but not much.

Export lists as This setting is recommended. When it is selected numbered and

tables: bulleted lists are converted to tables in HTML-based output. This is
the only way to make stable lists that display correctly in all
browsers, using the indents that you set. Even in HTML Help,
which uses MS Internet Explorer for HTML rendering, you will find
that lists display better as tables.
If you deselect this option lists will be exported as standard <OL>
and <UL> lists with <LI> list elements. Unless you use very simple
lists the rendering of these elements will be unsatisfactory in many
browsers.

If an image has Images in HTML pages can have an ALT attribute that displays a
no caption small text in a "tooltip" when the user positions the mouse pointer
export file name over the image.
as hint:
Selecting this option exports the image file name as the ALT
attribute if the image doesn't have a caption. Unless your graphics
files have very descriptive names it is normally advisable to switch
this off.

Conversion This option controls how the images in your project are converted
options for and exported when you compile to HTML-based formats.
bitmaps and
Impict images:
Which option provides the best results depends on the type of
images in your project. GIF provides the smallest files with the best
quality for screenshots with 256 colors or less.
Screenshots of any resolution almost always look terrible when
converted to JPG so you should always choose your settings to
make sure that this doesn't happen. Always use GIF and no more
than 256 colors for screenshots.
JPG and true-color PNG are really only needed for photographs
and continuous-tone graphics. To minimize help file size make sure
that all other files have no more than 256 colors.

Output quality You can reduce file size by decreasing the quality but this will also
for JPEG images: make the images look less good. A value of between 80 and 90 is
normally acceptable.
Note that this quality setting is only applied to JPEG images
actually generated by the program on the basis of the conversion
settings (see above). JPEG images that you insert in your project
directly are not affected. They are used as they are, without any
changes.

See also:
Configuring Your Output 292

© 1997 - 2009 by EC Software, all rights reserved

688 Help & Manual 5 - User Help

Publishing Your Projects 292

These options control many key aspects of how your project content is converted to HTML
code for all the HTML-based output formats, including how the styles used in your project
are exported to a CSS cascading style sheet file, how graphic images are converted and
exported and a number of other important settings.

This is a shared section:

Note that these options are shared by all HTML-based output formats (HTML Help, Visual
Studio Help (MS Help 2.0), Webhelp and Windows Exe and ePub eBooks). They are
accessible in several locations in your project Configuration but no matter where you edit
them you are always editing the same settings. You cannot save different HTML Export
settings for the individual HTML-based output formats.
With a couple of small exceptions (noted in the descriptions of the individual settings) all
the options are used by all output formats.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 689

Extension for By default all HTML topic files are exported with the extension .
HTML topic files: htm. You can change this to .html, .asp, .php or a manually-
entered extension but these extensions are only supported in
Webhelp.
The .htm extension is always used for topic files in HTML Help,
and MS Help 2.0.
This setting is irrelevant for eBooks.

CSS stylesheet This setting allows you to change the name of the stylesheet file
file name: exported with the CSS style information. The default file name is
default.css.

Font size This setting allows you to choose how font sizes are defined in your
encoding: output. You can choose pt (points), px (pixels), % (percent) or
ems (where 1 em = 100%). Which setting you choose controls
how fonts are displayed on the user's screen and whether or not
the user can change the font size.
Choose Pixels to lock your font size and layout, Percent to
allow the user to change the font size.
Points:
When you export the font size in points the user cannot adjust the
font size. However, the size of the fonts displayed on the user's
computer screen will vary depending on the Windows screen DPI
setting and/or font size settings. For example, if you develop your
help on a machine with Windows set to 96dpi (the standard) your
text layout may be incorrect on computers set to 120dpi (fonts look
much too big, text in hanging indents may be wider than the indent
etc). This is because the size of the fonts changes but the size of
the other layout elements (indents, locked table cells etc.) doesn't.
Pixels:
This is the only setting that ensures that the fonts and your layout
will always be displayed exactly as you see them on your
development machine. The font size is always uses the same
number of pixels, so it is always the same size relative to other
elements of your layout like indents, graphics and so on.
Percent or Ems:
If you select percent or Ems the user will be able to adjust the font
size in the help, for example by holding down Ctrl and turning the
mouse scroll wheel. This may or may not be a good thing, because
the size of other layout elements (graphics, indents, locked table
cells etc.) will not change, so the user adjustments may "break"
your layout.

Font size of If you choose percent or ems for font size encoding (see above)
Normal style: you can also use this setting to define the size of the Normal style
in relation to the default font of the user's browser. The value is
expressed in percent and the default is 100%. This is normally
preferable because most users will have set the default font in their
browsers to the size of font they prefer.
© 1997 - 2009 by EC Software, all rights reserved
Export XHTML If you select this Help & Manual will generate HTML code that is
1.1 compliant compliant with the XHTML 1.1 specification.
HTML:
This is only used in Webhelp. The HTML Help compiler cannot
 690 Help & Manual 5 - User Help

See also:
Configuring Your Output 292
Publishing Your Projects 292
Webhelp 730 (Help Formats)
9.3.3.3 Adobe PDF

The settings in this section control how your project is exported to Adobe PDF, which can be
displayed with Adobe Acrobat or Acrobat Reader version 3 or later. The most important
setting is the link to the print manual template which defines the appearance and layout of
your PDF output.
In addition to selecting the template you can choose whether you want to generate an
interactive PDF with active hyperlinks for on-screen viewing or a print manual style PDF
designed to enable the user to print out a hard copy of the user manual. You can also adjust
a number of security-related settings.

See also:
Customize - PDF Export 650
PDF and Printed Manuals 325
Adobe PDF 737 (Help Formats)
9.3.3.3.1 PDF Layout

The settings in this section have an effect on the appearance and style of your PDF output.
The most important setting is the link to the print manual template 330 which defines the page
layout of your PDF output and adds additional pages and features (cover, index, contents
etc). See PDF and Printed Manuals 325 for details.
Options:
Print Manual This selects the template to be used for formatting your project
Template: when you output to PDF. This template controls the appearance
and layout of your PDF document and the elements it contains.
You can also use the template to specify which elements (index,
TOC etc.) you want to include in your PDF output.
Clicking on the Design button opens the selected template for
editing in the Print Manual Designer 537 program.

Interactive PDF Generates a PDF designed for interactive on-screen viewing.

document: When you select this option you can also select active hyperlinks
and an interactive Table of Contents (see below).

Similar to a Generates a static PDF designed for printing rather than on-
printed manual: screen viewing. Automatically disables all the other interactive
options in this section.

Create Table of Generates an interactive Table of Contents which is displayed in

Contents: the "Bookmarks" section of Adobe Reader. Only available for
interactive PDF documents.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 691

Note that this is not the same as the Table of Contents section
configured in the print manual template 330 , which is designed for
use in printed PDFs.

PDF has active Makes all the hyperlinks in your PDF output active. Topic links,
hyperlinks: Internet links and file links (without parameters) are all supported.
See Links, Anchors, Macros, Scripts and HTML 214 for more
information. Only available for interactive PDF documents.
Note that the active links will only be visible if you activate the
Underline topic links and paint in color option (see below).

File links - embed Activating this option physically embeds external files in the PDF
linked files: file so that you can distribute additional files with your PDF
document. Only files linked to in your document with file links 220
will be embedded.

Insert page Inserts a small icon containing the link target page number after
referrers: every hyperlink. Recommended for PDFs designed for printing.

Underline topic This allows you to choose whether the links in your PDF are
links and paint in visible and defines the color.
color:
If you turn this off in a PDF document with active hyperlinks the
links will still be active but they will be formatted as normal text
and will not be visible!

Ignore blank If you configure your print manual template 330 to start chapters on
pages in PDF file: odd pages you will have blank pages in your PDF file. This is fine
for printing but not so good for on-screen viewing.
This option enables you to suppress the blank pages without
editing the print manual template. Don't forget to turn it off after
using it, however – otherwise it's easy to think that "Start on odd
page" isn't working!

See also:
Customize - PDF Export 650
PDF and Printed Manuals 325
Embedding files in PDFs 332
9.3.3.3.2 PDF Options

These options set the standard options for saving the PDF output file. These are identical
with the options that you can set in Acrobat and they should all be self-explanatory.

Using variables:
Note that you can use variables 376 in all the Document Information fields.

See also:
Customize - PDF Export 650

© 1997 - 2009 by EC Software, all rights reserved

 692 Help & Manual 5 - User Help

PDF and Printed Manuals 325

9.3.3.3.3 Font Embedding

If you use non-standard fonts in your project your PDF document will normally only be
displayed correctly on the user's computer if the fonts are also installed there. You can solve
this problem by embedding the fonts in your PDF document, but this can increase the size of
your document considerably, particularly if you are using Unicode-based languages like
Asian languages.
If you need to keep your PDF files as small as possible it is advisable to only use standard
fonts like Arial and Times Roman that will be installed on all users' computers. You can then
reduce the PDF file size by adding these fonts to the exclusion list (see below).

© 1997 - 2009 by EC Software, all rights reserved

 Reference 693

Options:
Embedding If you must embed fonts you can reduce the size of your PDF files by
True Type selecting the right embedding option.
fonts:
Embed TrueType fonts embeds all TrueType fonts except the fonts
you add to the exclusion list (see below).
Embed symbol fonts only embeds fonts like Symbol and Wingdings.
This ensures that special characters that depend on these fonts will be
displayed correctly. Other fonts not found on the user's computers will
be substituted with available similar fonts.
Use Base 14 Type1 fonts tells Acrobat to substitute its own built-in
fonts. This switches off font embedding and will work adequately if your
fonts are similar enough to the Base 14 fonts (Times/Mac or Times
New Roman PS MT /Win; Helvetica/Mac or Arial MT/Win; Courier,
Symbol, and Zapf Dingbats, each with regular, bold, italic or oblique,
and bold italic styles).
Embed TrueType subset only embeds the code pages of the
TrueType fonts that are actually used in your project.
Embed TrueType subset (used characters only) saves even more
space by only embedding the characters that are actually used in your
project. Note that this can slow down compiling considerably with
larger projects.

Do not embed If you choose Embed TrueType fonts you can reduce the size of your
these fonts: output file by excluding all the common fonts that all users are likely to
have installed on their computers.
All the fonts you add to this list will not be embedded in your output file.

CID Font The CID Font Mode option in Configuration > Publishing Options
Mode: > Adobe PDF > Font Embedding can reduce the size of your PDF
for projects written in Unicode-based languages, particularly Asian
languages. In addition to this it also improves the correct rendering of
special Unicode characters in PDF.
When you set CID Font Mode to Unicode only the characters actually
used in the font are embedded in the PDF file, in a special internal
format.
This works correctly with most Asian languages. However, it may
sometimes cause problems with western languages like Russian or
other European languages with special characters.
See CID mode for Unicode fonts 332 for more details.

See also:
Customize - PDF Export 650
PDF and Printed Manuals 325

© 1997 - 2009 by EC Software, all rights reserved

 694 Help & Manual 5 - User Help

9.3.3.4 Visual Studio Help

This section provides settings for publishing Visual Studio Help, which is also known as MS
Help 2.0.

Do not use Visual Studio Help for normal applications!

Please note that this is a special help format that is only used for documenting third-party
programming components designed for integration into Visual Studio .NET. It is not
suitable for any other purpose and cannot be used for normal help projects for application
programs!

Shared settings:
The options in the HTML Export Options section are shared by all HTML-based output
formats (HTML Help, Webhelp, Windows Exe and ePub eBooks and Visual Studio Help/
MS Help 2.0). These settings are accessible in the Webhelp 684 and HTML Help 671
sections of your project configuration.
These are the general settings for all HTML output formats, including image conversion
and export options and the options for the CSS style sheet used to export the style
formatting information from your project. Here too, there is only one CSS style sheet and
one set of HTML Export Options for all these output formats. You cannot enter different
settings for each output format.

See also:
Visual Studio Help 490 (Advanced Procedures)
Visual Studio Help 738 (Reference)
9.3.3.4.1 Namespace & Options

This section is where you enter the special settings required for compiling Visual Studio Help
(MS Help 2.0). Please refer to the documentation of Visual Studio .NET and the Visual
Studio Help Integration Kit for full details!

Help file registration:

Unlike HTML Help CHM files, Visual Studio Help HXS files cannot be opened unless they
are registered in the Windows Registry (see About compiling VS Help 491 ). Also, they are
not called by their file name but by their "Namespace".
Namespa The Namespace identifier used for calling MS Help 2.0 files. No special
ce: characters or spaces are permitted. See the VS.NET documentation for
details.

Unique The unique identifier (rather like a topic ID for an entire help file) required
Identifier for Visual Studio Help files. See the VS.NET documentation for details.
:

© 1997 - 2009 by EC Software, all rights reserved

 Reference 695

Export options:
Output You can output either a single .HXS file or an .HXS file with a separate .HXL
file type: file. See the VS.NET documentation for details.

Indexes: Help & Manual can generate both full-text search and associative keyword
indexes using the A-keywords entered in the tabs of your topics.

F-Index Forces the generation of the F-Index file for use in Visual Studio Help.

See also:
Visual Studio Help 490 (Advanced Procedures)
Visual Studio Help 738 (Reference)
9.3.3.4.2 Popup Topics

These options define how popup topics are handled in Visual Studio Help. Note that only the
JavaScript popups option will export popup topics that really function as popups.
For full details see Creating popup topics 125 and Using JavaScript popups 129 .

Popup mode:
Microsoft has completely abandoned popup technology in Visual Studio Help, this format
has no native format for popups and does not support field-level popups. However, you
can add Help & Manual's own JavaScript popups for display within the main help file.
HTML-encoded Selecting this option generates popup topics as normal topics
topics: without headers – i.e. they are no longer popup topics. When this
mode is activated links to popup topics will display the topics in
the main browser window in the topic pane.

JavaScript This mode outputs popup topics using JavaScript code that allows
popups: you to use formatted text (bold, italics etc.), images, Internet and
topic hyperlinks, tables (with grid lines and borders) and even
video files in your popups.

Customizing JavaScript popups:

JavaScript popups are highly-customizable. Click on the Customize button to display the
configuration dialog:

© 1997 - 2009 by EC Software, all rights reserved

696 Help & Manual 5 - User Help

Click/ Displays the popup on user click or mouseover (i.e. as soon as the user
mouseover: moves the mouse pointer over the link). Be careful with using the
mouseover option as many users find this intrusive and it may also
trigger popup blockers in some browsers.

Minimum Setting this to 0 makes the popup width automatic, on the basis of the
width: amount of text and/or other content.
Setting it to any other value (in pixels) explicitly defines the width of the
popup. If the popup only contains text it will have the width you specify.
If it contains other content (graphics, videos) it will be at least as wide
as the specified width and wider if required by the content.

Border width: Enter 0 for no border, any value above 0 (in pixels) to draw a border
around the popup box.

Border The distance between the popup content and the border or edge of the
padding: popup (if there is no border) in pixels.

Background: The background color of the popup box.

Border color: The color of the border, if there is one.

Visual These effects are only supported by MS Internet Explorer. This means
effects: that they are available in HTML Help (which uses MSIE) and in
Webhelp when the user is using Internet Explorer. They are ignored by
all other browsers.
These effects are easier to see than to describe. Experiment! (Note
that the transition effects are only for opening the popup box. The
popups always close in the same way, no matter what effect you
select.)

See also:
Creating popup topics 125

© 1997 - 2009 by EC Software, all rights reserved

 Reference 697

Using JavaScript popups 129

9.3.3.4.3 HTML Export Options

These options control many key aspects of how your project content is converted to HTML
code for all the HTML-based output formats, including how the styles used in your project
are exported to a CSS cascading style sheet file, how graphic images are converted and
exported and a number of other important settings.

This is a shared section:

Note that these options are shared by all HTML-based output formats (HTML Help, Visual
Studio Help (MS Help 2.0), Webhelp and Windows Exe and ePub eBooks). They are
accessible in several locations in your project Configuration but no matter where you edit
them you are always editing the same settings. You cannot save different HTML Export
settings for the individual HTML-based output formats.
With a couple of small exceptions (noted in the descriptions of the individual settings) all
the options are used by all output formats.
Extension for By default all HTML topic files are exported with the extension .
HTML topic files: htm. You can change this to .html, .asp, .php or a manually-
entered extension but these extensions are only supported in
Webhelp.
The .htm extension is always used for topic files in HTML Help,
and MS Help 2.0.
This setting is irrelevant for eBooks.

CSS stylesheet This setting allows you to change the name of the stylesheet file
file name: exported with the CSS style information. The default file name is
default.css.

Font size This setting allows you to choose how font sizes are defined in your
encoding: output. You can choose pt (points), px (pixels), % (percent) or
ems (where 1 em = 100%). Which setting you choose controls
how fonts are displayed on the user's screen and whether or not
the user can change the font size.
Choose Pixels to lock your font size and layout, Percent to
allow the user to change the font size.
Points:
When you export the font size in points the user cannot adjust the
font size. However, the size of the fonts displayed on the user's
computer screen will vary depending on the Windows screen DPI
setting and/or font size settings. For example, if you develop your
help on a machine with Windows set to 96dpi (the standard) your
text layout may be incorrect on computers set to 120dpi (fonts look
much too big, text in hanging indents may be wider than the indent
etc). This is because the size of the fonts changes but the size of
the other layout elements (indents, locked table cells etc.) doesn't.

© 1997 - 2009 by EC Software, all rights reserved

698 Help & Manual 5 - User Help

Pixels:
This is the only setting that ensures that the fonts and your layout
will always be displayed exactly as you see them on your
development machine. The font size is always uses the same
number of pixels, so it is always the same size relative to other
elements of your layout like indents, graphics and so on.
Percent or Ems:
If you select percent or Ems the user will be able to adjust the font
size in the help, for example by holding down Ctrl and turning the
mouse scroll wheel. This may or may not be a good thing, because
the size of other layout elements (graphics, indents, locked table
cells etc.) will not change, so the user adjustments may "break"
your layout.

Font size of If you choose percent or ems for font size encoding (see above)
Normal style: you can also use this setting to define the size of the Normal style
in relation to the default font of the user's browser. The value is
expressed in percent and the default is 100%. This is normally
preferable because most users will have set the default font in their
browsers to the size of font they prefer.

Export XHTML If you select this Help & Manual will generate HTML code that is
1.1 compliant compliant with the XHTML 1.1 specification.
HTML:
This is only used in Webhelp. The HTML Help compiler cannot
handle XHTML-compliant code and it is also not relevant for
eBooks.
Note that XHTML code is fine for modern browsers but the
specification contains a number of features that older browsers
cannot handle correctly. If you believe you have a significant
number of users still using old browsers it is better to deselect this.
New browsers will not have a problem with this because they can
also handle code that is not fully XHTML-compliant .

Export Webhelp Only switch this off if you are using PHP code in your project and
with UTF-8 BOM: your server's PHP system is having trouble with the BOM at the
beginning of your webhelp files. If you don't know what PHP is you
don't need to turn this off!
All Help & Manual webhelp files are stored in UTF-8 Unicode. The
UTF-8 BOM (Byte Order Mark) is a special character code at the
beginning of the file that identifies it as UTF-8 Unicode. It is
generally better to leave this in because it will prevent old and
badly-configured servers from misinterpreting the UTF-8 Unicode
formatting. However, the PHP installations on almost all servers
still have trouble with the BOM and so it is better to switch the BOM
off if you are using PHP.

Apply date and When this is on (default setting) the timestamps of your HTML
time stamp of topic files will be set to the date and time of the topic in your

© 1997 - 2009 by EC Software, all rights reserved

 Reference 699

topic to HTML project, which is equivalent to the time of the last change. This
topic files: makes it easier to synchronize your output folder with an old
version on your web server, for example. This is only really relevant
for Webhelp output – in CHM help the topic files are all hidden
inside the CHM.
If you turn this off the timestamps of all HTML files will always be
the date and time at which your entire project was compiled.
Do not turn this setting off unless you have a specific reason to do
so.

Modify archive Turning this on will automatically switch the archive bits of all
bit of topic files modified files in your Webhelp output folder. Use this if you have
depending on an FTP program like Second Copy that can synchronize your
changes: output folder with your web server folder using archive bits.
The advantage of this is that it automatically flags all modified files,
even if their timestamps have not changed. This is important
because the timestamps of your topic files are only changed if the
topics have actually been edited. For example, if you change your
HTML templates this will change all your topic files but it will not
change the timestamps of topic files that have not been edited,
even though their contents change because of the template
changes. Using archive bits guarantees that all modified files are
identified.
Using this option only makes sense if you have an FTP program
that supports folder synchronization on the basis of archive bits,
however...

Export style When this is selected Help & Manual uses the full names of your
names: styles in the stylesheet. This makes the sheet much easier to read
if you ever want to view or edit it manually.
If you deselect this option the style names are converted to brief,
alphanumeric codes that are not so "human-friendly". This can
make your project a little bit smaller but not much.

Export lists as This setting is recommended. When it is selected numbered and

tables: bulleted lists are converted to tables in HTML-based output. This is
the only way to make stable lists that display correctly in all
browsers, using the indents that you set. Even in HTML Help,
which uses MS Internet Explorer for HTML rendering, you will find
that lists display better as tables.
If you deselect this option lists will be exported as standard <OL>
and <UL> lists with <LI> list elements. Unless you use very simple
lists the rendering of these elements will be unsatisfactory in many
browsers.

If an image has Images in HTML pages can have an ALT attribute that displays a
no caption small text in a "tooltip" when the user positions the mouse pointer

© 1997 - 2009 by EC Software, all rights reserved

 700 Help & Manual 5 - User Help

export file name over the image.

as hint:
Selecting this option exports the image file name as the ALT
attribute if the image doesn't have a caption. Unless your graphics
files have very descriptive names it is normally advisable to switch
this off.

Conversion This option controls how the images in your project are converted
options for and exported when you compile to HTML-based formats.
bitmaps and
Impict images:
Which option provides the best results depends on the type of
images in your project. GIF provides the smallest files with the best
quality for screenshots with 256 colors or less.
Screenshots of any resolution almost always look terrible when
converted to JPG so you should always choose your settings to
make sure that this doesn't happen. Always use GIF and no more
than 256 colors for screenshots.
JPG and true-color PNG are really only needed for photographs
and continuous-tone graphics. To minimize help file size make sure
that all other files have no more than 256 colors.

Output quality You can reduce file size by decreasing the quality but this will also
for JPEG images: make the images look less good. A value of between 80 and 90 is
normally acceptable.
Note that this quality setting is only applied to JPEG images
actually generated by the program on the basis of the conversion
settings (see above). JPEG images that you insert in your project
directly are not affected. They are used as they are, without any
changes.

See also:
Configuring Your Output 292
Publishing Your Projects 292
Visual Studio Help 490 (Advanced Procedures)
Visual Studio Help 738 (Reference)
9.3.3.5 Winhelp

The settings in this section control how your project is exported to Winhelp. Winhelp is now
an obsolete format that should not be used for modern applications but Help & Manual still
includes full support for it for backward compatibility. However, support for the 16-bit
Winhelp format used in Windows 3.0 is no longer provided as this format is no longer
relevant or necessary for any purposes. The 16-bit version of Winhelp is so buggy on 32-bit
and 64-bit versions of Windows that it is unusable.
Since the introduction of Windows 98 HTML Help 727 has been the standard format for help
for Windows applications and it should be used for local help installed on the user's
computer for all new applications. Webhelp 674 should be used for help accessed on network
drives or the Internet.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 701

Winhelp is not supported by default in Windows Vista:

Support for Winhelp is disabled by default in Microsoft Windows Vista. Even if your
applications run under Vista, any calls to Winhelp help will simply produce an error
message. Support for Winhelp can be added by downloading and installing the Vista
version of the Winhelp viewer from Microsoft but developers are not permitted to
distribute this update with their products. It is also possible that the operating system
support for Winhelp may be removed in the future. We thus strongly recommend that you
start transitioning to an alternative help format as soon as possible. See here for details

See also:
Winhelp 740 (Help Formats)
Winhelp Options 663 (Help windows)
9.3.3.5.1 Miscellaneous Settings

These settings configure the basic features of Winhelp in your output file.
Full text If you enable full text search capabilities for Winhelp (HLP) files the
search index: help compiler will generate a full-text search index for the help file and
the Find tab in the Winhelp viewer will be populated the first time the
user selects it.
The only advantage of this is that your users will not be prompted to
generate the index the first time they open the help. On modern
computers generating the index is completed almost instantaneously
and users are used to doing it, so you can speed up compiling and
reduce your distribution file size by turning this option off.

Include... Self-explanatory options for the full-text search feature in Winhelp.

Citation: When users copy and paste text from a Winhelp help file this text is
automatically included at the top of the pasted text. You can use it for a
copyright notice or any other information you want to display when your
uses paste text.
You can also use the text entered here anywhere in your project by
using the <%CITATION%> variable. See Using Variables 376 for details.

Encoding of Winhelp treats anchors in topics as absolute IDs that have the same
topic status as topic IDs. If anchor IDs were used on their own it would
anchors: theoretically be possible to have an anchor ID that was identical to an
existing topic ID, and this would cause problems.
To ensure that an anchor is always unique Help & Manual generates a
new ID for anchors by combining the topic ID and the anchor ID,
separating the two with a colon (:) by default.
This is suitable for most situations. If you need a different encoding,
you may either select a different separator (an underscore or a dot).
Alternatively you can choose the last option: Use anchor ID without
topic ID. This option encodes the anchor IDs as they are and

© 1997 - 2009 by EC Software, all rights reserved

 702 Help & Manual 5 - User Help

assumes that they are unique and do not conflict with topic IDs. Note
that Help & Manual does not check for duplicates so you use this
option at your own risk.

Export A- By default Help & Manual generates A-keywords 281 as A-footnotes in

keywords as: the temporary RTF file used to generate the Winhelp output. This is
the default value for Winhelp and if you don't know what it is for please
do not change this setting.
If you do need to change it you can enter any footnote character you
like here for the A-keywords. (See the documentation of Microsoft Help
Workshop if you need more information on this subject.)

Limit images The Winhelp viewer has an uncorrected bug that can cause the viewer
to 256 colors: to hang or crash on computers with a display that has limited color
depth if the help file contains images with more than 256 colors.
This option automatically reduces all images to 256 colors to prevent
these crashes. Using it is strongly recommended since you have no
control over the display configuration on your users' computers!

See also:
Winhelp 740 (Help Formats)
Winhelp Options 663 (Help Windows)
Anchors - jump targets 226
Using Variables 376
Keywords and Indexes 273
9.3.3.5.2 Modular Help Options

This option is relevant for the way modular help is handled in Winhelp projects. Please
study Working with Modular Help Systems 446 and Modular Projects 764 before using these
features!
Table of This setting adjusts the indentation ("offset") of your child help modules
contents Table of Contents entries when they are inserted in the TOC of the
offset: parent (master) module. A value of 1 represents an offset of one sub-
topic level, a value of 2 represents an offset of two sub-topic levels and
so on.
You only need to adjust the setting for child modules in modular help
projects. Set it to 0 for non-modular projects and master modules.

See also:
Winhelp 740 (Help Formats)
Winhelp Options 663 (Help Windows)
Working with Modular Help Systems 446
Modular Projects 764 (Reference)
Choosing the merge method 451

© 1997 - 2009 by EC Software, all rights reserved

 Reference 703

9.3.3.5.3 Extended .HPJ Settings

This section enables you to add or overwrite sections of the HPJ project file used to
generate your Winhelp output. (See Winhelp project files 742 for details). Normally you will
never need to use this feature but there may be situations when you want or need to make
changes to your Winhelp output by making changes or additions to the HPJ file.
This feature is designed for advanced users familiar with manual Winhelp encoding! Please
do not make any entries here unless you understand .hpj files and how to edit them. You
can find information on the sections and settings in the documentation distributed with
Microsoft Help Workshop.

How to edit the Extended .HPJ Settings:

Normally Help & Manual generates the settings for the HPJ file automatically and you will
almost never need to change them. If you do want to add settings that are not generally
included you must enter them in with same format and syntax as in an INI file.
This example shows a typical HPJ file exported by Help & Manual to generate a Winhelp
file:

Example of an .hpj file as exported by H&M

; This file is maintained by HCW. Do not modify this file

directly.
[OPTIONS]
HCW=0
COMPRESS=12 Hall Zeck
LCID=0x409 0x0 0x0 ;English (USA)
REPORT=Yes
CHARSET=1
FTS=1
CONTENTS=Introduction
TITLE=Help & Manual help
CNT=.\HELPMAN.cnt
COPYRIGHT=© 2005 EC Software, all rights reserved
CITATION=© 2005 EC Software
DEFFONT=MS Sans Serif,8,0
HLP=.\HELPMAN.hlp

[FILES]
.\HELPMAN.rtf

[WINDOWS]
Another="Secondary window",(110,276,679,408),27904,(r16777088),
(r12632256),1
Main="Main window",(204,3,592,743),28420,(r16777215),
(r12632256),f3

There is no [MAP] section in this file because no help context numbers were defined in
any of the topics. Let's assume that you want to include another file that contains the
mappings for context sensitive help. You can achieve this by adding the appropriate entry
to the [MAP] section together with an #include statement to include the external file

© 1997 - 2009 by EC Software, all rights reserved

704 Help & Manual 5 - User Help

containing the mappings.

In addition to this, let's also assume that you want to change the target path of the
compiled help file. This requires two lines in the [OPTIONS] section, one each for the
main help file and the contents file.
To make these changes you would enter the following lines in the edit box of the
Extended .HPJ Settings section:
[OPTIONS]
CNT=F:\data\common projects\help\helpman.cnt
HLP=F:\data\common projects\help\helpman.hlp
[MAP]
main_index=HID_MAIN
#include .\ProjektX.txt
The next time Help & Manual exports your project these lines will be merged with the
standard output and the result will look like this (the inserted items are shown in red):

Merged .hpj file with manually-inserted lines:

; This file is maintained by HCW. Do not modify this file

directly.
[OPTIONS]
HCW=0
COMPRESS=12 Hall Zeck
LCID=0x409 0x0 0x0 ;Englisch (USA)
REPORT=Yes
CHARSET=1
FTS=1
CONTENTS=Introduction
TITLE=Help & Manual help
CNT=F:\data\common projects\help\helpman.cnt
COPYRIGHT=© 2005 EC Software, all rights reserved
CITATION=© 2005 EC Software
DEFFONT=MS Sans Serif,8,0
HLP=F:\data\common projects\help\helpman.hlp

[FILES]
.\HELPMAN.rtf

[WINDOWS]
Another="Secondary window",(110,276,679,408),27904,(r16777088),
(r12632256),1
Main="Main window",(204,3,592,743),28420,(r16777215),
(r12632256),f3
[MAP]
main_index=HID_MAIN
#include .\ProjektX.txt

See the documentation distributed with Microsoft Help Workshop. for full details on HPJ
files and their settings.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 705

See also:
Winhelp 740 (Help Formats)
Winhelp Options 663 (Help Windows)
9.3.3.6 Microsoft Word RTF

The settings in this section control how your project is exported to MS Word RTF, which
generates Rich Text files compatible with the RTF files generated by Microsoft Word.
Support for this format is provided for backward compatibility only, it is not a good format for
high-quality modern documentation.

Limitations of the Word RTF format:

Because of its limitations Word RTF is generally not recommended. PDF provides
superior output and much more control over formatting. There may be some special
cases where you still need to use RTF, but generally PDF is always preferable.

9.3.3.6.1 Page Setup & Headings

The options in this section control the layout, appearance and functionality of your MS Word
RTF output. These are the only options that have an effect on Word RTF output. Everything
else is controlled by your formatting in your topics.
Options:
Page Format: These settings configure the basic format of your output pages
and are the same as in Word.
Margins:
Mirror margins automatically reverses asymmetrical margins so
that they are displayed correctly on facing even and odd pages.

Texts for Header, The text and font settings for the headers, footers and page
Footer and numbering. You can use variables 376 in these fields.
"Page":
Note that the page number is inserted automatically after the
"Page:" text. You don't need to use a variable for this.

Level formats for Sets the fonts and settings for your topic headers. The levels are
topic headings: the levels in the TOC. The headers will always use the formatting
specified here, not the formatting applied in the header box in
your project.
You can also activate heading chapter numbering and automatic
insertion of page breaks for the individual levels.

Export active Exports the hyperlinks supported by Word RTF so that they can
hyperlinks: be used for online viewing. (Not all link types are supported.
Unsupported links will be exported as plain text.)

Insert file name Images in your project are not embedded in the RTF file because
marker for linked of the poor way in which RTF manages embedded images.
images: Selecting this option inserts the name of the file after the image,
which makes it easier to identify the external image files.

© 1997 - 2009 by EC Software, all rights reserved

 706 Help & Manual 5 - User Help

See also:
MS Word RTF 739 (Help Formats)
9.3.3.7 eBooks

The settings in this section control how your project is exported to eBooks, which are self-
contained, single-file formats designed to simulate the experience of reading books on
computers or electronic devices.
Help & Manual supports two eBooks formats: Windows Exe eBooks for Windows only and
the cross-platform ePub eBooks format, which also supports hardware eBook readers. See
the sections on eBooks in the Publishing Formats 732 and Configuring Your Output 292
chapters for more information on these two formats.

See also:
Publishing Formats - eBooks 732
Configuring Your Output - eBooks 304
9.3.3.7.1 Windows Exe eBooks

Windows Exe eBooks can only be viewed on Windows computers and are compatible with
all versions from Windows 95 on up without additional software. They are distributed in an
executable .exe file that also contains the viewer, so they are completely self-contained.
See Windows Exe eBooks 735 in the Publishing Formats chapter for more details.
This is an HTML-based format that shares some settings with the other HTML-based output
formats supported by Help & Manual.

Shared settings:
The options in the HTML Export Options section are shared by all HTML-based output
formats (HTML Help, Webhelp, Windows Exe and ePub eBooks and Visual Studio Help/
MS Help 2.0). These settings are accessible in the Webhelp 684 and HTML Help 671
sections of your project configuration.
These are the general settings for all HTML output formats, including image conversion
and export options and the options for the CSS style sheet used to export the style
formatting information from your project. Here too, there is only one CSS style sheet and
one set of HTML Export Options for all these output formats. You cannot enter different
settings for each output format.

9.3.3.7.1.1 Visual Appearance

As the name indicates, the settings in this section control the appearance of your Windows
Exe eBooks output. In addition to selecting the template (non-editable) defining the
appearance of the integrated eBook help viewer you can also define the size and position of
the viewer on the screen, a graphic for a splash screen, a file icon and two sound effects.
Options:
Viewer template: This template defines the appearance of the eBook viewer. You
must choose one of the templates stored in the
\Templates\ebooks folder in the Help & Manual program

© 1997 - 2009 by EC Software, all rights reserved

 Reference 707

directory.
These templates are not user-editable. Also, please note that the
graphical templates are not resizable so their size cannot be set
with the Default Position & Size settings (see below).

Form icon: This option allows you to select an icon file to be displayed in
Windows explorer for your eBook EXE file. You can only select
standard ICO icon files for this.

Startup screen: The graphic image you select here will be displayed briefly in an
external window as a "splash screen" when the user starts your
eBook.
The image must be in BMP format. It will be converted to a
compressed format automatically by Help & Manual when you
compile your project.

Startup sound: You can use these options to add sound effects to your eBook.
Page turn sound: The startup sound is played when the eBook is opened and can
be a little longer. The page turn sound should be very brief,
otherwise users will be annoyed by the delay.
You can only use audio files in the standard Windows WAV
format. They will be compressed together with the eBook when
you publish your output.

Default position These values define the initial position and size of the eBook
and size: viewer when it is first displayed if you are using a resizable
template. You can enter them manually as pixel values or use the
Position Wizard button.
The default values of -1 for all four settings leave the viewer size
and position undefined and let Windows choose the window size
and position automatically.
If you choose a fixed-size template only the position values are
used, the size values are ignored.

Viewer window is Maximizes the eBook viewer on the user's screen when it is
maximized: opened. This option is not supported for fixed-width viewer
templates.

The Position Wizard displays a dummy window that you can

position and resize on the screen to set the size and position
values.
If you have a dual-monitor system use the Position Wizard in the
primary monitor and make sure that the primary monitor is on the
left: On dual-monitor systems the 0,0 position is defined as the top
left corner of the primary monitor, so doing this will make sure that
the resulting values also work on single-monitor computers.

© 1997 - 2009 by EC Software, all rights reserved

 708 Help & Manual 5 - User Help

The Default Positions button resets all the position and size
values to -1 to let Windows handle the window sizing (see above).

See also:
Windows Exe eBooks 735 (more information on this format)
9.3.3.7.1.2 Functionality & Security

This section includes options that control how your Windows Exe eBook works, its interface
language and some useful security features to protect your content.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 709

Options:
Language pack: Allows you to select the language to be used for the eBook
interface. Several language packs for common languages are
included with the program. They can be found in the
\Templates\ebooks folder in the Help & Manual program
directory.
Language packs are plain text files with the extension .lng
containing the definitions for the texts used in the viewer.
If there is no language pack available for your language you can
create one yourself by making a copy of the English.lng pack and
editing it. Don't delete or change any variable names and be
careful not to change the format of the file!

Enable keyword Include or exclude the keyword index and full-text search options
index: in the viewer.
Enable full text
search:

Compress viewer This reduces the size of the eBook by compressing the viewer
application: program. This can cause a slight delay when the program is
started so if you are distributing your eBook on a CD it is better
not to compress the application.

Text for About The text to be displayed when the user clicks on the About icon in
box: the viewer. You can use user-defined variables 378 to insert text in
this box.

Security: Here you can prevent users from being able to copy text from the
eBook to the clipboard and password-protect your eBook.

Copy protect If you select this option the viewer can only be run from a CD with
viewer: the specified serial number. If it is copied to a hard disk or another
CD it will not be functional.
Important:
All your CDs must have the same serial number for this function
to work! Since this capability has been removed from all publicly-
available CD burning programs for security regions this feature
can only be used on pressed CDs where you can apply the same
serial number to all the CDs.

See also:
Windows Exe eBooks 735 (more information on this format)
9.3.3.7.1.3 Popups in eBooks

Popup topics can be used in Windows Exe eBooks and they support hyperlinks and
graphics. However, they are not configurable – that is why there are no settings for them in
the Windows eBooks section of Project Properties. They are sized automatically on the

© 1997 - 2009 by EC Software, all rights reserved

 710 Help & Manual 5 - User Help

basis of their content and they use the background color of the HTML Page Template 666
selected for the popup topic.

See also:
Creating popup topics 125
Windows Exe eBooks 735 (more information on this format)
9.3.3.7.2 ePub ebooks

The ePub eBook format is outstanding for universal distribution across many platforms and
devices but precisely because of this it is also more restrictive than some other formats. It is
designed to be more like a book than an electronic document and it thus has some special
requirements and restrictions.
Before publishing to ePub first visit the Adobe Digital Editions download page and install
the Digital Editions eBook reader. This is essential because without it you will not be able to
view your ePub eBooks after you have created them.
You will also need to check whether everything in your project is compatible with ePub.
Please also study the information on ePub eBooks in the Configuring Your Output 305 and
Publishing Formats 732 and Configuration Settings 710 chapters before proceeding.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 711

Configuration settings
The only configuration options you need to enter for generating ePub eBooks are an
identifier and a number of standard information fields. The only field that is absolutely
required is the UID, which is the unique identifier for your eBook.
You can use text variables 376 in all these fields! These settings are available in Project
Explorer > Configuration > Publishing Options > eBooks > ePub Standard.
UID (required): Required!
This is the unique identifier of your eBook, so you should attempt to make
it genuinely unique to avoid confusion with other available publications.
You can use any alphanumeric text string here – for example your web
address plus the name of the book. If the book has an official ISBN book
catalog number then use that.
URI: Optional but recommended
A web link, for example to a page with information about the book on your
website. It's a good idea to include this as eBook readers often have
online access. Always include the http:// prefix with the URI, plain www.
addresses may not work!
Subject: Optional but recommended
A short description of your eBook.
Description: Optional, generally helpful
A longer description of your eBook.
Relation: Optional
Relation information for your eBook, this can be an URI (weblink, the new
term for URLs) or other information.
Creator: Optional but recommended
The author of your eBook – if you have entered the author of your project
in your Common Properties you can insert the Tim Green variable here to
use the same text string automatically.
Publisher: Optional but recommended
The publisher (i.e. your company) of the eBook.

9.4 Styles, Formatting and Tables

This section provides some general background information on the styles used in Help &
Manual and how they work. If you are familiar with using styles in word processors like
Microsoft Word most of this will already be familiar to you but there are also some
differences that you should be aware of.

See also:
Text Formatting and Styles 155 (how-to instructions)
9.4.1 Why use dynamic styles?
The advantages of dynamic styles are so great that you will never want to go back to
manual formatting once you have learned how to use them. They will speed up your work,

© 1997 - 2009 by EC Software, all rights reserved

712 Help & Manual 5 - User Help

make it more efficient and make your finished product look more attractive and professional.
If you wish, it is quite possible to use only manual formatting in your Help & Manual projects.
However, if you do this you will create a lot of unnecessary extra work for yourself and your
documentation will not look so good.

Instant changes throughout your project

When you format text manually you have to go back and change everything manually
whenever you change your mind about how you want a headline or a paragraph to look.
This can take hours in a big project, and since it's boring and repetitive work you are also
likely to make mistakes. Also, when you format manually you will often apply slightly
different formatting to text passages that are supposed to look the same, and your work
will look messy as a result.
Suppose your client or your boss says that they want to use Verdana 16 point instead of
Times Roman 14 point in the topic headers. With styles all you need to do is change the
definition of the heading style, which takes a couple of seconds, and all the headers in
your entire project are updated instantly.
You can think of a style as a named formatting definition for either text or an entire
paragraph. When you use styles you have a separate style for every different type of
paragraph and text in your project. For example, by default normal body text paragraphs
are normally formatted with a style called Normal, and the topic headers are normally
formatted with a style called Heading1. You can define as many other styles as you like
for other purposes.

Instant formatting
Once you get the hang of it, working with styles is much faster than using manual
formatting. To format an entire paragraph you just select the style in the menu, or press
the hotkey combination for the style, and all the formatting is applied immediately. You
don't even have to select the paragraph. And all new text and paragraphs you type from
that point will also have the selected style until you change it.

Uniform appearance and layout

Since your styles are predefined all your formatting, indents and so on will be identical,
giving your projects a uniform and much more professional appearance.

"Branding" your output with skins

If you have the Professional version of Help & Manual you can save all your styles and
your other project layout settings in a special format file called a "skin". When you publish
another project you can apply all the styles from the skin to it by selecting the skin file in
the Publish 590 dialog all the styles in the project with matching names will then be
replaced by the styles from the skin.
See Transforming Your Output with Skins 321 for full details on this.

Dynamic inheritance
Help & Manual's styles aren't just dynamic, they also have dynamic inheritance. This
means that styles based on other styles automatically "inherit" the properties of their
parent styles. All properties that you do not change in the child styles are dynamically

© 1997 - 2009 by EC Software, all rights reserved

 Reference 713

linked to the parent style.

This means you can create families of styles in which you can change properties
throughout the entire family just by modifying a single parent style. See About inheritance
in styles 714 for full details on dynamic inheritance and how it works.

Smaller output files

Note that using styles efficiently can also make your output files quite a bit smaller,
particularly in HTML-based output (HTML Help, Webhelp, Visual Studio Help, Windows
Exe and ePub eBooks). Manual formatting must include a large number of detailed tags
every time it is applied – in extreme cases these tags can use up more bytes than the text
itself. Styles are only defined once and are applied with a simple and very brief reference
to the internal stylesheet.

See also:
Text Formatting and Styles 155 (how-to instructions)
About inheritance in styles 714
9.4.2 How do styles work?
To understand how dynamic styles work you need to understand three concepts: Style
definitions, dynamic linking and dynamic inheritance. Style definitions are how you create
styles, dynamic linking is how your styles are associated with your text and dynamic
inheritance enables you to create related "families" of styles.

Style definitions:
A style is a set of formatting definitions with a name that makes it possible for you to
identify and select it. It can include all the formatting attributes that you can apply to text
and paragraphs with the Font, Paragraph and Borders and Backgrounds formatting tools.
For convenience, you can create two kinds of styles: Text styles, which only define font
formatting attributes, and paragraph styles, which define all available attributes, including
font attributes. Similarly, styles can also be linked to either entire paragraphs or individual
passages of text. These are the two "units" that are used in connection with styles. (See
Paragraph and text styles 718 for details.)

Dynamic linking:
A set of formatting definitions is no good on its own, of course. Styles are useful because
you can link them to paragraphs and text in your project. As soon as you apply a style 167
to a paragraph or a passage of text the style definition is dynamically linked to that
paragraph or that text. All the style attributes are applied to the paragraph or the text
automatically, and when the cursor is in the paragraph or the text the name of the style is
displayed in the style selector in the Toolbar:

Here the cursor is in a paragraph

formatted with the Normal style.

© 1997 - 2009 by EC Software, all rights reserved

 714 Help & Manual 5 - User Help

We say that the style is dynamically linked because all changes in the style definition are
automatically and immediately reflected in all paragraphs and/or text linked to the style. If
you change the font face, font size, paragraph indents and so on in the style definition
these changes are all immediately reflected in all the paragraphs and text linked to the
style.

Dynamic inheritance:
Most styles are based on other styles this makes defining styles easier, because you
often have groups of quite similar styles. In addition to this it also makes styles much
more powerful. Here's why:
We refer to "parent" and "child" styles. Just as a human child inherits some genes from
its parents and has some unique characteristics of its own, styles also inherit some
properties from their parents and have some properties of their own.
In styles, however, inheritance is dynamic, in exactly the same way that linking to the text
formatted by styles is dynamic. All attributes that you don't change in the child styles are
shared with the parent style. If you change an attribute in the parent style the change is
immediately reflected in both the child style and all paragraphs and/or text formatted with
the child style.
This means that you can make changes to entire "families" of styles, and to all the text
formatted with those styles, just by editing one parent style. For example, you can usually
change the font in your entire project by changing the font setting in the Normal style,
because most of styles in your project are usually based on that style.
See About inheritance in styles 714 for full details on this subject.

See also:
Text Formatting and Styles 155 (how-to instructions)
About inheritance in styles 714
9.4.3 About inheritance in styles
Alongside dynamic linking 713 , dynamic inheritance is the second feature that gives dynamic
styles their great flexibility and power. If you understand dynamic inheritance you will be able
to use and organize your styles much more efficiently, so please do study this topic carefully!

What is dynamic inheritance?

Put briefly, dynamic inheritance means that styles based on other styles inherit the
attributes of their parent styles, and the inherited attributes are dynamically linked to the
same attributes in the parent styles. If an attribute is changed in the parent the change is
automatically (and immediately) inherited by all child styles. Equally, these changes are
also automatically and immediately reflected in all texts to which the child styles are
linked.
For example, if you change the font of the Normal style, which is usually the
"Granddaddy" style on which almost all styles in any project are based, this automatically
and immediately changes the font in (almost) all styles in your project. The only
exceptions are styles that are not based on Normal, and styles which already have
different fonts set.
And this is the next important aspect of dynamic inheritance: It only applies to attributes

© 1997 - 2009 by EC Software, all rights reserved

 Reference 715

that have not been changed in the child styles. As soon as an attribute is changed in a
style it is "fixed", and no longer affected by changes in the parent style. Styles based on
the changed child style will then inherit this new attribute, not the original attribute from
the original parent.

The inheritance tree

Styles do not have to be based on other styles but they usually are. When you create a
new style on the basis of another style (see Defining styles 161 ) it is initially an exact copy
of its parent style, so that it shares all its attributes of the parent. We say that the child
style "inherits" all the attributes of its parent style.
Two identical styles wouldn't be much use, so you then edit some of the attributes of your
new style and leave others unchanged. The key to understanding dynamic inheritance is
understanding its relationship to the changed and unchanged attributes in the child styles.
Let's have a look at a simple example of a style inheritance tree. The standard style on
which almost all other styles are based is called Normal. You can edit this style, but like
the other standard styles 717 you cannot rename it or delete it. The example below shows
some styles based on Normal. Please note that this tree is simplified to make the
explanations easier; in reality there are many more attributes, and each style could also
have multiple children on each level instead of just one.

Fig. 1: Simplified example of a style tree

Changed and unchanged attributes:

In this example changed attributes are shown in blue, unchanged attributes in black.
The unchanged attributes are dynamically linked to the corresponding attributes in their
parent styles – changes made to these attributes in the parent are automatically inherited
by the children. By the same token, inheritance from the parent stops at the changed
attributes.
How this works in the example:
In the example above all the child styles except Callout inherit the Arial font from Normal,
because this font face has not been changed in any of these styles. If you edit Normal
and change Arial to Times Roman then the font of all the child styles except Callout will

© 1997 - 2009 by EC Software, all rights reserved

716 Help & Manual 5 - User Help

automatically change from Arial to Times Roman.

The styles Normal Indent and Normal Indent 2 also inherit the font size from Normal. If
you edit Normal and change the its font size from 11 points to 12 points this change will
be inherited by these two styles, but not by the two Heading styles.
Another good example is the Space After attribute. In Normal this attribute is set to 0.1",
and this value is inherited by all of the child styles except Heading2. If you edit Normal
and set its Space After attribute to 0.0" this change will be inherited by all the child styles
except Heading2.
Changed attributes start a new inheritance sequence:
A changed attribute in a child style starts a new inheritance sequence:
In Callout the original font has been changed to Verdana 10. Callout 2 inherits the font
face, but the size has been changed to 12. This means that if you edit Callout and
change its font to Tahoma, this change will be inherited by Callout 2. However, changing
the font size in Callout will not be reflected in Callout 2, because the font size has been
changed there, thus stopping inheritance for that attribute.
The same applies to the font weight in the two Heading styles. In Heading1 the font
weight has been changed to bold, so changes to the font weight in Normal will not have
any effect on Heading1 or any of its children. Heading2 inherits the font weight attribute
from Heading1, so if you edit Heading1 and change its weight to non-bold this change will
be inherited by Heading2.
This illustrates the most important characteristic of inheritance for changed attributes:
Changing an attribute turns off inheritance from the parent for that attribute. At the same
time, however, it starts a new inheritance tree for the same attribute: when you create
new styles based on the modified style the new setting is inherited by the new styles.

Parallel inheritance and serial inheritance:

You can also organize the inheritance of your style families in two different ways, with
parallel inheritance and serial inheritance. It works like this:

Fig. 2: Parallel and serial inheritance

In parallel inheritance trees all the sub-styles are direct children of the parent style. This
option is used when you are creating direct variants of a parent style. For example, you
might use this to create three different variants of your body text style that have different
indents but are otherwise identical.
In serial trees you have a grandparent - parent - child relationship structure. Each new
style is based on the preceding variant. This option is used for families of styles that
change progressively. A typical example of this is a family of headline styles with font
sizes that get progressively smaller.
As Fig. 1 715 further above in this topic shows, most style trees use a combination of

© 1997 - 2009 by EC Software, all rights reserved

 Reference 717

parallel and serial inheritance.

Why dynamic inheritance is useful:

Just as dynamic styles make it possible to reformat your entire project by editing a couple
of style definitions, dynamic inheritance makes it possible to make basic changes to
entire families of styles by editing a single style definition. For example, you can usually
change the base font for your entire project by changing the font setting of Normal. For
more details on using these features to plan your styles see Style organization strategies
720 .

Stopping inheritance:
Precisely because dynamic inheritance is so powerful there may be times when you want
to stop it. There are situations when you want to make absolutely certain that a style will
never be changed when you make changes to another style.
Doing this is very simple: Just don't base your new style on another style: When you
create a new style 161 select (None) in the Based on Style: field for the style definition. You
can also change this later if you want. See Editing styles 164 for details.
The standard Code Example style used for formatting program code with the syntax
highlighter 195 is an example of this. This style does not have a parent because its format
must always be the same – you don't want any other styles to be able to change its font,
size or paragraph formatting.
A style without a parent starts a new inheritance tree
A style without a parent does not inherit any attributes from any other styles. This means
that it is "protected" against unexpected changes caused by changes in parent styles.
At the same time, a style without a parent is also the "first parent" in a new inheritance
tree: If you base new styles on this style they will inherit the properties of the style. You
can use these capabilities to create new and separate families of styles. See Style
organization strategies 720 for some more ideas on this.
Switch off inheritance with caution!
When you are learning how to use styles it is tempting to switch off inheritance for many
styles because you may think this will give you greater control over your formatting. In the
short term this is true but in the long term it is better to learn to use inheritance efficiently.
Defining many styles without parents will actually create much more work for you later if
you decide to make far-reaching changes in your formatting. Again, see Style
organization strategies 720 for some more ideas on this.

See also:
Style organization strategies 720
Text Formatting and Styles 155 (how-to instructions)
9.4.4 The standard styles
If you look at the styles list in the styles editing dialog you will notice that some styles are
displayed in bold with the words (Standard Style) in brackets after the style name. These
styles are special styles that Help & Manual always expects to find because it uses them for
specific purposes. You can edit them but you cannot change their names and you cannot

© 1997 - 2009 by EC Software, all rights reserved

 718 Help & Manual 5 - User Help

delete them.

The standard styles and what they are for:

Normal: This is the basic parent style that almost all other styles, including header
styles, are normally based on. By default Normal is also used for the
standard starting paragraph in all new topics. (You can change this by
defining a new standard topic content template 423 .)
Having almost all other styles based on Normal makes it possible to make
changes to the appearance of your entire project by editing Normal. For
example, changing the font of Normal automatically changes the font of
all other styles in which you have not explicitly defined a different font
from the one set for Normal.
For more details on this see About inheritance in styles 714 and Style
organization strategies 720 .

Code This style is automatically applied to all program code formatted with the
Example: Syntax Highlighter 195 . Unlike most other styles it is not based on Normal,
because you don't want its appearance to change when you change the
formatting of the rest of your project.

Comment: This style defines the appearance of the comments 143 you can enter in
your project. This style is quite limited compared to most other styles.
See Image caption and comment styles 176 for details.

Heading1: This is the style used for the topic header displayed in the box above the
editing area. It's a good idea to use it as the parent for a family of heading
styles for use in the rest of your project.

Image This style is applied to the captions of graphics 239 inserted in your topics.
Caption: Like the Comment style it is quite limited: See Image caption and
comment styles 176 for details.

Notes: This style is reserved for functions that may be added to Help & Manual in
a future release.

See also:
Text Formatting and Styles 155 (how-to instructions)
9.4.5 Paragraph, text and table styles
There are three different kinds of styles: paragraph styles, text styles and table styles.
Paragraph and text styles are closely related, table styles are actually completely separate.
As their names suggest, paragraph styles are for formatting entire paragraphs, text styles
are for formatting text only. See Defining styles 161 and Formatting text with styles 167 and for
details on how to define and use paragraph and text styles.

About table styles

Table styles are used for tables only and do not have anything to do with the styles used for

© 1997 - 2009 by EC Software, all rights reserved

 Reference 719

formatting text and paragraphs. However, the rules of dynamic styles and dynamic
inheritance also apply for table styles. See Table styles 263 in the Working with Tables
chapter for details on using table styles.

The difference between paragraph and text styles:

Paragraph styles:
These are the most commonly-used styles. They include all style attributes (font and
paragraph, including borders and background colors) and they are used for controlling
the general layout of your entire project. A paragraph style is generally applied to one or
more paragraphs.
Note that border and background attributes are set separately but they are actually a
subset of the paragraph attributes.
Text styles:
These styles only include font attributes. They are used for applying standard formatting
to individual passages of text.

Display in the Ribbon:

In the style selector in the Ribbon paragraph styles are identified by a paragraph symbol,
text styles by an underlined a symbol.

Can you convert between the two style types?

Yes. The division between paragraph and text styles is actually made for convenience; in
reality all styles can always store all possible style attributes.
Converting a text style to a paragraph style:
You can always convert a text style to a paragraph style simply by adding paragraph
attributes to it. This is possible even if the style is based on another text style because
you are adding attributes, not taking them away, and this does not cause any
problems in the style's dynamic inheritance tree (see below).
Converting a paragraph style to a text style:
You can also convert a paragraph style to text styles, but this is a little more difficult. If the
paragraph style is based on another paragraph style you must change its parent setting
164 to (None) or to a text style. This is necessary because of dynamic inheritance: If a

style is based on a paragraph style it must inherit its parent's paragraph attributes, and
this makes it impossible for it to be a text style.

© 1997 - 2009 by EC Software, all rights reserved

 720 Help & Manual 5 - User Help

See About inheritance in styles 714 for more information on dynamic inheritance.

See also:
Text Formatting and Styles 155 (how-to instructions)
Defining styles 161
Editing styles 164
About inheritance in styles 714
9.4.6 Style organization strategies
This section describes some basic principles that will help you to use styles more efficiently.
Once you understand styles the way you use them is also a question of your personal
working preferences. For example, some people prefer to have a small, more manageable
set of styles and pay for this convenience with a little more manual formatting work. Others
prefer to have a large and almost complete set of styles that allows them to control virtually
all their formatting by editing styles.

Separating formatting and content:

One of the basic purposes of dynamic styles is to allow you to separate formatting and
content. Theoretically, if you do this completely all the formatting in your entire project
would be controlled by styles and you would be able to change the appearance of
everything just by modifying the styles. In the real world all projects will normally contain a
certain amount of manually-formatted text. For example bold and underlining to
emphasize individual words and passages, and individual manually-formatted paragraphs
and sections for which it would not be worthwhile to create one or more special styles.

The "many styles" and "few styles" strategies:

The number of styles you really need depends mainly on the amount of manual
formatting you are willing to do. There are two basic approaches to this, the "many styles"
strategy and the "few styles" strategy:
Many styles:
If you want to control all your formatting with styles you will need quite a large number of
styles for each project. Most of these styles will not be unique, they will be variants of
other styles. For example you will probably want to have several variants of the Normal
style used for standard paragraphs with indents and other modifications.
Few styles:
The "few styles" approach uses exactly the opposite strategy. Here you would use a
single style for each basic paragraph type, heading type and so on. With this strategy you
don't create any variants of these styles: If you want to use a variant, for example with an
indent, you must then apply the indent manually while you are writing and editing your
topics.
This approach results in a much smaller list of styles that is easier to manage. It works if
you are quite clear about what formatting you are going to apply manually. However, you
must really be absolutely sure that all the manual formatting you apply are things you are
not going to change. In the case of indents, for example, this is generally a relatively safe
assumption.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 721

You can still make global changes to your styles when you use this method, but any
manual formatting you have applied will not be changed when you change the style
definitions. (Manual formatting always has priority over style formatting.)

Style families
No matter whether you use many or few styles it is always advisable to organize your
styles in "families", both by name and by inheritance 714 .
Style name families:
This is simply logical and makes your styles easier to identify and find. It makes sense to
create families of headline styles called Heading1, Heading2, Heading3 and so on. Then
they all appear together in the list and you know what they are for. If you want you can
also include some key information in the names. You can organize your other style
groups like body text and so on in the same way.
Remember that you can rename your styles at any time!
Don't hesitate to rename your styles if you need to! Help & Manual automatically updates
all style references so you can rename them to improve your styles organization
whenever you want.
Style inheritance families:
Styles inherit properties from the styles they are based on. If you base groups of styles
on a common parent style you can make changes to the common properties of the entire
style group by editing the parent style.
For example, you could base all your headline styles on the standard style 717 Heading1, if
you want them to be similar to Heading1. If you don't want them to be similar to Heading1
you could create a new parent style for the headlines you want to use in your topics, and
base your other headline styles on that.
The same applies to other groups of styles for text or paragraphs with similar attributes.
See About inheritance in styles 714 for more background information on this.

Naming paragraph and text styles

It's advisable to apply a prefix to text styles that automatically distinguishes them from
paragraph styles and keeps them together in all the style selection lists, which are sorted
alphabetically for example P_ for paragraph styles and T_ for text styles.
Actually, you only need to use a prefix for one of the two because anything that doesn't
have the prefix is automatically identifiable as the other type.

One inheritance tree or multiple trees?

By default all the styles in Help & Manual except the standard Code Example style (see
The standard styles 717 ) are based on Normal, which is also the style used for standard
paragraphs in topics. This means that you have a single style inheritance tree. The
advantage of this is that it makes it possible to change attributes throughout your entire
project by editing Normal. You can change the standard font in all your styles simply by
changing the font of Normal, provided you haven't explicitly changed the base font in any
styles. The same applies for all other inherited attributes of Normal.

© 1997 - 2009 by EC Software, all rights reserved

 722 Help & Manual 5 - User Help

Creating new style inheritance trees:

When you create a new style that is not based on any other styles you effectively create a
new style inheritance tree. The question is, is this an advantage or a disadvantage?
The main advantage of a completely new tree is that it is guaranteed that you can't
accidentally change the attributes of styles in the tree by editing Normal or another
higher-level style. Many authors use one tree for body text styles and another tree for
header styles, for example.
The disadvantage is the same as the advantage: You have to edit the styles in the
second tree separately, which means maintaining your styles can be a little more work.
But it can be worth it if you find making this division makes it easier for you to manage
your project.
It's a question of personal preference:
Ultimately it's a question of personal preference whether you use the one-tree or the
multi-tree method. However, it's probably a bad idea to create too many trees, as that can
get really troublesome to manage.
If you do use multiple trees it's best to stick to one tree for each main group, for example
one tree for body text styles, one tree for header styles (particularly if you use different
fonts for headers and body text) and so on.

Using hotkeys
Last but not least, don't forget to assign hotkeys (keyboard shortcuts) to your frequently-
used styles! If you spend any amount of time working with Help & Manual (and if you're
writing help you will) this can radically speed up your work.

See also:
Text Formatting and Styles 155 (how-to instructions)
9.4.7 Tabs, indents and HTML
Tab stops and indents as used in word processors are unknown in HTML. You should thus
always avoid using tab stops in any topics intended for output to HTML-based formats, i.e.
HTML Help, Webhelp and Windows Exe and ePub eBooks.
Attempts to use spaces to create indented effects in HTML-based output will also not be
very successful. This is because all HTML browsers ignore multiple spaces: It doesn't matter
whether you enter a single space or 100 spaces, the browser will always render them as a
single space unless you enter hard (non-breaking) spaces with Alt+0160 on the numeric
keypad.
Help & Manual actually converts multiple spaces you enter in the editor to space/hard space
pairs in HTML output to get around this problem, but this still doesn't make spaces a good
tool for indents spaces render with different widths in different fonts and hard and soft
spaces can also have different widths.

Tabs and indents are not the same thing:

In the Tab Stops settings of the Paragraph formatting dialog you will see the following
warning:

© 1997 - 2009 by EC Software, all rights reserved

 Reference 723

This might make you think that you can't use indents at all for HTML-based output but
this is not the case. You can use indented paragraphs, you just shouldn't try to use tabs
or spaces to make indents. You should always use Help & Manual's paragraph indenting
172 functions.

How Help & Manual handles indents in HTML:

How Help & Manual handles indented paragraphs depends on how they are formatted.
Paragraphs with simple indents are formatted with margin settings.
Hanging indents are converted to tables, because this is the only way to make this
construction stable in HTML.

Special case – hanging indents with a tab stop:

Hanging indents are the only place you should use a tab stop. Here the tab is used to
separate the text in the left part of the indent (the hanging part) from the main body of the
paragraph, as shown in the example below. Paragraphs like this are converted to tables
in HTML, which is the only really stable structure for displaying paragraphs with hanging
indents in all browsers and the Microsoft HTML Help viewer.

This also works if the beginning of the first line is indented from the left margin. This will
also be converted to a table structure that will be stable in HTML-based output.

See also:
Using indents 172
9.4.8 About table and column widths
The dynamic behavior of tables in the Help & Manual editor and published output may be a
little unfamiliar and even frustrating at first if you come from a word processing background.
This is because they work much more like HTML tables than like tables in word processors

© 1997 - 2009 by EC Software, all rights reserved

724 Help & Manual 5 - User Help

like Word or Open Office Writer. However, if you have experience with HTML you will feel
right at home with Help & Manual's table sizing functions.

Table and column width values

Tables have two sets of width values that interact with one another: The width of the table
and the widths of the individual columns. These values can be defined or undefined.
Undefined width:
When the width value of a table or a column is undefined its width is determined by its
content then the cells and columns will expand just enough for the content to fit, and no
more. This also applies to the height of table cells.
Defined width:
When the width value of a table or column is defined it will be at least as wide as the
defined value. If the content is wider the defined value will be ignored and the table or
column will expand to fit the content.

Content expands table cells

Table cells are always at least as large as the content they contain. Your width and height
settings will always be ignored if your content is wider or higher. Table cells always
expand to accommodate all the text and graphics they contain. Additional wrapping text
will only make a cell higher but graphics and non-wrapping text can also make cells
wider, overriding the width settings.

Table width settings

Tables have three different "width modes":
Autosize:
This is the default setting. Initially, the width of the table and all columns is undefined. All
widths are dynamic and everything expands to fit the content the content defines the
width of both the columns and the table.
Fit on page:
Equivalent to a width of 100%. The table will always expand to fit the current margins of
the paragraph or the entire page. Any column width settings that prevent this will be
ignored. The table should have at least one dynamic column to allow it to expand to fit the
page, otherwise all columns will automatically switch to dynamic width.
Manual:
The table will always have the preset width in percent or absolute pixels. It should have at
least one dynamic column that can expand or contract to make the defined width
possible. If the defined table width is not possible with the preset column widths all
columns will automatically switch to dynamic width.

Column width settings

By default, columns are "dynamic" this means that they do not have a width setting,
they expand automatically to fit the content in their cells and the table width settings.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 725

"Lock Column":
The Lock Column tool in the Table tab locks the current width of the selected column as
a fixed value in pixels. This width will be maintained if possible. This tool also shows
whether the current column is locked or unlocked it is highlighted when the column is
locked.
Column width in the Table Properties dialog:
You can lock the column width to a pixel or percentage value with Table > Properties
> Selected Cells. This width will be maintained if possible.

Resizing column widths with the mouse:

Resizing column widths with the mouse always locks both columns affected by the resize
operation. Be aware of this when planning your tables! You will often need to unlock one
column after resizing with the mouse to allow your table to resize correctly.

Impossible column widths

If any column width setting is not possible all column widths in the table will be reset to
dynamic. This will happen if the column contains content (graphics, non-breaking text)
that is wider than the set width or if the set width is made impossible by the other table
settings.
For example, this will happen if:
· The table has a fixed width in pixels and the sum of the individual column widths is
greater than the width of the table.
· The sum of the column widths in percent is greater than 100%.
· Any table column contains content that is wider than the defined width of the column.

Height settings
Tables do not have height settings. Their height is always defined by the height of their
content.
Row/cell height is dynamic by default it expands automatically to fit the content. You
can set a minimum fixed height value in pixels in Table > Properties > Selected Cells
. If the content of the cell or row is smaller than this value white space will be added. If the
content is higher the setting is ignored.

See also:
Working with Tables 253
Table Properties 638

9.5 Publishing Formats

This section provides an overview of the features, characteristics, advantages and
disadvantages of the output formats currently supported by Help & Manual. There is no such
thing as the "best" format. Each format serves its purpose, and each can be a good choice
for some tasks and a less good choice for others.

© 1997 - 2009 by EC Software, all rights reserved

726 Help & Manual 5 - User Help

The supported formats:

HTML Help: 727 This is currently the most popular electronic help format for Windows
applications. It packs your entire help project into a single CHM file.
Fast, compact, excellent navigation and usability, universally
compatible and full interaction with applications. Displayed by the HTML
Help Viewer, that has been included with Windows since Windows 98.

Webhelp: 730 Displays in normal web browsers on all platforms (Windows, Linux, Mac
OS X, Unix). An emulation of the HTML Help interface, designed for
use on the Web and intranets. Complete with a dynamic Table of
Contents pane, keyword index and full-text search. Consists of a
directory containing a large number of HTML files, graphics files and
the files needed to display the Table of Contents etc.

Windows Exe This proprietary Help & Manual format packs your entire project into a
eBooks: 735 single executable file with an integrated viewer program that can be
displayed on any Windows computer, from Windows 95 and above
without any additional software. This format also provides an emulation
of the familiar HTML Help Viewer layout so that all users will be able to
use it intuitively without additional explanation.

ePub ebooks ePub eBooks are an open format that is rapidly becoming a universal
732 : standard. They are supported by a large number of software readers
for all operating systems and also by hardware readers, including the
Sony Reader, the BeBook Reader, the Apple iPhone and iPod Touch
and many mobile phones. Many thousands of ePub eBooks are already
available.

Adobe PDF: 737 Your project can also be output as a fully-formatted and full-featured
PDF file that can be displayed on any computer with a PDF reader.
Ideal for providing manuals that users can print themselves, either on
CDs or for download.

Printed The Print Manual feature (in the Application Menu) generates a
manuals: 738 temporary PDF file in the background and outputs it to your printer.
Also supports booklet format (multiple pages per sheet) and duplex
printing.

MS Word RTF: Old print-style format, support is provided for backward compatibility.
739 Outputs your project to an MS Word Rich Text Format RTF file. Many
dynamic help features are not supported, minimum options.

Visual Studio This special format is also known as MS Help 2.0. It is provided for
Help: 738 programmers who need to use MS Help 2.0 to document projects in
Visual Studio .NET. It is not documented extensively in the help
because Microsoft has not released it for general use under Windows.
This format is irrelevant for normal application documentation.
For details see Visual Studio Help 490 in the More Advanced Procedures
section and the documentation of the MS Visual Studio .NET package.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 727

(If you don't have this package you don't need and cannot use Visual
Studio Help.)

Winhelp: 740 The predecessor of HTML Help, now obsolete and should not be used
for new projects, although Help & Manual includes full support for
Winhelp for backward compatibility. Not supported in Windows Vista by
default. Consists of separate help (HLP) and contents (CNT) files. Not
particularly user-friendly, looks and is out of date. Not recommended
unless it cannot be avoided.

9.5.1 HTML Help

HTML Help is now fully established as the standard Windows help format and unless you
have a very good reason to use something else it is the best choice for online help
distributed with modern Windows applications. Users are familiar with it, navigation is
intuitive and it supports all the interactive and context-sensitive help technologies that make
good help effective. And since it is HTML-based you have considerable flexibility for both
formatting and introducing special features and functions.
HTML Help does have a couple of disadvantages: It is not ideal for web-based help or for
help on networks, but it is the top choice for help installed with applications on the user's
computer.

Restrictions on HTML Help on network drives:

Security restrictions in Windows now prevent access to HTML Help files network drives
and the Internet. File links 220 in HTML Help files will now generally not work at all across
networks, you can only link to files stored in the same folder as the HTML Help CHM file.
It is possible to enable display of HTML Help on network drives with some special
Windows Registry entries, for which EC Software provides a free tool.

Features and pros and cons of HTML Help:

File extension: .chm

Format: One CHM file contains the entire help.

Platforms: All Windows versions since Windows 98

Typical use: Local online help for applications installed on the user's computer

Table of Yes. Integrated in the CHM file and always visible in the viewer.
contents: Excellent, immediately intuitive navigation for the user.

Keyword index: Yes

Full text search: Yes

Context sensitive Yes, full context-sensitive help support. Can include text-only field-
help: level popups 372 which can be displayed directly within your
application without the main help window.

© 1997 - 2009 by EC Software, all rights reserved

 728 Help & Manual 5 - User Help

Popups: Yes, both in the help viewer and for context-sensitive help. Natively,
HTML Help only supports text-only popups without formatting or
graphics. Only these plain-text popups can be used for field-level
popups displayed in your application.
You can also use Help & Manual's JavaScript popups 129 in HTML
Help. In addition to formatted text and graphics JavaScript popups
also support hyperlinks and even videos and animations.
You cannot mix JavaScript popups and plain-text popups in a single
project but you can create a separate project containing only your
plain-text popups if you want to include JavaScript popups in your
main project.

Multimedia: Flash video and all Windows-compatible video formats are

supported. However, support for playing the formats used must also
be installed on the user's computer. For example, if you use a DiVX
video don't expect it to be playable on all user machines! Flash is
the only format that will always play reliably on all computers and it
has the added advantage that it is embedded in the HTML Help
CHM file, so you have no additional files to distribute.

Printable by The Print function of HTML Help is very limited. The help viewer can
user: print topics and chapters but each topic is printed on a separate
page.

Pros: Single file containing all topics, graphics and the table of contents.
More attractive, modern appearance than classic Winhelp. Intuitive,
directory tree style table of contents that is always visible to the
user. Flexible formatting with HTML (in Help & Manual you have full
control over your topic pages with HTML templates 430 ), including the
ability to add functions with JavaScript etc. by adding your own code
to topics 231 and templates 430 .The HTML base makes it easy to
produce a browser-based version for the web that looks almost
identical to the HTML Help version.

Cons: Popup topics are limited to plain text in native mode. Severe
restrictions on deployment in networks and the Internet, primarily
suitable for help installed locally on the user's computer together
with the application.

See also:
HTML Help 294 (Configuring Your Output)
HTML Help 667 (Configuration Options)
9.5.1.1 HTML Help project files

When you publish your project to HTML Help Help & Manual creates a temporary directory
called \~tmpchm in your project directory (this is the directory containing your .hmxp or .
hmxz project file). It then outputs all the files needed by the Microsoft HTML Help compiler to
this directory. These files include all the standard HTML Help project files that you would
create if you were producing HTML Help manually with HTML Help Workshop.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 729

Viewing the HTML Help source files:

Normally the \~tmpchm directory and all its contents are deleted after your project has
been published. If you want to view the files after publishing to check them just deselect
the Delete temporary files option in the Publish 590 dialog.

HTML Help project files:

projectname. This is the "control" file that brings together all the elements of the
hhp: project, telling the compiler what is going to be used and what goes
where.

projectname. This file contains the table of contents.

hhc:

projectname. This file contains the keyword index.

hhk:

projectname. This is the map file containing the help context number assignments.
hm:

projectname. This file contains the alias assignments, if applicable.

h:

projectname. This file is generated by the Microsoft HTML Help compiler. It contains
log: the log of the last compile session and any error messages or
warnings.

default.css: This file is generated by Help & Manual and contains the styles
information for your project. It may have a different name if you have
changed it in Configuration > Publishing Options > HTML Help
> HTML Export Options 697 (Note that these settings are shared with
all HTML-based output formats. They are also accessible in the
Webhelp and Visual Studio Help sections of the Configuration
section.)

CSHelp.txt: This file is generated by Help & Manual if you have activated plain-text
popups for HTML Help. It is a plain-text file containing the texts of your
popup topics. It may have a different name if you have changed it in
the the popup options 667 for HTML Help.

hm_popuptopi This file is generated by Help & Manual if you have activated
cs.js: JavaScript popups 129 in your project. It contains the code for your
JavaScript popups. It is added to the compiled CHM help file.

HTML files: These files with the extension .htm or .html contain your topics. They
are generated from your project by Help & Manual so that the
Microsoft compiler can use them to create the compiled CHM help file.

Graphics files: These files are generated from your project in the correct formats by
Help & Manual so that the compiler can use them to create the
compiled CHM help file.

© 1997 - 2009 by EC Software, all rights reserved

 730 Help & Manual 5 - User Help

9.5.2 Webhelp
Webhelp outputs your project to normal HTML pages that can be displayed with a standard
web browser, either locally or on the Internet. The Webhelp generated by Help & Manual is
designed to emulate the appearance and functionality of HTML Help, with a TOC tree pane,
a keyword index and full-text search (Pro version only).
The HTML code generated for Webhelp is CSS and DHTML based and is compatible with
all modern browsers on all platforms (Windows, Linux, Mac OS X, Unix). It is intelligent code
that automatically "downgrades gracefully" when it encounters old browses and browsers
with restrictive security functions. On these browsers some of the "eye candy" functions will
be turned off but the help will still be fully functional.
Webhelp is the best choice for help on the Internet and on local intranet systems, where
HTML Help is restricted by Windows security barriers.

Features and pros and cons of Webhelp:

File extensions: .htm and .html, graphics in JPG, PNG or GIF format. You can also
set the extensions of your topic files to anything else required by
your project in HTML Export Options 671 (e.g. .php etc.).

Format: A collection of HTML, graphics and other files in a directory, just like
a website (it is a website)

Platforms: All major computer platforms and browsers, including Mac and Linux

Browser The Webhelp output generated by Help & Manual is fully compatible
compatibility: with all major browsers. In addition to this the output will also work
transparently on older and security-restricted browsers. It achieves
this by automatically identifying browser capabilities and
"downgrading gracefully", providing less dynamic and formatting
features but still presenting a fully-functional help system.

Typical use: Online help and documentation on the web or on local intranets
where the use of HTML Help is not practical.

Table of Yes
contents:

Keyword index: Yes

Full text search: Yes (available in the Professional version of Help & Manual only)

Context-sensitive Context calls from applications 373 to topics and anchors in topics are
help: supported. Field-level context popups displayed within your
applications are not supported.

Popups: Yes, with JavaScript popups 129 that are compatible with all current
browsers and do not trigger popup blockers.

Multimedia: Flash video and other video formats are supported. Support for
playing the formats used must be installed on the user's computer.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 731

Also, the degree and quality of the support also depends on the
support provided by the browser the user is using. So please test
your output on all relevant browsers before distributing! If you really
want to be sure your video will work use Flash.

Printable by Limited to browser print functions, which can generally only print
user: individual topics.

Pros: Platform and cross-browser compatible, ideal for help on the web
and intranet systems. All the flexibility and formatting power of
HTML, including the ability to add functions with JavaScript etc. by
adding your own code to topics 231 and templates 430 .

Cons: Webhelp consists of many individual HTML files, graphics and other
files.

See also:
Webhelp 296 (Configuring Your Output)
Webhelp 674 (Configuration Options)
Browser compatibility 731
9.5.2.1 Browser compatibility

The top priority of the code design of Help & Manual's Webhelp output was that it should
always work, no matter what browser it is viewed with. A modern browser will allow the help
to display all of its advanced dynamic features, but an older browser or a browser with
JavaScript turned off won't break your help. This enables you to distribute Webhelp with
confidence because you know that the huge majority of your users will be able to view it
properly.

Different appearance in different browsers:

It is unavoidable that your Webhelp output will look slightly different depending on the
browser used to view it. HTML Help and Visual Studio Help / MS Help 2.0 are controlled
Microsoft formats that use MS Internet Explorer to render their HTML code, and your
output in these formats will always look almost exactly like your source in the Help &
Manual editor.
This is not possible in Webhelp. The HTML code generated is the best possible
compromise between compliance with the W3C specifications for HTML 4.01 and CSS1
and the quirks and weaknesses of individual browsers. Unfortunately, no browser is really
compliant with all the standards. In addition to this, individual browsers often interpret the
same rules differently.

Smooth backward compatibility:

The code generated is smoothly backward compatible with "graceful automatic
downgrading". This means that the full features require a newer browser with JavaScript
activated. However, viewing the code with an older browser or with JavaScript support
disabled will not "break" the display, it will just switch off the dynamic features. This
process is completely transparent to the user.

© 1997 - 2009 by EC Software, all rights reserved

 732 Help & Manual 5 - User Help

Requirements for all features:

The minimum requirement to display all supported features is a browser that supports
Cascading Style Sheets (CSS1) and JavaScript. This now applies to all major browsers,
for example Netscape 5 and above, MS Internet Explorer 4 and above, Opera 7 and
above and the current versions of Firefox, Mozilla and Safari. Most older browsers will still
display the help but with less functionality and less "pretty" formatting.
Whether or not all features are actually supported will also depend on user settings. For
example, if the user turns off JavaScript support the menu will be static instead of
dynamic, but it will still work. On browsers with support for frames turned off the TOC and
topics will not be displayed side by side, but they will still both be displayed.

JavaScript popups, full-text search and toggles:

The only features that have an absolute make or break requirement are full-text search 680
, JavaScript popups 129 and toggles 350 . These functions depend entirely on JavaScript and
will not work on browsers where JavaScript is unavailable or turned off. The content of
toggles will still be displayed, however, but they will always be expanded.

See also:
Webhelp 296 (Configuring Your Output)
Webhelp 674 (Configuration Options)
9.5.3 eBooks
Enter topic text here.
9.5.3.1 ePub eBooks

Key Information
ePub is simple to make it as universal as
possible. Avoid complex layouts and
formatting, only use simple tables and
don't use invisible topics. Only a..z, A..Z,
0..9 and _ are permitted in topic IDs in
ePub eBooks!

The ePub format (file extension .epub) is a standard for e-books created by the
International Digital Publishing Forum. It is quickly becoming widely established, with many
thousands of ePub eBooks already in circulation. It is already supported by the multi-
platform Adobe Digital Editions software reader, the Sony Reader hardware eBook reader,
the Apple iPhone and iPod Touch, mobile phones and many other devices and software
readers.
See ePub Resources 309 for more details, including sources for reader software and devices.

The ePub format

The eBook format is completely open and fully documented. An ePub eBook consists of
basic XHTML for the book content, XML for descriptions, and a zip archive file with the
extension .epub containing all the files.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 733

Features and pros and cons of ePub eBooks:

File extension: .epub

Format: A single zip archive file containing the XHTML and XML files and
other components.

Platforms: Viewable on any platform or device for which an ePub reader is

available. Includes Windows, Apple OS X, Linux, Unix, Sony
Reader, Apple iPhone and iPod Touch, BeBook Reader, mobile
phones and many more.

Typical use: Truly portable

Table of Yes, not supported by all readers

contents:

Keyword index: No

Full text search: Yes, but search functionality depends on reader

Context-sensitive No support for context-sensitive help, you cannot make direct calls
help: to specific topics in the help

Popups: No

Multimedia: No

Printable by Yes, but print functionality depends on reader

user:

Pros: Single-file, universal cross-platform format already supported by

many software and hardware readers. Large number of ePub
eBooks already published, likely to become a universal standard.
Generally intuitive handling (depends on reader).

Cons: This is really a dedicated format for books in electronic form. Not
appropriate for application help because of the lack of context
sensitive help support. No index, simple formatting only, no
multimedia or popup support. No password protection. Many readers
handle tables poorly.

See also:
ePub eBooks 304 (Configuring Your Output)
ePub eBooks 710 (Configuration Options)
9.5.3.2 ePub resources

This page contains a selection of hardware, software and information resources relating to
the ePub format and ePub eBooks. It is not necessarily complete, but it is a good starting-
point.

© 1997 - 2009 by EC Software, all rights reserved

734 Help & Manual 5 - User Help

Important: The reference software reader is Adobe Digital Editions. Before trying to
create ePub eBooks you should download this free reader from Adobe and install
it. If you don't do this you won't be able to view your ePub eBooks after creating
them with Help & Manual.

Hardware devices supporting ePub eBooks

The following hardware readers currently support ePub eBooks, either directly or with
free additional software. The most notably absent device on this list at the moment is the
Amazon Kindle, which still uses its own closed proprietary format – the Kindle can't even
display PDFs without conversion, although a free service is available for this.
The Sony Reader
The Sony Reader was one of the first major hardware eBook readers and it is now a
very mature device with wide support and distribution.
The BeBook Reader
The BeBook reader supports ePub eBooks natively, like the Sony Reader. In addition to
this it also supports a wide variety of other formats and mp3 audio files and audio books.
It is sold under a variety of different names depending on geographical location.
Apple iPhone and iPod Touch
Both these devices from Apple can display ePub eBooks with the free Stanza reader
software available from the Apple App Store that can be accessed in iTunes (see below).
Mobile phones, smartphones, other readers
Many other mobile devices also support ePub eBooks with the free MobiPocket software
(see below).

Software readers for ePub eBooks

Software readers for ePUB e-books are already available on many platforms. The
following list only includes the known software-based readers that support the ePUB
format at the time of writing – others may already be available.
The reference software reader is Adobe Digital Editions, this is the one you should get
for testing.
Adobe Digital Editions (Windows, Apple OS X)
This free program is the reference ePub reader with the best support for ePub and we
strongly recommend that you install it for testing your ePub books. It is currently still the
only reader that fully supports the ePub table of contents.
FB Reader (Windows, Linux, Apple OS X)
Open source reader software, does not yet support the ePub table of contents or
bookmarks.
Openberg (Firefox plugin)
Open source reader software, does yet not support the ePub table of contents or
bookmarks.
MobiPocket (Windows and many mobile devices)
Freeware, support for bookmarks, no support for table of contents yet. The great

© 1997 - 2009 by EC Software, all rights reserved

 Reference 735

advantage of MobiPocket is that it brings eBooks to a wealth of mobile devices, free of

charge.
dotReader (Windows, Linux)
Open source, cross-platform ePub reader, early beta. No support for table of contents.
Stanza (Windows, iPhone, iPod Touch)
Desktop (Windows) and iPhone version available. Supports both bookmarks and the
ePub table of contents. The iPhone/iPod Touch version is available directly from the
Apple App Store, which must be accessed through iTunes.
Bookworm (any OS with an Internet connection)
Online open source reader, supports the ePub table of contents. Good HTML and CSS
display but requires an active Internet connection.

Online resources for ePub eBooks

International Digital Publishing Forum

This is main home page for ePub and everything relating to the ePub format.

Open Packaging Format specification

Full specifications of the OPF ePub format.

TeleRead blog
An informative and entertaining blog about eBooks.

Jedisaber ePub tutorial

An online tutorial explaining how to make ePub eBooks manually. Useful if you want to
learn about the format and structure of ePubl eBooks.

Feedbooks
Free classics in ePub format.

Snee
Free children's picture books in ePUB format

LexCycle eBook Library

Large library of ePub eBooks maintained by LexCycle, the creators of the Stanza ePUB
reader for Windows and the Apple iPhone and iPod Touch.

9.5.3.3 Windows Exe eBooks

This is a proprietary Help & Manual format that combines a viewer and data in one .exe file
that will run on any Windows system (Windows 95 and above) without installation, additional
files or software. The format is HTML-based and the viewer also provides a navigation
structure similar to that of HTML Help and Help & Manual's Webhelp 730 format.

Key Information
Help & Manual Windows Exe eBooks are
designed to be self-contained and have a
built-in viewer. Use ePub, PDF or Word

© 1997 - 2009 by EC Software, all rights reserved

736 Help & Manual 5 - User Help

RTF if you want to generate eBooks that

can be read on electronic eBook readers.

Features and pros and cons of Windows Exe eBooks:

File extension: .exe

Format: A single executable file containing the viewer and all data

Platforms: All Windows versions (Windows 95 and later)

Typical use: Online CD ROM catalogs and documentation, stand-alone

documentation, kiosk applications, eBooks

Table of Yes
contents:

Keyword index: Yes

Full text search: Yes

Context-sensitive No support for context-sensitive help, you cannot make direct calls
help: to specific topics in the help

Popups: Yes, formatted popups containing formatted text (bold, italics, fonts
etc), graphics and hyperlinks to other topics are supported. No
support for context-sensitive field-level popups in your applications.

Multimedia: Flash videos are supported if support for playing Flash is installed
on the user's computer. Other video formats are not supported.

Printable by Limited printing function for single topics only

user:

Pros: Single file format. Look and feel similar to HTML Help (familiar and
intuitive navigation). Runs immediately without installation of any
additional files on all Windows versions. Password protection is
possible. A number of viewer templates are available for different
layouts and appearances.

Cons: Not appropriate for application help because of the lack of context
sensitive help support – you cannot open specific topics with calls
from your applications. No support for JavaScript or interactive
features, only basic HTML and CSS support. Cannot be displayed
on electronic eBook readers (use ePub 732 , PDF or RTF for these
devices, check the supported formats for your target devices first).

See also:
eBooks 304 (Configuring Your Output)
eBooks 706 (Configuration Options)

© 1997 - 2009 by EC Software, all rights reserved

 Reference 737

9.5.4 Adobe PDF

Adobe's Portable Document Format is now the de facto industry standard format for
electronic distribution of printable manuals. PDF provides a high level of formatting fidelity.
Layout and appearance are "fixed", and unlike HTML it is not dependent on the quirks of
browsers.
It is also a compact, single-file format that is now supported by all major computer platforms
as well as Windows. Navigation can be quite good but it is less flexible for on-screen viewing
and navigation than HTML Help. The domain of PDF is printable manuals with clearly-
defined layout and formatting that do not change on different systems. It is suitable for
downloading but not for online viewing on the Web as users must always download the
entire document, even if they only want to view a single page.

Features and pros and cons of Adobe PDF:

File extension: .pdf

PDF version: The PDF output conforms to version 1.2 of the PDF specification
and can be viewed with version 3 and above of Adobe Acrobat and
Adobe Reader.

Format: One .pdf file containing all text and graphics

Platforms: All major computer platforms and operating systems

Typical use: Print manuals distributed in electronic form, electronic books

Table of Yes, integrated in the PDF file. Hyperlinks are supported for on-
contents: screen viewing.

Keyword index: Yes but limited, just page number references at the end of the
document.

Full text search: Yes, in Adobe Reader

Context-sensitive No, zero support for context help

help:

Popups: No support for popups. Popup links are displayed as normal text.

Multimedia: No multimedia support.

Printable by Yes. The PDF format is ideal for printing.

user:

Pros: Printer orientated format supporting precise layout with specifically

defined page sizes, margins, headers, footers, etc. Highly
customizable with Help & Manual using print manual templates 425 .

Cons: Requires the Adobe Reader viewer but this is free and installed on
almost all computers. Not appropriate for application help because

© 1997 - 2009 by EC Software, all rights reserved

 738 Help & Manual 5 - User Help

of the lack of context-sensitive features. Not suitable for Internet

access because the entire document must be downloaded to view a
single page.

Other All the topics not included in your project's Table of Contents are
information: excluded from PDF output and printed manuals. This is by design
because PDF is treated as a print format. By definition, there is no
place in print-style documents for topics that are not included in the
TOC, which are only designed to be accessed with hyperlinks.
If you want to include information from topics not included in your
TOC you need to use Help & Manual's conditional output features 399
to make alternative content for the PDF version.

See also:
Adobe PDF 301 (Configuring Your Output)
Adobe PDF 690 (Configuration Options)
PDF and Printed Manuals 325
9.5.5 Printed manuals
When you output a manual to your printer with the Print Manual in the Application Menu
Help & Manual generates a temporary PDF file and deletes it after the printout has been
completed.
Just like Adobe PDF output, the layout of printed manuals is controlled with print manual
templates 330 . For details on printing manuals and using print manual templates see PDF and
Printed Manuals 325 .

See also:
Adobe PDF 301 (Configuring Your Output)
PDF and Printed Manuals 325
9.5.6 Visual Studio Help
Visual Studio Help is also known as MS Help 2.0. Originally this help format was intended to
be the successor of HTML Help. However, Microsoft then postponed its release indefinitely
and it is now clear that it is never going to be released as a help format for normal user
applications.
Please note that the support for Visual Studio Help/MS Help 2.0 is only included in the
Professional version of Help & Manual.

Visual Studio Help is not for consumer applications!

Visual Studio Help is only used for documenting components designed to be integrated
into the Visual Studio .NET programming environment. The advantage of this is that the
documentation becomes part of VS.NET's own documentation, making it possible to
provide context-sensitive help for third-party VS.NET components.
For all other online help applications you should always use HTML Help. For more
information see Visual Studio Help 490 in the More Advanced Procedures section.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 739

See also:
Visual Studio Help 490 (Advanced Procedures)
Visual Studio Help 694 (Configuration Options)
9.5.7 MS Word RTF
This format – equivalent to the Rich Text Format files generated by MS Word – is provided
for backward compatibility. Because of its limitations as a help and documentation format its
use is generally not recommended. PDF provides very superior output and much more
control over formatting. There may be some special cases where you still need to use it, but
generally PDF is always preferable.

Features and pros and cons of the Word RTF format:

File extension: .rtf

Format: One RTF file, graphics in external files if used

Platforms: Actually platform-independent but optimized for MS Word

Typical use: Print manuals distributed in electronic form, has now been generally
replaced by PDF

Table of Yes, but very limited (page number references without links at the
contents: beginning of the document)

Keyword index: Yes, but very limited (page number references without links at the
end of the document)

Full text search: Yes (with MS Word or other program supporting RTF files)

Context sensitive No
help:

Popups: No support for popups. Popup links are displayed as plain text.

Multimedia: No multimedia support.

Printable by Yes (with MS Word or other programs supporting RTF files)

user:

Pros: Can be viewed, searched and printed with MS Word and other
programs that support the RTF format.

Cons: Limited formatting options, many Help & Manual features not
supported, large files, graphics are in external files.

Other All the topics not included in your TOC are excluded from RTF
information: output. This is by design because RTF is treated as a print format.
By definition, there is no place in print-style documents for topics
that are not included in the TOC, which are only designed to be
accessed with hyperlinks.

© 1997 - 2009 by EC Software, all rights reserved

 740 Help & Manual 5 - User Help

If you want to include information from topics not included in your

TOC you need to use Help & Manual's conditional output features 399
to make alternative content for the RTF version.
Hyperlinks 705 are supported in MS Word RTF files.

See also:
MS Word RTF 304 (Configuring Your Output)
MS Word RTF 705 (Configuration Options)
9.5.8 Classic Winhelp
Winhelp is now obsolete and is not supported by default in Windows Vista. It was the
original help format introduced with Windows 3.1 in the 1980s. It was improved slightly in the
32-bit version released with Windows 95 but not much has changed since then. Like HTML
Help its primary purpose is to provide local help for applications installed on the user's
computer.
Navigation in Winhelp is counter-intuitive (you cannot view a topic and the table of contents
at the same time). Winhelp is RTF-based and formatting is not as flexible as HTML Help,
and it is difficult to produce a Winhelp help file that matches the appearance of modern
applications. Only use this format if you absolutely must for specific reasons.

Winhelp is not supported by default in Windows Vista:

Support for Winhelp is disabled by default in Microsoft Windows Vista. Even if your
applications run under Vista, any calls to Winhelp help will simply produce an error
message. Support for Winhelp can be added by downloading and installing the Vista
version of the Winhelp viewer from Microsoft but developers are not permitted to
distribute this update with their products. It is also possible that the operating system
support for Winhelp may be removed in the future. We thus strongly recommend that you
start transitioning to an alternative help format as soon as possible. See here for details

Features not supported by Winhelp:

Winhelp is a very old format and it has not been changed or upgraded for many years. It
lacks support for a lot of modern formatting features. The following Help & Manual editor
formatting features are not supported by Winhelp and should not be used if you plan to
generate Winhelp output:
Chapters with The Winhelp format does not support chapters with text. If your
text: project contains chapters with text they will be exported twice: Once
as a chapter without text and once as a sub-topic of the chapter
without text, with the same name as the chapter. This "duplicate"
topic will contain the content of your chapter with text.
If you are outputting to both Winhelp and formats that support
chapters with text you can use Help & Manual's conditional output
features 399 to create alternative topic and chapter versions for
Winhelp and the other formats.

Complex tables: Winhelp only includes extremely limited support for tables. You can

© 1997 - 2009 by EC Software, all rights reserved

 Reference 741

only use very simple tables to arrange items in the topic page.

Table borders: Table borders are not supported by Winhelp and will be invisible if
you define them.

Nested tables: Nested tables are not supported and will generate compiler errors
when you publish to Winhelp.

Backgrounds and Winhelp has no support at all for background colors or borders. This
borders: applies to text, paragraphs and tables.

Superscript/ Winhelp does not support superscript, subscript or any other non-
subscript: standard text decorations.

Features and pros and cons of classic Winhelp:

File extensions: .hlp (help file) and .cnt (table of contents)

Format: One HLP file for the help and a separate CNT file for the TOC

Platforms: All Windows versions except Windows Vista (support in Vista must
be installed manually by the user). The old 16-bit version of Winhelp
is not supported because it is very buggy on all current Windows
versions it was only designed to run on Windows 3.0.

Typical use: Local online help for applications installed on the user's local
computer

Table of Yes, in a separate CNT file

contents:

Keyword index: Yes

Full text search: Yes

Context-sensitive Yes, full support, including field-level popups

help:

Popups: Yes, fully-formatted popups with graphics, both in the help viewer
and for context-sensitive help. In Winhelp popups can also contain
hyperlinks.

Multimedia: Multimedia support in Winhelp is very limited. Only standard

Windows AVI videos are supported. Flash video and other video
formats are not supported.

Printable by Not really. The Winhelp viewer will only print single topics. Poor
user: graphics print quality.

Pros: Compact file format with strong compression, all graphics are
packed in the HLP file, just as in HTML Help. Supported by virtually

© 1997 - 2009 by EC Software, all rights reserved

 742 Help & Manual 5 - User Help

all Windows application development tools, easy to integrate with

applications.

Cons: Very unintuitive navigation. The navigation controls (Table of

Contents, keywords and full text search) are in a separate window
that cannot be displayed at the same time as the topic viewer. Less
flexible formatting than HTML Help. Only supports BMP graphics
(these are compressed, however). More difficult to produce help
matching modern applications in appearance. Users are now
generally more familiar with HTML Help. Only use Winhelp if you
absolutely must.

See also:
Winhelp 303 (Configuring Your Output)
Winhelp 700 (Configuration Options)
9.5.8.1 Winhelp project files

When you compile your project to Winhelp Help & Manual creates a temporary directory
called \~tmphlp in your project directory (this is the directory containing your .hmxz or .
hmxp project file). It then outputs all the files needed by the Microsoft Winhelp compiler to
this directory. These files include all the standard Winhelp project files that you would create
if you were producing Winhelp manually with MS Word and Microsoft Help Workshop.

Viewing your project files:

Normally the \~tmphlp file and all its contents are deleted after your project has been
compiled. If you want to view the files after compiling to check them just deselect the
Delete temporary files option in the Publish 590 dialog.

Winhelp project files:

projectname.hpj This is the Winhelp project file, which contains all the project's
settings. It describes the entire structure and of your project and all
the project settings. The topics and text are stored in the RTF file
(see below).

projectname. This is the map file containing the help context number
hm: assignments.

projectname.rtf This RTF file contains the topics and help text along with the topic
IDs and keywords.

projectname.cnt This file contains the table of contents (TOC) of the Winhelp project.
In Winhelp this is actually both a project file and a distribution file – it
must be distributed together with the compiled HLP file, otherwise
the Winhelp viewer cannot display the TOC. Because it is also a
distribution file Help & Manual generates it in your project directory
and not in the temporary \~tmphlp directory.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 743

projectname. This file is generated by the Winhelp compiler. It contains the log of
log: the last compile session and any error messages or warnings.

bitmap files (. If the help includes graphics you also need the BMP bitmap source
bmp) files (Winhelp can only use BMP), which may be stored in the
project directory or another directory.

9.5.9 Windows Vista Help

Originally known as Windows Longhorn Help, this is the second major help format that
Microsoft has promised to deliver and then withdrawn. Microsoft originally announced that
help authors would be able to use Vista Help soon after the release of Vista. However, the
release of the compiler and the development kit have now been postponed indefinitely and it
currently looks as though Vista Help is only going to be used internally by Microsoft for
documenting Windows Vista itself.
If Vista Help is ever released for use as a general help format support for the Vista Help
compiler will be added to Help & Manual at short notice.

9.6 Project Content

This section covers some subjects relating to the content of your projects, including Section
1194.21 accessibility information, background information on using snippets and multiple
TOC references, information on using graphics and videos in your projects and information
on scripts, inline HTML code objects and macros.

9.6.1 Accessibility
The purpose of the Voluntary Product Accessibility Template, or VPAT, is to assist Federal
contracting officials in making preliminary assessments regarding the availability of
commercial “Electronic and Information Technology” products and services with features
that support accessibility. It is assumed and recommended that offerers will provide
additional contact information to facilitate more detailed inquiries.

Date: March 6, 2007

Product Name: Help & Manual® 4 (Standard and Professional Edition)
Product Version Number: Version 4.3
Vendor: EC Software GmbH
Contact for more information: Alexander Halser, Managing Director, EC Software
GmbH
Summary Table for Help & Manual
Voluntary Product Accessibility Template
Criteria Supporting Features Remarks and explanations
Section 1194.21 Software Completed See Section Detail for
Applications and Operating 1194.21.

© 1997 - 2009 by EC Software, all rights reserved

744 Help & Manual 5 - User Help

Systems 744
Section 1194.22 Web-based Completed See Section Detail for
internet information and 1194.22.
applications 746
Section 1194.23 Not applicable Help & Manual is not a
Telecommunications Products Telecommunications Product.
Section 1194.24 Video and Not applicable Help & Manual is not a Video
Multi-media Products or Multi-media Product
Section 1194.25 Self- Not applicable Help & Manual is not a Self-
Contained,Closed Products Contained or Closed Product.
Section 1194.26 Desktop and Not applicable Help & Manual is not a
Portable Computers Desktop or Portable
Computer.
Section 1194.31 Functional Completed See Section Detail for
Performance Criteria 749 1194.31.
Section 1194.41 Information, Completed See Section Detail for
Documentation, and Support 1194.41.
750

Section 1194.21 Software Applications and Operating Systems - Detail

Voluntary Product Accessibility Template
Criteria Supporting Features Remarks and explanations
(a) When software is
designed to run on a system
All actions are executable
that has a keyboard, product
from the keyboard. Frequently
functions shall be executable
Criteria fully met. used functions have
from a keyboard where the
customizable keyboard
function itself or the result of
shortcuts.
performing a function can be
discerned textually.

(b) Applications shall not

disrupt or disable activated
features of other products that
are identified as accessibility
features, where those Help & Manual does not
features are developed and disrupt any accessibility
Criteria fully met.
documented according to features of the operating
industry standards. system.
Applications also shall not
disrupt or disable activated
features of any operating
system that are identified as

© 1997 - 2009 by EC Software, all rights reserved

 Reference 745

accessibility features where

the application programming
interface for those
accessibility features has
been documented by the
manufacturer of the operating
system and is available to the
product developer.
(c) A well-defined on-screen
indication of the current focus
shall be provided that moves
among interactive interface
elements as the input focus
Criteria fully met.
changes. The focus shall be
programmatically exposed so
that Assistive Technology can
track focus and focus
changes.
(d) Sufficient information
about a user interface
element including the identity,
Information about user
operation and state of the
interface elements including
element shall be available to
the identity, operation and
Assistive Technology. When Criteria fully met.
state of the element is
an image represents a
available to Assistive
program element, the
Technology.
information conveyed by the
image must also be available
in text.
(e) When bitmap images are
used to identify controls,
status indicators, or other
programmatic elements, the
Criteria fully met.
meaning assigned to those
images shall be consistent
throughout an application's
performance.
(f) Textual information shall be
provided through operating
system functions for
displaying text. The minimum
Criteria fully met.
information that shall be made
available is text content, text
input caret location, and text
attributes.

(g) Applications shall not

Criteria fully met.
override user selected

© 1997 - 2009 by EC Software, all rights reserved

746 Help & Manual 5 - User Help

contrast and color selections

and other individual display
attributes.
(h) When animation is Help & Manual does not use
displayed, the information animations, except for
shall be displayable in at least progress bars, where
Criteria fully met.
one non-animated additional textual information
presentation mode at the about the progress of an
option of the user. operation is available.
(i) Color coding shall not be The status of a help topic - a
used as the only means of user defined attribute - (e.g.
conveying information, "complete", "under
indicating an action, Criteria fully met. construction") is indicated by
prompting a response, or color highlighting and also
distinguishing a visual available as textual
element. information.
(j) When a product permits a
user to adjust color and
contrast settings, a variety of
Criteria fully met.
color selections capable of
producing a range of contrast
levels shall be provided.
(k) Software shall not use
flashing or blinking text,
Help & Manual does not use
objects, or other elements
Criteria fully met. flashing or blinking text,
having a flash or blink
objects or any other elements.
frequency greater than 2 Hz
and lower than 55 Hz.
(l) When electronic forms are
used, the form shall allow
people using Assistive
Technology to access the
Help & Manual does not use
information, field elements, Not applicable.
electronic forms.
and functionality required for
completion and submission of
the form, including all
directions and cues.

Section 1194.22 Web-based Internet information and applications - Detail

Voluntary Product Accessibility Template
Criteria Supporting Features Remarks and explanations
Notes to section 1194.22: this section applies to Help & Manual's HTML based output
formats, such as Webhelp and compiled HTML Help. Help & Manual offers user
customizable export options for these output formats, which may overwrite the default

© 1997 - 2009 by EC Software, all rights reserved

 Reference 747

values set by the program.

(a) A text equivalent for every
Help & Manual by default
non-text element shall be
creates a text equivalent for
provided (e.g., via "alt", Criteria fully met.
every non-text element. This
"longdesc", or in element
option is user customizable.
content).
It is the authors (users)
responsibility to implement
(b) Equivalent alternatives for
alternatives, if the author uses
any multimedia presentation
Not applicable. multimedia presentations in
shall be synchronized with the
help topics. Help & Manual
presentation.
has no direct influence on
user defined content.
(c) Web pages shall be
designed so that all
information conveyed with
Criteria fully met.
color is also available without
color, for example from
context or markup.
(d) Documents shall be Help & Manual creates HTML
organized so they are pages that are readable
Criteria fully met.
readable without requiring an without an associated style
associated style sheet. sheet.
(e) Redundant text links shall
Help & Manual does not
be provided for each active
Not applicable. create server-side image
region of a server-side image
maps.
map.
Help & Manual creates client-
(f) Client-side image maps
side image maps with
shall be provided instead of
geometric shapes when using
server-side image maps
Criteria fully met. links in image. A non-text
except where the regions
element ("alt", "title" tag) is
cannot be defined with an
provided automatically. This
available geometric shape.
option is user customizable.
Help & Manual cannot distinct
between tables with
(g) Row and column headers
informational content and
shall be identified for data Criteria not met.
tables used for layout. It has
tables.
no direct influence on user
defined content.

(h) Markup shall be used to

associate data cells and
header cells for data tables Criteria not met.
that have two or more logical
levels of row or column

© 1997 - 2009 by EC Software, all rights reserved

748 Help & Manual 5 - User Help

headers.
Frames, when used, are
(i) Frames shall be titled with automatically titled with
text that facilitates frame Criteria fully met. descriptive names such as
identification and navigation "navigation frame" and
"content frame".
(j) Pages shall be designed to
avoid causing the screen to
flicker with a frequency Criteria fully met.
greater than 2 Hz and lower
than 55 Hz.
(k) A text-only page, with
equivalent information or
functionality, shall be provided
to make a web site comply
with the provisions of this part,
when compliance cannot be Not applicable.
accomplished in any other
way. The content of the text-
only page shall be updated
whenever the primary page
changes.
Help & Manual does not use
(l) When pages utilize scripting languages to display
scripting languages to display content or create interface
content, or to create interface elements. It is, however,
elements, the information possible for the author to
Criteria fully met.
provided by the script shall be customize the output with
identified with functional text user defined scripts. Help &
that can be read by Assistive Manual has no direct
Technology. influence on user defined
content.
Help & Manual does not
require applets or plug-ins to
(m) When a web page be present on the client
requires that an applet, plug- system. It is, however,
in or other application be possible for the author to
present on the client system customize the output and
Criteria fully met.
to interpret page content, the extend content with user
page must provide a link to a defined HTML code that may
plug-in or applet that complies require applets. Help &
with §1194.21(a) through (l). Manual has no direct
influence on user defined
content.

(n) When electronic forms are Help & Manual does not
Not applicable.
designed to be completed on- create electronic forms.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 749

line, the form shall allow

people using Assistive
Technology to access the
information, field elements,
and functionality required for
completion and submission of
the form, including all
directions and cues.
(o) A method shall be
provided that permits users to
Criteria fully met.
skip repetitive navigation
links.
(p) When a timed response is
required, the user shall be
alerted and given sufficient Criteria fully met.
time to indicate more time is
required.

Section 1194.31 Functional Performance Criteria - Detail

Voluntary Product Accessibility Template
Criteria Supporting Features Remarks and explanations
(a) At least one mode of
operation and information
retrieval that does not require
user vision shall be provided,
Criteria fully met.
or support for Assistive
Technology used by people
who are blind or visually
impaired shall be provided.
(b) At least one mode of
operation and information
retrieval that does not require
visual acuity greater than
20/70 shall be provided in
audio and enlarged print Criteria fully met.
output working together or
independently, or support for
Assistive Technology used by
people who are visually
impaired shall be provided.

(c) At least one mode of Help & Manual does not

operation and information provide information in audio
Criteria fully met.
retrieval that does not require form. No information retrieval
user hearing shall be requires hearing.

© 1997 - 2009 by EC Software, all rights reserved

750 Help & Manual 5 - User Help

provided, or support for

Assistive Technology used by
people who are deaf or hard
of hearing shall be provided
(d) Where audio information is
important for the use of a
product, at least one mode of
operation and information Audio information is not
retrieval shall be provided in Criteria fully met. required for operation of Help
an enhanced auditory fashion, & Manual.
or support for assistive
hearing devices shall be
provided.
(e) At least one mode of
operation and information
retrieval that does not require
user speech shall be Speech is not required for
Criteria fully met.
provided, or support for operation of Help & Manual.
Assistive Technology used by
people with disabilities shall
be provided.
(f) At least one mode of
operation and information
retrieval that does not require
No fine motor control or
fine motor control or
Criteria fully met. simultaneous actions are
simultaneous actions and that
required.
is operable with limited reach
and strength shall be
provided.

Section 1194.41 Information, Documentation, and Support - Detail

Voluntary Product Accessibility Template
Criteria Supporting Features Remarks and explanations
EC Software provides
(a) Product support
electronic versions the
documentation provided to
product documentation, with
end-users shall be made
Criteria fully met. mechanisms available for the
available in alternate formats
conversion of these
upon request, at no additional
documents to alternate
charge.
formats.

(b) End-users shall have EC Software provides

access to a description of the electronic versions the
Criteria fully met.
accessibility and compatibility product documentation, with
features of products in mechanisms available for the

© 1997 - 2009 by EC Software, all rights reserved

 Reference 751

alternate formats or alternate conversion of these

methods upon request, at no documents to alternate
additional charge. formats.
(c) Support services for Support for EC Software
products shall accommodate products is available in
Criteria partially met .
the communication needs of electronic form only (email,
end-users with disabilities. user forum).

9.6.2 Snippets and multiple references

Help & Manual gives you two different ways to "reuse" topics in your project: The Snippets
Tool 149 , which which inserts a copy of the contents of one topic in another topic, and
multiple references 208 to a single topic in the Table of Contents (TOC). Both these methods
have their advantages and disadvantages.

About multiple TOC references to a single topic:

Creating multiple TOC references to a single topic is a little like having several doors to
the same room. You may be able to enter through different doors, but the room is always
the same. A topic with multiple TOC references is still just one topic, but the user can
display it by clicking on different entries in the TOC.
For the user it looks as though there is a separate copy of the topic in several different
locations. Actually, however, there isn't. There is still just one topic, and this means that it
is 100% identical in every location. It cannot have even the smallest difference because it
is the same topic. The only difference that is possible is that you can have different
captions (titles) for the TOC entries for each instance the doors are different but the
room is the same.
See Multiple TOC entries for one topic 208 for instructions on using this feature.
Advantages:
· The "multiple topics" do not increase the size of your output files because there is really
only one topic.
Disadvantages:
· All the "instances" have the same topic ID so it is only possible to create hyperlinks to
the original instance.
· For the same reason all keywords associated with the topic will always link to the
original instance of the topic.
· All the instances are 100% identical because they are the same topic. You cannot have
different text before or after the "copies" in the individual locations.

About the Snippets Tool:

The Snippets Tool 149 allows you to insert the contents of one topic in another topic. This
can be done either in Copy mode or in Link mode.
Using Copy mode is like copying and pasting text the contents of the other topic are

© 1997 - 2009 by EC Software, all rights reserved

752 Help & Manual 5 - User Help

pasted into the current topic and can be edited. Only the text is copied and once the copy
has been made the text is part of the current topic. If the topic you inserted from is edited
nothing changes in the current topic.
This mode is used for text blocks that you want to edit after inserting them, for example
tables that need to be filled out.
When you use Link mode you create a link to the other topic you can't edit the text
inside the current topic but when the original topic is changed the changes are reflected
in the linked copy as well. When you publish your project a static copy is made of the
linked topic, but until then the link is dynamic and all changes in the linked topic are
updated.
Linked snippets can be used in multiple places and all the "copies" will be updated
simultaneously when the linked topic is edited. This mode is used for text that you want to
use in many places in exactly the same way.
The current contents of the source topic are displayed in the editor at the insertion point
with a shaded background.
In addition to this the source topic also exports any index keywords 274 it contains to the
target topic. This means that any keywords associated with the source topic also only
need to be entered once; they are automatically exported to all target topics and
combined with any keywords the target topic already contains. This only works with index
keywords, however. A-keywords 281 , topic IDs 205 and help context numbers 205 are not
exported, because this would cause logical problems.
Advantages:
This method has several important advantages over multiple TOC references 208 :
· You can include different text before and after the embedded topic. This makes
embedded topics ideal for documentation where you need to repeat the same
instructions in different contexts.
· In the compiled output all the topics containing embedded topics are real, unique topics
containing copies of the source information. Each topic has its own unique topic ID that
can be linked to directly.
· All normal index keywords are embedded together with the topic – you only need to
enter the keywords for the embedded text once. (A-keywords are not embedded
because this would cause logical contradictions.)
Disadvantages:
· The only real disadvantage of embedded topics is that they make your project larger,
but not really all that much larger. Text does not take up much room and multiple
instances of graphics don't inflate your file size because there is never more than one
copy of identical graphics in your output file.
See Re-using content with snippets 149 for instructions on using this feature.

See also:
Multiple TOC entries for one topic 208
Re-using content with snippets 149

© 1997 - 2009 by EC Software, all rights reserved

 Reference 753

9.6.3 Graphics, Videos and OLE Objects

This section contains some useful background information on using graphics, multimedia
files and OLE objects in your help projects.

9.6.3.1 Graphic formats and file size

The main factor that increases the size of your help files is the use of big graphics with too
many colors. Compared to images text hardly takes up any space at all.
In most cases it is most practical to use standard uncompressed BMP bitmap files for your
graphics in your projects. This may seem odd at first because BMP files are generally larger
than all other graphic formats. However, they can be converted most easily and since they
are completely uncompressed they suffer no quality degradation. Help & Manual converts
the files to the appropriate format and compress them automatically when you publish your
output.

How to keep your graphics and help files small:

Here are some basic rules of thumb for minimizing the size of your graphics and output
files:
Always use images with 256 colors or less for screenshots.
This will generally reduce your output file size more than anything else. You will never
need more than 256 colors for screenshots unless your program contains graphical
components with complex color gradients.
Don't use JPEGs for screenshots.
Help & Manual allows you to insert compressed JPG, PNG and GIF images directly into
your projects for HTML and HTML Help output. However, JPG images are always
TrueColor, so it's not possible to reduce the number of colors to 256 or less. Also, the
compression used in JPEG images often makes screenshots look bad because it creates
ugly "artefacts" at the sharp transitions between screen elements.
It's better to use uncompressed BMP images with 256 colors or less and allow Help &
Manual's Image Conversion function to handle the compression at publish time. If you
want to do the compression yourself use GIF or PNG for 256-color images, the quality will
be much better than with JPG.
The Image Conversion settings are in the HTML Export Options 671 , which can be
accessed in both the HTML Help and the Webhelp sections of Configuration >
Publishing Options in the Project Explorer.

Don't use PNG for images with more than 256 colors
The PNG format is an excellent choice for images with up to 256 colors. It is even more
compact than GIF and has excellent quality. However, PNG files with more than 256
colors are actually a different format. These files are radically larger than the equivalent
JPG files – sometimes they are only a little smaller than BMP files.
This also means that you should make sure that your image conversion settings 671 will
not convert images with more than 256 colors to PNG. If your project contains images
with more than 256 colors it is better to choose JPG as the conversion format.

© 1997 - 2009 by EC Software, all rights reserved

754 Help & Manual 5 - User Help

Avoid conversion of photos reduced to 256 colors:

Modern graphics programs can do an excellent job of reducing photos to 256 colors with
little or no reduction in visible quality, which also saves space. However, doing this can
cause a problem in Help & Manual if you save the images as BMP:
If your image conversion settings 671 are set to convert images with 256 colors or less to
GIF your photos will also be converted to GIF if they are stored in GIF files. This can
make them look bad, with nasty posterizing effects, and it can also increase the size of
your files because continuous-tone images compress poorly in the GIF format.
If you get bad results with 256-color photos saved as BMP try saving them in the PNG
format with your graphics program and then insert them directly into your Help & Manual
project. This will ensure that they will not be converted in HTML-based output formats.
Keep the dimensions of your graphics small.
Smaller graphics take up much less space. Do you really need to include a full-size
screenshot of the main program window? If the user is reading your help the program you
are describing is already on the screen, and full-size screenshots also make the help
difficult to navigate. A 75% or even 50% size version is normally plenty as a visual
reference.
You can shrink the screenshot and add attractive callouts and other features with Impict
536 , the full-featured screenshot editing program bundled with Help & Manual. You can

also make screenshots at reduced sizes directly with Help & Manual's integrated screen
capture utility 532 or with the stand-alone TNT screen capture program.
Reduce the use of photographs.
Lots of full-color photos will also bloat your output files. If you do use them keep them
small and if you are producing HTML Help or Webhelp make sure that your image
conversion settings 671 are set to Convert 256 colors to GIF and True Color to JPEG.
While you are at it, experiment with the JPG compression setting in the same place; your
pictures may be smaller and look just as good with a lower quality setting. A value
between 70 and 80 is generally fine for most purposes and you can often get away with
even higher compression settings.
Don't show the entire image if you don't have to.
Areas of an image that are a single color take up almost no space when the image is
compressed and parts of an image that are not there take up no space. Quite often you
can save space by cropping your images to remove unnecessary information, and this
also focuses user attention on what is important.
You can also crop your screenshots with special effects like Ripped Paper Edge in the
Screen Capture 532 tool and the Impict 536 screenshot editing program. This both saves
space and makes your screenshots look better!

Tips and tricks for graphics formats:

Adding JPGs, PNGs and GIFs to your projects directly:
Help & Manual inserts JPG, PNG and GIF images directly, without converting or re-
compressing them. They are simply inserted in your compiled output as they are. This
means that you must handle the compression yourself with a graphics program before
using the images in your projects.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 755

JPGs, PNGs and GIFs in Winhelp projects:

The Winhelp compiler is a very old program that only understands BMP images (they are
compressed by the compiler). Help & Manual automatically converts these formats to
BMP when you compile to Winhelp.
Note that you don't get any compression advantage by using these formats in Winhelp
because they are converted to uncompressed BMP files before being re-compressed by
the compiler! On the contrary you will probably get a reduction in quality because of the
compression-decompression-recompression cycle!
Windows metafiles:
You also can add vector-format Windows metafiles (WMF and EMF files) to your projects
directly. When you publish your projects these files are converted to BMP and then the
normal conversion and compression options set in your Image Conversion settings are
applied.

See also:
Using Graphics 238
Image conversion settings 671
9.6.3.2 Embedded graphics

Normally when you insert graphics in Help & Manual you only insert references to external
graphics files. This is also the recommended way for handling graphics because it is much
more efficient and prevents your project file from getting too large.
There are two kinds of images that actually get embedded in your project files as
encapsulated binary data: Embedded OLE objects 494 and images pasted together with text
from word processing programs like Microsoft Word.

Avoid using embedded images whenever you can.

For technical reasons embedded images use up many times their own size in memory
and also place quite a heavy load on system resources. If you use a lot of them they will
also significantly increase the size of your project files, which may slow down the
functioning of the Help & Manual editor on older computers with limited memory.
Embedded OLE objects:
See Embedded OLE objects 757 and Inserting OLE objects 494 for information on how to
use OLE objects in your projects without embedding them. Embedded OLE objects are
also embedded in your topic files, which bloats the files unnecessarily.
Pasting graphics from MS Word:
When you paste graphics together with text from MS Word the images are initially
embedded. After doing this you should always immediately go through the pasted text
and check the images. Right click-on each image and if you see the Convert Embedded
Image menu option then convert the image to a disk file.
If you have already embedded graphics in your project you can also convert them to
external files by right-clicking on the graphic and selecting Convert Embedded Image in
the popup menu. This is always advisable.

© 1997 - 2009 by EC Software, all rights reserved

 756 Help & Manual 5 - User Help

Identifying embedded images:

When you click on an embedded image it does not appear as a "negative" image.
Normally-inserted images appear as negatives with all their colors reversed when you
click on them.

See also:
Using Graphics 238
9.6.3.3 About using video files

Video files used in Help & Manual and the output formats it generates are always handled by
the associated players and codecs, not by Help & Manual itself. These players and the
necessary codecs for the specific formats must be properly installed, both on your computer
for editing and on the user's computer for viewing. Because of this a number of restrictions
apply that you should be aware of before using video files in your projects.

Use Flash video

If you want to make life easy for yourself, use Flash video. This is the only format that
always works on all platforms and it has the added advantage that Flash video files are
embedded in HTML Help CHM files and Windows Exe eBooks, so that you don't have to
distribute additional files. All other video formats will generally fail to play on at least some
users' computers.
Note: ePub eBooks do not support any video, audio or multimedia formats.

Support for media files in output formats:

Classic Winhelp support for media files is extremely limited. Winhelp only
Winhelp supports Microsoft Media Player objects, which are restricted to AVI
(HLP) files without sound. Flash videos are not supported.

HTML Help Supports all video formats supported by Windows. Whether the formats
(CHM) are playable on the user's computer depends on installation of the
associated players and codecs on the user's computer (see below 757 ).

Webhelp ( Supports all media formats supported by the user's browser. Whether
HTML): the formats are playable on the user's computer depends on installation
of the associated codecs and players (see below 757 ).

Windows Exe Flash animations are supported and are embedded in the eBook .exe
eBooks (EXE): file. Other video formats are not supported.

ePub eBooks: No support for media files

Adobe PDF: No support for media files

MS Word RTF: No support for media files

See Conditions and Customized Output 399 for details on creating alternative content for
different output formats.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 757

Embedding video files:

Flash videos are embedded in HTML Help (CHM) files and Windows Exe eBooks. All
other video files must be distributed with your help as separate files, including Flash
animation files when used in Webhelp (HTML). When you compile your project a list of
the files you need to distribute with your help is always displayed in the compiler window,
so always remember to check this!

Important warnings and restrictions for video files:

Players and codecs are required on the target system
Videos and other video files always use the associated players to play, even in compiled
help files. This means that they will only play in your help file on the user's computer if the
user has the correct player and/or video codecs installed.
If you want to be absolutely certain that your video files will play on the maximum number
of users' computers it is best to use Flash video. This is now the de facto standard and
will work on all systems.
Functionality in Help & Manual also depends on the players
How and whether the preview function works in Help & Manual also depends on the
player installation on your computer. If the necessary players or codecs are not available
or not installed properly the preview function will not work.
You may need administrator rights to run the preview function
On some systems you need to be working in a Windows account with full administrator
rights to use the movie preview function. If the function doesn't work and you know that
the correct player is installed try switching to a full administrator account.

See also:
Adding video files 269
9.6.3.4 About using OLE objects

OLE support has some restrictions because of the impossibility of supporting OLE in the
compiled output formats generated by Help & Manual. OLE objects in the editor remain
clickable and editable so that you can edit them in their associated applications. However,
when you publish your project the objects are converted into static graphics.
It is best to think of OLE objects as static graphics that remain editable until you compile
your output.

Linking is always preferable to embedding:

You can either embed OLE objects in your project or insert them as a link to an external
file. The Create New option in the Insert OLE Object 635 dialog always embeds the object
in your project. The Create from File option embeds the object if you deselect the Link
option.
Embedding OLE objects in your projects has several disadvantages:
· It increases the size of your project files.
· Handling embedded objects generates considerable system overheads. This can slow

© 1997 - 2009 by EC Software, all rights reserved

 758 Help & Manual 5 - User Help

down Help & Manual, particularly on older computers and systems with less memory.
· Embedded objects can only be edited by opening Help & Manual and double-clicking
on the object in the editor. Linked objects can be edited normally as external files
It is thus always preferable to use links to external files instead of embedded OLE
objects.

Restrictions on OLE objects in Help & Manual

Because of the restrictions listed below it is advisable to only use OLE objects when there
is no alternative. For example, you can copy text with tables and complex formatting 139
directly from MS Word and Excel, so you no longer need to use OLE objects for this. You
can also use linked snippets 149 for reusing content once you have converted it to a Help &
Manual XML file.
You can only use OLE You cannot use dynamic objects like videos and other media
objects that can be files. The OLE selection dialog is a Windows element that
displayed as graphics. automatically displays all the OLE-capable applications
installed on your system. This does not mean that you can use
all the object types listed!

Only the visible part of For example, if you insert a Word document consisting of
large OLE objects is several pages only the page (or part of the page) that is visible
included in the output. in the Help & Manual editor will be included in your compiled
output. This is a restriction imposed by conversion of the
objects into static graphic images.

Print quality and the This is caused by the conversion to static graphics designed
quality of OLE objects for on-screen viewing and cannot be prevented.
in PDFs may be
slightly inferior.

See also:
Using OLE Objects 494
Insert OLE Object 635
9.6.4 Scripts, HTML and Macros
In addition to creating word-processor style content help authors sometimes want or need to
"get under the hood" of their help output and add their own code in the form of JavaScript,
HTML code or Winhelp macros. Help & Manual has extensive facilities that allow you to do
this:
· You can create links in your text that execute Winhelp macros or JavaScript code 223 in
the appropriate output formats. These links can be inserted both in the text 223 of your
topics and in hotspots 246 in your graphics.
· You can enter inline HTML code 231 in your topics that will be inserted in your output
exactly as you wrote it, without any changes. (HTML-based output formats only, of
course.) This code can include anything supported by HTML, including scripts.
· You can manually edit the HTML templates 430 that are used to generate the topic pages
in HTML-based output formats.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 759

You need to be familiar with HTML, scripting and Winhelp macros to use these features. It is
assumed that you know what you are doing and the code you enter is entirely your
responsibility. It is not corrected, parsed or syntax-checked by Help & Manual. The only
exceptions are some graphic file references in your HTML topic page templates, which are
parsed and exported 811 with your output.
The topics in this section provide some extra background information that will help you to
use these features more effectively.

9.6.4.1 About JavaScript links

You can enter links that execute JavaScript code both in the text 223 of your topics and in in
hotspots 246 in your graphics. Since JavaScript is an HTML-based technology requiring a
browser this feature is only supported in HTML-based output formats (HTML Help, Webhelp
and Visual Studio Help/MS Help 2.0). Note that although Windoows Exe and ePub eBooks
are also HTML-based, JavaScript is not supported in eBooks: The embedded viewer in Exe
eBooks does not support JavaScript at all. Even though scripting is included in the ePub
specification the majority of readers for ePub eBooks have little or no support for it.
You can also include JavaScript and other script code in plain HTML code inserted in your
topics using the Insert > HTML Code 231 feature. This option is normally preferable to script
links for more complex code. See About inline HTML code 762 for some more information on
this.

JavaScript restrictions in users' browsers:

In HTML Help you can generally assume that MSIE-compatible JavaScript will work
because the HTML Help viewer is actually Microsoft Internet Explorer with a different user
interface. However, when you use JavaScript in Webhelp you must always remember
that users' browsers may restrict or completely prevent the execution of JavaScript code.

JavaScript links that refer to script functions:

You can also refer to JavaScript functions stored in your own external JavaScript code (i.
e. code that you have written) in JavaScript links. There are several different ways to
make these functions available to the JavaScript links:
· Add your separate .js script file to the Baggage Files 485 to include it in your output.
Then edit the HTML page template 433 for your topics and add an include for the .js
script file in the appropriate location in the template file.
· Use HTML variables 395 – you can then insert your script in the correct position in your
template with the variable and redefine it on a per-topic basis in the tab, allowing you to
use different versions of your code in every topic if you want.
· Edit the HTML template for your topics and manually add the script with the functions to
the <head> section of the template. Note that this will include the script code in every
topic page, even those pages where the functions are not needed. (See About inline
HTML code 763 for details on how to avoid this problem.)
· Insert the script code containing the functions at the beginning of the topic containing
the link with the Insert > HTML Code 231 function. If you use this method the code will
only be available in the topic where you insert it. Note also that this will insert the code
between the <BODY> tags of the topic page – this will work in most cases but since

© 1997 - 2009 by EC Software, all rights reserved

760 Help & Manual 5 - User Help

referenced scripts should generally be in the <HEAD> section you may want to use one
of the other methods.

How Help & Manual handles JavaScript code in links:

To use this feature effectively it is important to understand how Help & Manual handles
the JavaScript code you enter in your links. When you select the JavaScript option in the
Insert Hyperlink 617 dialog the script you enter in the dialog box is only part of the final
code generated in your output:

This dialog is effectively identical for script links

in your text and script links in hotspots in
In the HTML output the code is put together as follows:
<a href=" + your code + "> + link caption + </a>
For example, if you enter javascript:alert('Hello World!'); in the Script: entry
box and Hello World! in the Caption: field Help & Manual will generate the following
link:
<a href="javascript:alert('Hello World!');">Hello World!</a>
That is just a simple example. Here is a more complex piece of JavaScript as entered in
the Script: entry box (this example opens a popup window):
javascript:window.open('http://www.ec-software.com/helphtml/index.html?
whatsnew.htm','PopupWindow','toolbar=0,location=0,directories=0,status=0,
menubar=0,resizable=yes,scrollbars=1,width=600,height=600,left=0,top=0');
The output generated from this script would look like this:
<a href="javascript:window.open('http://www.ec-software.com/helphtml/
index.html?whatsnew.htm','PopupWindow','toolbar=0,location=0,
directories=0,status=0,menubar=0,resizable=yes,scrollbars=1,width=600,
height=600,left=0,top=0');">Your Link Caption</a>

Entering complex JavaScript Code:

Effectively, Help & Manual enters your JavaScript code between the " and " characters for
the href= attribute of the <a> tag. However, this is not nearly as restrictive as it sounds at
first. When you understand how Help & Manual actually generates the output code you

© 1997 - 2009 by EC Software, all rights reserved

 Reference 761

can also enter quite complex scripts. You just have to remember the syntax and work
within it:
<a href=" + your code + "> + link caption + </a>
For example, you can also create a complex link tags like this, using multiple quotes
within the tag:
<a href="javascript:void(0);"
onmouseover="return overlib('Popup text.', STICKY, MOUSEOFF);"
onmouseout="return nd();">Display Overlib Popup</a>
All you need to do to achieve this is copy the entire link shown above into the Script:
field, leaving out the <a href=" at the beginning and the ">Display Overlib Popup</
a> at the end. For the above example you would first enter Display Overlib Popup in
the Caption: field and the following code in the Script: field:
javascript:void(0);"
onmouseover="return overlib('Popup text.', STICKY, MOUSEOFF);"
onmouseout="return nd();

JavaScript stumbling blocks:

Remember that JavaScript is very picky about syntax and case! For example, if you
enter javascript:Alert instead of javascript:alert you will just get an error
message.
You must also remember to be very careful about nesting single and double quotes. Help
& Manual generates script links with double quotes on the outside so any quotes nested
within those quotes must be single quotes.

See also:
Inserting script and macro links 223
Inserting plain HTML code 231
About inline HTML code 762
Using HTML Templates 430
9.6.4.2 About Winhelp macro links

The Winhelp macro option in the Insert > Hyperlink 223 function allows you to insert all the
macros available in Winhelp in your projects. Full documentation of these macros is included
with the Microsoft Help Workshop package, which is installed on your computer
automatically when you install the Winhelp compiler, the latest version of which is always
available from the EC Software website.

Winhelp macros translated in HTML Help:

Winhelp macros are a Winhelp technology and they are thus only fully supported in
Winhelp output. If you are outputting to more than one format you may thus want to use
conditional text 410 and other conditional output features to create alternative content for
the other output formats.
In all formats other than Winhelp the macro links will be displayed as plain text without
any function. This also applies in HTML Help, with the following four exceptions, which
are translated to the ActiveX and HTML equivalents so that they work in HTML Help:

© 1997 - 2009 by EC Software, all rights reserved

 762 Help & Manual 5 - User Help

ALink() KLink()
TCard() Close()

These macros are translated because their Winhelp syntax is much easier to use than
the complex HTML code needed to use the HTML Help ActiveX object. This is particularly
useful when you are using A-Keywords to build automated See Also.. lists and links
between help files in modular help systems.
For details see Inserting script and macro links 223 and Using A-keywords 281 .
Note that only keywords are supported as arguments in the ALink and KLink macros
when they are used in HTML Help. All other arguments are ignored.

You don't need the ExecFile() macro

If you have upgraded from Help & Manual 3 you may be wondering what has happened
to the ExecFile() Winhelp macro, which used to be translated in HTML Help. This is no
longer necessary because you can now use file links 220 instead, which produce the same
result much more efficiently.

See also:
Inserting file links 220
Inserting script and macro links 223
Using A-keywords 281
9.6.4.3 About inline HTML code

The Insert HTML Code Object tool in Write > Insert Object allows you to include plain
HTML code at any point in your topics and export it unchanged to all HTML-based output
formats (HTML Help, Browser-based HTML, Windows Exe and ePub eBooks and Visual
Studio Help/MS Help 2.0).
This topic assumes that you are already familiar with writing code in HTML and JavaScript.

Plain HTML code in eBooks:

Note that although plain HTML is exported to eBooks only plain formatting code and
basic CSS will actually work in this format. You cannot use scripts or DHTML. The simple
viewer application embedded in Windows Exe eBooks does not support scripting. The
ePub specifications includes scripting but almost all ePub readers have little or no
support for it, so it is effectively unavailable.

When to use plain HTML code:

There are basically two situations where you may want to use plain HTML code:
· When you want to add features to your HTML-based output with dynamic HTML and
scripting.
· When you want to write your own HTML code to achieve formatting results that you
can't create directly with Help & Manual.
HTML code objects are preferable to using JavaScript links 759 for inserting more complex
JavaScript code in your pages. Since the code is inserted in the page you can also

© 1997 - 2009 by EC Software, all rights reserved

 Reference 763

include links, and you have more freedom to format your code because you are not
restricted by the link insertion syntax.

How plain HTML code is inserted:

Plain HTML code objects are inserted directly at the current insertion point in your topic
text. The code is inserted exactly as you write it without any changes, and it is not parsed
or syntax-checked in any way. The only exceptions are some graphic file references in
your HTML topic templates, which are parsed and exported 811 with your output.
This means that you are 100% responsible for making sure that you write valid code!
Since the entire topic contents are always inserted between the <body> and </body>
tags of the HTML topic page template 433 the plain HTML code you enter is also always
inserted after the opening <body> tag, even if you enter it right at the top of the topic
page. It is important to remember this if you are inserting scripts that need to be in the
<head> section.

Adding HTML code to HTML topic page templates:

You cannot use the Insert HTML Code Object tool to add code outside the <body> and
</body> tags of your topic pages. If you need to do this you must add the code to the
HTML template 433 that is used to generate all the topic code outside the <body> and </
body> tags.
You can do this either directly or with HTML variables. In addition to this you can also edit
the content of your variables on a by-topic basis by redefining variables for individual
topics in the tab. See The power of editable variables 395 for more details on this.

Adding template code to selected topics only

If you need different versions of the code in individual topics you can use HTML variables
to achieve this. Basically you define an HTML variable to hold the code and insert it in
the appropriate location in your HTML page template. Then you redefine the content of
the variable for individual topics in the tab, in the Topic Variables table at the bottom of
the screen.
You can also use these redefinable variables to link to different versions of external script
files in individual topics. See The power of editable variables 395 for more details on this.

Referencing script functions in plain HTML code:

If the code you insert in your topics with the HTML Code Object tool contains calls to
JavaScript functions you have written you may want or need to include these functions in
external .js files or in the <HEAD> section of your topic pages. There are two ways to do
this:
· Add your separate .js script file to the Baggage Files 485 to include it in your output.
Then edit the HTML template 433 for your topics and add an include directive for the .js
script file in the appropriate location in the template file.
· Edit the HTML template for your topics and manually add the script with the functions to
the <head> section of the template.

© 1997 - 2009 by EC Software, all rights reserved

 764 Help & Manual 5 - User Help

See also:
Inserting script and macro links 223
About JavaScript Links 759
Inserting plain HTML code 231
The power of editable variables 395
Using HTML Templates 430

9.7 Modules, Conditional Output & Variables

This section provides background information on the features of Help & Manual that allow
you to create variants of your projects.
Modular projects make it possible to combine multiple projects in a single master project, in
which you can edit and publish them as though they were a single project.
Conditional output is used to generate different versions of your project for different output
formats or different purposes.
Variables are used to quickly insert standard texts and they can be redefined quickly for
project variants.

9.7.1 Modular Projects

A modular help system is a help system that consists of multiple help projects that can be
edited separately but published as though they were a single project. There are also two
levels of "modularity": Modular help projects (your project consists of multiple Help & Manual
modules) and modular help systems (your output help files also consist of modules).

Modular help projects:

A modular project consists of multiple projects, referred to as "modules", that you edit
separately but publish together with the help of a main project referred to as a "master
project" or "master module".
You can output a modular project as a single help file, then you are only using authoring
modularity, or as multiple help files, then you are also using output modularity.
Authoring modularity gives you practical advantages for managing your projects, output
modularity gives you additional flexibility for the configuration of different versions of your
help.

Modular help systems:

A modular help system is one that is made of separate modules at "runtime", i.e. when
the user is viewing it. Modular help systems are only possible in HTML Help (CHM) and
the obsolete Winhelp (HLP) format.
A modular help system consist of a "master" module containing the main TOC, which
must always be present, and one or more "child" modules, any of which may or may not
be present.
If a child module is present at runtime its TOC will be included in the TOC of the master
module – for the user everything looks like a single help file. If the child module is not
present its TOC is not included. This process is automatic and depends only on the

© 1997 - 2009 by EC Software, all rights reserved

 Reference 765

presence of the child module in the same folder as the master module.
With a little planning you can easily distribute different versions of your help for different
product versions just by including or excluding individual modules in your distribution
package.
See Runtime and publish time merging 767 for more details on truly modular projects.

Linked snippets are not modules

In addition to modular help systems Help & Manual also allows you to include individual
topic files and chapters from other projects in your current project as linked snippets. 149
This blurs the distinction between modular and non-modular projects slightly.
It is important to understand that true modular help systems are only possible when entire
projects are used as modules. When you insert a topic or chapter from another project it
becomes part of the current module when you publish. Such topics and chapters cannot
be handled as separate modules in published modular help systems, even in HTML Help
and Winhelp.

Why use modular help systems?

There are a number of very good reasons for using modular help systems:
Create different versions without editing:
In HTML Help and the obsolete Winhelp you can create genuinely modular help systems
(see above) in which you can include and exclude entire sections of the help simply by
including and excluding help files from your distribution package. You must always
include the master file but if a child file is not found its contents are simply excluded from
the TOC automatically. This is ideal for applications with different versions.
Reusing content efficiently:
You can create "boilerplate" projects for reusable project sections, for example
introductions that are always very similar or your product lists or terms and conditions.
(Note that in many cases snippets 149 are also an efficient way of doing this.)
More efficient group work:
When you are working on a project in a team you can assign separate modules to each
team member. Each author can then work on his or her own modules separately if they
do not have access to the central version on the server.
Managing very large projects:
Modularizing your help projects makes very large projects easier to manage. Among
other things, compiling the smaller child modules is faster and you can check your output
more quickly.

Master projects and child projects

A modular project consists of one master project and one or more child projects (which
can in turn be master projects containing their own child projects).
Both master projects and child projects are ordinary Help & Manual projects. The only
thing that makes them "modular" is the way they are structured: Child projects are
inserted in the TOC of the master project as single items, in exactly the same way that

© 1997 - 2009 by EC Software, all rights reserved

766 Help & Manual 5 - User Help

you insert topics.

Editing modules inserted in publish-time merging mode:
· In the Master TOC:
Publish-time merging modules are displayed as part of the master TOC and can be
edited directly in the TOC, in the same way as the master project's own topics. (To
enable in-place editing you may need to activate this in Configuration > Common
Properties > Miscellaneous and then reload your project.)
· In the Merged Projects section:
If you open the Configuration section in the Project Explorer you will find a section
called "Merged Projects" right down at the bottom. This gives you direct editing access
to the entire contents of the module, including its Configuration settings, project files
and so on.
Editing modules inserted in runtime merging mode:
Modules inserted for runtime merging are just placeholders, however. To edit them you
need to right-click on the placeholder in the master TOC and select Open Child Project...
The project will then be opened as a normal additional project in the Project Explorer.

Publishing modular projects

When you publish the master project it behaves as though it is a single project. The entire
TOC of each child project and all the topics it contains is merged into the output. This
works in all output formats supported by Help & Manual, but there are differences in how
it is handled and the options you have depending on the format you choose:
HTML Help You can choose whether you want to merge the projects completely
and Winhelp: and create a single output file, or create individual projects whose
TOCs are all displayed and accessed through the TOC of the master
help file. See Runtime merging and publish time merging 767 .
Important: The project filenames and the output filenames of the
HLP or CHM files must be identical. The references between
the child and the master help files are based on the filenames
and if project and output filename don't match the references
will be invalid.

Webhelp: In Webhelp the output of a modular project is always merged

completely. The files of all the modules are output to a single directory
and accessed with a single index.html file that integrates the master
and all child TOCs in a single master TOC.

Windows Exe The entire modular project is always published to a single eBook. The
and ePub TOCs of the master module and all child modules are integrated in the
eBooks: single TOC of the eBook.

PDF and RTF: Modular projects are always merged to a single document when you
output to PDF or RTF or print a user manual with the Print Manual
function in the Application Menu.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 767

See also:
Working with Modular Help Systems 446
9.7.1.1 Runtime and publish time merging

In HTML Help (CHM) and the obsolete Winhelp (HLP) you can create genuine modular help
systems with separate help files that are displayed in a single TOC at runtime (when the
user views them). Alternatively, you can also combine all your modules to one large help
file.
See Choosing the merge method 451 for instructions on how to set the different merge
methods for HTML Help and Winhelp output.

Publish time merging – one integrated help file

Publish time merging generates one single help file from all your module projects. From
the point of view of your output this is no different from working with one single project
without modules. With this method the project is only modular while you are working on it,
your output is exactly the same as that produced from a single help file without modules.
One of the more practical advantages of publish time merging is that all the modules,
including all the child modules, are compiled in a single quick process when you compile
the master project. You don't have to open and compile every module separately as you
do for projects configured for runtime merging.

In publish time merging Help & Manual combines all the modules and
creates one big help file when you publish the master module. If you
want to exclude a module you must republish without the module.

Runtime merging – separate help files

When you generate separate help files for each module in your project this is called
runtime merging: When the user "runs" the help the separate help files are "merged"
and displayed in a single help viewer with a single Table of Contents (TOC) containing all
the topics of all the available modules.
Runtime merging produces genuinely modular help systems in both Winhelp and HTML

© 1997 - 2009 by EC Software, all rights reserved

768 Help & Manual 5 - User Help

Help. The master module containing the main TOC must always be present, but you can
include or exclude the other modules from the help simply by including and excluding the
help files of the child modules from the directory in which the help is stored. If a module's
help file is not present its topics are simply not included in the TOC.
The great advantage of this is the enormous flexibility it gives you. With a little planning
you can reduce the work involved in distributing different versions of your help for
different versions of your product to almost zero. All you need to do is include or exclude
help files from your distribution package.
Important: The project filenames and the output filenames of the HLP or CHM files must
be identical. The references between the child and the master help files are
based on the filenames and if project and output filename don't match the
references will be invalid.

With runtime merging you create separate help files for the master and
child
modules (each module must be compiled separately). Help files that
are not
present on the user's computer are automatically excluded from the
TOC.

Mixing runtime and publish time merging

You specify whether child projects are to be merged at publish time or runtime when you
insert the project in the master project. Since this is specified separately for each project
it is possible to mix runtime and publish time merging. However, you need to be careful
when you do this as it is quite easy to lose track of what you are doing in complex
projects with a lot of modules.

Exporting runtime modules to other formats

When you insert a module in runtime mode it will only be exported to HTML Help and
Winhelp. If you want to export the same module to other formats you must insert it in your
TOC a second time in publish-time mode. When you do this you should also set the
include options for each version so that the correct version gets exported automatically
depending on the output format you choose:

© 1997 - 2009 by EC Software, all rights reserved

 Reference 769

Setting the include options:

Just right-click on the main module "node" (spiky green icon) in the TOC, select Include
in Builds in the context menu and then set the include options appropriately. Make sure
that you set the options so that it is not possible to export both versions together!
You can also access the include options in Manage Topics > Change in the Project tab.
See Conditions and Customized Output 399 for more details on using include options.

Advantages and Disadvantages of the Two Merging Methods

The following table summarizes the pros and cons of the two merging methods.
Remember that runtime merging is only possible in HTML Help (CHM) and the obsolete
Winhelp (HLP).

Runtime Merging Publish Time Merging

Advantages Disadvantages Advantages Disadvantages

Truly modular, All the component Single help file, You must republish
dynamic help modules must be exactly like those 461 to produce

systems. Different published produced from different versions

versions can be separately 461 . single Help & of the help for
created simply by Manual projects. different product
including and All the component versions.
excluding help files modules are
in your distribution compiled
without automatically in a
recompiling. single quick
process.
Duplicate topic IDs When creating Links to the help You must be
and context links to the help from your careful to avoid
numbers in from your application are duplicate topic IDs
modules are not a application you always to the same 456 and context

problem because must always be help file. numbers in

the output files are careful to link to different modules

© 1997 - 2009 by EC Software, all rights reserved

 770 Help & Manual 5 - User Help

Runtime Merging Publish Time Merging

Advantages Disadvantages Advantages Disadvantages

Truly modular, All the component Single help file, You must republish
dynamic help modules must be exactly like those 461 to produce

systems. Different published produced from different versions

versions can be separately 461 . single Help & of the help for
created simply by Manual projects. different product
including and All the component versions.
excluding help files modules are
in your distribution compiled
without automatically in a
recompiling. single quick
process.
truly separate. the correct help file because the
459 . modules are
merged to a single
help file.
Invisible topics of Multiple files that A little easier to
all modules are must be distributed manage because
included instead of a single you can handle all
automatically help file. the projects as if
because the child they were a single
modules are project.
compiled
separately.

See also:
Working with Modular Help Systems 446
Planning modular projects 770
9.7.1.2 Planning modular projects

If you want to get the full benefits from modular projects you need to do some planning.
Module divisions should be logical rather than arbitrary. You must break your project up into
modules in a way that increases your flexibility, and you need to plan ahead to make sure
that you take any possible future changes into account. You also need to think very carefully
about links between modules and make sure that any links you create will not create
problems for you later.

Planning for future modular help systems

Even if you are not using modular projects now it is a good idea to plan ahead just in
case you decide to modularize your projects in the future. In particular, you should always
use topic ID naming schemes that will enable you to combine projects at a later date
without creating ID conflicts. Then you always have the freedom to switch to runtime
merging if you want, and your projects will also have a better and more logical structure
that is easier to manage in the long run.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 771

Be clear about which module is your master module:

Even though every Help & Manual project can contain as many modules as you like you
should always manage each modular help system with one master project, otherwise you
will go crazy trying to keep track of everything and mistakes are almost guaranteed
sooner or later. You can reuse modules in different modular help systems, but then they
should be completely separate systems with their own master modules.

Don't nest your modules too deeply

Sub-modules can also contain their own sub-modules and there are no physical limits on
how far you can nest sub-modules. However, it is best to make cautious use of this
capability because it is easy to lose track of what you are doing. This applies in particular
when you are mixing runtime and publish time merging.
It's a good idea to store your child module projects in a clearly-organized directory system
without many levels of subdirectories. Even if your project itself has many levels, you will
find your project files much easier to access if you store them all on the same level in
folders with descriptive names, possibly including level numbers.

Don't create modules unless you really need to

Don't create modules just for the sake of making modules. A single project is always
easier to manage, it can be edited by multiple users at the same time (Professional
version only) and Help & Manual can manage large projects with ease.

Master modules with and without content

The master module can have content of its own or you can use it as an empty framework
for the sub-modules. If the master has content then the common components of your
documentation that are always included should be in the master module.
If you put everything in separate modules so that the master module has no content of its
own then nobody ever needs to actually edit the master module except the person
responsible for doing the final compile, and this can be an advantage.

Minimize links between modules:

Each module should be as independent and complete in itself as possible. It should
contain all the information needed to describe the module of your application that it is built
for.
If you are using runtime merging it is particularly important to make sure that the context-
sensitive help topics 369 needed by your application are going to be there when the user
needs them. It may be necessary to move topics to one of the main modules that is
always present. If you don't want to include the topic in the TOC you don't have to, you
can create a topic without a TOC entry and link to that.
It is generally advisable to avoid context links across module boundaries, even if you are
currently using publish time merging. This will save you a lot of unnecessary work if you
ever decide you want to switch to runtime merging.
Links to the master module are never a problem because that is always present, but links
between modules and from the master to the child modules should be kept to an absolute

© 1997 - 2009 by EC Software, all rights reserved

 772 Help & Manual 5 - User Help

minimum. If you must create inter-module links you should make absolutely sure that the
target module will always be present when the user runs the help. Alternatively, use A-
links 459 to make sure that links to non-existent modules will display a suitable alternative
topic.

Always call popup topics directly

Calls to popup topics are not routed from the master module to the child modules. If you
call popup topics in HTML Help or Winhelp files from your application you must always
make the popup calls directly to the help file containing the popup topic, not to the master
file. (This only applies for runtime merging, of course in publish time merging there is
always only one help file you can make calls to.)

Take steps to avoid duplicate topic IDs and context numbers:

In publish time merging duplicate topic IDs and help context numbers 801 in modules will
cause link failures and other errors in your help files. Help & Manual can only prevent
duplicates within a single project so you have to take steps to prevent duplicates in your
modules yourself. For details see Managing IDs and context numbers 456 in Working with
Modular Help Systems 446 .

Always place all your output files in the same directory

This is essential for runtime-merged projects. The Microsoft HTML Help viewer in
particular has some annoying bugs that make it almost impossible to call files from the
help that are not in the same directory as the help file. Even if links to other directories
seem to work on your test computer they will fail on very many users' computers, so
don't use them.
Don't worry about the whys and wherefores, just always put all your help files and any
external files you need to call in the same directory. That is the only way to avoid
problems and have a help system that always works.

See also:
Working with Modular Help Systems 446
9.7.2 Variables and Conditional Output
This section contains background information on the various kinds of variables and
conditional switches available in Help & Manual and reference lists of all the variables and
switches.

See also:
Using Variables 376
9.7.2.1 Where you can use variables

The following table provides a quick reference showing where you can use which kinds of
variables in your projects:

Location: Supported variables:

© 1997 - 2009 by EC Software, all rights reserved

 Reference 773

Topic text and Plain-text variables:

headers
Global predefined variables and user-defined variables inserted
with the Text Variable tool in Write > Insert Object:
<%VARIABLE_NAME%>
Note that variables typed in manually are not highlighted in the
editor and double-clicking on them will not open the variable
selection list.
HTML variables:
HTML variables inserted in these locations will only insert the
text portion of the HTML code. For example, if the variable
contains:
<a href="http://www.ec-software.com>EC Software
Website</a>
only "EC Software Website" will be inserted. All the HTML code
(blue) will be stripped out. If there is no plain-text portion
nothing will be inserted.

TOC, keywords, image Plain-text variables:

captions, link
captions, macros in
Global predefined variables and user-defined variables inserted
macro links manually by typing the variable names.
HTML variables:
In these locations only the plain-text portion of HTML variable
values will be inserted (see example above). If there is no
plain-text portion nothing will be inserted.

HTML code objects Plain-text variables:

and scripts in script
links
Global predefined variables and user-defined variables inserted
manually by typing the variable names.
Important: You cannot use HTML template variables 778 in
HTML code objects or script links because the code objects are
parsed together with the topic content, before it is inserted in
the template.
HTML variables:
You can use HTML variables in HTML code objects and scripts
in script links. However, don't use HTML template variables as
part of the variable value because they won't be parsed (see
above).

HTML templates Plain-text variables:

Global predefined variables, user-defined variables and special
HTML template variables inserted manually by typing the
variable names.

© 1997 - 2009 by EC Software, all rights reserved

 774 Help & Manual 5 - User Help

HTML variables:
You can use HTML variables without restriction in HTML
templates. The HTML code stored in the variable will be
inserted in the in the template. You can also use HTML
template variables 778 as part of the value of the HTML variable.

PDF templates Plain-text variables:

Global predefined variables, user-defined variables and special
PDF template variables inserted manually by typing the variable
names.
HTML variables:
HTML variables will only insert the plain-text portion of the
variable value in PDF templates. If there is no plain-text portion
nothing will be inserted.

See also:
Using Variables 376
9.7.2.2 Global predefined variables

These variables can be used everywhere in your project where variables are supported,
including topics, headers, links, the TOC, scripts, macros and all HTML templates. See
Using Variables 376 for details.
All the date and time variables use the corresponding date and time formats set in the
Windows configuration on the computer on which you are running Help & Manual.
Variable Content and/or function of the variable

<%TITLE%> The title of the help project defined in Project > Project
Properties > Common Properties > Title & Copyright
.

<%COPYRIGHT%> The copyright statement defined in Project > Project

Properties % Common Properties > Title & Copyright
.
<%AUTHOR%> The name of the author of the help defined in Project >
Project Properties > Common Properties > Title &
Copyright.

<%SUMMARY%> The Summary text for the project defined in Project >
Project Properties > Common Properties > Title &
Copyright.

<%VERSION_MAJOR%> The Major Version text for the project defined in Project >
Project Properties > Common Properties > Title &
Copyright.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 775

Variable Content and/or function of the variable

<%TITLE%> The title of the help project defined in Project > Project
Properties > Common Properties > Title & Copyright
.

<%VERSION_MINOR%> The Minor Version text for the project defined in Project >
Project Properties > Common Properties > Title &
Copyright.

<%VERSION_BUILD%> The Build Version text for the project defined in Project >
Project Properties > Common Properties > Title &
Copyright.

<%VERSION%> An automatically-generated combination of the Major, Minor

and Build version variables, with dots between the versions.
For example, if Major=3, Minor=25 and Build=329 then <%
VERSION%> will be 3.25.329.

<%CITATION%> The "citation" for Winhelp files defined in Project >

Project Properties > Winhelp > Miscellaneous
Winhelp Options. This is the text automatically added to text
copied and pasted from compiled Winhelp files.
<%SELF%> The name of the current project file without path or
extension.
<%SELFFULLNAME%> The name of the current project file including the file
extension and the full path to the project directory, as
displayed in the Help & Manual title bar. This can be useful
for documenting which project version you have used to
generate your documentation.
<%DATE%> The current date in short format.
<%DATELONG%> The current date in long format.
<%TIME%> The current time in short format.
<%TIMELONG%> The current time in long format.
<%NOW%> The current date and time.
<%YEAR%> The current year in 4-digit format.
<%MONTHNAME%> The current month in long format (i.e. February, not Feb or 2)
<%TOPICLASTEDITED%> The date when the topic containing the variable was last
edited in short format.
<%TOPICLASTEDITEDTIME The time when the topic containing the variable was last

© 1997 - 2009 by EC Software, all rights reserved

 776 Help & Manual 5 - User Help

Variable Content and/or function of the variable

<%TITLE%> The title of the help project defined in Project > Project
Properties > Common Properties > Title & Copyright
.

%> edited.

See also:
Using Variables 376
Using HTML Templates 430
9.7.2.3 Date & time formatting in variables

A number of the predefined variables in Help & Manual enter the current date or time or the
date or time associated with an item in your project. Normally these variables will
automatically use the date and time format set in your Windows configuration. However, you
can add a formatting string to the variable to change this if you want.
Note that this only works with variables that return date and time values, if you add format
strings to any other variables the variable will no longer work. Also, you can only use this
option on variable names entered in your topics – you cannot define variables with these
formatting options.

Key Information
You cannot DEFINE variables with date
and time formatting information the
format strings will fail in variable definitions.
You can only use these options by editing
variable names in the editor after inserting
the variables.

Basic syntax
To use this feature you insert the variable in your project, either manually or with the
Insert Variable tool, and then manually type a format string in parentheses inside the
variable name in the Help & Manual editor:
<%NOW(format string)%>

Position and syntax of the format string:

The format string must be inserted in parentheses between the last letter of the variable
name and the closing %> characters of the variable tag. The string can contain both
"specifiers" that define the date and time format and normal text, which must be enclosed
in double quotes.
Specifiers may be written in upper or lower case, the result will be the same.
Example:
This topic was last modified on Montag, Jänner 26, 2009, at 05:47 PM
Result: This topic was last modified on Tuesday, January 3, 2007, at 12:22 PM

© 1997 - 2009 by EC Software, all rights reserved

 Reference 777

The text within the quotes will be inserted exactly as it is written. Any spaces required
must be included within the quotes and the quotes must be separated from the specifiers
by spaces.

Date and time format specifiers

Specifier Function
" text " Anything enclosed in single or double quotes is inserted unchanged as plain
' text ' text and does not affect formatting.
. and , You can include periods and commas in the formatting string with the
specifiers, these characters to not need to be quoted.
c Displays the date using the standard Windows short date format, followed by
the time using the standard Windows long time format. The time is not
displayed if the fractional part of the DateTime value is zero.
d Displays the day of the month as a number without a leading zero (1-31).
dd Displays the day of the month as a number with a leading zero (01-31).
ddd Displays the day as an abbreviation (Sun-Sat) using the standard Windows
strings for short day names.
dddd Displays the day as a full name (Sunday-Saturday) using the standard
Windows strings for full day names.
ddddd Displays the date using the standard Windows short date format.
dddddd Displays the date using the standard Windows long date format.
m Displays the month as a number without a leading zero (1-12). If the m
specifier immediately follows an h or hh specifier, the minute rather than the
month is displayed.
mm Displays the month as a number with a leading zero (01-12). If the mm
specifier immediately follows an h or hh specifier, the minute rather than the
month is displayed.
mmm Displays the month as an abbreviation (Jan-Dec) using the standard
Windows values for short month names.
mmmm Displays the month as a full name (January-December) using the standard
Windows values for long month names.
yy Displays the year as a two-digit number (00-99).
yyyy Displays the year as a four-digit number (0000-9999).
h Displays the hour without a leading zero (0-23).
hh Displays the hour with a leading zero (00-23).
n Displays the minute without a leading zero (0-59).
nn Displays the minute with a leading zero (00-59).
s Displays the second without a leading zero (0-59).

© 1997 - 2009 by EC Software, all rights reserved

 778 Help & Manual 5 - User Help

ss Displays the second with a leading zero (00-59).

z Displays the millisecond without a leading zero (0-999).
zzz Displays the millisecond with a leading zero (000-999).
t Displays the time using the standard Windows short time format.
tt Displays the time using the standard Windows long time format.
am/pm Uses the 12-hour clock for the preceding h or hh specifier, and displays 'am'
for any hour before noon, and 'pm' for any hour after noon. The am/pm
specifier can use lower, upper, or mixed case, and the result is displayed
accordingly.
ampm Uses the 12-hour clock for the preceding h or hh specifier, and displays the
contents of the Windows TimeAMString global variable for any hour before
noon, and the contents of the TimePMString global variable for any hour
after noon.
/ Displays the date separator set in your Windows configuration.
: Displays the time separator set in your Windows configuration.

See also:
Using Variables 376
9.7.2.4 HTML template variables

You can use all global predefined variables 774 and user-defined variables 378 in HTML
templates 430 . In addition to this you can also use the following special predefined variables,
which are only relevant in HTML templates.

Variables for use in topic page templates only:

These variables can only be used in topic page templates. They are valid in all HTML-
based output formats (HTML Help, Webhelp, Windows Exe and ePub eBooks and Visual
Studio Help / MS Help 2.0).
Variable Content and/or function of the variable

<%DOCTYPE%> Inserts the correct DOCTYPE tag at the beginning of the

HTML output pages. This variable is essential in all
templates and should not be removed. If you do remove
it you will get an error message from the compiler.

<%DOCCHARSET%> Inserts the correct character set information in the meta

tags at the beginning of the HTML output pages. This
variable is essential in all templates and should not be
removed. If you do remove it you will get an error
message from the compiler.
<%STYLESHEET%> Inserts the reference to the CSS stylesheet containing all
the styles information for your project. This variable is
essential in all templates and should not be removed. If

© 1997 - 2009 by EC Software, all rights reserved

 Reference 779

Variable Content and/or function of the variable

<%DOCTYPE%> Inserts the correct DOCTYPE tag at the beginning of the

HTML output pages. This variable is essential in all
templates and should not be removed. If you do remove
it you will get an error message from the compiler.

you do remove it you will get an error message from the

compiler.
<%TOPIC_HEADER%> Inserts the header of the current topic if it exists. If the
current topic has no header the value of this variable is
null. This can be different from the topic caption inserted
with <%TOPIC_TITLE%>.

<%TOPIC_HEADER_TEXT%> Inserts the header of the current topic as plain text. This
is particularly useful if your project headers are different
from and longer than the TOC captions, which is
inserted with <%TOPIC_TITLE%>.
This is used primarily for search engine optimization, for
which you would insert it in the description meta tag,
like this:
<meta name="description" content="<%
TOPIC_HEADER_TEXT%>">

<%TOPIC_TEXT%> Inserts the body text of a topic, i.e. the entire topic as
edited and formatted in your project in the Help &
Manual editor. This is the most important variable – if
you leave it out your topics will be empty!
<%TOPIC_BREADCRUMBS%> Generates a series of "breadcrumb trail" navigation links
to topics above the current topic in the TOC tree. This
variable is empty in top-level topics. In second-level
topics and below the variable generates a series of links
in the format Link1 > Link2 > Link3 ...
The current topic is not included in the series. If you
want to place the current topic title at the end of the
breadcrumb trail you can do so with the <%TOPIC_TITLE
%> variable (see below).
The breadcrumb trail variable is empty in topics in the
Invisible Topics section.
This variable has a matching condition pair:
<IF_TOPIC_BREADCRUMBS> and
<IFNOT_TOPIC_BREADCRUMBS> . These conditions can
be used to only insert the trail where it is relevant and to
insert alternative content when it is not relevant.
See here 433 for details on how to use this variable.

© 1997 - 2009 by EC Software, all rights reserved

780 Help & Manual 5 - User Help

Variable Content and/or function of the variable

<%DOCTYPE%> Inserts the correct DOCTYPE tag at the beginning of the

HTML output pages. This variable is essential in all
templates and should not be removed. If you do remove
it you will get an error message from the compiler.

<%TOPIC_TITLE_PATH%> This variable is similar to the breadcrumbs variable

above but it delivers the breadcrumb trail as a plain text
string without any links. Unlike the breadcrumbs variable
it also includes the name of the current topic, so it
always delivers a full trail.
The primary use of this variable is for search engine
optimization, for which you would insert it in the <title>
tag of your topic page template instead of the normal <%
TOPIC_TITLE%> variable, like this:
<title><%TOPIC_TITLE_PATH%></title>

Modification for HTML Help:

If you also output to HTML Help you should use
conditional text to ensure that this variable is only used
in Browser Help, otherwise you will get the full path as
the topic name in your search results in the HTML Help
viewer. Do it like this:
<title><IF_HTML><%TOPIC_TITLE_PATH%></
IF_HTML><IF_CHM><%TOPIC_TITLE%></IF_CHM></
title>

<%TOPIC_TITLE%> Topic title (this is the caption of the topic in the TOC).
<%TOPICID%> Returns the plain topic ID as written in the Topic ID:
field of , without any filename extension and without
changing the ID text to lower case. This can be used to
add an ID reference in your meta attributes in your web
pages, for example:
<meta name="id" content="<%TOPICID%>" />
(This variable can also be used in normal topic pages.)
<%TOPIC_KEYWORDS%> Inserts all the keywords 274 of the current topic, comma-
separated. Needless to say, this variable is essential for
the keyword index and shouldn't be removed...
<%TOPIC_AKEYWORDS%> Inserts all the A-keywords 281 of the current topic,
comma-separated.
<%HREF_PREVIOUS_PAGE%> Link address of the previous topic (used for Previous/
Next buttons).
<%HREF_NEXT_PAGE%> Link address of the next topic.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 781

Variable Content and/or function of the variable

<%DOCTYPE%> Inserts the correct DOCTYPE tag at the beginning of the

HTML output pages. This variable is essential in all
templates and should not be removed. If you do remove
it you will get an error message from the compiler.

<%HREF_DEFAULT_PAGE%> Link address of the "Default" topic. This is used for the
standard Top navigation link in the topic headers so that
users can return to the default topic in your project.
<%HREF_PARENT_CHAPTER%> Link address of the parent topic (chapter). This can be
used as an alternative to <%HREF_DEFAULT_PAGE%>.
If the parent is a chapter without text, this is the link
address of the parent's parent. If no valid parent is
available, the variable is the link address of the default
page.
<%HREF_CURRENT_PAGE%> Link address of the current page.

Note on HREF-Variables: All the HREF variables insert the local names of the
corresponding pages within the current directory without
any path information, e.g. topic1name.htm,
topic2name.htm and so on.

Variables for use in Webhelp only:

All the remaining variables are only relevant in Webhelp 730 (HTML):
Global variables for all Webhelp templates:
Variable Content and/or function of the variable

<%HREF_TOP_PAGE%> Link address of the top frame (e.g. "index.html")

<%HREF_CONTENT_PAGE%> Link address of the TOC page

<%HREF_INDEX_PAGE%> Link address of the keyword index-page
<%HREF_SEARCH_PAGE%> Link address of the full-text search page

© 1997 - 2009 by EC Software, all rights reserved

 782 Help & Manual 5 - User Help

Variables for the Layout frameset template only:

Variable Content and/or function of the variable

<%HREF_CONTENT_PAGE_DYN% Link address of the dynamic TOC page.

>

<% Link address of the static TOC page.

HREF_CONTENT_PAGE_STATIC
%>

<%NAVIGATION_SCRIPT%> Inserts the navigation script required by the top frame.

Variables for the Table of Contents template only:

Variable Content and/or function of the variable

<%TABLE_OF_CONTENTS%> Inserts the entire TOC in the page.

Variables for the Keyword Index template only:

Variable Content and/or function of the variable

<%KEYWORD_INDEX%> Inserts the entire keyword index in the page.

Variables for the Search template only:

Variable Content and/or function of the variable

<%SEARCH_SCRIPT%> Inserts the full-text search script in the page.

See also:
Using Variables 376
Using HTML Templates 430
Editing HTML templates 431
Help Windows 807
9.7.2.5 HTML template output conditions

You can use all of Help & Manual's standard conditional output options in HTML templates,
both your user-defined include options 406 and options based on the current output format. In
addition to this there are a few special conditional switches which are only for use in Help &
Manual's Webhelp output, because they are only relevant there. See the lists below for
details.
These conditions are like special HTML tags. They are used to enclose blocks of HTML
code in your template that you want to include in the output only if the condition is fulfilled.
In HTML templates you can only use output format conditions for HTML-based output
formats (CHM, HTML, EBOOK and HXS). This is because these templates are only used for
HTML-based output so <IF_PDF> would not have any meaning, for example. Note that the

© 1997 - 2009 by EC Software, all rights reserved

 Reference 783

EBOOK condition applies both for Windows Exe and ePub eBooks.

Conditions are stripped before publishing

All the condition tags are stripped from your code before actually generating the HTML
output. No proprietary tags are included in your output!

Predefined HTML template conditions:

In addition to the predefined conditions listed here you can also use your own user-
defined include options 406 as conditions in HTML templates. See Conditional output in
HTML templates 441 for details on how to use the conditions.
Conditions Function of the condition

<IF_TOPIC_HEADER> True if the current topic has a header and the header is not
empty (the variable <%TOPIC_HEADER%> is not equal to "").

<IF_PREVIOUS_PAGE> True if a previous page exists (the variable <%

HREF_PREVIOUS_PAGE%> is not empty). Used to suppress or
display a grayed-out version of the Previous navigation
button in the very first topic.
<IF_NEXT_PAGE> True if a next page exists. Used to suppress or display a
grayed-out version of the Next button in the very last topic.

<IF_INDEX_PAGE> True if a keyword index is included in the output. Only

relevant for Webhelp.
<IF_SEARCH_PAGE> True of full-text search is included in the output. Only
relevant for Webhelp.
<IF_FRAMES> True if Webhelp is exported with frames (a frame-based
format is selected in the Navigation 676 options). This could
be used for entering a link from topic pages to your TOC
page when you select the No Frames, No Scripts layout
option, for example. Only relevant for Webhelp.
<IF_TOPIC_BREADCRUMBS> True if the <%TOPIC_BREADCRUMBS%> variable is not empty
(see HTML template variables 778 ). For example, this variable
is always empty in topics in the Invisible Topics section and
in top-level topics.
<IF_HTML> True when you generate Webhelp (HTML)
<IF_CHM> True when you generate HTML Help
<IF_HXS> True when you generate Visual Studio Help / MS Help 2.0
<IF_EBOOK> True when you generate e-Books, applies for both Windows
Exe and ePub eBooks

© 1997 - 2009 by EC Software, all rights reserved

 784 Help & Manual 5 - User Help

Conditions Function of the condition

<IF_TOPIC_HEADER> True if the current topic has a header and the header is not
empty (the variable <%TOPIC_HEADER%> is not equal to "").

<IF_TOGGLES> True if the current topic contains one or more toggles 350
(expanding text and images).

"IFNOT" versions negate the meaning of the conditions:

Exclude Conditions Function of the exclude condition

<IFNOT_TOPIC_HEADER> Negates the positive version of the condition.

<IFNOT_PREVIOUS_PAGE> Negates the positive version of the condition.

<IFNOT_NEXT_PAGE> Negates the positive version of the condition.

<INOTF_INDEX_PAGE> Negates the positive version of the condition.

<IFNOT_SEARCH_PAGE> Negates the positive version of the condition.

<IFNOT_FRAMES> Negates the positive version of the condition.

<IFNOT_TOPIC_BREADCRUM Negates the positive version of the condition.
BS>

<IFNOT_HTML> Negates the positive version of the condition.

<IFNOT_CHM> Negates the positive version of the condition.

<IFNOT_HXS> Negates the positive version of the condition.

<IFNOT_EBOOK> Negates the positive version of the condition.

<IFNOT_TOGGLES> Negates the positive version of the condition.

See also:
User-defined include options 406
Using HTML Templates 430
Conditional output in HTML templates 441
Help Windows 807
9.7.2.6 PDF template variables

You can use all Help & Manual's global predefined variables 774 and your own user-defined
variables 378 in the text objects in PDF print manual templates 330 . In addition to this there are
also a number of special predefined variables that can only be used in print manual
templates. These variables are described and listed in the separate help and documentation
of the Print Manual Designer program included with Help & Manual.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 785

Key Information
Conditions are not supported in PDF print
manual templates. You cannot use
conditional text or any other conditions in
these templates.

Using variables in PDF templates

Global and user-defined variables from your project:
Just type the variable in any text object in your PDF template, using the standard <%
VARIABLENAME%> syntax.

Special PDF template variables:

These variables can be typed in manually but they can also be inserted from a list by
selecting the Variable button in the text object dialog. This option is preferable because it
automatically shows you which PDF template variables are valid in the current location.

See also:
Using Variables 376
PDF and Printed Manuals 325
The Print Manual Designer 537
9.7.2.7 Conditional output

Help & Manual supports multiple levels of conditional output that give you very precise
control over what is included in your published projects on the basis of output format and
user-defined output conditions 406 . These features make it possible to generate different
versions of your project for different purposes and formats. You can control the inclusion or
exclusion of everything from individual words (or even single letters) to entire topics and
branches of the Table of Contents (TOC).
For example, if you output your project to both HTML Help and PDF you will generally need
to make some small changes to the text for the PDF version because some things that are
relevant in electronic help don't make sense in PDF or a printed manual. With conditional
output you can include both versions in the same project and only the relevant components
will be included when you publish.

How conditional output works:

Instead of creating and maintaining multiple versions of your project for different versions
you only have one project, or one set of modular projects, containing all the content and
topics for the alternate versions you need to generate. The chapters, topics and topic
content (text, graphics, tables etc.) for the alternate versions are "tagged" with conditions
called "include options" (also known as build conditions) that control whether they are
included in the output or not.
Note that in HTML Help and the obsolete Winhelp format you can also create different
versions of your documentation with runtime modular projects. See Runtime and publish
time merging 767 for details on this.

© 1997 - 2009 by EC Software, all rights reserved

786 Help & Manual 5 - User Help

Format-based include options:

These options allow you to include or exclude topics and content on the basis of the
selected output format.
For example, suppose you have two different versions of a sentence, one for the HTML
Help version and one for the PDF version. You would enclose the first version in an
IF_CHM conditional text tag 410 and the second in an IF_PDF tag. And that is all you have
to do, everything else is automatic. When you compile to HTML Help only the IF_CHM
version is included, and when you compile to PDF only the IF_PDF version is included.

User-defined include options:

These options allow you to include or exclude topics and content on the basis of
conditions that you define. This makes it possible to create different versions of your
published output irrespective of the output format. For example you may have different
documentation for different versions of a product.
For example, suppose you defined an include option called BETABUILD and tag specific
text passages and topics in your project with an IF_BETABUILD condition. To include
those passages in your output you just select the BETABUILD include option in the
Publish 590 dialog when you publish, along with any other relevant options.

Conditional output and links

It is important to plan your links when you are working with conditional output. When you
exclude a topic from your output any hyperlinks to that topic in other topic will be dead
unless you also exclude the links.
Before excluding a topic always right-click on its TOC entry and select Check Referrers to
locate any links to the topic. You can then use the same conditions to exclude the links
from your output. In addition to this you may want to add additional conditional text
options to include alternative text to replace the links.
You can configure Help & Manual to include the topic anyway 649 to prevent dead links,
but it is better to exclude the links using the same output conditions.

Levels of conditional output supported by Help & Manual:

Conditional On the text level you can use conditional text tags 410 to mark
text: sections in your topics – paragraphs, graphics, sentences
and even individual words and letters – that should only be
included when a specific condition is fulfilled (output format
or user defined).

Text Text variables (see Using Variables 376 ) allow you to use
variables: variables for text items. Then if the item changes you only
need to redefine the variable once to implement the change
throughout your entire project.
Variables are not really conditional output in the strictest
sense of the term, but you can use them for conditional
output by redefining them globally 414 with a project skin or a

© 1997 - 2009 by EC Software, all rights reserved

 Reference 787

variables file that replaces the variable definitions in your

project at publish time.

Topic These conditions allow you to include or exclude entire

conditions: topics and chapters 407 on the basis of output format or user-
defined conditions.

Modular Help & Manual's modular projects features 446 enable you to
projects: include or exclude entire projects in your help at publish
time. This makes it possible to quickly add or remove entire
blocks with multiple chapters

HTML You can also use some special conditional switches in

conditions: HTML templates 430 to control when code in the template
should be included or excluded.

See also:
Conditions and Customized Output 399
Using Variables 376
Working with Modular Help Systems 446
Conditional output in HTML templates 441
9.7.2.8 Topic entry and topic file include options

Your TOC entries and topic files are actually two separate items: The TOC entries are
connected to the topic files by a kind of hyperlink. The TOC entry and the topic files also
have separate include options. If you work in the TOC you will normally not need to think
about this because the matching include options for the associated topic files will be set
automatically.
However, the situation is different if you have multiple TOC entries 208 for the same topic in
the TOC. Then you need to think about what happens when you set different include options
for TOC entries linked to the same topic file.

How build options are applied to TOC entries and topic files
Working in the TOC:
When you work in the Table of Contents section of the Project Explorer setting or
changing an include option for the TOC item automatically sets the same option for the
topic file to which the TOC entry is linked. Normally this is a 1:1 association and you don'
t need to think about it at all, it is fully automatic. However, the situation is different for
topic files with multiple TOC entries. See below for details.
Working in the Topic Files section:
Setting or changing an include option for a topic file does not automatically change the
include options for any associated TOC entries. For technical reasons, the topic files
cannot be permitted to control the TOC entries. Among other things, this would create a
mess when the TOC contains multiple references to the topic file, each with different
build options.

© 1997 - 2009 by EC Software, all rights reserved

 788 Help & Manual 5 - User Help

Topic files with no TOC entry

If a topic file has no TOC entry (for example for popup topics or topics displayed in
external windows) you must set include options directly for the topic file, in Topic Files in
the Project Files section of the Project Explorer.
This is generally the only time when you should set include options for topic files directly.
In all other cases you should set the options in the TOC unless you have a specific
reason for wanting different options for the TOC entry and the associated topic file.

Topic files with multiple TOC entries

If you have multiple TOC entries 208 for the same topic in the TOC setting include options
for the individual TOC entries is a little more complicated. Basically, the following
principles are applied:
· The include options are saved separately for each TOC entry.
· The include options of the linked topic file are set as the sum of all the options set for
the linked TOC entries.
Note that these settings are handled automatically if you set the options in the TOC.
However, if you set the include options for the topic files directly you are responsible for
getting the associations right yourself.
Examples:
In the following example the include options of the topic file are set to ALL because only
this setting will cover all the settings required for both the associated TOC entries.
Item Type Name Include Options
TOC entry 1 Introduction CHM
TOC entry 2 Introduction(2) ALL
Topic file Introduction.xml ALL
In the following example the include options of the topic file are set to the combination of
the options for both associated TOC entries.
Item Type Name Include Options
TOC entry 1 Introduction CHM, HTML
TOC entry 2 Introduction(2) PDF
Topic file Introduction.xml CHM, HTML,
PDF

9.7.3 Context-Sensitive Help & Popups

Context-sensitive help 789 enables users to obtain help that is directly relevant to a specific
program feature or the task they are currently performing. It can make it much easier for
users to learn how to use your application because they get information about what they are
trying to do while they are trying to do it. This makes your users happier and saves you time
and money by reducing the amount of support you have to provide.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 789

What is context-sensitive help?

There are basically three kinds of context-sensitive help that you need to think about as a
help author:
· The user presses F1 and the help is displayed with a topic relevant to the "context" in
which the user pressed the key. For example, pressing F1 in an editor could display a
topic on editing, pressing F1 in a configuration dialog could display a topic on the
features of that dialog, and so on.
· Clicking on a "Help" button in a dialog displays a help topic describing that dialog.
· Right-clicking on a control in an application and selecting What's This? displays a
popup window with a text describing the control and what it is for.
· Clicking on any other kind of control in an application (an icon etc.) to display a
small popup directly in the application.
The first two kinds of context-sensitive help are implemented with normal calls to specific
topics in your help. These are almost always ordinary topics that are included in the Table
of Contents (TOC). As the help author you only have to make sure that relevant topics
are available, and you must also coordinate with the programmers on the topic IDs and/or
help context numbers 801 that are to be used to access the topics from the application.
See About implementing context help 796 for some more background information on this.
Embedded context-sensitive help with popup topics needs a little more explaining. See
About field-level popups 794 in this chapter for full details.

See also:
Context-Sensitive Help 369 (HowTo)
About field-level popups 794
9.7.3.1 Context-sensitive help technologies

A full tutorial on implementing context-sensitive help in applications would go well beyond

the scope of this help. This topic is just provided to inform you of the various context-
sensitive help technologies that are available in Windows so that you can consider using
them in your application.

Context-sensitive help technologies available in Windows:

Windows now provides a large and powerful set of context-sensitive help tools, including:
Tooltips: Little "tips" that appear automatically when the user moves the mouse
over a control. These are usually implemented in the application itself
rather than being stored in an external help file. Most modern
programming environments support tooltips.
Even if you don't implement any other kind of context help for the
controls in your application it is always a good idea to include tooltips
with brief explanations of what the controls do. This alone can
significantly reduce the number of support requests you have to deal
with!

© 1997 - 2009 by EC Software, all rights reserved

790 Help & Manual 5 - User Help

What's This? In many modern applications you can right-click on a control and
help: select a What's This? option that displays a popup window with a help
text. If you can make your users aware of this (and that is not easy)
this can significantly reduce support requests.
This can be implemented with the help of popup topics created in Help
& Manual. The advantage of this is that the topics are displayed on
their own in a little independent window, without opening the entire
help.
Microsoft includes support for What's This? help in its programming
languages. The free EC Software Help Suite tools package (see
above) makes implementing What's This? help much easier in Borland
Delphi and Borland C++.

Help buttons These buttons link directly to the relevant topic in your main help file.
in dialogs: These are implemented with a direct call to the help file and the topic.
All dialogs requiring any explanation should have a HELP button. In
addition to making your application much easier to use these buttons
also help to ensure that your users actually read your help instead of
just reaching for the phone or writing you an email!

F1 context Relevant help is displayed automatically when the user presses the F1
help: key. What help topics or features are called depends on where and
when the user presses F1 (the "context"). How this is implemented
depends on the individual programming language and it is entirely up
to the programmer. As the help author you only have to provide the
programmers with the necessary topic IDs and/or help context
numbers 801 so that they can call the appropriate topics.

Training card This is a powerful but rather cumbersome help technology developed
help: by Microsoft and supported in both HTML Help 727 and Winhelp 740 . It
allows you to create interactive tutorials in your help that automatically
perform actions in your application when the user clicks on hotspots
and links in your help. For example, you can invoke functions, display
menus, select options and fill out data fields to show the user how to
do things.
For programming information on implementing training card help see
the MSDN Library on Microsoft's website we can't provide direct
links here because the MSDN web programmers change the
addresses so frequently.
Although training card help is a very powerful tool there are good
reasons why it is very rarely used. It can be quite tricky to implement
and every programming language handles it differently.
It is also very important to design interactive wizards using training
card help wizards very carefully. In particular, you need to give the
user the opportunity to actually practice the procedures you are
explaining. Otherwise you can end up teaching the user how to
operate the wizard rather than the program!

© 1997 - 2009 by EC Software, all rights reserved

 Reference 791

Interactive There are basically two kinds of interactive wizards: "Programmed

wizards: wizards" created as part of your program and "help wizards" created
with help technologies like Winhelp and HTML Help.
We don't want to go into programmed wizards here, but they can be
very useful for guiding your users through complex configuration
tasks. For example, a help wizard could guide a user through the
process of configuring a complex program, only continuing to the next
dialog screen when all the settings have been completed correctly.
Non-programmed help wizards are simply ordinary help files, or
sections of help files, that teach users how to perform a specific task
in a systematic way. They can be integrated in your main help but it is
generally a good idea to create them as separate help files. Then they
can be called when needed and they don't get in the way when they
are no longer needed.
Simple help wizards guide the user through a task or procedure
without direct interactivity. For example, you could create a little help
project that shows the user how to configure your program. Each topic
would be a single step in the procedure, with screenshots showing
exactly what needs to be done and Next and Previous buttons for
navigation.
More advanced help wizards make use of training card help (see
above) to open dialogs and perform operations in your application. If
you use this you should always also prompt your users to try the
procedure out for themselves as well, otherwise they will only learn
how to use the wizard rather than the program itself!

Flash demos: Flash demos are not really a context-sensitive help technology but
they can be a useful addition to interactive wizards. Help & Manual
can insert Flash demos 269 in your help files with just a few mouse
clicks.
These demos are animated movies in the Flash format that show your
users exactly how specific operations are performed in your
application, just as if a teacher was there demonstrating it for them on
the screen. There are now a number of software tools available for
making Flash demos. These tools are like screenshot programs,
except they record a movie of what you do on your screen instead of
just a single still image. Some even allow you to include sound
Making Flash demos can be a quite a lot of work but they are an
excellent way of showing beginners how to do things. It is not a good
idea to include them in the main help because users generally don't
need to view them more than a couple of times. It is best to use them
in separate help wizards that users only run when they want to learn
how to perform a specific task.

See also:
Using Context-Sensitive Help 369
Creating popup topics 125

© 1997 - 2009 by EC Software, all rights reserved

 792 Help & Manual 5 - User Help

9.7.3.2 About popup topics

Popup topics 125 should always be created without TOC entries 112 because they are never
included in the TOC (Table of Contents). Their name describes their function: instead of
being displayed in the help viewer they are displayed in little "popup windows" that are
closed again when the user clicks after reading their contents.
All popup topics can be displayed with links from within your help file. HTML Help and
Winhelp popups can also be displayed within your application, without displaying the main
help viewer; then they are referred to as "field-level popups".

The two uses for popup topics:

Within the Inside the help file popups are used to display small items of
help file: information that you want to make available but you don’t want to
include again and again in the help text.
A good example of this would be a definition of a technical term that is
used frequently in your text. Instead of repeating the definition again
and again you would turn the term into a link that links to a popup topic.
However, if you have the Professional version of Help & Manual you
may also want to consider using inline text toggles 355 for this.
When the user clicks on the link the contents of the topic are displayed
in a small popup box, without leaving the current topic.

Context- HTML Help and Winhelp popup topics (but not JavaScript popups 129 )
sensitive help: can also be called directly from applications. When they are called in
this way they are displayed on their own, without displaying the help
file, and closed again immediately when the user clicks on them. This
makes them a useful context-sensitive help tool for describing controls
and functions in programs. See About field-level popups 794 for more
details.

The pros and cons of using popups:

Popups are definitely useful and it is tempting to make extensive use of them. However,
there are a couple of issues you need to think about before doing so:
· Using popups makes it more difficult to produce a printed version of your help. The
user can’t display popups in a PDF or a printed manual so to produce the printed
version you need to provide different ways of accessing the same information, for
example by creating different versions of the text and using conditional output 399 . This
can be quite a lot of work and can get quite complicated to maintain.
· Popups reduce the multi-output compatibility of your source. Popups work differently in
Winhelp and HTML Help, and in Webhelp (HTML) you can only use JavaScript popups
129 . Popups do not work at all in Word RTF, PDF and printed manuals.

· If you want to produce multiple format versions of your help project from the same
source it’s best not to use popups too much because they can significantly increase the
work involved in maintaining the multiple versions.
· If you need context-sensitive field-level HTML Help or Winhelp popups for display

© 1997 - 2009 by EC Software, all rights reserved

 Reference 793

within your application it may be advisable to make a separate Help & Manual project
just for these popups.

Where popup topics are supported:

Popups are not supported in all the output formats generated by Help & Manual, and the
way popups are handled and the options available also vary from format to format. The
following table provides a summary of where and how you can use popups:

Winhelp is not supported by default in Windows Vista:

Support for Winhelp is disabled by default in Microsoft Windows Vista. Even if your
applications run under Vista, any calls to Winhelp help will simply produce an error
message. Support for Winhelp can be added by downloading and installing the Vista
version of the Winhelp viewer from Microsoft but developers are not permitted to
distribute this update with their products. It is also possible that the operating system
support for Winhelp may be removed in the future. We thus strongly recommend that you
start transitioning to an alternative help format as soon as possible. See here for details

© 1997 - 2009 by EC Software, all rights reserved

 794 Help & Manual 5 - User Help

Where popups are supported

Output Format Supported Popup Types Where Supported

HTML Help (. · Plain-text popups integrated in Plain-text popups are

CHM): the main help file. Context supported both in the help
numbers are required for these text and as field-level popups
popup topics! in applications.
· Formatted JavaScript popups 129 Formatted JavaScript popups
stored in the main help file. can only be used in the help
text. They are not supported
for context-sensitive help.
Winhelp (.HLP): · Fully-formatted Winhelp Winhelp popups are
popups stored in the main help supported both in the help
file. text and as field-level popups
in applications.
Browser-based · Fully-formatted JavaScript JavaScript popups can only
HTML popups 129 integrated in the be used in help topics. You
(.HTM): individual HTML files. cannot link to them from
your application.
Windows Exe · Fully-formatted popups with Only available within eBooks.
eBooks: graphics, fonts, emphasis eBooks do not support
(bold, italics etc.) and context calls of any kind.
hyperlinks (topic and Internet
links).
ePub eBooks: · Popups are not supported. N/A
Popup links are automatically
converted to plain text.
Adobe PDF and · Popups are not supported. N/A
printed user Popup links are automatically
manuals: converted to plain text.
Word RTF: · Popups are not supported. N/A
Popup links are automatically
converted to plain text.

See also:
Context-Sensitive Help 369 (HowTo)
Conditions and Customized Output 399
Using JavaScript popups 129
9.7.3.3 About field-level popups

A field-level popup is a popup displayed directly from within your application.

The first thing to understand is that field-level popups are actually the same topics as the
normal popup topics displayed within your help. In your Help & Manual project the same
popup topics can be used for both purposes. The main difference is how they are called:

© 1997 - 2009 by EC Software, all rights reserved

 Reference 795

· Normal popup topics are displayed within the help when the user clicks on a link in a
topic – for example to display a definition or an explanation.
· Field-level popup topics are called directly by the application and displayed in little
windows of their own. This is done without displaying the rest of the help at all. Only the
little popup is displayed, and it is closed again as soon as the user clicks on it.
In addition to this there are settings in your Project Configuration that control how popups
are handled in HTML Help and Webhelp. (See below for more details.)

Example of a field-level popup:

The example on the left shows a popup topic
displayed in an application. It is displayed on its
own, without the main help file. This example is a
Winhelp popup, which supports bold text, but
which cannot be used in Windows Vista.
Exactly the same popup could also be displayed
A context-sensitive popup in an
application.
within the help with a popup link. It would look
almost identical – in the help it would just usually
be white instead of yellow. (This is dictated by the
help viewer and cannot be controlled from within
Help & Manual.)

Help & Manual also supports custom JavaScript popups 129 for formatted popups in HTML
Help and Webhelp. JavaScript popups cannot be used for field-level popups however i.
e. they cannot be called from your application on their own.

About creating field-level popups:

Field-level popups are only possible in HTML Help and Winhelp. They are a proprietary
Microsoft technology and they are not supported in any other output format.
To create field-level popups basically all you need to do is create popup topics 125 and
provide the necessary topic IDs and/or help context numbers to the programmers so that
they can make the calls. See About implementing context help 796 for more information on
this.
If you are writing field-level popups for an application you may have to produce a lot of
popups. You can save yourself a lot of work by generating your field-level popups
automatically 375 .
In Winhelp:
In the obsolete Winhelp format you don't need to configure anything to generate field-
level popups. The popup topics in the Invisible Topics section will be integrated in the
main help file and support formatted text, graphics and links. Context-sensitive calls are
made directly to the topics in the main help file.
In HTML Help:
In HTML Help you can choose from three different popup modes. Only HTML Help's
native text-only popups can be used for field-level popups called from applications.
Go to Configuration > Publishing Options > HTML Help > Popup Topics 667 to set

© 1997 - 2009 by EC Software, all rights reserved

 796 Help & Manual 5 - User Help

the popup mode for HTML Help.

Mode supporting field-level popups:
Text-only This is HTML Help's "native" popup mode. The popups are stored in
popups: the main help file in an internal plain text-file, which is called CSHelp.
txt by default (you can change this). Calls are made to this file using
the standard popup calling syntax of the HTML Help API. No graphics,
links or formatted text (bold, italics etc.) are supported.

Modes not supporting field-level popups:

HTML- This mode outputs popup topics as normal topics that are displayed in
encoded the main window of the HTML Help viewer. They are basically just
popups: invisible topics using the template of the popup window type. This mode
cannot be used for field-level popups called from applications because
the topics are not really popups, they are normal topics.

JavaScript This popup mode uses JavaScript coding to generate popups that can
popups: contain formatted text, links, graphics and even videos and animations.
These popups also support graphical effects and transitions (fade-in
etc.), and can be used in both HTML Help and Webhelp. However,
JavaScript popups also cannot be used as field-level popups called
from applications. See Using JavaScript popups 129 for details.

See also:
Creating popup topics 125
Using Context-Sensitive Help 369
IDs, Context Numbers and Keywords 801
9.7.3.4 About implementing context help

Generally, implementing context-sensitive help called from the application is the job of the
programmers. They must write the calls that access specific topics in your help, and the
syntax of these calls depends both on the help format and the programming language they
are using.
Winhelp (HLP) and HTML Help (CHM) support both context-sensitive calls to specific help
topics and field-level popups displayed within your application. Webhelp only supports calls
to specific topics (see Context calls to Webhelp for details 373 ).

Free tutorials and context-sensitive help tools for programmers:

How the context-sensitive help calls to your help are made varies depending on the
programming language you are using. A collection of free tutorials for programmers is
available on the tutorials page at the EC Software website. These tutorials cover
implementing context-sensitive help and interfacing with the help files generated by Help
& Manual in most common programming languages.
You may also be interested in EC Software Help Suite (EHS), a free package of tools
for interfacing with help for Borland Delphi and Borland C++ programmers. EHS is
particularly useful for implementing all kinds of context-sensitive help and ships with the
full source code. It is available on the Delphi resources page at the EC Software

© 1997 - 2009 by EC Software, all rights reserved

 Reference 797

website, where you can also download a comprehensive free tutorial on integrating help
in Delphi applications.

Your job as the help author

There are a number of things that you need to do as the help author to help make
context-sensitive help work:
Topic IDs and context numbers for the programmers
Your programmers need a way to access the topics in the help. This applies equally to
topics in the main help that bring up the entire help and popup topics that are accessed
individually.
Programs access the topics in HTML Help and Winhelp with the topic IDs and/or the help
context numbers 205 , both of which are stored in the tab of each topic. When you are
planning your help project you need to talk to the programmers and find out which they
want to use, and if they need to use special formats. (Some programming languages
require special formats for topic IDs or specific number ranges for help context numbers.)
Topic ID prefixes: If your programmers require special topic ID prefixes you can
apply these to the IDs of new topics automatically. Just go to
Configuration > Common Properties > Miscellaneous 665
and insert the prefix you want to use in the Topic ID Prefix field.
If you have the Professional version of Help & Manual you can
also use an external editor 456 to add ID prefixes to existing topics
globally throughout your entire project (advanced users only).

Auto-generating Help & Manual can generate and apply help context numbers to
help context new topics automatically. Go to Project > Project Properties
numbers: > Common Properties > Miscellaneous 665 to set up this
feature.

Applying help You can apply help context numbers to existing topics and import
context numbers to "help context map files" with lists of context numbers provided by
existing topics: your programmers. See The Help Context Tool 539 for details.

Changing topic IDs: Don't despair if you discover that you've been using the wrong
topic ID format! You can edit your topic IDs at any time, Help &
Manual updates all internal links automatically. See Topic IDs
and context numbers 205 for details.

Planning your structure for context-sensitive help

Before you start writing you also need to plan the kind of context-sensitive help you are
going to use. For example, if the dialogs in the application are going to have a Help
button you need to have appropriate topics for those buttons to link to from all the
relevant dialogs. This may sound trivial but it's quite easy to forget!
Planning the use of field-level popup topics
Field-level popup topics are exactly the same as popup topics used within your help. The
only difference is that they are accessed directly by the application instead of with a link
from a help topic.

© 1997 - 2009 by EC Software, all rights reserved

 798 Help & Manual 5 - User Help

When they are used in this way they are displayed in their own little window that is closed
after the user has read the contents, without displaying the entire help. They are most
commonly used for What's This? help 790 , but they can also be accessed by buttons etc.
If you are going to use field-level popup topics these require some careful planning.
Among other things, you need a full list of all the controls and other program elements for
which you need field-level popups, along with all the topic IDs and/or help context
numbers that are going to be used to access them.
Auto-generating your field-level popup topics
Since there are generally a lot of these topics creating them manually can be time-
consuming, and you will probably start to wish that you could generate them
automatically. Well, you can!
All you need to do is get a "help context map file" from the programmer with a list of the
topic IDs and help context numbers (if applicable). Once you have this you can
automatically generate all the popup topics in Help & Manual together with the matching
IDs and help context numbers. See Auto-generating field-level popups 375 for details.

See also:
Using Context-Sensitive Help 369
The Help Context Tool 539
Creating popup topics 125
Topic IDs and context numbers 205
Auto-generating field-level popups 375
9.7.3.5 Popups in Winhelp and HTML Help

There are a couple of things you need to bear in mind when editing popup topics because of
the different ways they are handled by HTML Help and Winhelp.
In addition to Winhelp and HTML Help popups are also supported in Windows Exe eBooks.
This format also supports popups with formatted text, graphics and links. However, these
features can all only be used within the eBook. No context-sensitive features are supported.
ePub eBooks do not support popups at all.

Winhelp is not supported by default in Windows Vista:

Support for Winhelp is disabled by default in Microsoft Windows Vista. Even if your
applications run under Vista, any calls to Winhelp help will simply produce an error
message. Support for Winhelp can be added by downloading and installing the Vista
version of the Winhelp viewer from Microsoft but developers are not permitted to
distribute this update with their products. It is also possible that the operating system
support for Winhelp may be removed in the future. We thus strongly recommend that you
start transitioning to an alternative help format as soon as possible. See here for details

Popup topics in Winhelp:

In Winhelp popup topics have all the features of regular topics except that they do not
have a header. In fact, they are regular topics, just without headers. This means that they
can contain formatted text, graphics, tables (note that Winhelp cannot display table grid
lines) and even macros and links.
You can create links both from regular topics to popup topics and from popup topics to

© 1997 - 2009 by EC Software, all rights reserved

 Reference 799

regular topics. Theoretically, you can also create links between popup topics but this is
not recommended it is confusing for users and often fails because of bugs in the
Winhelp viewer.
All the features of Winhelp popups are also supported when they are used as field-level
popups 794 .

Popup topics in HTML Help:

HTML Help's native popup topics are plain-text only. They do not support anything
except plain text. This means that even if you enter formatted text in the popup topics in
the Help & Manual editor (which is possible because it is needed for other output formats)
all formatting, links, graphics, tables, table contents etc. will be stripped when you
compile to HTML Help.
Information for application programmers:
When you export to HTML Help with native, plain-text popups Help & Manual stores the
popup text topics in an internal text file in the HTML Help CHM file. By default this file is
called CSHelp.txt, but you can change this file name in Configuration > Publishing
Options > HTML Help > Popup Topics 667 . When your application calls makes context
calls to plain-text popups you must include this file name in the call.
Formatted JavaScript popups:
Help & Manual also supports a custom JavaScript popup mode that can be used in both
HTML Help and Webhelp. However, you cannot make application calls to JavaScript
popups. See Using JavaScript popups 129 for details.

Controlling the width of popup topics:

In both Winhelp and HTML Help the width of popup windows is controlled by the help
viewer on the basis of the amount of text and the user's screen width. Since this system
was designed a long time ago it does not allow for modern computers with wide-format
screens and multiple monitors. When normal popups are displayed on these computers
the popups can be much too wide, which looks terrible.
There are a couple of simple tricks for solving this problem, which are described in
Creating popup topics 125 in the Basic Procedures section.

See also:
Creating popup topics 125
Using Context-Sensitive Help 369
Using JavaScript popups 129
9.7.3.6 About map files

The compilers for many modern programming languages have facilities for automatically
generating text files called "map files" containing the topic IDs and/or help context numbers
for the components and controls used in the program. These files can save you a lot of work
in Help & Manual.

Generating missing topics and context numbers:

Help & Manual can use these files both to assign missing help context numbers to

© 1997 - 2009 by EC Software, all rights reserved

800 Help & Manual 5 - User Help

existing topics and to automatically generate missing topics with the topic IDs and help
context numbers. This second capability is particularly useful for generating the field-level
popup topics used to document program components controls and controls with the right-
click What's This? function and other similar functions. See Auto-generating field-level
popups 375 and The Help Context Tool 539 for details.

Map file syntax:

By default, these files have a very simple syntax, which can be either #define syntax or
INI syntax. When anchor IDs are used they must follow directly on the associated topic
ID, separated by a # character:
Example of #define syntax:
#define IDH_DEFAULT 100001
#define IDH_OK_BTN 100002
#define IDH_CANCEL_BTN 100003
#define IDH_CLOSE#example 100004
#define IDH_HELP_BTN 100005
#define IDH_APPLY_BTN 100006
#define IDH_APP_HMB 100010
#define IDH_WHAT_IS_THIS_CMD 100011
#define IDH_WHAT_IS_THIS_POPUP 100012

Example of INI syntax:

AboutImage = 10172
AboutIMPICT = 10000
AddingCallout#example = 10236
AddingCursorsandDazzle = 10230
AddingDropShadow = 10167
AddingLensObject#example = 10234
AddingLinesandArrow = 10229
AddingMoreBitmap = 10225

Alternative map file syntax:

When you are exporting map files 539 with the context tool you can also generate your own
alternative syntax using the following variables:
HM_Ref_ContextPop The topic ID of the topic being exported
_MapFiles
<%ANCHORID%> The anchor ID of the anchor being exported
<% The help context number
TOPIC_HELPCONTEXT
%>
Just select the Custom option in the export dialog to configure your own map file with
these variables. You can place any text characters you need between the variables, they
will be exported as-is.

Restrictions of map files:

Using map files to apply help context numbers to existing topics is very straightforward.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 801

However, there are two basic restrictions when you are using map files to generate topics
that do not yet exist in your help project:
You cannot generate topic captions
Since the map file syntax only includes the topic ID and the help context number you
cannot include captions (i.e. the names of the topics in the TOC) for the topics in the map
file and you cannot use the map file to generate captions. All topics generated from map
files use the topic ID as the caption.
You can only generate topics without TOC entries
This second restriction follows from the first. Since auto-generated topics cannot have
captions they are always generated without TOC entries, as topic files in the Topic Files
section of the Project Explorer.
This is generally not a problem since the primary purpose of this function is to auto-
generate field-level popup topics for documenting program components. If you need to
use the function to generate topics in the TOC you must create TOC items 210 for them
manually after importing them.
You cannot assign context numbers to anchors
Help & Manual's context tool can export the information about anchor links to map files
but you cannot import context numbers to existing or new anchors from a map file.

See also:
Auto-generating context-sensitive topics 375
The Help Context Tool 539
Using Context-Sensitive Help 369

9.8 Project Structure & Templates

This section includes some background information about the structure of your projects and
some of the features that are important in help files and Webhelp output. Studying this
section will give you a better understanding of these formats.

9.8.1 Topic IDs, Context Numbers and Keywords

Topic IDs, context numbers and keywords are grouped together in this chapter because
they are all used for locating things in your help files.
Topic IDs and context numbers are used as the "addresses" of topics, both for links within
your help files and for context-sensitive calls to your help file from applications.
Keywords are used for generating index entries, which are also hyperlinks to topics in
electronic help files. In addition to this there are also special keywords called "A-keywords"
can also be used to create other kinds of links, including See Also... links to related topics
and links between different help files.

9.8.1.1 About topic IDs and anchors

Topic IDs:
Every topic in your help project has a unique alphanumeric topic ID, which you can view

© 1997 - 2009 by EC Software, all rights reserved

802 Help & Manual 5 - User Help

by clicking on the topic's tab above the editor pane. The topic ID is required because it is
the unique identifier of each topic. Without the topic ID neither Help & Manual nor any
electronic help system can find the topic.
Topic IDs are used as the "addresses" for accessing topics within your help, both via the
TOC and via hyperlinks. In addition to this they are also used as the addresses for calls
to topics in your help from applications, both on their own and in combination with help
context numbers 803 .
For information on making these calls to different help formats see the documentation of
your programming language and the tutorials for programmers available on the EC
Software website.
Topic ID properties:
Maximum Topic IDs can be up to 256 characters long.
topic ID
length:

Permitted Spaces and a number of special characters like (\ / : * ? # = + % ! @

characters: [ ] > " | , < > & ') are not permitted in topic IDs and Help & Manual will
display a warning message if you try to enter them. In addition to this,
however, it is actually advisable only use a..z, A..Z, 0..9, the underline
character _ and the $ character in topic IDs.
This will ensure that you do not experience problems later, particularly
in HTML-based publishing formats. The HTML filenames in your output
are generated with your top IDs and most browsers can only handle
plain ASCII filenames.

Changing topic IDs:

Help & Manual allows you to edit topic IDs at any time. All internal links within your project
are updated automatically when you do this. However, remember that changing topic IDs
may break links from other projects and calls to the topics from applications.
· For more information see Topic IDs and context numbers 205 .
Topic IDs and HTML output files:
Topic IDs are used for creating the names of the HTML files generated for your topics by
Help & Manual. This is also how they are used as addresses in the HTML-based output
formats – links and calls to them simply access the HTML files containing the topics.
This applies both for the visible files generated in Webhelp and the "internal" files used in
HTML Help (here the HTML topic files are hidden inside the CHM help file, as though
they were inside a directory).
In both cases the file name is created by converting the topic ID to all lower case
characters and adding the file extension. In HTML Help this extension is always .htm. In
Webhelp the default is also .htm but you can change this in Project > Project
Properties > Webhelp > HTML Export Options 684 .

Anchors:
Anchors are named "jump targets" that you can insert in your topics so that you can

© 1997 - 2009 by EC Software, all rights reserved

 Reference 803

create links to specific locations within topics. They can be used both for hyperlinks within
your help project and for calls to your help topics made from application programs.
Anchors are entered with the Anchor Tool in Write > Insert Object. The anchors
stored in each topic are listed in the topic's tab in the Anchor: list. This list always
contains at least one anchor called (Top of Page), which is the standard jump target for
links without anchors.
· For details see Anchors - jump targets 226 .
Maximum Anchor IDs can be up to 256 characters long.
anchor ID
length:

Permitted Spaces and a number of special characters like (\ / : * ? # = + % ! @

characters: [ ] > " | , < > & ') are not permitted in anchor IDs and Help & Manual will
display a warning message if you try to enter them. In addition to this,
however, it is actually advisable only use a..z, A..Z, 0..9, the underline
character _ and the $ character in anchor IDs.
This will ensure that you do not experience problems later, particularly
in HTML-based publishing formats. Most browsers only support plain
ASCII filenames and anchor names.

Where not Links to anchors are not supported in external windows 429 in HTML
supported: Help.

Anchors with context numbers and keywords

Help & Manual allows you to assign both help context numbers and keywords to anchors.
This makes it possible to make help calls to anchors from application programs and to
create index entries that take the user to a specific location in a topic instead of to the top
of the topic containing the keyword.
· For details see Topic IDs and context numbers 205 and Using keywords with anchors 280 .
Syntax for browser links to anchors in topics
You can create ordinary links from web pages to anchors in your Webhelp topic pages.
However, the syntax for these links is slightly different from the standard HTML syntax for
linking to anchors:
index.html?topicname.htm#anchorname
· See Anchors - jump targets 226 for details.

See also:
Topic IDs and context numbers 205
Anchors - jump targets 226
9.8.1.2 About help context numbers

Help context numbers are a second unique numeric identifier for each topic (the first and
main identifier is the topic ID 801 ). Unlike topic IDs context numbers are optional – you can
use them if you want, but you don't have to.

© 1997 - 2009 by EC Software, all rights reserved

804 Help & Manual 5 - User Help

Introduction:
Like topic IDs context numbers can be viewed and edited in the tab of each topic. They
are displayed in the Help Context Number: field. You can enter and edit them there,
but they can also be assigned automatically. See Topic IDs and context numbers 205 for
details.
Help context numbers were introduced with WinhelpNote that Windows Vista does not support
Winhelp. If you want to be compatible with Vista you must transition to a different help format. as the
main way of making application calls to help topics. Many programmers and
programming languages still use them but they have actually become less popular in
recent years. Since they are numeric only they are not very "human-friendly" and it is
quite easy for a programmer to make a call to the wrong help context number and not
notice it.
Most modern programming languages can make calls directly to topic IDs 801 in both
HTML Help and Winhelp without using context numbers at all. Topic IDs are fully
alphanumeric and can be up to 256 characters long, which means that they can
descriptive and easily human-readable.

Help context number range:

Help context numbers are stored as unsigned 4-byte integers. This means you can enter
values between 1 and 4294967295. This gives you nearly 4.3 billion unique numbers,
which should be just about enough for most help projects.

Help formats that use context numbers:

Help context numbers are a Microsoft help technology and are only used for calls from
applications to topics in your help in Winhelp and HTML Help. They are not used for
internal hyperlinks within your help project and are completely irrelevant in all other output
formats. You cannot use context numbers for generating filenames or IDs in Webhelp, for
example.

Context numbers in anchors:

In addition to context numbers in topics Help & Manual also allows you to assign help
context numbers to anchors 226 . This makes it possible to make direct context number
application help calls to defined points within topics instead of just opening the topic at
the top.

Compatibility and call syntax:

Help & Manual's HTML Help and Winhelp output is generated directly by the Microsoft
compilers and is 100% compatible with all HTML Help and Winhelp standards. This also
includes the format and syntax of the help context numbers. If your project contains help
context numbers you can make calls to them with the standard syntax of the Winhelp and
HTML Help APIs.
For details on making calls to help context numbers see the documentation Microsoft
Help Workshop for Winhelp and Microsoft HTML Help Workshop for HTML Help. In
addition to this you can also find some useful tutorials for programmerson the EC
Software website that explain how to interface to Winhelp and HTML Help with range of

© 1997 - 2009 by EC Software, all rights reserved

 Reference 805

common programming languages.

See also:
Topic IDs and context numbers 205
9.8.1.3 About index keywords

Index keywords are a list of words associated with a topic that are used to generate the
keyword indexes in the output formats that support them (all formats except Word RTF).
Keywords are entered and viewed in the Keywords: field of each topic's tab. In addition to
this you can also view and manage the resulting index interactively by right-clicking in the
Index tab in the Table of Contents / Index pane.
· See Keywords and Indexes 273 for details on using these features.

Keywords and sub-keywords:

Keywords can have sub-keywords, which are also described as child keywords. This is a
standard feature of all indexes in both printed and electronic form. For example, an entry
called Indexes might have the following kind of child keywords:
Indexes
about
editing
editing, in teams
organizing
problems

One level of sub-keywords only:

Indexes cannot have more than one level of sub-keywords. This is a restriction of the
output formats, not of Help & Manual. All the supported output formats only have one
level of sub-keywords and Help & Manual is thus also limited to one level.

Choosing relevant keywords:

Producing a good index is not a process that can be automated. It is an art, not a
science, and needs to be done manually. There is simply no alternative to the selection of
individual relevant keywords in each topic by the author. For example, an index including
all occurrences of all the words in your help would be worse than useless, because it
would make it impossible to find anything relevant. You need to examine each topic
individually and make individual decisions whether a word merits being added to the
index or not.
It may be relevant to list every single reference to an author's name, for the sake of
completeness. However, in a help file you will not want to list every single reference to
most subjects. For example, index entries that refer to passing mentions in introductory
chapters will simply waste the user's time. When users click on an index entry they want
to find information that they can use, and that should be the criterion for including a term
in the index.

See also:
Keywords and Indexes 273

© 1997 - 2009 by EC Software, all rights reserved

 806 Help & Manual 5 - User Help

9.8.1.4 About A-Keywords

A-keywords, which are also referred to as "associative keywords" (that's what the A stands
for) or "A-link keywords", are quite a mystery to many help authors. They are actually not as
complicated as many people believe, but they tend to get neglected because most people
believe they are too difficult to understand or use.

Introduction to A-keywords
The following brief list describes the main features and capabilities of A-keywords. First
and foremost it is important to understand that A-keywords are a Microsoft help
technology that is only available in HTML Help and the obsolete Winhelp. Their
functionality is not available in any other output format.
A-keywords are invisible
A-keywords are similar to ordinary index keywords ("K-keywords" or "K-link keywords")
but they are never seen by the user. This might seem strange at first what good is a
keyword that nobody can see? That brings us to the purpose of A-keywords:
A-keywords are used for "associative" linking
A-keywords are not used for indexes, they are used for creating "associative" links. When
an A-keyword is accessed it returns a list of links to all the topics in the help that contain
that keyword. We say that the topics are "associated" with the keyword.
These links are not pre-defined by the help author, they are generated actively when the
user views the help. When the user clicks on a special hyperlink that access an A-
keyword the help viewer searches all the topics in the help to see whether they contain
the keyword, including all topics in external help files in modular help systems 446 .
This makes it possible to use them to generate lists of links to "relevant" topics. To add a
topic to the list you just need to include the relevant A-keyword in its .
A-keywords are "soft" and "conditional"
This means that you don't have to "hard code" links to specific topic addresses. Only links
to topics containing the A-keyword (or keywords) at runtime are displayed. This means
you can create links to topics that may or may not be present when the user views the
help, which usually only happens in modular help systems.
A-keywords have their limitations
All this being said, A-keywords do have their drawbacks. They are extremely useful for
creating links to external help files in modular projects. However, as you will discover
yourself when you try, it is a lot of work to use them to create genuinely meaningful "See
also" lists.
The problem is that the inclusion of a simple keyword is too mechanical to be able to
provide a real basis for relevance in all but the most simple and technical texts. Also,
managing your A-keywords and their relevance is actually much more difficult than simply
deciding yourself which topics are really relevant to the current topic. You will either end
up overwhelming the user with too many links that are not really relevant, or you will miss
the relevant links.

More information about A-keywords

If you are interested in more background information about the technology and uses of A-

© 1997 - 2009 by EC Software, all rights reserved

 Reference 807

keywords the best place to start is the website www.helpware.net. Be warned,

however, that the information provided there will be easiest to understand if you have
experience with developing HTML Help and WinhelpNote that Windows Vista does not support
Winhelp. If you want to be compatible with Vista you must transition to a different help format. files
manually with Microsoft's Help Workshop and HTML Help Workshop!

The main uses of A-keywords

There quite a few technical uses for A-keywords but the main purposes in normal help
files are for automated generation of "See also" lists and for links between separate help
files in modular help systems 446 .
"See also" lists:
You can use A-keywords to create "See Also" links that automatically display link lists of
related topics when the user clicks on them. The list includes all topics found containing
the A-keywords specified in the A-link macro definition. These links work in both
individual help files and modular help systems 446 consisting of multiple help files.
One of the most interesting features of this function is that you don't have to specify
which help files you want to look in. The help viewer will automatically search all available
help files that are part of the modular help system for the A-keyword. This means that it
will automatically include topics from modules that are available from the list and exclude
topics from modules that are not available.
See Using A-Keywords 281 for details on how to make your own "See also" lists.
Links between help modules:
You can also A-keywords to create links between modular help files 446 . The advantage of
this method is that if the target file is not available at runtime the link is not dead. Instead,
the user sees an alternative topic from the current help file. If the target file is available
the user sees a dialog in which he or she can choose the topic from the target file or the
alternative topic.
See Using A-keywords 281 for details on how to make associative links between help
modules.

See also:
Keywords and Indexes 273
Using A-keywords 281
9.8.2 Help Windows
The Microsoft HTML Help and Winhelp formats use sets of definitions referred to as "help
windows" to configure the help viewers used to display these formats. Help window
definitions can also be used to display individual topics in external windows when you link to
them.
Help window definitions are only relevant for HTML Help and Winhelp output. Their settings
are ignored in all other output formats.

Help windows in Help & Manual

In Help & Manual help window definitions are stored with your projects. Each project has
its own set of help window definitions, which you can view, edit and add to in the Project

© 1997 - 2009 by EC Software, all rights reserved

 808 Help & Manual 5 - User Help

Explorer in Configuration > Common Properties > Help Windows.

Secondary windows
By default there is only one help window called Main, which defines the configuration of
the main help viewer for HTML Help and Winhelp.
You can define additional "secondary" help windows are used to display topics in external
help viewer windows when you link to them. You do this by selecting the name of the
secondary window in the Insert Hyperlink dialog, in the Window: field.
This is the only use for secondary windows, they have no other purpose and they are only
relevant in HTML Help and Winhelp.

See also:
Help Windows settings 660
Using help windows 121
External windows and invisible topics 808
9.8.2.1 External windows

In HTML Help and Winhelp you can use additional or "secondary" help window definitions to
display topics in external windows. An external window is a full-featured help viewer window
that is displayed separately from the main help window. In a way external windows are like
popups, but they have all the features of the main help viewer.
External windows are only supported in HTML Help and the obsolete Winhelp and can only
be activated by specifying a secondary help window in the definition of a hyperlink.

External windows in HTML Help

In HTML Help you must activate secondary windows to be able to display external
windows. This is a global setting when you activate it all links to topics specifying a
secondary window will be displayed in external windows. The appearance and features of
the external window are defined by the HTML Help Options settings in Configuration >
Common Properties > Help Windows.
Note that in HTML Help using a secondary window in a hyperlink does not change the
background colors or the topic template, which are controlled by the topic's HTML page
template, 123 not by the help window. The buttons, controls, window position and size from
the secondary help window definition are all used, however.
· To display an external window with different background colors in HTML Help you must
define the topic file itself with an HTML page template that has different background
colors.

External Windows in Winhelp

External Windows in Winhelp work almost the same as in HTML Help, there are just two
differences:
· You do not need to activate external windows in Winhelp. Links to secondary windows
are always opened in external windows in this format.
· In Winhelp the help window definition also controls the background colors of the topic.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 809

This makes it possible to display a normal topic with different background colors by
linking to it with a secondary help window.

Secondary windows cannot be used in the TOC

It is not possible to create topics in the TOC that automatically open in external windows
when you click on them. You can only activate secondary windows by specifying the
window type in a hyperlink definition.

See also:
Help Windows settings 660
Using secondary windows 429
9.8.2.2 Help windows in HTML Help

In HTML Help the Main help window definition defines the buttons and other features of the
main help viewer window. The size and position settings are only used the first time the user
opens the help after that Windows stores the user' settings and uses those the next time
the help is opened.
Secondary help windows can be used in HTML Help to display topics in external windows
with hyperlinks. This is a global setting (see below) if you turn it on all topics associated
with secondary windows will be displayed in external windows.

About help windows in HTML help:

Level of The definition of the Main help window controls the entire appearance
control: of the HTML Help viewer and the controls it contains.
The size and position settings are only used the first time the user
opens the help after that Windows stores the user' settings and uses
those the next time the help is opened.

Secondary Hyperlinks to topics specifying secondary windows can display the topic
windows: in an external window if this feature is activated in the HTML Help
Options in Configuration > Common Properties > Help
Windows.
If this feature is not activated the Window: option in the Insert Hyperlink
dialog will simply be ignored.

Popups: Help window settings are irrelevant for popup topics. Popup topic files
are defined by selecting "Popup" as the Topic Class, either when
defining the topic or in the tab.

See also:
Help Windows settings 660
Using help windows 121
Creating popup topics 125

© 1997 - 2009 by EC Software, all rights reserved

 810 Help & Manual 5 - User Help

9.8.2.3 Help windows in Winhelp

In Winhelp the help window defines the header and topic background colors as well as the
buttons and other features of the help viewer.
Hyperlinks to topics specifying a secondary window in the hyperlink definition always open
the target topic in an external window in Winhelp. If the window definition includes different
background colors they will be used when the topic is displayed.

About help windows in Winhelp:

Level of The definition of the Main help window controls the entire appearance
control: of the Winhelp viewer and the buttons and controls it contains. It also
controls the background colors of the header and topic.
If the defined background colors are different from the background
colors of the Default HTML page template 123 the colors will not be
displayed in the Help & Manual editor, which always displays the HTML
page template colors.

Secondary Hyperlinks to topics specifying secondary windows in the hyperlink

windows: definition always display the target topic in an external window in
Winhelp, using the background colors defined for the secondary
window.

Popups: Help window settings are irrelevant for popup topics. Popup topic files
are defined by selecting "Popup" as the Topic Class, either when
defining the topic or in the tab.

See also:
Help Windows settings 660
Using help windows 121
Creating popup topics 125
9.8.3 HTML Templates
Help & Manual uses editable HTML files referred to as "templates" to define the basic layout
of your topic pages in your published output. There are templates for your topic pages that
are used for all HTML-based output formats and additional templates that are only used for
Webhelp output, which are used to define the overall layout (frameset) and the Table of
Contents, Search and Index panes in the Webhelp help system generated by Help &
Manual.

HTML templates are not help windows!

HTML templates and help windows 807 are completely separate. Help windows are only
relevant in HTML Help (CHM) and Winhelp (HLP) output, where they are used to
configure the help viewer and for opening linked topics in external windows.
HTML page templates can be assigned to individual topics in the tab behind the editor.
Help windows cannot be assigned to individual topics, you can only use them in
hyperlinks.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 811

HTML topic page templates

These templates define the layout and appearance of your topic pages in all HTML-based
output formats, including the background colors of the topic and the topic header.
By default there is one HTML topic page template called Default that is assigned to all
topics. You can edit this template and you can also define as many additional templates
as you like and assign them to individual topics, by selecting them in the HTML Page
Template: field in the tab behind the editor.
The HTML topic page templates can be accessed in Configuration > HTML Page
Templates in the Project Explorer. See Using HTML Templates 430 for more details.

How topic page templates work

If you are familiar with HTML you will know that HTML pages consist of a number of
standard sections. The visible content of the page is stored between the <body> and </
body> tags. The general page definition and any additional functions (for example the
page title, keywords, scripts, search engine information etc.) are stored in the other
sections above and sometimes also below this main body section.
When you publish your project to HTML-based output formats the HTML pages for your
topics are "assembled" from two components: The HTML page template is taken as the
framework and the content from the Help & Manual editor is inserted in this template
between the <body> and </body> tags. Individual content outside the body section is
inserted with variables. (In fact, the content of your topics is also inserted by a variable
called <%TOPIC_TEXT%>, which

Additional Webhelp templates

In addition to the HTML topic page templates there are also four additional HTML
templates that are used to configure your Webhelp output. These templates define the
layout of the entire help (frameset) and the pages for the Table of Contents, Search and
Index panes in your Webhelp output.
These templates can be accessed in Configuration > Publishing Options >
Webhelp in the Project Explorer. Unlike the topic page templates there is only one copy
of each of these Webhelp templates per project, you cannot define additional versions as
you can for HTML topic page templates. However, you can apply different versions to
your output with "skins". See Transforming your Output with Skins 321 for details and
instructions.

See also:
Using HTML Templates 430
Templates in Help & Manual 416
Using help windows 121
9.8.3.1 Graphics in HTML templates

You can reference external graphics in HTML templates, using any graphics types
supported in HTML this is generally JPG, GIF and PNG.

© 1997 - 2009 by EC Software, all rights reserved

812 Help & Manual 5 - User Help

Automatic identification and export of graphics files

Graphics referenced in your templates with <img> tags and with background attributes in
<body> and <table> tags (see below) will be located and exported automatically if
possible:
· Graphics stored in the project directory (i.e. in the same directory as the .hmxz or .
hmxp project file) or in directories listed the project search path 656 will be found and
exported automatically. You do not need to enter path information in your templates for
graphics files stored in these locations.
· Graphics stored in other locations will be found and exported if you include the paths to
the files in your template code. These paths will be stripped from the code
automatically when the project is published.
If you use other tags and/or store the files in one of the above locations you need to add
the files to your Baggage Files. 485 They will then be exported to your published output
automatically, irrespective of where and how they are referenced.
See Graphics references in HTML templates 442 for instructions and more information.

How graphics references in your templates are processed:

When you compile your project to an HTML-based format Help & Manual parses the
template, resolves the file paths to graphics files if specified, copies the file to the
destination output directory and removes any path information from the file references. In
the case of HTML Help and Visual Studio Help / MS Help 2.0 the graphic is automatically
integrated in the output file.
However, the parser only parses the three HTML tags and attributes listed below. No
other image references are processed automatically.

Supported HTML tags:

Graphics referenced using the tags and attributes shown below are identified
automatically by Help & Manual and exported with your project when you compile to
HTML-based output formats. You do not need to do anything yourself to include them in
your project.
If you reference graphics in your templates using other tags you should add them to the
Baggage Files 485 to make sure they are exported with your project. In particular, this also
includes the variant images for mouseover buttons as they are not referenced with the
tags listed below!
You should also add your graphics to the Baggage Files if they are not stored in the
project folder and you do not want to add the paths to the graphics in your template code.
Automatically Supported Attributes
Parsed Tags
<body> Images referenced with the background="" attribute.
OR
Images referenced within the style="" attribute using the syntax

© 1997 - 2009 by EC Software, all rights reserved

 Reference 813

style="background: #FFFFFF url(image.jpg)"

(this can be combined with other style elements, of course)

<img> Images referenced with the src="" attribute

<table> Images referenced with the background="" attribute

OR
Images referenced within the style="" attribute using the syntax
style="background: #FFFFFF url(image.jpg)"
(this can be combined with other style elements, of course)

See also:
Using Baggage Files 485
Using HTML Templates 430
Editing HTML templates 431
Help Windows 807
9.8.3.2 HTML Template Variables

You can use all global predefined variables 774 and user-defined variables 378 in HTML
templates 430 . In addition to this you can also use the following special predefined variables,
which are only relevant in HTML templates.

Variables for use in topic page templates only:

These variables can only be used in topic page templates. They are valid in all HTML-
based output formats (HTML Help, Webhelp, Windows Exe and ePub eBooks and Visual
Studio Help / MS Help 2.0).
Variable Content and/or function of the variable

<%DOCTYPE%> Inserts the correct DOCTYPE tag at the beginning of the

HTML output pages. This variable is essential in all
templates and should not be removed. If you do remove
it you will get an error message from the compiler.

<%DOCCHARSET%> Inserts the correct character set information in the meta

tags at the beginning of the HTML output pages. This
variable is essential in all templates and should not be
removed. If you do remove it you will get an error
message from the compiler.
<%STYLESHEET%> Inserts the reference to the CSS stylesheet containing all
the styles information for your project. This variable is
essential in all templates and should not be removed. If
you do remove it you will get an error message from the
compiler.

© 1997 - 2009 by EC Software, all rights reserved

814 Help & Manual 5 - User Help

Variable Content and/or function of the variable

<%DOCTYPE%> Inserts the correct DOCTYPE tag at the beginning of the

HTML output pages. This variable is essential in all
templates and should not be removed. If you do remove
it you will get an error message from the compiler.

<%TOPIC_HEADER%> Inserts the header of the current topic if it exists. If the

current topic has no header the value of this variable is
null. This can be different from the topic caption inserted
with <%TOPIC_TITLE%>.

<%TOPIC_HEADER_TEXT%> Inserts the header of the current topic as plain text. This
is particularly useful if your project headers are different
from and longer than the TOC captions, which is
inserted with <%TOPIC_TITLE%>.
This is used primarily for search engine optimization, for
which you would insert it in the description meta tag,
like this:
<meta name="description" content="<%
TOPIC_HEADER_TEXT%>">

<%TOPIC_TEXT%> Inserts the body text of a topic, i.e. the entire topic as
edited and formatted in your project in the Help &
Manual editor. This is the most important variable – if
you leave it out your topics will be empty!
<%TOPIC_BREADCRUMBS%> Generates a series of "breadcrumb trail" navigation links
to topics above the current topic in the TOC tree. This
variable is empty in top-level topics. In second-level
topics and below the variable generates a series of links
in the format Link1 > Link2 > Link3 ...
The current topic is not included in the series. If you
want to place the current topic title at the end of the
breadcrumb trail you can do so with the <%TOPIC_TITLE
%> variable (see below).
The breadcrumb trail variable is empty in topics in the
Invisible Topics section.
This variable has a matching condition pair:
<IF_TOPIC_BREADCRUMBS> and
<IFNOT_TOPIC_BREADCRUMBS> . These conditions can
be used to only insert the trail where it is relevant and to
insert alternative content when it is not relevant.
See here 433 for details on how to use this variable.
<%TOPIC_TITLE_PATH%> This variable is similar to the breadcrumbs variable
above but it delivers the breadcrumb trail as a plain text

© 1997 - 2009 by EC Software, all rights reserved

 Reference 815

Variable Content and/or function of the variable

<%DOCTYPE%> Inserts the correct DOCTYPE tag at the beginning of the

HTML output pages. This variable is essential in all
templates and should not be removed. If you do remove
it you will get an error message from the compiler.

string without any links. Unlike the breadcrumbs variable

it also includes the name of the current topic, so it
always delivers a full trail.
The primary use of this variable is for search engine
optimization, for which you would insert it in the <title>
tag of your topic page template instead of the normal <%
TOPIC_TITLE%> variable, like this:
<title><%TOPIC_TITLE_PATH%></title>

Modification for HTML Help:

If you also output to HTML Help you should use
conditional text to ensure that this variable is only used
in Browser Help, otherwise you will get the full path as
the topic name in your search results in the HTML Help
viewer. Do it like this:
<title><IF_HTML><%TOPIC_TITLE_PATH%></
IF_HTML><IF_CHM><%TOPIC_TITLE%></IF_CHM></
title>

<%TOPIC_TITLE%> Topic title (this is the caption of the topic in the TOC).
<%TOPICID%> Returns the plain topic ID as written in the Topic ID:
field of , without any filename extension and without
changing the ID text to lower case. This can be used to
add an ID reference in your meta attributes in your web
pages, for example:
<meta name="id" content="<%TOPICID%>" />
(This variable can also be used in normal topic pages.)
<%TOPIC_KEYWORDS%> Inserts all the keywords 274 of the current topic, comma-
separated. Needless to say, this variable is essential for
the keyword index and shouldn't be removed...
<%TOPIC_AKEYWORDS%> Inserts all the A-keywords 281 of the current topic,
comma-separated.
<%HREF_PREVIOUS_PAGE%> Link address of the previous topic (used for Previous/
Next buttons).
<%HREF_NEXT_PAGE%> Link address of the next topic.
<%HREF_DEFAULT_PAGE%> Link address of the "Default" topic. This is used for the

© 1997 - 2009 by EC Software, all rights reserved

816 Help & Manual 5 - User Help

Variable Content and/or function of the variable

<%DOCTYPE%> Inserts the correct DOCTYPE tag at the beginning of the

HTML output pages. This variable is essential in all
templates and should not be removed. If you do remove
it you will get an error message from the compiler.

standard Top navigation link in the topic headers so that

users can return to the default topic in your project.
<%HREF_PARENT_CHAPTER%> Link address of the parent topic (chapter). This can be
used as an alternative to <%HREF_DEFAULT_PAGE%>.
If the parent is a chapter without text, this is the link
address of the parent's parent. If no valid parent is
available, the variable is the link address of the default
page.
<%HREF_CURRENT_PAGE%> Link address of the current page.

Note on HREF-Variables: All the HREF variables insert the local names of the
corresponding pages within the current directory without
any path information, e.g. topic1name.htm,
topic2name.htm and so on.

Variables for use in Webhelp only:

All the remaining variables are only relevant in Webhelp 730 (HTML):
Global variables for all Webhelp templates:
Variable Content and/or function of the variable

<%HREF_TOP_PAGE%> Link address of the top frame (e.g. "index.html")

<%HREF_CONTENT_PAGE%> Link address of the TOC page

<%HREF_INDEX_PAGE%> Link address of the keyword index-page
<%HREF_SEARCH_PAGE%> Link address of the full-text search page

© 1997 - 2009 by EC Software, all rights reserved

 Reference 817

Variables for the Layout frameset template only:

Variable Content and/or function of the variable

<%HREF_CONTENT_PAGE_DYN% Link address of the dynamic TOC page.

>

<% Link address of the static TOC page.

HREF_CONTENT_PAGE_STATIC
%>

<%NAVIGATION_SCRIPT%> Inserts the navigation script required by the top frame.

Variables for the Table of Contents template only:

Variable Content and/or function of the variable

<%TABLE_OF_CONTENTS%> Inserts the entire TOC in the page.

Variables for the Keyword Index template only:

Variable Content and/or function of the variable

<%KEYWORD_INDEX%> Inserts the entire keyword index in the page.

Variables for the Search template only:

Variable Content and/or function of the variable

<%SEARCH_SCRIPT%> Inserts the full-text search script in the page.

See also:
Using Variables 376
Using HTML Templates 430
Editing HTML templates 431
Help Windows 807
9.8.3.3 HTML Template Output Conditions

You can use all of Help & Manual's standard conditional output options in HTML templates,
both your user-defined include options 406 and options based on the current output format. In
addition to this there are a few special conditional switches which are only for use in Help &
Manual's Webhelp output, because they are only relevant there. See the lists below for
details.
These conditions are like special HTML tags. They are used to enclose blocks of HTML
code in your template that you want to include in the output only if the condition is fulfilled.
In HTML templates you can only use output format conditions for HTML-based output
formats (CHM, HTML, EBOOK and HXS). This is because these templates are only used for
HTML-based output so <IF_PDF> would not have any meaning, for example. Note that the

© 1997 - 2009 by EC Software, all rights reserved

818 Help & Manual 5 - User Help

EBOOK condition applies both for Windows Exe and ePub eBooks.

Conditions are stripped before publishing

All the condition tags are stripped from your code before actually generating the HTML
output. No proprietary tags are included in your output!

Predefined HTML template conditions:

In addition to the predefined conditions listed here you can also use your own user-
defined include options 406 as conditions in HTML templates. See Conditional output in
HTML templates 441 for details on how to use the conditions.
Conditions Function of the condition

<IF_TOPIC_HEADER> True if the current topic has a header and the header is not
empty (the variable <%TOPIC_HEADER%> is not equal to "").

<IF_PREVIOUS_PAGE> True if a previous page exists (the variable <%

HREF_PREVIOUS_PAGE%> is not empty). Used to suppress or
display a grayed-out version of the Previous navigation
button in the very first topic.
<IF_NEXT_PAGE> True if a next page exists. Used to suppress or display a
grayed-out version of the Next button in the very last topic.

<IF_INDEX_PAGE> True if a keyword index is included in the output. Only

relevant for Webhelp.
<IF_SEARCH_PAGE> True of full-text search is included in the output. Only
relevant for Webhelp.
<IF_FRAMES> True if Webhelp is exported with frames (a frame-based
format is selected in the Navigation 676 options). This could
be used for entering a link from topic pages to your TOC
page when you select the No Frames, No Scripts layout
option, for example. Only relevant for Webhelp.
<IF_TOPIC_BREADCRUMBS> True if the <%TOPIC_BREADCRUMBS%> variable is not empty
(see HTML template variables 778 ). For example, this variable
is always empty in topics in the Invisible Topics section and
in top-level topics.
<IF_HTML> True when you generate Webhelp (HTML)
<IF_CHM> True when you generate HTML Help
<IF_HXS> True when you generate Visual Studio Help / MS Help 2.0
<IF_EBOOK> True when you generate e-Books, applies for both Windows
Exe and ePub eBooks

© 1997 - 2009 by EC Software, all rights reserved

 Reference 819

Conditions Function of the condition

<IF_TOPIC_HEADER> True if the current topic has a header and the header is not
empty (the variable <%TOPIC_HEADER%> is not equal to "").

<IF_TOGGLES> True if the current topic contains one or more toggles 350
(expanding text and images).

"IFNOT" versions negate the meaning of the conditions:

Exclude Conditions Function of the exclude condition

<IFNOT_TOPIC_HEADER> Negates the positive version of the condition.

<IFNOT_PREVIOUS_PAGE> Negates the positive version of the condition.

<IFNOT_NEXT_PAGE> Negates the positive version of the condition.

<INOTF_INDEX_PAGE> Negates the positive version of the condition.

<IFNOT_SEARCH_PAGE> Negates the positive version of the condition.

<IFNOT_FRAMES> Negates the positive version of the condition.

<IFNOT_TOPIC_BREADCRUM Negates the positive version of the condition.
BS>

<IFNOT_HTML> Negates the positive version of the condition.

<IFNOT_CHM> Negates the positive version of the condition.

<IFNOT_HXS> Negates the positive version of the condition.

<IFNOT_EBOOK> Negates the positive version of the condition.

<IFNOT_TOGGLES> Negates the positive version of the condition.

See also:
User-defined include options 406
Using HTML Templates 430
Conditional output in HTML templates 441
Help Windows 807

9.9 International Languages and Unicode

Help & Manual's project files are always encoded in Unicode, which means that it can be
used to develop help projects in all languages, including Asian languages and other
languages with more than 255 characters that are supported under Windows.
When you are working with languages requiring Unicode and some other languages
requiring special characters, including Eastern European languages, Greek and Turkish, it is

© 1997 - 2009 by EC Software, all rights reserved

 820 Help & Manual 5 - User Help

important to configure your project correctly to avoid problems in your compiled help files.
In addition to this there are also some important requirements for your Windows
configuration for Unicode-based languages, and you need to be aware of these before you
start work on a project in a language requiring Unicode.
The topics in this chapter provide some useful background information on handling
international languages that should make these issues easier to understand.

See also:
Language Settings 654 (Configuration Options)
International Language Setup 94
9.9.1 About H&M's Unicode support
This topic provides some important background information that will help you to understand
how to use Help & Manual with languages that cannot be edited or displayed properly
without Unicode.
In addition to reading this section please also see International languages setup 94 and
Language Settings 654 for details on configuring your project output in the language you are
using, both with Unicode-based languages and other languages.

Unicode support in Help & Manual's output formats:

Provided the other requirements listed below are met Help & Manual can output projects
written in Unicode-based languages to all its output formats.

Windows versions supporting Unicode:

Help & Manual requires Windows 2000, XP or Vista. You cannot run the program on
Windows 95, 98, ME and NT4 because these versions of Windows do not support
Unicode.

Windows language version requirements:

Although you can edit and compile projects on any language version of Windows that is
properly configured you can only test the compiled Unicode HTML Help or Winhelp
properly on a version of Windows with a matching language.
For example, Chinese Winhelp and HTML Help can only be tested properly on a Chinese
version of Windows. You may be able to display the help, but things like full-text search
and the index will not work correctly.
This means that ideally, a matching language version of Windows 2000, XP or later is
probably required for development of help in Unicode-based languages. You need a
Chinese Windows to develop Chinese help, Thai Windows to develop Thai help and so
on.

Requirements for publishing projects:

The Microsoft help compilers for HTML Help (CHM files) and Winhelp (HLP files) are
quite old and they are not Unicode enabled programs. This means that some special
configuration settings in Windows are required when you are publishing projects using
Unicode-based languages like Chinese or Thai to these formats.

© 1997 - 2009 by EC Software, all rights reserved

 Reference 821

Webhelp, Windows Exe and ePub eBooks, RTF, Visual Studio Help / MS Help 2.0:
You can compile Unicode projects to these formats with any version of Windows 2000,
Windows XP or later provided you have the necessary language support installed to
display and edit the language you are using. Help & Manual itself handles the Unicode
output to Webhelp, eBooks and MS Word RTF, and the MS Help 2.0 compiler is fully
Unicode-compliant.
Winhelp and HTML Help:
The Winhelp and HTML Help compilers are not natively Unicode-enabled. (This is a
restriction of the compilers, not of Help & Manual). To be able to compile a project written
in a Unicode-based language to Winhelp or HTML Help the "system locale" of your
version of Windows 2000, Windows XP or later must be set to match the language you
are using. This is necessary to enable the HTML Help and Winhelp compilers to process
the language correctly for Unicode output.
Changing the system locale
Note that the system locale and the user locale are different! Simply setting the display
and/or data entry language does not change the system locale!
1. Log in to a user account with administrator privileges.
2. Open the Regional and Languages section in the Windows Control Panel.
· Windows 2000: Activate your language in the list of languages at the bottom of
the main tab and then select the same language as the locale at the top of the
same tab.
· Windows XP: Select your language as the default language for non-Unicode
programs in the Advanced tab (this tab is only displayed if you have
administrator privileges!).
· Windows Vista: Select the Change System Locale button in the Administrative
tab (this tab is only displayed if you have administrator privileges!).
3. Click on OK to apply the setting and then restart Windows.

Requirements for viewing Unicode-based help:

Webhelp, eBooks, MS Word RTF:
You can view Unicode help in these formats with any version of Windows 95 or later
provided you have the necessary language support installed to display the language in
question. The browser and word processor used to display Webhelp and RTF must be
Unicode-enabled, of course. The operating system must also be able to run the reader
software for ePub – some readers may not run on very early versions of Windows.
Winhelp and HTML Help:
You can display Unicode in these formats with any version of Windows 95 or later
provided you have the necessary language support installed to display the language you
are using. However, some features of the help, such as the full-text search and index, will
only work properly on Windows versions with a matching language. (Windows 95 and
Windows NT4 must also be updated with MSIE 4 or later and the HTML Help runtime to
be able to display HTML Help, of course.)

© 1997 - 2009 by EC Software, all rights reserved

 822 Help & Manual 5 - User Help

Visual Studio Help / MS Help 2.0:

MS Help 2.0 is only supported on Windows 2000, Windows XP or later. However, it is
fully Unicode-compliant and will display properly with all features on any language version
of these versions of Windows provided they have support installed for the language of
your help file.

See also:
International languages setup 94
Language Settings 654
9.9.2 About project language settings
The language settings for your project in Configuration > Common Properties >
Language Settings control how texts with international languages and character sets are
handled in your output. If you work in English or any other Western European language you
should not need to change the default settings, but in other languages you will need to
adjust the settings to avoid font display problems in your compiled output.

Language of the Help File:

This sets the language code of your project. On its own this setting does not actually
affect how characters are displayed, it only identifies the language to the system and
controls how sorting is handled in the Keyword Index and everywhere else where sorting
is used.
Setting for English and other Western European Languages:
The default setting is English (United States) and if you are using English or any
other Western European language you don't need to change this. In fact, it's better if you
don't because if you do you may experience a known problem in your HTML Help output:
On some users' computers the title bar of your help will sometimes display "HTML Help"
instead of the title of your help project. Setting this option to English (United States)
will prevent this problem.
Setting for other languages:
If you are using languages with special character sets or Unicode character sets like
Eastern European languages, Greek, Turkish, Chinese, Japanese or Thai you must
change this setting to the language you are using. In these languages this setting makes
sure that sorting works correctly. In addition to this it also identifies the language to the
system so that special characters and Unicode processing (if necessary) are handled
correctly for the language.
In addition to this you must also change the Font Character Set setting (see below) to
the correct character set for your language. In these languages both these settings must
set to the correct values for the language you are using for the language to be handled
properly in your output.

Bi-directional Language Mode:

This is used to switch Help & Manual's writing mode to right-to-left for languages like
Hebrew, Arabic and Farsi. The setting makes radical changes to the way Help & Manual
operates, switching the writing direction of the TOC and all text in both the program itself

© 1997 - 2009 by EC Software, all rights reserved

 Reference 823

and all output formats.

Don't change the default setting unless you are using one of these languages! Please
also note that right-to-left languages are only supported in HTML Help, you cannot
publish help in other formats in these languages.

Font character set:

This is the setting that really controls how international characters are displayed on the
user's computer, because it defines the character set containing the characters to be
displayed.
Setting for English and other Western European Languages:
The default setting is ANSI_CHARSET and this character set contains all the characters
required for English and all other Western European languages. If you are using any of
these languages you do not need to change this, and you shouldn't! For example, if you
change it to DEFAULT_CHARSET or any other value you may experience display problems
with special characters in your output.
Setting for other languages:
If you are using languages with special character sets or Unicode character sets like
Eastern European languages, Greek, Turkish, Chinese, Japanese or Thai you must set
the correct character set for the language you are using to ensure that all characters are
handled correctly in your output.
In addition to this you must also change the Language of the Help File setting (see
above) to ensure correct sorting and to identify the language you are using to the system.
In all these languages both these settings must set to the correct values for the language
you are using to be handled properly in your output.

The Default Font setting:

This setting is only relevant for HTML Help and the obsolete Winhelp format. Despite its
rather misleading name, which was chosen by Microsoft, it does not set the default font
for your entire project. It only sets the font for the Table of Contents (TOC) and dialog
boxes displayed in these two Microsoft help formats.
Setting for English and Western European languages
The default setting for this is MS Sans Serif,8,0 and the HTML Help and Winhelp
viewers were originally designed for the size of letters generated by this font at this
setting. It is thus generally advisable to leave the setting as it is for English and Western
European languages. If you do change it you should test your compiled help thoroughly
on as many versions of Windows as you can and with Windows set to both regular and
large fonts to make sure that everything fits.
Languages with special character sets
It may be necessary to choose other fonts for languages with special character sets,
including Eastern European languages, Greek, Turkish and Asian languages. In these
cases you may need to experiment a little until you find a font that produces satisfactory
results.
You should always use a standard font included with Windows in these languages,
however, otherwise the font may not be available on your users' systems when the help is

© 1997 - 2009 by EC Software, all rights reserved

 824 Help & Manual 5 - User Help

displayed.

See also:
Language Settings 654
International Languages Setup 94
9.9.3 Language settings and PDF
There are some additional settings that are relevant for PDF output when you are publishing
Unicode-based languages like Asian languages.

The Reference Printer Driver for PDF

In addition to the language settings in the Project Explorer in Configuration >
Common Properties > Language Settings, which apply to all output formats, font
handling in PDF and printed user manuals is also controlled by the reference printer
driver that is used to generate the PDF output. (Printed manuals are also generated
using PDF.)
Problems with the reference driver used for generating PDF output can also result in
incorrect displays for special characters and international languages. However, if you
experience issues like this first check the language settings of your project to make sure
that everything is set up correctly. If you still have problems in your PDF output after
making sure that your language settings are correct you can try using a different
reference printer driver.
To set the reference printer driver for PDF output go to View > Program Options >
PDF Export. See Program Options - PDF Export 650 for more details.

CID Font Mode

The CID Font Mode option enables more efficient embedding of Unicode fonts in PDF
files, particularly for Asian languages with very large character sets. You can set it in
Configuration > Publishing Options > Adobe PDF > Font Embedding. See CID
font mode for Unicode fonts 332 for more details on this.

See also:
Language Settings 654
Program Options - PDF Export 650
PDF Font Embedding 692

© 1997 - 2009 by EC Software, all rights reserved

Part

X
 826 Help & Manual 5 - User Help

10 Frequently Asked Questions

This section covers some problems that are frequently encountered by users of Help &
Manual. The questions are organized by category and where necessary links are provided to
relevant sections of the help.

10.1 General questions

Which help format is the best?
There is no simple answer to this question. Each of the formats currently supported by
Help & Manual (eight including printed manuals) has its advantages and
disadvantages. For detailed information see Help Formats 725 in the Reference section.

How can I integrate my help files with my application?

Help & Manual creates 100% standards-conform help files. How compiled help files are
integrated with Windows applications depends on the development tool used for
creating the application. You can download a collection of free tutorials for
programmers from our website describing how to integrate Winhelp and HTML Help
with number of leading programming tools:
http://www.ec-software.com/tutorial.htm
Webhelp can be integrated with your application with normal URLs. The syntax is
explained in Application links to Webhelp 234 , along with examples.

Where can I get the Microsoft help compilers for compiling my output?
The free Microsoft help compilers are needed to generate HTML help CHM files and
Winhelp HLP files. These compilers can be freely downloaded from the Microsoft
website.
However, since the compilers are quite hard to find on the Microsoft site and the
locations sometimes change we provide links to most recent versions on our website:
http://www.ec-software.com/reshelp.htm
Visual Studio Help / MS Help 2.0 compiler:
The Visual Studio Help / MS Help 2.0 compiler is part of the Visual Studio Help
Integration Kit (VSIK) which can be downloaded from the Microsoft MSDN website.
However, it is not a stand-alone compiler, it can only be used in combination with the
Visual Studio .NET programming package. You don't need it if you don't have this
package. This format is only used for documenting Visual Studio .NET components. It
is not used for creating normal help for applications and you will not need it unless you
are a Visual Studio .NET programmer.

10.2 Publishing questions

I get a message saying topics have been "implicitly included"!
This is the result of a configuration option that prevents dead hyperlinks in your output.

© 1997 - 2009 by EC Software, all rights reserved

 Frequently Asked Questions 827

When this option is used Help & Manual will automatically include topics referenced by
active hyperlinks even if you exclude them from your output with conditional output
controls.
There are a number of other options and methods for dealing with hyperlinks to
excluded topics. See Preventing dead links 404 for more information on all these options.

I get a message saying hyperlinks in my output have been deleted!

This is the result of a configuration option that prevents dead hyperlinks in your output.
When this option is used Help & Manual will automatically convert active hyperlinks to
excluded topics to plain text.
There are a number of other options and methods for dealing with hyperlinks to
excluded topics. See Preventing dead links 404 for more information on all these options.

I get a message saying the "help compiler" cannot be found!

You need to install the free Microsoft help compilers to be able to publish your project
to the HTML Help (CHM) and Winhelp (HLP) formats. You can download these
compilers from this page on our website:
http://www.ec-software.com/downloads_mscomp.html
After installing the compilers to View > Program Options > Compilers and check
that the paths to the compiler programs are correct.

See also:
Compiling your Output 311
Conditions and Customized Output 399

10.3 Dynamic styles questions

My paragraph style is "stuck", applying a style doesn't seem to change it!
You have probably applied manual formatting to the paragraph. To apply a new style or
reapply the original settings of the current style first select the entire paragraph, then
apply the style. If only part of the text in the paragraph is selected only font attributes
are applied.
Imported formatted text is always initially "manually formatted". You must apply styles
to it to bring it under the control of the Help & Manual styles system. For example, you
can use Create style from selection 161 to define and use new styles on the basis of your
imported formatted text.

I can't reformat a new empty paragraph. Applying a new style doesn't seem
to change anything.
A new paragraph must contain some text before you can apply a style correctly. Enter
some text first, then you will be able to apply the style.

Nothing happens when I apply a style to a list paragraph!

The indentation of bulleted and numbered lists is controlled by the first item in the list.
You can apply styles to the other items but the paragraph attributes will be ignored in

© 1997 - 2009 by EC Software, all rights reserved

 828 Help & Manual 5 - User Help

all items except the first list item. See Formatting lists 193 for more details.

See also:
Text Formatting and Styles 155

10.4 Editing questions

I'm trying to activate paragraph borders but no borders are being
displayed!
You have to select a Border Style option in the Paragraph Border & Background 611
dialog. The default setting is None and this does not display any borders.

Editing has become very slow and my .hmxz project file is much larger than
I expected!
You probably have a large number of image objects embedded in the text. This can
happen when you copy and paste images and text together MS Word. This
automatically inserts the images as embedded OLE objects, which uses up a very
large amount of memory and computer resources. Inserting a large number of large
OLE objects can also have the same effect, particularly on older and slower computers
with limited memory.
To solve this problem you can convert these embedded images into external graphics
files. Just right-click on the embedded images and select Convert Embedded Image in
the popup menu.
Identifying embedded images:
When you click on an embedded image it does not appear as a "negative" image.
Normally-inserted images appear as negatives with all their colors reversed when you
click on them.

I'm having trouble copying paragraphs with the mouse – my copied

paragraph gets "combined" with the next paragraph!
You're probably used to working with a word processor like Word or Open Office. Help
& Manual's editor is a little different from these programs and it stores its paragraph
formatting in a different way. Because of this it's not possible to select the "paragraph
mark" at the end of each paragraph.
The best way to copy paragraphs "cleanly" is to press Enter once in the target location
to create an empty paragraph, then copy to the empty paragraph. After completing the
copy you can then delete any extra paragraphs without losing style information.

I sometimes experience unexpected small changes in indents and spacing

when I change paragraph and other formatting attributes!
Help & Manual calculates all dimensions in pixels internally. If you display your
dimensions in inches or another unit the values are converted from pixels and the
results must often be rounded.
If you want to work with maximum precision choose pixels for all dimensions. You will
get used to it quite quickly and then you won't experience any rounding "surprises".

When I format lists in a single indented paragraph the indent disappears!

© 1997 - 2009 by EC Software, all rights reserved

 Frequently Asked Questions 829

Technically lists need to contain at least two items (paragraphs) because the formatting
of the list is "controlled" by the first paragraph. You can solve this problem by selecting
more than one paragraph or the entire text of a single paragraph before selecting the
bullet or numbering tool in the Toolbar.
Alternatively you can also place the cursor at the very beginning of the paragraph
(before the first paragraph) before selecting the list tool, this will also work.

See also:
Writing and formatting text 132

10.5 HTML and HTML Help questions

My HTML Help CHM file doesn't work on a network drive – I just see error messages
instead of the topic pages!
Windows now imposes severe restrictions on accessing HTML Help CHM files on
networks and the Internet. File links will now generally not work at all and HTML Help
itself is also severely restricted.
Without registry changes on the user's computer HTML Help now cannot be used at all
on networks. EC Software has produced a small free tool called HHReg to help with
this problem, which can be downloaded here:
HHReg CHM Utility
However, it is really better to use Webhelp for help on networks and on the Internet.
These registry changes must be made on every computer that needs to access the
help, and although HHReg can be integrated in your install process opening up these
registry keys on your users' computers does represent a security risk.

I entered tab stops or spaces to create indents but they don't work in any HTML-
based output formats!
Tab stops are unknown in HTML, it simply doesn't support them at all. Spaces also
don't work for indents in HTML because all groups of spaces are ignored and displayed
as a single space. Help & Manual converts multiple spaces to alternating hard and soft
spaces to solve this problem but this will still not be accurate for tabular data.
If you need to create accurate spacing to format code examples use indented
paragraphs (these are converted automatically in HTML-based output formats) or
tables. You can use multiple spaces for indenting in code examples if you turn word
wrap off in the paragraph settings then all spaces will be non-breaking spaces, which
will render correctly.
Also use tables to create tabulated lists in HTML-based output formats.

Search isn't working in my HTML Help CHM output, even though I enabled it in my
project configuration!
This is probably a Microsoft HTML Help Workshop installation problem. To correct this
proceed as follows:
1. Uninstall MS HTML Help Workshop.
2. Download the latest version from our website at http://www.ec-software.com/

© 1997 - 2009 by EC Software, all rights reserved

830 Help & Manual 5 - User Help

reshelp.htm
3. Log on to a Windows account with administrator rights (this is essential!) and install
the new version.

I can't activate search in my Webhelp output!

Full-text search for Webhelp is only supported in the Professional version of Help &
Manual because a royalty-free license for the search indexing tool is required.
When publishing to Webhelp you should also make sure that your user account has full
read-write access permissions to the Help & Manual program directory. Not having
write access here can sometimes cause generation of the search index to fail.

I want to change the Top / Previous / Next navigation texts in the topic headers of
my output!
You can change these texts and also select graphics files to use as buttons instead of
the texts. In the Project Explorer select the Default template in Configuration >
HTML Page Templates to change these texts.
If you want to get more fancy and do things like adding buttons with mouseover effects
you will need to edit the HTML code of the template yourself. See Using HTML
Templates 430 for more information on editing HTML templates.

How can I change the title of the help viewer window?

By default the title bar of the help viewer displays the Project Title entered in
Configuration > Common Properties > Title & Copyright 654 .
This text is inserted in the help window title by inserting the <%TITLE%> variable in the
help window definition. This makes it possible to define different titles to be displayed
when topics are displayed in external windows using different help window definitions:
Go to Configuration > Common Properties > Help Windows 660 . Select the Main
help window type and check the Title bar text: field. If you insert <%TITLE%> here it will
insert the topic title, but you can enter any text you like.
Note that if a different title is assigned to the current help window this has priority over
the Help Title entered in the Title & Copyright 654 section. The help window title will
then be displayed in the help viewer title bar when a topic using the corresponding
window type is displayed.

I entered the title correctly but the help viewer of my CHM file always has the title
"HTML Help"!
This is a bug in the Microsoft HTML Help viewer. Non-English HTML Help files always
display "HTML Help" in the title bar when they are displayed by Windows versions with
a different language from the language of the help file. Only the titles of English help
files are displayed correctly on all language versions of Windows.
The only known solution is to set the Language of the help file in Configuration >
Common Properties > Language Settings to English (United States) if this is
possible for your help project. (This is generally possible for all western European
languages without special character sets.)
See About project language settings 822 for more details.

© 1997 - 2009 by EC Software, all rights reserved

 Frequently Asked Questions 831

The names of my image files are displayed as tooltips in my HTML-based output

formats!
In the Project Explorer go to Configuration > Publishing Options > HTML Help
> HTML Export Options 671 and deselect the option If an image has no caption export
file name as hint (ALT tag).
Note that these are shared options. They can also be accessed in the Webhelp and
Visual Studio Help sections.

The popups in my HTML Help output are only plain text, although I included bold
and other formatting in my popup topics!
By default, HTML Help only supports plain-text popups without any formatting. Help &
Manual provides another solution for formatted popups in HTML Help. See Creating
popup topics 125 for details

Can I view and edit the HTML Help source files?

Help & Manual generates all the files needed for viewing and editing HTML Help
projects with the MS HTML Help Workshop application. However, these files are
normally deleted automatically after publishing.
To prevent this deselect the option Delete temporary files after compilation in the
Publish 590 dialog when you publish your project to HTML Help. You will then find all the
project files in the \~tmpchm folder in your project directory (the directory containing
your project file).

I want to use my own custom icons in the HTML Help TOC!

Help & Manual includes 42 predefined icons that can be used in the HTML Help TOC
by selecting Project > Manage Topics > Change > Icon. These icons are
predefined by HTML Help and they are the only ones that are available. Although the
Microsoft HTML Help Workshop documentation suggests that these default icons can
be replaced by a custom icon strip this feature has never actually worked in HTML
Help. Please complain to Microsoft. Loudly.

My help file fails or crashes if it is installed in a path containing a # character!

This is a restriction of HTML Help that cannot be changed. The # character is reserved
for bookmark (anchor) references from URLs and cannot be used in the paths. The
only solution is to make sure that there are no # characters in the paths to your help
files.

I would like to call a HTML Help CHM file from the command line!

Just execute the hh.exe HTML Help viewer with the name of the help file as the first
parameter:
HH "myhelp.chm"
HH.exe is the HTML Help executable. It is located in the Windows directory does not
require a path.
Examples:
Note that topic names are referenced as Topic ID + .htm in all lower case characters.

© 1997 - 2009 by EC Software, all rights reserved

 832 Help & Manual 5 - User Help

(The standard extension is .htm but this can be changed in Configuration >
Publishing Options > HTML Help > HTML Export Options 671 .)
HH "myhelp.chm::/requestedtopic.htm"
Opens the file myhelp.chm and displays the topic requestedtopic.htm. The "::/" in the
parameter separates the requested topic (the html file name in the internal structure of
the .chm file).
HH "myhelp.chm::/requestedtopic.htm#paragraph2"
Opens the file myhelp.chm and displays the topic requestedtopic.htm and jumps to the
topic anchor paragraph2.
HH -mapid 123456 myhelp.chm
Opens the file myhelp.chm and displays a topic referring to its help context number.

Our programmers need a list of help context numbers!

Select Context Tool in the Tools tab and then select the option Export Map File. This
exports the Topic IDs and corresponding context numbers to a standard map file. See
The Help Context Tool 539 for full instructions.

See also:
HTML Help 727 (Help Formats)

10.6 PDF questions

The formatting of topic headings in my PDFs doesn't match what I see in
the H&M editor!
This is normal. Although all the formatting of your topic content is preserved in PDF
only the text of your topic headers is used in your PDF documents. In PDF the
formatting of your topic headers and the layout of your pages are controlled by the
"print manual template" for your PDF output. See Topic headings in PDF 325 for details.

My PDF files seem to be too big. What could be causing this?

There are a number of possible causes for this:
· Graphics scaling: The first thing to check is the images used in your files. Help &
Manual supports image scaling 242 of high-resolution images for PDF files. If you are
using large images to improve printout quality your files will be bigger and there is not
a lot you can do about it, other than turning off scaling and using smaller images.
· Graphics compression: Check your image compression settings for PDF in
Configuration > Publishing Options > Adobe PDF > PDF Options 691 . You
can significantly reduce the size of your files with JPEG compression but this also
reduces image quality.
· Font embedding: Embedded fonts significantly increase the size of PDF files.
Unless it's absolutely essential only use standard fonts like Arial and Times Roman
so that you don't have to embed fonts. Check your embedding settings in
Configuration > Publishing Options > Adobe PDF > Font Embedding 692 .

© 1997 - 2009 by EC Software, all rights reserved

 Frequently Asked Questions 833

· Graphics in your PDF template: If you insert very large graphics in your PDF
templates 425 this will also increase the size of your PDF. Check all the template
sections for forgotten graphics, including graphics objects whose size has
accidentally been made very small they will still be exported to the PDF!
Note that the nominal image format doesn't affect the size of your PDF files. All
supported formats are converted to bitmaps.

Where are the settings for activating/deactivating PDF pages?

If you are upgrading from Help & Manual 3 you may be looking for the Project
Properties settings that activate and deactivate PDF components (TOC, Introduction
etc.) in your output. This functionality is now only available in the print manual template
330 , which you must edit with the Print Manual Designer 537 . In Help & Manual 3 it was

possible to make these settings in two places (Project Properties and the template),
and this caused conflicts and mistakes for some users.

I configured my template to start chapters on odd pages but all my

chapters are starting on the next available page, no matter whether the
page is odd or even!
Go to Configuration > Publishing Options > Adobe PDF > PDF Layout 690 and
deselect the option Ignore blank pages in PDF file. Setting this option disables the
"Start on odd pages" setting because it makes it impossible to insert blank pages in the
output to force topics to start on odd pages.

Graphics in tables extend beyond the edge of the page in PDF output!
When you place graphics on the page without tables they are automatically resized to
fit on the page in PDF. This is not possible for graphics in tables, however, because
here the table cell and not the page is the container for the graphic. When you insert
graphics in tables you need to make sure that your layout will fit on the page. In
addition to graphics clipping oversized graphics in tables will also switch all column
widths to variable in PDF, which will probably mess up your layout.

The text in my PDF output looks strange or garbled!

Help & Manual uses a printer driver to generate PDF documents and "optimized"
drivers from printer manufacturers sometimes cause output problems.
You can solve this problem by installing a different printer driver and selecting it as the
reference driver for PDF generation. This driver does not have to be for a printer that is
physically connected to your computer. In fact, you will probably achieve the best
results with a standard printer driver from the Windows CD rather than with an
"optimized" driver from a printer manufacturer.
If you are not using WMF or EMF graphics it is generally best to use the screen device
to generate PDFs. A proper printer driver is needed to mange EMF and WMF graphics,
however.
See Customize - PDF Export 650 for details on how to set this up.

I created a PDF with active hyperlinks but the links are invisible!
Go to Configuration > Publishing Options > Adobe PDF > PDF Layout and

© 1997 - 2009 by EC Software, all rights reserved

 834 Help & Manual 5 - User Help

activate the Underline topic links and paint in color: option to define the visibility and
color of the hyperlinks in your PDF document.
For more details see PDF Layout 690 .

My hyperlinks to topics in other projects don't work in PDF!

PDF is really a print-style documentation format that was not originally designed for use
as interactive help. Hyperlinks within PDF files will now work but you cannot link
between PDF files.
You can link to external PDF files with file links, 220 provided the external PDF is in the
same folder as the PDF containing the link, but this will only open the PDF file. You
cannot link to a specific topic inside an external PDF file.

See also:
Adobe PDF 737 (Help Formats)

10.7 Printing questions

The page referrer numbers aren't shown in my print preview!
This is not an error. Page referrers can only be displayed in the actual printout.

The text in my printed manuals looks strange or garbled!

When you print a user manual Help & Manual first generates a PDF file and then prints
it. The PDF is generated using a printer driver and "optimized" drivers from printer
manufacturers can sometimes cause output problems. The printer driver used to
generate the PDF is normally your default printer driver but it is possible to select a
different driver for PDF generation if necessary.
You can generally solve this problem by installing a different printer driver and selecting
it as the reference driver for PDF generation. This driver does not have to be for a
printer that is physically connected to your computer. In fact, you will probably achieve
the best results with a standard printer driver from the Windows CD rather than with an
"optimized" driver from a printer manufacturer.
See Customize - PDF Export 650 for details on how to set this up.

See also:
PDF and Printed Manuals 325
Customize - PDF Export 650

10.8 Searching in Webhelp

How does searching work in Webhelp?
After you compile your Webhelp project the indexer scans all the files found in the
HTML output directory and creates an index file. This index contains a list of all the
words found and their locations in the files in your project.
When the user accesses the search function for the first time the index file is
downloaded by the user's browser. All subsequent searches during the current session

© 1997 - 2009 by EC Software, all rights reserved

 Frequently Asked Questions 835

then access this local copy on the user's computer.

My index includes references to additional files that I added to my output

directory manually! Huh??
It's important to understand that the indexer scans all the files in your output directory!
This means if you add your own files to the directory before you compile they will be
scanned too.
If you don't want your own files to be included in the index you must add them to the
output directory after you compile your project – or upload them to your server
separately so that they cannot be indexed when you compile.

My index includes references to deleted topics! What's happening?

Normally Help & Manual doesn't delete anything in your HTML output directory. Since
every topic is a separate HTML file in Webhelp the files for deleted topics are still in the
output directory when you compile a new version of the project that no longer contains
these topics.
To prevent this it's a good idea to use the Delete all files in output folder function in the
Publish dialog when you compile a build for distribution. See Publishing 313 for more
details on this.

Why can't I search for phrases in Webhelp?

Full-text search uses an index of words found in the project, together with the locations
where the words are found. This means that it is not possible to search for phrases
because the index only knows about the locations of the individual words. Enclosing
words or phrases in quotes searches for exact words (see below).

How can I search for exact words in Webhelp?

Enclosing one or more words in quotes searches for exact words. For example,
entering cat will find cat, catalog and advocate, but entering "cat" with quotes will
only find cat. This also works for groups of words – entering "cat dog fish" will only
find the exact occurrences of all three words.
This can be combined with wildcard characters. For example, "cat*" will find catalog
but not advocate.

See also:
Full-text Search configuration options 680

10.9 Spell check questions

Can I create custom dictionaries for specific projects or subjects?
Yes, as many as you like! You can store your custom dictionaries wherever you like,
including network drives, and multiple users can use them at the same time. See The
Spell Checker 543 for full details on how to create and use custom dictionaries.

I selected "Auto-Correct" for a correction during spell checking but the

auto-correct word pair was not added to the custom dictionary!

© 1997 - 2009 by EC Software, all rights reserved

 836 Help & Manual 5 - User Help

Check which custom dictionary you have activated for adding terms in the current
project in Spelling > Configure Spell Checker in the Project tab. You can use multiple
dictionaries for spell checking but you can only add new terms to one dictionary at a
time.

Where can I get additional dictionaries for the spell checker?

You can download additional dictionaries directly from the spell checker configuration
dialog. Select Spelling > Configure Spell Checker in the Project tab, then click on
Download dictionaries... in the Dictionaries tab.
Note that main dictionaries must be saved in the Dictionaries folder in the Help &
Manual program directory, otherwise Help & Manual will not be able to find them.

See also:
Spell checking 145
Spell Checker 543

10.10 Table questions

The widths of the columns in my tables are different from what I expect
them to be!
You have probably entered contradictory settings for the table and cell/column widths.
When this happens Help & Manual automatically sets the widths of all columns to
dynamic and they then adjust themselves on the basis of their content. You can usually
correct this by setting at least one column with a dynamic width so that you can "lock"
the width of the other columns.
You can turn column width locking on and off with the Lock Column tool in the Table
tab. The tool is highlighted when the cursor is in a column that is locked.

Graphics in tables extend beyond the edge of the page in PDF output!
When you place graphics on the page without tables they are automatically resized to
fit on the page in PDF. This is not possible for graphics in tables, however, because
here the table cell and not the page is the container for the graphic. When you insert
graphics in tables you need to make sure that your layout will fit on the page. In
addition to graphics clipping oversized graphics in tables will also switch all column
widths to variable in PDF, which will probably mess up your layout.

See also:
Working with Tables 253

10.11 User interface questions

There are two copies of my topics – once in the TOC and once in Topic Files!
Actually, there is only one copy of each topic. The Table of Contents is really just a list
of links, like hyperlinks on a web page. The actual topic files are stored in Topic Files in
the Project Files section of the Project Explorer. For convenience the topic files that
TOC entries link to are displayed for editing automatically when you click on the

© 1997 - 2009 by EC Software, all rights reserved

 Frequently Asked Questions 837

entries.

I undocked a Help & Manual window and now I can't dock it again!
You can always redock a window by double-clicking on its title bar (double-clicking also
works for undocking, by the way). In addition to this you can dock or undock any
dockable window by dragging it to the border of the main Editor window. Most windows
can be docked to any side of the editor window.

I'd also like to be able to undock the Topic Options tab!

This is not possible. The Editor window components and tabs are fixed and cannot be
undocked.

See also:
Options & Keyboard Shortcuts 31

10.12 Video questions

My movie is not playing properly in my published output. What can I do?
Check that the correct codec and/or player are installed. Videos can only be played if
the correct player and codec support for them is installed on the computer where your
help is being viewed. So it's a good idea to only use common formats like Flash and
Windows Media that most users will have support installed for.
With some formats and/or browsers you may need to activate the Start Automatically
and Show Controls options in the Insert Movie 625 dialog for the animation or video to
play correctly. Flash videos do not support these external controls if you want player
controls for Flash you must embed them in the video with the program that you use to
create it.

The movie preview function in Insert Movie dialog doesn't seem to be

working!
On some systems you may find that need to be working in a Windows account with full
administrator rights to use the movie preview function. If the function doesn't work and
you know that the correct player is installed try switching to a full administrator
account.

See also:
Flash Animations and Video 269

10.13 Winhelp questions

Hotspots in my graphics don't work in Winhelp!
Graphics with hotspots are no longer supported in the obsolete Winhelp format.
Hotspots in Winhelp graphics can be imported from old Winhelp projects for use in
other publishing formats but you can no longer generate Winhelp files with active
hotspots.

I would like to use browse sequences in my Winhelp files!

© 1997 - 2009 by EC Software, all rights reserved

838 Help & Manual 5 - User Help

Browse sequences are no longer supported. They were actually only relevant in
Winhelp (HTML Help and all other formats do not support browse sequences), which is
now an obsolete format that is only supported backward compatibility. If you are still
using Winhelp you should consider switching to HTML Help (CHM) or Webhelp (HTML)
as soon as possible.

My published Winhelp file doesn't display a Table of Contents!

Winhelp always consists of two files: An .hlp file containing the help topics and a .cnt
file containing the Table of Contents (TOC). You must always distribute both of these
files if you want to have a TOC. If you only distribute the .hlp file the help will be
functional but you will not have a TOC.

The "chapters with text" in my project are empty in the Winhelp output!
The obsolete Winhelp format doesn't support chapters with text. If your project
contains chapters with text they will be exported twice: Once as a chapter without text
and once as a sub-topic of the chapter without text, with the same name as the
chapter. This "duplicate" topic will contain the content of your chapter with text.
If you are publishing both to Winhelp and to formats that support chapters with text you
can use Help & Manual's conditional output features 399 to create alternative topic and
chapter versions for Winhelp and the other formats.

The custom TOC icons I selected aren't displayed in my Winhelp output!

This is one of the many limitations of the obsolete Winhelp format. It does not support
custom icons in the TOC.

Single top-level topics become sub-topics of the next chapter above them in
the TOC!
This is an uncorrected bug in the Microsoft Winhelp format. If a chapter in the TOC is
followed by a single top-level topic the single topic will become a sub-topic of the
chapter above it.
This problem only affects single topics (i.e. topics that are not part of a chapter) that
are top-level topics. Help & Manual automatically applies a fix to correct the problem for
single topics that are not top-level topics. However, there is no solution for the top-level
topics because Microsoft has not corrected the bug in the compiler. The only
workaround is not to use single topics below other chapters in the TOC.

How can I call a Winhelp file directly from the command line?
Just execute the winhlp32.exe Winhelp viewer followed by the name of the help file
you want to open:
winhlp32 "myhelp.hlp"
The viewer program is located in the Windows directory does not require a path.
Command line parameters:
-Kxxxx
Find a keyword (xxxx)
-Nxxxx

© 1997 - 2009 by EC Software, all rights reserved

 Frequently Asked Questions 839

Open a specific topic using the help context number (xxxx)

-Ixxxx
Open a specific topic using the topic ID (nnnn)
-H
Run Winhelp and open Winhelp.hlp (help on help)
Examples:
winhelp32 -N23678 "myhelp.hlp"
Opens the file myhelp.hlp and displays the topic with the context number 23678.
winhelp32 -Iintroduction "myhelp.hlp"
Opens the file myhelp.hlp and displays the topic with the ID introduction.

Our programmers need a list of help context numbers!

Select Context Tool in the Tools tab and then select the option Export Map File. This
exports the Topic IDs and corresponding context numbers to a standard map file. See
The Help Context Tool 539 for full instructions.

Winhelp is not supported by default in Windows Vista:

Support for Winhelp is disabled by default in Microsoft Windows Vista. Even if your
applications run under Vista, any calls to Winhelp help will simply produce an error
message. Support for Winhelp can be added by downloading and installing the Vista
version of the Winhelp viewer from Microsoft but developers are not permitted to
distribute this update with their products. It is also possible that the operating system
support for Winhelp may be removed in the future. We thus strongly recommend that you
start transitioning to an alternative help format as soon as possible. See here for details

See also:
Winhelp 740 (Help Formats)

© 1997 - 2009 by EC Software, all rights reserved

 840 Help & Manual 5 - User Help

Accessibility 743

Index Across 521

adding material to on every page 433
addresses 39
Adobe PDF
-#- about 325, 737
CID font mode 94, 332, 692
#MERGE command for importing HTML files 107
clipped graphics 650
configuring Adobe PDF output 301
-.- font embedding 301
font embedding settings in Project Configuration
.dfm files 94, 692
eBook templates 429 generating 326
.hhp file for HTML Help including/excluding pages 301, 326, 330, 425
options for modifying 670 layout settings in Project Configuration 690
.hmskin files 75 max. TOC levels 326
.hmxp save mode 85 no graphics 650
.hmxz save mode 85 page referrers 575, 690
.hmxz~~ backup files 643 Print Manual Designer 537
printer driver required for 301
.hpj file for Winhelp
pros and cons 737
options for modifying 703
reference driver for 650
.hxs files
settings 326
namespace 491
settings in Project Configuration 690, 691
registration requirement 491
template variables 784
unique identifier 491
templates for 425, 537
.ini files
templates, location 330
for command line options 480
templates, using 330
.ipp files
topic headings in 325
hotspots in old .ipp files 238, 246
Unicode now supported 824
.skin files
video files support 756
eBook templates 429
videos and animations 272
.xls stylesheet files 75
Adobe PDF problems
.xsd schema file 75 can't output 832
files too big 832
-[- garbled output 832
heading formatting doesn't match project 832
[****] links 225 including/excluding pages 832
invisible hyperlinks 832
odd/even page problems 832
-<- A-keywords
about 806
<!--ZOOMRESTART--> 300
automated "See Also" lists 236, 281
<!--ZOOMSTOP--> 300 find and replace 280
in HLP and CHM only 236, 281
-A- linking between help modules 236, 281, 459
not supported in embedded topics 149
about Help & Manual 16 not translatable in XML 528
accelerator keys 31 uses and limitations 806

© 1997 - 2009 by EC Software, all rights reserved

 Index 841

ALink() macro
translation in HTML Help 223, 761
A-Links for links between modules 79 -B-
anchors background and borders (dialog reference) 611
about 801
background colors 93
assigning help context numbers to 205
backups
cannot import context numbers to 539
.hmxz~~ backup files 643
cannot search keywords in 280
automatic 83, 643
context numbers in 803
Baggage files
dead anchors 226
about 485, 486
do not edit 226
alternative to Extended .HHP settings 670
embedded topics 215
avoiding duplicates 488
hyperlinks to 71
defined 25
in browser-based HTML 226
graphics files, HTML template references 442
in embedded topics 215
include options with 488
Insert dialog (dialog reference) 627
integrating external files 231, 486
inserting 226
non-graphics files 486
linking to 226
removing and exporting 487
linking to anchors in 215
renaming 487
linking to in topics 215
restrictions and handling 488
linking to in Webhelp 229, 801
size of 488
maximum length 801
supported file formats 488
permitted characters 801
Baggage Files section 25
syntax for calling 801
batch files
using keywords with 226, 275, 280
for command line options 480
animations and videos 837
blanks for indents 172, 195
Insert dialog (dialog reference) 625
movie preview function not working 837 BMP images 238
videos not playing properly 837 BODY section of HTML template
Application Button 24 adding HTML code outside of 762
Application Menu BOM, switch off for PHP 671, 684, 697
Print Manual (dialog reference) 575 Bookmark 590
print preview (dialog reference) 577 bookmarks 593
Version Control System 578 bookmarks and comments
archive bit folder synching for FTP 671, 684, 697 inserting, using and editing 143
Asian languages borders
requiring Unicode 820 in tables 268
test-publishing on non-Asian Windows 94, 313 no paragraph borders displayed 828
tolerant option for compiling 649 borders and background (dialog reference) 611
associative linking breadcrumb trail navigation 778
and A-keywords 806 example and how-to 433
auto-correct function 546, 548 browse sequences
dictionary 145 not supported 837
spell checker 145 build conditions 785
automatic numbering 391 conditional text 410
autosize tables 254 defined 400
defining user conditions 406
for topic entries 787
for topic files 787

© 1997 - 2009 by EC Software, all rights reserved

 842 Help & Manual 5 - User Help

build conditions, defining 78 checklist for publication 312

build options child projects 764
about 400 copying 454
filer TOC with 585 second copies 454
filtering in the TOC 402 CHM files
filtering TOC with 211 settings for importing 105
for topics without TOC entries 112 CID font mode for PDF 94, 332, 824
format-based 400 class (topic class) 581
insert dialog (dialog reference) 628 Clipboard functions 579, 601
logic 402 Close() macro
modular project build options 412 translation in HTML Help 223, 761
OR logic 400 Code Example style 717
topic build options 407 Collapse All
user-defined 400 code to collapse TOC in Webhelp 437
using 402 collections (Webhelp projects) 464
bulleted lists column width and height 723
adjusting indents 193
column widths (tables)
changing 180
controlling 256
changing bullet color 193
locking/unlocking 256
creating 180
preferred width 256
customizing 180
setting 256
styles in 193
troubleshooting 256
bullets and numbering (dialog reference) 612
columns (tables)
adding/deleting 259
-C- formatting 258
resizing 258
captions (TOC) selecting 258
spell checking 145 widths 254
captions for graphics 239 command line options
formatting 176 about 466
style of 176 and include options (conditional output) 475
cells (tables) applying skins 321, 478
borders 268 INI and batch files 480
deleting contents 261 multiple-format output 476
formatting 258 publishing directly from your application 485
merging/unmerging 260 redefining variables 394, 478
resizing 258 syntax reference 466
selecting 258 using 473
splitting 260 Comment style 717
centering tables 262 comments
change icon 585 formatting 176
chapters Insert dialog (dialog reference) 633
moving, cutting and pasting 199 style of 176
chapters with text comments and bookmarks
not supported in Winhelp 110, 837 inserting, using and editing 143
check for update 652 common HTML settings 667, 674, 706
Check In 588 compilers
Check Out 588 help compilers not found 826

© 1997 - 2009 by EC Software, all rights reserved

 Index 843

compilers for Microsoft help formats multiple context numbers per topic 205
compiler messages settings 649 required for CHM popups 125
options 649 value range 205
setting locations 649 Context Tool 600
where to get help compilers 311, 826 context-sensitive help
compile-time merging 461, 767 about 369, 788
compiling vs. publishing 288 about implementing 796
complex search and replace 154 and Webhelp 234, 373
compressed single-file mode 85 application calls and 372
conditional output auto-generating topics for 375
about 772, 785 creating topics for 370
and command line options 475 dual-mode HTML Help not supported 370
build conditions 785 field-level popups 234, 370, 373, 792, 796
conditions for HTML templates 782 in supported output formats 369
explained 400 popup topics for 370
find referrers 402 popups and 792
HTML template conditions 415 technologies for in Windows 789
in HTML templates 810 tutorials and tools for programmers 372, 796
include options 785 converter
links and 785 command line syntax 471
logic 402 converting old H&M projects 51, 87, 550
redefining variables for 414 converting styles 718
topic entry include options 787 converting tables to text 262
topic file include options 787 converting text to tables 262
tutorials 78 converting to plain text 143
using, general instructions 402 copy and paste 43
conditional text 785 between projects 102
insert dialog (dialog reference) 628 copying, cutting and pasting 579, 601
conditional text include options from Word 58
setting and editing 410 text and other content 139
Configuration unformatted text 139
and multi-user editing 518 without style information 139
setting color for read-only topics 518, 647 copyright notice 91
Configuration settings counter variables for numbering 391
variables in 388 creating hyperlinks 71
contact support - email link 652 creating new topics 56
content templates for new topics 110 creating projects (tutorial) 54
context numbers CSS styles 355, 357, 361
and anchors 205 custom builds
assigning automatically 205 settings in Project Configuration 658
assigning manually 205 custom code in HTML templates
auto-generating 205 transferring from .HM3 projects 87, 550
changing globally 456 custom user dictionaries
editing 205 multiple languages 145
finding 141, 290 spell checker 145
generating list 829, 837 customizing Help & Manual 31
Help Context Tool 600 automatic backups 643
in modular projects 456 compiler location settings 649
listing 534
© 1997 - 2009 by EC Software, all rights reserved
 844 Help & Manual 5 - User Help

customizing Help & Manual 31

editor customizing options 647
keyboard shortcuts 646 -E-
mouseover hints 643
eBooks
PDF reference driver 650
functionality settings in Project Configuration
Ribbon Toolbar 645 708
shortcuts 646 layout settings in Project Configuration 706
Tools menu 643 popup topics in 125
cut and paste settings in Project Configuration 706
from Word and Excel 139 support for videos and animations 272
inserting graphics with 239 template files 75
inserting text with 139 templates for 429
cutting and pasting topics 63 video files support 756
Windows and ePub eBooks 304

-D- Windows eBooks, configuring 304

eBooks, ePub
dead link highlighting 289 about 732
dead links 288 configuring output 305
dead links, preventing 404 hardware readers 309, 733
pros and cons 732
default font (language settings) 94
publishing 313
default topic 91
resources 309, 733
deleting TOC entries and topics 201
restrictions and requirements 305
demote/promote topics in the TOC 589
software readers 309, 733
dialog icons 24
source files for manual editing 305
dictionaries for spell checker
eBooks, Windows Exe
auto-correct function 145, 546
about 735
custom project dictionaries 546
CD ROM catalogs 735
custom user dictionaries 546, 548
configuring output 304
downloading 145
field-level popups 735
excluded words 546
kiosk applications 735
multi-user use 546
popups in 709
selecting and downloading 543
pros and cons 735
displaying next to Editor 46
EC Software contact information 39
distribution files (output formats) 319
Edit menu
do not contain formatting 135 Find and Replace 602
docking and undocking program windows 836
editable variables 395
Drag & Drop in HTML templates 439
creating hyperlinks with 215
editing topics 58
creating topics with 110
editor
disable in TOC 585
change font for 647
duplicate graphics filenames 249, 456 customizing 647
dynamic styles editing is slow, oversized .HMX projects 828
quick guide to using 157 navigating in 132
dynamic styles (see styles) 711 paragraph copying problems 828
protect text against changes 132
sections 29
selecting text in 138
using 132
© 1997 - 2009 by EC Software, all rights reserved
 Index 845

ELSE condition updating old expanding sections 366

and text include options 410 expanding text and images, troubleshooting
and topic include options 407 large output files 365
not supported in HTML templates 441 output file size 365
embedded graphics page breaks in PDFs and printed manuals 365
identifying 755 problems with expanding section toggles 365
embedding files in PDFs 220, 332 problems with formatting in toggle links 365
EMF images 238, 753 problems with IDs 365
Excel Explorer
copying from and to 139 folders 211
excluded topics managing Topic Files 211
export if referenced (option) 649 exporting
remove dead links (option) 649 topics as XML files 204
excluding topics and content 78 Extended .HHP Settings 670
ExecFile() macro file references in 231
no longer needed in HTML Help 223 external data
Expand All importing into projects and topics 100
code for expanding Webhelp TOC 437 external files
expanding image toggles integrating in projects 486
converting existing images 357 referencing in HTML code 231, 486
creating 357 external windows
formatting with CSS 357 and hyperlinks 231
expanding inline text toggles and invisible topics 808
creating 355 displaying topics in 121
formatting text and links 355 how to display topics in 429
expanding section toggles in HTML Help 809
creating 351 in modular projects 808
editing 351 in Winhelp 810
embedded topics in 351 opening topics in 231
existing tables with IDs 351 restrictions in modular projects 459
formatting headers 351
icons, swapping 351
icons, using in 351
-F-
indents in 351 F1 context help 789
nesting 351 FAQ for upgraders 18
supported content 351 field-level popups 125, 129, 234, 294, 369, 370,
expanding sections 373, 667, 727, 788, 792, 794, 796, 798
nesting 350 about 794
expanding text and images and map files 799
copying 359 in HTML Help 794
copying and editing 360 in Winhelp 794
CSS styles for links 361 file links
duplicate ID conflicts 360 compatibility in output formats 220
examples 350 creating 220
Expand All / Collapse All functions 363 linking to specific pages in PDFs 220
IDs 359 using in hotspots in graphics 246
Print button with Expand All 363 file size
support in output formats 350 smaller with styles 711
troubleshooting 365
© 1997 - 2009 by EC Software, all rights reserved
 846 Help & Manual 5 - User Help

files formatting
excluding from full-text search in Webhelp 300 replacing, about 497
filter TOC by build options searching and replacing, about 498
filter TOC 585 formatting text 58
Find and Replace frames in Webhelp 674
Edit menu 602 frequently-used graphics
font styles 498, 500, 503 creating shortcuts to 251
formatting 498 FTP
graphics 249 archive bit mode for folder synching 671, 684,
images 141, 290 697
in TOC and Invisible Topics 141, 290 Second Copy folder synching program 671,
multi-user editing 518 684, 697
paragraph styles 498, 507, 510 full text search template 810
referrers 141, 290 full-text search
styles 828 excluding files from search index in Webhelp
text 141, 290 300
topics 141, 290 excluding page sections from search index in
Webhelp 300
variables 392
HTML template for Webhelp 438
Find Referrers 402, 404
in Webhelp 731
Topics menu 586
issues in Webhelp 313
F-Index 694
language files for other languages 75
Firefox
not working in HTML Help 829
underlined TOC entries, suppressing 77
settings for Webhelp 680
firewalls special settings for in Webhelp 300
and update checking function 643 template for in Webhelp 300
Flash files 269, 789 full-text search in Webhelp 296
editing HTML code for 271 deleting output folder before publishing 834
in eBooks 756 searching for exact words 834
in output formats 756 searching for phrases not possible 834
inserting in topics 269
font character set (language settings) 94
font size preview 132
changing 58, 132
-G-
font styles Get Latest VCS Version 588
searching and replacing 498, 500, 503 getting help for Help & Manual 37
fonts ghost links 225
change font for XML and HTML editors 647 GIF images 238, 753
CID font mode 692 global predefined variables 774
different in print and help file 175 global variables
embedding in PDF files 692 name syntax 381
Format Font (dialog reference) 606 plain text only 381
formatting tools 155 where supported 381
footers and headers graphics
creating in topics (HTML only) 433 about 753
in HTML pages 123 aligning 241
Format Font (dialog reference) 606 as table background 267
Format menu 604 caption style 717
Syntax Highlighting 607 captions, adding and formatting 239
converting to expanding image toggles 357

© 1997 - 2009 by EC Software, all rights reserved

 Index 847

graphics project search path 656

creating shortcuts to 251 setting locations for 656
duplicate filenames 249, 456 group work
editing 242 with modular projects 764
editing and resizing 242
embedded 755
exporting text in as XML 528 -H-
finding and replacing 249
hanging indents
folders for 249
and tab stops 722
formats and file size 753
restrictions 172
frequently-used 251
using 172
hi-res for PDF and printing 242
hard page breaks
hotspots, macros and scripts in 246
inserting 143
Image Shortcuts for frequently-used graphics
251 hard spaces 722
in HTML templates 811 HEAD section of HTML template
in modular projects 249, 456 adding HTML code and scripts to 762
Insert dialog 622 header
inserting 67 adding material to on every page 433
inserting from files 239 additional content in 119, 136
inserting in topics 239 changing background color 119, 136
inserting with cut and paste 67, 239 formatting 119, 136
listing 534 in electronic help formats 119, 136
managing 249 in PDF, RTF and printed manuals 119, 136
missing 288 turning on and off 119, 136
missing and unused, finding 534 headers and footers
moving and renaming 249 creating in topics (HTML only) 433
opening in Impict graphics editor 244 in HTML pages 123
pasting from Word 67, 755 Heading1 style 717
positioning 241 Help & Manual
project search path 249 about 16
recently-used images, reinserting 251 buying 39
referencing in HTML templates 442 customizing 643
replacing manually 249 getting help 37
resizing increases output size 242 Quick Start Tutorials 41
selecting 138 support address 37
setting default editor 596, 643 tutorials 37
supported formats 238 user interface 23
testing for missing graphics 289 why Help & Manual? 16
translating text in 525, 528 Help & Manual 3 projects
updating for translations 525 converting 87, 550
using 238 custom HTML code in 87, 550
using as hyperlinks 245 invisible topic conversion 550
zoom factor 239, 242 style conversion 87, 550
graphics editor table conversion 87, 550
Impict 536 Help & Manual 4 differences 18, 568
setting default editor 536, 596, 643 Help & Manual 4 projects
using 536 converting 87
graphics folders Help & Manual 5, differences from HM4 18, 568

© 1997 - 2009 by EC Software, all rights reserved

 848 Help & Manual 5 - User Help

Help & Manual help Webhelp 730

using as a template for your projects 417 Winhelp 740
Help & Manual help source code 81 Help menu
Help 2.0 738 reference 652
setting compiler location 649 help project
Help buttons 789 language and character set 94
help compilers 311 help title 91
compiler messages settings 649 help viewers
not found 826 background colors 93
options 649 changing appearance of 121
setting locations 649 defining appearance of 93
where to get 826 for different output formats 121
help context numbers help window title in HTML Help 829
about 803 help windows
and anchors 205 about 807
assigning automatically 205 and output formats 292
assigning manually 205 changing for topic 121
auto-generating 205, 665 choosing (basic setup) 121
auto-generating topics with 539 creating, deleting and editing 121
cannot import to anchors 539 external 231
changing globally 456 in HTML Help 809
context numbers 539 not linked to HTML templates 810
exporting and importing 539 secondary windows 231
generating list 829, 837 secondary windows, using 429
help formats 803 setting title 91
multiple context numbers per topic 205 settings in Project Configuration 660, 661, 663
output format compatibility 803 types 292
preventing duplicates in modular projects 456 Winhelp 810
reassigning and deleting multiple 539 Winhelp options 663
settings in Project Configuration 665 HLP files
supported range 539, 803 settings for importing 105
value range 205 HM3 IPP graphics with hotspots 238
Help Context Tool 600 HM3 projects
using 539 converting 87, 550
help files custom HTML code in 87, 550
integrating with applications 826 invisible topic conversion 550
TOC link to 115 style conversion 87, 550
help for Help & Manual 37 table conversion 87, 550
help formats HMXP 85
about 725 HMXZ 85
Adobe PDF 737 converting for version control systems 339
eBooks, ePub 732 horizontal lines
eBooks, Windows exe 735 inserting 143
HTML Help 727 hotkeys
Longhorn Help 743 for styles 161, 169
MS Word RTF 739 Hotspot editor (dialog reference) 624
printed manuals 738 hotspots
Vista Help 743 aligning 246
Visual Studio Help/Help 2.0 738 compatibility in output formats 246
© 1997 - 2009 by EC Software, all rights reserved
 Index 849

hotspots field-level popups in 794

in old .ipp and .SHG files 238, 246 help window title issues 829
inserting in graphics 246 help windows 808
linking to popup topics 246 help windows in 809
not supported in Winhelp 246, 837 HTML page templates 666
HTML JavaScript popups 798
appearance in different browsers 296 keep on top 661
configuring Webhelp output 296 links to external windows across modules 459
expand Webhelp automatically on open 296 merge options for modules 451
output format for lists 194, 671, 684, 697 modular help settings 670
single-click option for Webhelp navigation 296 navigation links in header 829
timestamp of HTML topic files 671, 684 popup topics in 125, 798
HTML (Webhelp) 730 popup topics settings 667
HTML code project files 728
about using 758 pros and cons 727
for inserting videos 271 referencing external files in 670
inserting in topics 231 restrictions on network drives 727, 829
saving to and loading from files 231 search not working 829
HTML code object secondary windows 808
Insert dialog (dialog reference) 632 setting compiler location 649
HTML code objects settings in Project Configuration 667
about 762 support for modular projects 447
and HTML variables 762 support for videos and animations 272
inserting in topics 231 temporary files 728
inserting outside <body> tags 762 TOC behavior, configuring 294
limitations in eBooks 762 users get error message 829
referencing script functions in 762 vido files support 756
saving to and loading from files 231 HTML Help options 661
variables in 388 HTML page templates
where supported 762 background colors 123
HTML Export Options 671, 684, 697 headers and footers 123
HTML files HTML editing mode 666
importing into individual topics 100 navigation links 123
importing to topics 204 setting for individual topics 123
merging into existing topics 107 simple editing mode 666
settings for importing 105 HTML templates
HTML Help about 427, 431, 810
about 727 and Baggage graphics 442
anchor keyword display in 280 conditional output in 441
calling from command line 829 defined 416
compiler 311 editable variables in 439
configuring output 294 editing 431
context-sensitive help 369 ELSE condition 441
crashes 829 for topic pages 433
custom TOC icons 829 graphics in 811
editing source files 829 HTML page templates 666
Extended .HHP settings 670 in HTML Help 809
external windows 808 in Winhelp 810
field-level popups 798 include options in 415

© 1997 - 2009 by EC Software, all rights reserved

 850 Help & Manual 5 - User Help

HTML templates to popup topics 125

Index template for Webhelp 438 topic links 215
Layout template 437 types supported 214
output conditions (reference) 782
referencing external files in 444
referencing graphics in 442 -I-
Search template for Webhelp 438
icon
TOC template for Webhelp 437
change icon 585
troubleshooting 445
IDs
variables and 810
assigning and choosing 205
variables in 388, 393, 439
internal numerical IDs (Project Synch) 565
variables in (reference) 778
prefixes for topic IDs 205
HTML topic page templates
image captions
defined 416
entering 239
HTML variables 395
formatting 176, 239
defining 378
standard style for 167, 176, 717
how they work 378
variables in 388
managing 657
image editor
search engine optimization 395
selecting default 596
settings in Project Configuration 657
image folders
using with HTML code objects 762
managing 249
where supported 377
moving and renaming 249
HXS files
project search path 656
namespace 491
setting locations for 656
registration requirement 491
Image Shortcuts
unique identifier 491
for frequently-used graphics 251
hyperlinks
images
[****] links 225
converting to expanding image toggles 357
and external windows 231
creating shortcuts to 251
and secondary windows 231
exporting text in as XML 528
captions 225
frequently-used 251
converting to normal text 225
Image Shortcuts for frequently-used graphics
creating 71
251
editing and formatting 225
recently-used images, reinserting 251
file links 220
translating text in 528
ghost links 225
images (see graphics)
graphics as hyperlinks 245
supported formats 238
Insert dialog (dialog reference) 617
using 238
Internet links 218
Impict
linking to pages in PDF 220
screen capture tool in 244
macro links 223
Impict graphics editor
preventing dead links 404
editable objects 244
script links 223
exporting text for translation 244
selecting 138
output file larger after resizing 242
testing for dead hyperlinks 289
resizing images with 242
to anchors 71, 226
using 244
to anchors in snippets 226
Impict screenshot editor
to browser-based HTML 229
using 536
to other projects and help files 229

© 1997 - 2009 by EC Software, all rights reserved

 Index 851

implicitly included topics 826 problems when adjusting 828

imported text problems with lists 193, 828
globally applying styles to 498 restrictions 172
globally applying styles to, example 513 unexpected changes 828
importing external data 99 using 172
external HTML files (#MERGE) 107 index
globally applying styles to imported text 498 anchors and 273
into existing projects 55 editing 273
into new projects 55 editing directly 275
settings for importing 105 HTML template for Webhelp 438
styles from other projects 161, 169 letter links in Webhelp 284
topics from external files 204 section header separators in 284
include conditions index keywords
defined 400 about 805
include options adding 274
about 400 duplicates and variants 274
and modular projects 412 editing 274
and publishing 313, 407, 410, 412 entry format 274
conditional text 410 in popups 274
defining user options 406 in topics without TOC entries 274
editing 407, 410, 412 red underline 274
exclude all a topic's subtopics 407 sub-entry levels 274
filter TOC with 585 sub-keywords 805
filtering in the TOC 402 index separators for Webhelp 679
for Baggage files 488 Index template 810
for topic entries 787 Index Tool 275
for topic files 787 Index Tool (dialog reference) 598
for topics without TOC entries 112 inheritance
format-based 400, 785 in styles 713, 714
in command lines 475 inheritance trees 714
in HTML templates 441 stopping 714
insert dialog (dialog reference) 628 style families 720
logic 402 INI files
nesting 410 for command line options 480
OR logic 400 inline HTML code (HTML code objects) 762
settings in Project Configuration (custom builds) inserting in topics 231
658 saving to and loading from files 231
topic include options 407
Insert / Insert Object (reference) 615
user-defined 400, 785
Insert Movie (dialog reference) 625
using 402
inserting graphics 67
indent tool
inserting tables 69
error message in lists 193
Interactive wizards 789
indenting tables 262
international languages
indents
about 819
and tab stops 722
and PDF 824
cannot indent lists 172
CID font mode for PDF 94
hanging indents 722
configuration settings for 94
how exported 722
project settings 822
leading spaces 172, 195
requiring Unicode 820
© 1997 - 2009 by EC Software, all rights reserved
 852 Help & Manual 5 - User Help

international languages A-keywords 236, 281

Unicode mode in Windows 2000 and XP 822 checking 288
Internet Explorer deleting 275
turning off yellow warning bar in Webhelp 313 duplicates and variants 274
Internet links editing 274, 275
compatibility in output formats 218 entry format 274
creating 218 find and replace 280, 292
creating automatically 218 in embedded topics 149
using in hotspots in graphics 246 in popups 274
invisible files 25 in topics without TOC entries 274
invisible topics listing for project 534
importing from old projects 550 red underline 274
invisible topics, converting from old projects 51 sorting problems 94
sub-entry levels 274
testing 292
-J- using with anchors 226, 280
variables in 388
JavaScript viewing in Index Tool 280
about JS links 759 K-keywords
about using 758 in embedded topics 149
complex code in links 759 KLink() macro
complex scripts 223 translation in HTML Help 223, 761
nesting quotes 759
script links 223
syntax in Help & Manual 759
troubleshooting 759
-L-
using in hotspots in graphics 246 language and character set 94
where supported 759 language of help file (language settings) 94
JavaScript popups 794, 798 language settings 91
in HTML Help and Webhelp 129 and PDF 824
in Webhelp 731 CID font mode for PDF 94
options 129, 667, 682 configuration settings for 94
using 129 default font 94
JPG images 238, 753 font character set 94
jump targets 226 for project 54, 822
help file language 94
in Project Configuration 654
-K- language of help file 94
project language and character set 94
keyboard shortcuts 31, 573 right-to-left languages, activating support for
customizing 646 654
for styles 161, 169 Unicode 94
using with styles 167 languages 820, 822
keyword index template 810 right-to-left languages 654
keywords 273 Layout emplate 437
about 801 Layout section in Webhelp 296, 298
adding 274 leading spaces 172
adding child keywords 275 legal numbering style 187
adding master keywords 275 level reset (outline numbering) 187
adding to anchors 275
© 1997 - 2009 by EC Software, all rights reserved
 Index 853

levels (outline numbering) 187 generating context numbers and topics with
lines 799
inserting 143 importing 539
link styling tutorial 77 restrictions 799
link texts master and child projects 764
editing 225 master projects 764
linking menu icons 24
to popup topics 125 menus reference
links Help tab 652
dead 288 MERGE command for importing HTML files 107
Insert dialog (dialog reference) 617 merge method in modular projects
preventing dead links 404 choosing and changing 447, 451
styling with CSS, tutorial 77 metafiles 753
to anchors 71, 226 Microsoft help compilers
to anchors in snippets 226 setting locations 649
tutorial 71 where to get 826
types supported 214 missing graphics 288
lists modular help
applying deletes indent 828 about 446
cannot indent 172 A-keywords and 236, 281, 806
output format in HTML 194, 671, 684, 697 linking between modules 236, 281
lists (dialog reference) 612 modular help systems
live spell checking 58 about 764
Load Topic from File 588 modular projects 764
loading multiple projects 43 about 764
loading projects 43 and Webhelp 464
localization 521 changing merge method 447
localization and translation child modules 770
features and support 522 child projects 447, 770
tutorials 522 context numbers, preventing duplicates 456
logic of include options 400 copying 454
Longhorn Help 725, 743 creating 447
editing child projects in master 447
editing in master 447
-M- graphics in 249, 456
hyperlinks between 229
macro links IDs, preventing duplicates 456
creating 223 include options 412
macros (Winhelp) inserting a project in the TOC (quick guide)
about 761 115
translation in HTML Help 223, 761 linking between modules 459, 770
macros and scripts managing modules in the TOC 454
variables in 388 master modules 770
map files master projects 447, 770
about 799 merge methods 451
auto-generating topics with 375 merge options for HTML Help 451
cannot import context nos. to anchors 539 merge options for Winhelp 451
exporting (with custom syntax) 539 nesting modules 770
field-level popups 799 planning 770

© 1997 - 2009 by EC Software, all rights reserved

 854 Help & Manual 5 - User Help

modular projects 764 multi-user editing

project and output names must match 312 and version control systems 335, 518
publishing 461 read-only mode for child projects 447
read-only mode 447
read-only mode for child projects 447
runtime and compile-time merging 767 -N-
second copies 454
named destinations in PDF files 220
structuring 770
navigation links in topic headers 123
support in output formats 447
Navigation section in Webhelp 296
modules
nested tables
changing merge method 447
don't split across pages 266
master and child 447
not supported in Winhelp 266
monitors, multiple
nesting include options 410
save window positions for 643
network drives
mouse wheel
HTML Help doesn't work 829
changing font size preview setting 647
restrictions on HTML Help 727
movies
new projects 83
Insert dialog (dialog reference) 625
creating with imported data 99
moving 46
non-breaking spaces 722
moving topics 63
non-scrolling header template 80
MS Excel
Normal style 61, 717
copying from and to 139
Notes style 717
MS Help 2.0 (Visual Studio Help)
about 490, 738 number format (outline numbering) 187
compiler 311, 490 number style (outline numbering) 187
compiling 491 numbered lists
configuring Visual Studio Help output 302 adjusting indents 193
example calls 491 creating 183
export options 694 customizing 183
limitations 490 format 183
namespace 491, 694 formatting numbers in 193
popups 695 inserting un-numbered paragraphs 183
publishing 73, 313, 491 outline numbered lists 187
registering HXS files 491 styles in 193
requirements 490 numbering
unique identifier 491, 694 restarting in numbered lists 183
MS Word style in numbered lists 183
copying and pasting from/to 58 numbering and bullets (dialog reference) 612
copying from and to 139 numbering, automatic with variables 391
differences from Word 135
mangles XML source code 154
pasting graphics from 755 -O-
MS Word RTF old projects, converting 51
about 739 OLE objects
pros and cons 739 about 494, 753
MS Word RTF output creating new 494
settings in Project Configuration 705 editing 494
multi-monitor displays embedded 755
save window positions for 643
© 1997 - 2009 by EC Software, all rights reserved
 Index 855

OLE objects
embedding 494
embedding vs. linking 757 -P-
examples 497
page breaks
implementation in Help & Manual 757
errors caused by tables 266
Insert dialog (dialog reference) 635
inserting 143
inserting from files 494
page referrers for PDF 575
restrictions 757
page referrers for PDF output 690
organizing styles 720
paragraph end marks
outline numbered lists
cannot select 135
customizing 187
paragraph marks
formatting 187
displaying in editor 647
level reset 187
paragraph styles 167, 718
levels 187
defining 161
number format 187
defining from selection 161, 169
number style 187
naming for easy finding 720
styles in 193
searching and replacing 498, 507, 510
output formats 87
paragraphs
about 725
borders and backgrounds (dialog reference)
Adobe PDF 737
611
configuring (introduction) 292
borders not displayed 828
configuring Adobe PDF output 301
copying problems 828
configuring ePub eBooks output 305
Format menu (dialog reference) 609
configuring HTML Help output 294
formatting tools 155
configuring printed manuals 301
indenting 172
configuring Visual Studio Help output 302
parent style
configuring Webhelp output 296
changing 164
configuring Windows eBooks output 304
paste as text
configuring Winhelp output 303
copying text without formatting 579, 601
configuring Word RTF output 304
PCD images 238
distribution files 319
PDF
eBooks, ePub 732
about 325
eBooks, Windows exe 735
additional pages in 325
ePub restrictions and requirements 305
CID font mode 94, 332, 692, 824
HTML Help 727
clipped graphics 650
Longhorn Help 743
configuring PDF output 301
MS Word RTF 739
embedding files in 220, 332
printed manuals 738
file embedding setting 690
Vista Help 743
font embedding 301
Visual Studio Help/Help 2.0 738
font embedding settings in Project Configuration
Webhelp 730
94, 692
which is best? 826
generating 326
Winhelp 740
including/excluding pages 301, 326, 330, 425
output size
layout settings in Project Configuration 690
larger after resizing graphics 242
linking to specific pages in 220
max. TOC levels 326
named destinations in 220
no graphics 650
page break errors 266
© 1997 - 2009 by EC Software, all rights reserved
 856 Help & Manual 5 - User Help

PDF about 788, 792

page referrers 575, 690 and context help 792
Print Manual Designer 537 application calls to 372
printer driver required for 301 auto-generating for context help 796
pros and cons 737 context numbers for CHM popups 125
reference driver for 650 creating 125
settings 326 field-level popups 125, 370, 788, 792, 794,
settings in Project Configuration 690, 691 796, 798
table widths 256 for context-sensitive help 370
template variables 784 in HTML Help 809
templates for 425, 537 in HTML Help and Winhelp 125
templates for, standard files 75 in Visual Studio Help/Help 2.0 695
templates, location 330 in Windows Exe eBooks 709
templates, using 330 in Winhelp 810
topic headings in 325 in Winhelp and HTML Help 798
Unicode now supported 824 JavaScript popups 129, 682
using hi-res graphics in 242 linking to 125, 215
video files support 756 linking to from hotspots 246
PDF manual 37 plain text only in HTML Help 829
PDF problems pros and cons 792
can't output 832 settings for HTML Help 667
files too big 832 settings for Webhelp 682
garbled output 832 where supported 125, 792
heading formatting doesn't match project 832 width of, controlling 125, 798
including/excluding pages 832 preview mode for screen and print styles 175
odd/even page problems 832 Print Manual (dialog reference) 575
PDF templates print preview 577
defined 416 Print Manual Designer 599
variables in 399 configuring PDF output with 301
per-topic variable redefinition 395 configuring printed manuals with 301
PHP, switch off the BOM for compatibility 671, 684, using 537
697 print manual templates 325, 328
pinning 46 defined 416
plain HTML code editing 330, 425
about 762 opening current template for editing 690
adding to <head> section 762 selecting 330, 425
and Baggage 486 standard files 75
and HTML variables 762 standard templates 330, 425
files referenced in 486 using 425
Insert dialog (dialog reference) 632 variables in 399
inserting outside <body> tags 762 print preview (dialog reference) 577
limitations in eBooks 762 Print Preview function
referencing script functions in 762 selected topics only 328
where supported 762 print styles and screen styles 175
plain-text variables printed manuals
defining 378 about 325, 738
PNG images 238, 753 configuring 301
Pocket PC, project template for 79 templates for 328, 425
popup topics printing

© 1997 - 2009 by EC Software, all rights reserved

 Index 857

printing sections 652

excluding TOC etc. 328 Text Variables 657
garbled printouts 834 Title & Copyright 654
no page referrers in print preview 834 Topic IDs and Help Context numbers 665
previewing before printing 328 variables in 653
selected topics only 328 Visual Studio Help (Help 2.0) settings 694
single and multiple topics 153 Webhelp 674, 676, 678, 679, 680, 682
toggles 367 Winhelp 700, 701
program code Winhelp Extended .HPJ Settings 703
Syntax Highlighting 607 Winhelp modular help options 702
Program Options - Compilers 649 Project Converter
Program Options - Editor 647 command line syntax 471
Program Options - General 643 converting H&M 3 projects 550
Program Options - PDF Export 650 converting old projects 87
Program Options - Ribbon 645 custom code in HTML templates 87, 550
Program Options - Shortcuts 646 invisible topic conversion 550
program workspace 574 restrictions and limitations 87, 550
project Project Explorer
title & copyright notice 654 defined 25
docking and undocking Explorer windows 31
Project Configuration
folders 211
about 652
managing Topic Files 211
Adobe PDF font embedding options 692
navigating in 43
Adobe PDF Layout 690
pinning Explorer windows 31
Adobe PDF Options 690, 691
sections, about 41
and multi-user editing 518
split view 585
CID font mode 692
Table of Contents 109
Common Properties 653
tutorial 41
copying settings between projects 139
custom builds 658 Project Explorer windows
eBooks functionality settings 708 split view 46, 58
eBooks layout settings 706 Project Files section 25
eBooks settings 706 defined 25
editing 91 Project menu
help windows 660 Project Configuration 594
help windows general options 660 project reports 288
help windows HTML Help options 661 saving as HTML files 534
help windows Winhelp options 663 using the Reports Tool 534
HTML Export Options 671, 684, 697 Project Reports tool 534
HTML Help 667 Project Reports tool (dialog reference) 596
HTML Help Extended .HHP settings 670 project search path 656
HTML Help modular help 670 and graphics 249
HTML Help popup topics 667 and snippets 149
HTML page templates 666 Project Synchronization
Language Settings 654 about 556
MS Word RTF settings 705 creating translation sibling pairs 557
project search path 656 how changes are synchronized 556
publishing options 667 identifying changes in synchronized projects
right-to-left languages, activating support for 563
654 interim updates 564

© 1997 - 2009 by EC Software, all rights reserved

 858 Help & Manual 5 - User Help

Project Synchronization PSP images 238

internal numerical IDs 565 Publish 590
material disappears after synchronization! 565 Publish Help File (dialog reference) 590
no text-level comparison 556 publishing
Professional version only 556 about 311
project folder and 557 Asian languages on non-Asian windows 313
synchronizing existing translations 565 checklist 312
synchronizing new versions 560 epub eBooks 313
translating changes 562 implicitly included topics message 826
translating the original project 559 include options and 313
updating the original project 560 Microsoft help compilers 311
Project Synchronization Tool modular projects 764
Ribbon reference 600 projects 313
project templates publish only complete topics 313
applying to existing projects 417 quick launching 313
creating 417 selected topics 313
defined 416 with skins 313
Help & Manual help project template 417 publishing directly from your application 485
using to create new projects 417 publishing formats 87
projects Publishing Options 667
checking status 534 publishing vs. compiling 288
converting old projects 51, 87, 550 publishing, about 764
copying and moving topics between 102, 199 publish-time merging 451
copying settings between 139
copying styles between 177
copying text and content between 139
creating 83
-Q-
creating (tutorial) 54 Quick Access Toolbar 24
creating new projects 83 Quick Launch 73, 313
creating with imported data 99
inserting in another project (quick guide) 115
invisible topics from old projects 550 -R-
language settings 822 read-only topics
large projects 764 setting display color in TOC 518, 647
multi-user edting 518 recently-used images, reinserting 251
PDF and language settings 824
Reference section 568
Project Configuration 594
references
publishing 73, 313
to topics, finding 586
quick launching 73, 313
referrers 288, 402
saving as skins 321
finding 141, 290
templates for 417
Refresh Project 590
testing 288
Refresh Project command
title, copyright and language settings 91
for multi-user editing 518
translating in Help & Manual 525
translating with XML in external editors 522 Reload Topic 588
promote/demote topics in the TOC 589 remote editing 335, 518
protect text against changes 132 replace
multi-user editing 518
protected variables 378
replace styles 828
PSD images 238

© 1997 - 2009 by EC Software, all rights reserved

 Index 859

replacing formatting Edit Styles (dialog reference) 604

about 498 Editing group (dialog reference) 601
replacing formatting and styles Font (dialog reference) 606
about 497 Font group (dialog reference) 605
replacing styles Hotspot editor (dialog reference) 624
about 498 HTML Code Object (dialog reference) 632
Report Tool (dialog reference) 596 Image (dialog reference) 622
Reporting Tool Insert / Insert Object 615
locating missing graphics with 289 Link 617
using to test projects 289 Movie (dialog reference) 625
reports OLE Object (dialog reference) 635
saving as HTML files 534 Paragraph (dialog reference) 609
using the Reports Tool 534 Paragraph group (dialog reference) 608
resizing graphics 239, 242 Replace Styles 605
reusing content 764 snippets (dialog reference) 633
Special Characters (dialog reference) 637
Ribbon - Project 579
Styles group (dialog reference) 603
Add File (dialog reference) 581
Text Variable (dialog reference) 627
Add Topic (dialog reference) 581
Toggles (dialog reference) 629
Bookmark 593
Change 585 Ribbon - Write tab
File 588 mini toolbar 589
Find Referrers (dialog reference) 586 Ribbon reference
Manage Topics group (dialog reference) 580 Project tab 579
Project group (dialog reference) 590 Ribbon Toolbar 24
Publish 590 accelerator keys 31
Ribbon - Table 638 customizing 645
Table Properties (dialog reference) 638 Ribbon Toolbar (Reference) 573
Ribbon - Tools 532, 594 right-to-left languages 654, 822
Customize 643 RoboHelp X5 projects
editor customizing options 647 settings for importing 105
general customize options 643 row height 723
Help Context Tool 600 rows (tables)
Image Editor 596 adding/deleting 259
Index Tool (dialog reference) 598 RTF
Print Manual Designer 599 configuring Word RTF output 304
Report Tool (dialog reference) 596 table widths 256
Screen Capture (dialog reference) 595 RTF files
Spell Checker 594 importing into individual topics 100
Synchronize 600 importing to topics 204
Ribbon - View 642 settings for importing 105
Ribbon - Write 600 RTF output format
Anchor (dialog reference) 627 about 739
Borders and Background (dialog reference) pros and cons 739
611 settings in Project Configuration 705
Bullets and Numbering (dialog reference) 612 ruler
Comment (dialog reference) 633 indent tool 172
Conditional Text (dialog reference) 628 rulers
Create Style from Selection (dialog reference) display vertical ruler 647
603 ruler units 647
© 1997 - 2009 by EC Software, all rights reserved
 860 Help & Manual 5 - User Help

runtime merging 451, 461, 767 variables 392

RVF files search engine optimization 778
importing into individual topics 100 per-topic variable redefinition 395
importing to topics 204 search interface language files for Webhelp 75
Search template 810

-S- Second Copy FTP folder synching program 671,

684, 697
secondary windows
sample projects 37
and hyperlinks 231
save mode
in HTML Help 809
uncompressed XML mode 85
in Winhelp 810
Save Topic to File 588 opening topics in 231
Screen Capture tool 532 using 429
using 244
Section 508 compliance 743
Screen Capture tool (dialog reference) 595
section header separators (in keyword index) 284
screen styles and print styles 175
See Also lists
screenshots creating with A-keywords 236, 281
Screen Capture Tool 532
selecting
with Screen Capture tool 244
keyboard shortcuts for 138
script links text and content 138
creating 223
SEO 395, 778
using in hotspots in graphics 246
settings
scripts copying project settings between projects 139
about using 758
shared HTML settings 667, 674, 706
files referenced in 486
SHG graphics with hotspots 238
inserting JavaScript in topics 759
SHG images
SDL Trados 521
hotspots converted automatically 238
INI file for 522
supported formats 238
SDL Trados INI file 81
shortcuts
search
customizing 646
excluding files and topics from Browser search
index 300 Show Differences 588
excluding page sections from search index Show History 588
300 skins 75
full-text search for Webhelp 300, 438 and styles 711
not working in HTML Help 829 command line option 478
special settings for in Webhelp 300 creating skin files 321
search and replace defined 416
complex with XML 154 editing skin files 321
font styles 498, 500, 503 multiple skins with command line options 321
formatting 498 publishing with 313
graphics 249 redefining variables with 394, 478
images 141, 290 using 419
in TOC and Invisible Topics 141, 290 using for HTML output formats 321
multi-user editing 518 snippets 204
paragraph styles 498, 507, 510 and project search path 149
referrers 141, 290 editing snippet files 149
text 141, 290 finding where used 149
topics 141, 290 hyperlinks and 149

© 1997 - 2009 by EC Software, all rights reserved

 Index 861

snippets 204 status

Insert dialog (dialog reference) 633 edit 585
keywords in 149 status (dialog reference) 659
linking to anchors in 226 style inheritance
locating source files with Find Referrers 586 in table styles 263
moving 633 styles
project search path 633 about 711
save selected text as snippet 588 aligning tables with 265
save topic as snippet 588 applying to table contents 178, 265
using 149 applying to tables 178
vs. multiple references 751 can't reformat empty paragraphs 827
snippets folders changing on the basis of selection 164
project search path 656 changing parent 164
setting locations for 656 converting styles 718
source code copying from other projects 177
ANSI SQL 195 copying text without styles 139
C++ 195 creating from selection 603
leading spaces for indents 172, 195 defining 161
Pascal 195 defining from selection 161, 169
syntax highlighting 195 defining new 61
syntax highlighting examples 197 different for print file and help file 175
Visual Basic 195 display in Toolbar 159
Visual Objects 195 dynamic linking and inheritance 713, 714
source code for the Help & Manual help 81 editing 164, 604
spaces explained 713, 714
hard spaces 722 families 720
multiple spaces in HTML 722 formatting text with 167
spaces for indents 172, 195 image captions and comments 176
spacing imported 161, 169
unexpected changes 828 importing from another project 161, 169
special characters in skin files 321
Insert dialog (dialog reference) 637 in tables 178
inserting 143 inheritance trees 714, 720
Spell Checker moving and renaming 164
configuring 543 organization strategies 720
custom user dictionaries 546, 548, 835 paragraph and text styles 167, 718
dictionaries 543 paragraph style "stuck" 827
disabling for selected styles 543 preview mode 175
using 543 quick guide to using 157
spell checking renaming 720
auto-correct 145 replacing, about 497
configuring 145 searching and replacing, about 498
custom dictionaries 145 selecting and applying 167
custom user dictionaries 835 smaller files with styles 711
live spell checking 58, 145 source code 195
manual 145 standard styles 717
multiple languages 145 syntax highlighting 195
TOC captions 145 table styles 69, 263, 718
split Explorer 585 toolbar display 718

© 1997 - 2009 by EC Software, all rights reserved

 862 Help & Manual 5 - User Help

styles table styles (dialog reference) 604

using (tutorial) 61 Table tab (dialog reference) 638
using in numbered and bulleted lists 193 table width and height 723
why use? 711 tables
styles preview mode (screen/print) 58, 132 about 253
stylesheets about table sizing 723
applying from project template 417 adding/deleting rows/columns 259
copying between projects 177 background images 267
subtopics borders 268
exclude all a topic's subtopics 407 column width problems 836
support address 37 column widths 254, 256
support email link 652 converting tables to text 262
symbols converting text to tables 262
inserting 637 creating 254
syntax highlighting deleting cell contents 261
customizing 195 displaying grid lines darker 647
examples 197 editing restrictions in 253
Format menu 607 formatting 258
leading spaces for indents 195 indenting and centering 262
system locale Insert dialog (dialog reference) 638
changing for Unicode 820 inserting 69
system locale, changing for language compatibility limitations in Winhelp 253
94 manipulating 69
merging/unmerging cells 260
nested 266
-T- paragraph settings for 262
printing settings 254
tab stops
resizing 258
and indents 722
selecting 258
not supported in HTML 722, 829
size options 254
table grid lines splitting cells 260
displaying darker 647 styles and 178
Table of Contents 25 table styles 253
changing topic icons in 209 tabs
defined 25 and indents 722
docking and undocking 836 not supported in HTML 722
multiple entries for one topic 208
TCard() macro
multi-user editing 518
translation in HTML Help 223, 761
organizing 63
templates
overview 63
content templates for new topics 110
promoting and demoting topics in 203
external templates included with Help & Manual
spell checking 145 77
timestamps 209 for eBooks 429
Table of Contents section for PDF 325
about, in Project Explorer 109 for PDF and printed manuals 328, 425
table styles 69, 178, 604, 718 for PDF and printed manuals, using 330
applying 61, 263 for projects 417
creating tables with 263 for topics (with content) 423
defining 61, 263 Help & Manual help project template 80

© 1997 - 2009 by EC Software, all rights reserved

 Index 863

templates of HTML topic files 671, 684

HTML templates 427, 431 timestamps
HTML templates, conditional output 441 topic and TOC timestamps 209
HTML templates, editing 431 title & copyright notice 654
HTML templates, external file references in title bar text 654
444 TOC 25
HTML templates, graphics references in 442 about, in Project Explorer 109
HTML templates, troubleshooting 445 changing topic icons in 209
HTML templates, variables in 439 custom icons in Webhelp 209
HTML topic templates 433 defined 25
Index template for Webhelp 438 disable Drag & Drop 585
PDF templates with Print Manual Designer 537 docking and undocking 836
Pocket PC help project template 79 expand/collapse 585
Search template for Webhelp 438 filter by build options 585
template types defined 416 filter display with build options 402
TOC template for Webhelp 437 filtering by build options 211
templates, HTML page multiple entries for one topic 208
background colors 123 multi-user editing 518
headers and footers 123 promoting and demoting topics in 203
navigation links 123 setting color for read-only topics 518, 647
setting for individual topics 123 spell checking 145
temporary files 742 timestamps 209
HTML Help files 728 variables in 388
Winhelp files 742 TOC entries
testing projects 288 adding to topic files 112
text deleting without deleting topic 112
copying unformatted 139 deletingb with and without topic files 201
copying without formatting 579, 601 TOC link to web page 115
copying, cutting and pasting 139 TOC template 810
formatting manually 155 toggles 351, 355, 357
formatting with styles 167 about 350
in images, translating 528 copying 359
selecting 138 copying and editing 360
wrapping around graphics 241 CSS styles for links 361
text style 143 duplicate ID conflicts 360
text styles 143, 167, 718 examples 350
creating from selection 603 Expand All / Collapse All functions 363
defining 161 IDs 359, 365
defining from selection 161, 169 Insert dialog (dialog reference) 629
display in Toolbar 159 nesting 350
editing 604 output file size 365
naming for easy finding 720 pre-expanding toggles for printing 367
Text Variable Print button with Expand All 363
Insert dialog (dialog reference) 627 printing 367
text variables Pro version only 350
managing 657 support in output formats 350
settings in Project Configuration 657 troubleshooting 365
TIF images 238 types 350
timestamp updating old expanding sections 366

© 1997 - 2009 by EC Software, all rights reserved

 864 Help & Manual 5 - User Help

toggles, expanding images Topic Files section 25

converting existing images 357 creating new folders in 112
creating 357 defined 25
formatting with CSS 357 topic header (editing box above topic)
toggles, expanding inline text additional content in 119, 136
creating 355 changing background color 119, 136
formatting text and links 355 editing 117, 433
toggles, expanding sections formatting 119, 136
creating 351 in electronic help formats 119, 136
editing 351 in PDF, RTF and printed manuals 119, 136
embedded topics in 351 link with topic caption (off/on) 117
formatting headers 351 turning off for individual topics 117
icons, swapping 351 turning on and off 119, 136
icons, using in 351 topic headings
indents in 351 in PDF 325
nesting 351 topic icons
supported content 351 changing in TOC 209
toggles, troubleshooting topic IDs
large output files 365 about 801
page breaks in PDFs and printed manuals 365 assigning and choosing 205
problems with expanding section toggles 365 auto-correcting blanks in 647
problems with formatting in toggle links 365 changing globally 456
problems with IDs 365 descriptive 205
Tooltips 789 editing 205
topic editing/changing 801
convert to chapter with/without text 585 finding 141, 290
load from file 588 hierarchical 205
reload function 588 in modular projects 456
save snippet (selected text) 588 listing 534
save to file 588 maximum length 801
status 585 permitted characters 801
topic caption (in TOC) prefixes, generating automatically 205
editing 117 settings in Project Configuration 665
link with topic header (off/on) 117 topic include options
topic class 581 checking and correcting dead links 407
topic content templates 423 exclude all a topic's subtopics 407
defined 416 setting and editing 407
topic files topic links
about - general introduction 109 compatibility in output formats 215
auto-generating from map files 112 creating multiple 215
creating without TOC entries 112 inserting 215
deleting 211 Topic Options
deleting with and without TOC entries 201 cannot undock 836
importing into individual topics 100 Topic Options tab
include options with 112 displaying next to Editor 31
managing 211 repositioning 31, 46
moving 211 topic page template 810
organizing in folders 210 topic status
sorting and grouping 211 edit 585
© 1997 - 2009 by EC Software, all rights reserved
 Index 865

topic status (dialog reference) 659 styles 102

topic templates, HTML testing 289, 290
breadcrumb trail navigation 433 text is unformatted! 102
using and editing 433 timestamps 209
topics TOC link to external help file 115
about - general introduction 109 translating 522
and project search path 102 topics without TOC entries
auto-generating with map files 799 creating 112, 210
background colors 121 include options with 112
copying and pasting between projects 102 organizing in folders 210
creating and editing 108 Trados 521
creating multiple in TOC 110 INI file for 522
creating new 56 Trados INI file 81
creating new in TOC 110 training card help 369, 789
creating popups 125 translatable elements in XML 528
creating with templates 110 translate="false" 528
creating without TOC entries 112 translating individual topics 522
cutting and pasting 63 translating individual topics with XML
display in external windows 429 tutorials 522
displaying in external windows 121 translating projects
edit caption (title) 589 and localization 521
editing caption and header 117 project synchronization and 556
excluding from full-text search in Webhelp 300 text in images 528
exporting 102 translating projects in Help & Manual 525
exporting and importing 204 translating with external editors 522
field-level popups 799 translation 521, 522, 528
finding 141, 290 procedure 525
finding references to 586 protecting text against changes and translation
formatting 102 525
implicitly included compiler message 826 translation and localization
importing 102 features and support 522
include options with 112 tutorials 522
inserting JavaScript in 759 troubleshooting 650
listing editing dates 534 TrueType fonts
move up/down 589 CID font mode 692
moving 63 embedding in PDF files 692
moving, cutting and pasting 199 tutorials
multiple TOC entries for one topic 208 adding topics 56
multi-user editing 518 background images for topics and headers 77
opening in external windows 231 conditional output 78
print 589 creating hyperlinks 71
printing single and multiple topics 153 creating projects 54
promote/demote 589 customized icons for Webhelp TOC 77
promoting and demoting in the TOC 203 DHTML Examples 77
publish only complete topics 313 entering and editing text 58
saving as snippets 204 expanding and collapsing sections 77
sharing 102 external tutorials included with Help & Manual
snippets 102 77
snippets vs. multiple references 751 inserting graphics 67

© 1997 - 2009 by EC Software, all rights reserved

 866 Help & Manual 5 - User Help

tutorials Ribbon Toolbar 24

inserting tables 69 user manuals
modular help systems 79 using hi-res graphics in 242
navigation buttons 77 user-defined variables
non-scrolling headers 77 where supported 378
organizing the TOC 63 UTF-8
Pocket PC help 79 not supported in HTML Help 94
Print link 77 UTF-8 BOM, switch off for PHP 671, 684, 697
publishing projects 73
Quick Start 41
styling hyperlinks with CSS 77 -V-
suppress underlined TOC entries in Firefox 77
using Help & Manual 37 variable name syntax 378
Using Styles 61 variable names
TXT files editing in the editor 382
importing into individual topics 100 variables
about 376, 772
breadrcrumb trail variable 778
-U- counter variables for numbering 391
date and time formatting 386
undocking and redocking 46 date and time formatting in 776
Unicode disable variable highlight 382
about support in H&M 820 disabling 382
editing requirements 820 editing and formatting 382
international language setup 94 find and replace 392
now supported in PDF 824 formatting and styles with 382
publishing requirements 820 global predefined variables 381, 774
which languages require 820 HTML variables 377
Windows requirements for 820 in HTML templates 393, 439, 810
Unicode mode in Windows 2000 and XP 822 in PDF templates 399, 784
update checker 652 Insert dialog (dialog reference) 627
update checking function inserting in topics and headers 386
and firewalls 643 managing 657
configuring 643 maximum characters 376
upgrading FAQ for HM4 users 18, 568 plain-text variables 377
URLs protected variables 378
detecting automatically 647 redefining for conditional output 394, 414
user dictionaries redefining in command line options 478
for spell checker 145 redefining in individual topics 394
multi-user 145 redefining with skins 321, 478
storage locations 145 search and replace 392
user interface 23 search engine optimization 395
Application Button 24 settings in Project Configuration 657
customizing 31 typing manually 386
dialog icons 24 user-defined, creating and editing 378
editor 29 user-defined, importing and exporting 378
menu icons 24 using outside topics 388
Project Explorer 25 variable name syntax 378, 381
Quick Access Toolbar 24 where supported 377, 772

© 1997 - 2009 by EC Software, all rights reserved

 Index 867

variables configuring Visual Studio Help output 302

with and without highlight 386, 392 example calls 491
VCS export options 694
advantages 335 F-Index 694
and multi-user editing 335 limitations 490
and remote editing 335 namespace 491, 694
Application Menu options 578 popups 695
connecting projects to VCS 339 publishing 73, 313, 491
control visibility 335 registering HXS files 491
converting HMXZ projects for VCS 339 requirements 490
manual check-out and check-in 665 settings in Project Configuration 694
multi-user editing 338 unique identifier 491, 694
Project tab functions 588 Visual Studio Help Integration Kit 490
supported systems 335 Visual Studio Help/Help 2.0
using with H&M 338 about 738
Version Control Systems pros and cons 738
advantages 335 Voluntary Product Accessibility Template 743
and multi-user editing 335 VPAT 743
and remote editing 335 VSIK 490
Application Menu options 578
connecting projects to VCS 339
control visibility 335 -W-
converting HMXZ projects for VCS 339
web pages
manual check-out and check-in 665
inserting in topics 115
multi-user editing 338
Project tab functions 588 Webhelp
supported systems 335 about 730
using with H&M 338 and modular projects 464
appearance in different browsers 296
vertical ruler
browser compatibility 731
display 647
configuring output 296
video files 269
context calls and 234, 373
about 753
custom icons 209
editing HTML code for 271
deleting output folder before publishing 313,
inserting in topics 269
590, 834
movie preview function not working 837
displaying topics without TOC 234, 373
support in output formats 272, 756
expand automatically on open 296
videos not playing properly 837
frames settings 674
Vista Help 743 FTP folder synching with archive bits 671, 684,
Visual Source Safe 697
support in HM 335 full-text search 296, 438
Visual SourceSafe full-text search issues 313, 834
connecting projects to VSS 339 full-text search settings 680
multi-user editing 338 HTML page templates 666
Project tab functions 588 index separators 679
using with H&M 338 JavaScript popups 731
Visual Studio Help (MS Help 2.0) Keyword Index settings 679
about 490 language files for Search interface 75
compiler 490 Layout section in Project Configuration 296
compiling 491 layout settings 674
© 1997 - 2009 by EC Software, all rights reserved
 868 Help & Manual 5 - User Help

Webhelp modular help settings 702

link syntax 464 nested tables not supported 266, 740
linking to anchors in 226 no TOC 837
links between projects 464 popup topics in 125, 798
links to 229 project files 742
navigation behavior (single or double click) 296 pros and cons 740
Navigation section in Project Configuration 296 secondary windows 808
navigation settings 676 setting compiler location 649
popup topics settings 682 settings in Project Configuration 700, 701
pros and cons 730 single-level topics become sub-topics 837
publishing 73 support for modular projecxtss 447
settings in Project Configuration 674 support for videos and animations 272
support for videos and animations 272 video files support 756
syntax for calls/links to 234, 373 Winhelp files
testing locally in Internet Explorer 313 settings for importing 105
TOC settings 678 Winhelp macros
turning off yellow warning bar in Internet Explorer about 761
313 translation in HTML Help 223, 761
video files support 756 wizards 789
welcome page 14 WMF images 238, 753
Welcome section 25 Word
defined 25 copying and pasting from/to 58
What's This? help 789 copying from and to 139
windows pasting graphics from 67, 755
docking and undocking 836 Word files (RTF)
external windows 231 importing graphics from (troubleshooting) 105
secondary windows 231 settings for importing 105
Windows metafiles 753 word formatting
Windows Vista Help 725 automatic for word left of cursor 828
Winhelp Word RTF
about 740 about 739
browse sequences no longer supported 837 configuring Word RTF output 304
calling from command line 837 pros and cons 739
chapters with text not supported 110, 585 videos and animations 272
compiler 311 workspace (about) 574
configuring output 303 writing and formatting text in the editor 132
context-sensitive help 369
custom TOC icons not supported 837
empty chapters 837
Extended .HPJ Settings 703
-X-
external windows 808 X5 projects
field-level popups 740 settings for importing 105
field-level popups in 794, 798 XML
formatting features restrictions 740 and translating projects 522
help windows in 810 exporting text in Impict images 244
help windowss 808 XML editing 493
hotspots not supported 246, 837 XML elements
limited formatting support 155 translatable elements 528
merge options for modules 451 XML Export/Import

© 1997 - 2009 by EC Software, all rights reserved

 Index 869

XML Export/Import
text in images 528
XML files
check list for translators and editors 528
editable elements 528
exporting/importing topics 204
importing 102
reusing as snippets 102
XML schema 522
documentation 154
XML schema and stylesheet files 75
XML source code
complex search and replace 493
editing 154, 493
XML Source tab 154, 493
editing XML source code 132
XML topic files
importing into individual topics 100

-Z-
zoom factor for graphics 239, 242

© 1997 - 2009 by EC Software, all rights reserved