103
392
Working on a Team
Doc-To-Help 2014 User Guide
2.
Select
File > Open Team Project
to connect to the repository. The
Load Remote Project
dialog box will
open.
3.
Select the
Repository Type
. (If necessary, enter your login credentials.)
4.
Select a team project (or choose
Select Team Project
from the drop-down box to browse for a project) and
click
OK
.
5.
Select
Tools > Clear Repository Backup
. The
Clear Repository Backup
dialog box will open.
6.
Select
Delete all backup files older than
in the lower part of the dialog box.
7.
Click the drop-down arrow next to the date and select a date from the calendar. Select a time using the up and
down arrows in the time box.
8.
Click
OK
. Backup files prior to the date and time specified will be removed from the repository.
The administrator can also use this dialog box to change the backup settings specified when the project was first shared.
See Changing Repository Settings on page 394.
Unlocking Files in the Repository
Checking out a file creates a lock in the repository that prevents other team members from checking out the same file.
This could cause a problem if an author checks out a file and forgets to (or cannot) check it back in. Then the file
remains permanently locked, preventing the other team members from checking it out and modifying it. The
administrator can manually remove the lock using
C1D2HTeamAdmin.exe
.
To unlock files in the repository
1.
Double-click C1D2HTeamAdmin.exe on page 391.
2.
Select
File > Open Team Project
to connect to the repository. The
Load Remote Project
dialog box will
open.
3.
Select the
Repository Type
. (If necessary, enter your login credentials.)
4.
Select a team project (or choose
Select Team Project
from the drop-down box to browse for a project) and
click
OK
.
The utility displays the folder tree of the repository and the files in each folder. Files that are currently locked
are indicated in the
Lock Status
column, showing the user name and the computer name that owns the lock.
5.
Select the folder from the
Project Folder
node on the left pane, then select the file from the right pane.
6.
Click the
Unlock
button on the toolbar or choose
Unlock
from the right-click menu.
Note:
Unlocking files must be done with caution by the administrator, because doing so resets the check-out state of the
file on the team member's machine without getting the latest version of that file from the repository.
Unlocking the .dhv File
Most team-authoring actions create a temporary lock in the repository for the duration of the action to prevent conflicts
between different team members using the repository simultaneously. This temporary lock is created in a special file,
<project_name>.dhv
, located in the
D2HTeamInfo
folder created by Doc-To-Help. Normally, these locks are only
temporary. However, if a team-authoring action is not normally closed due to an unexpected crash or power failure, it
may leave the project permanently locked in the repository. If this happens, no team members will be able to use the
repository, and Doc-To-Help will display errors saying the repository is busy doing other tasks, although no author is
actually doing anything with the repository. This is a very rare occurrence, but it may happen. If it does, the
administrator can use
C1D2HTeamAdmin.exe
to remove the lock from the
<project_name>.dhv
file.
To unlock the .dhv file in the repository
103
Doc-To-Help 2014 User Guide
Working on a Team
393
1.
Double-click C1D2HTeamAdmin.exe on page 391.
2.
Select
File > Open Team Project
to connect to the repository. The
Load Remote Project
dialog box will
open.
3.
Select the
Repository Type
. (If necessary, enter your login credentials.)
4.
Select a team project (or choose
Select Team Project
from the drop-down box to browse for a project) and
click
OK
.
5.
Click the
Version info
node on the left and select the
<project name>.dhv
file on the right.
6.
Click the
Unlock
button on the toolbar or choose
Unlock
from the right-click menu.
Note:
You can use the
Unlock All
button on the toolbar to release all locks from all files, but this should be done with
extreme caution.
Upgrading a Team Authoring Project
All users of a team project must have exactly the same version (including build number) of Doc-To-Help installed on
their machines. To upgrade the project to a newer version of Doc-To-Help, the administrator must first upgrade the team
project in the repository and then each team member can install the newest version of Doc-To-Help.
To upgrade the team project to a new version of Doc-To-Help
Note:
The following steps should be performed by the administrator.
1.
Install the new version of Doc-To-Help.
2.
Double-click C1D2HTeamAdmin.exe on page 391.
3.
Select
File >
Open Team Project
to connect to the repository. The
Load Remote Project
dialog box will
open.
4.
Select the
Repository Type
. (If necessary, enter your login credentials.)
5.
Select a team project (or choose
Select Team Project
from the drop-down box to browse for a project) and
click
OK
.
6.
Select
Tools
>
Upgrade Team Project to the Current Doc-To-Help Version
.
Once the project is upgraded to the current version of Doc-To-Help, all team members should install the same version of
Doc-To-Help, open their projects, and choose the
File
tab
> Team Authoring > Get Latest Version of the Project
.
Removing Team Authoring Support from a Working Copy
You can remove team-authoring support from a local, working copy of a project.
Removing team-authoring support is different from disabling team-authoring support (usually done when building a
Help target) or working offline on page 389. If you want to detach your working copy of the project from the repository
and remove all team-authoring functions (including the
Team Authoring
tab
and
Team Authoring window)
use
C1D2HTeamAdmin.exe
.
To remove team-authoring support from your working copy of the project
1.
Double-click C1D2HTeamAdmin.exe on page 391.
2.
Select
Tools > Detach local project from repository (remove team authoring support).
3.
Locate and select the local project you want to detach from the repository.
76
394
Working on a Team
Doc-To-Help 2014 User Guide
4.
Click
Open
. A dialog box appears, confirming team-authoring support has been removed from your project.
5.
Click
OK
. Your local project becomes a regular, single-author project without team-authoring support. This
action only changes your local project; it does not change the repository team project or other authors' projects.
Changing Repository Settings
When a project is first set up for team authoring using the
Share Project
wizard, the author sharing the project
determines if the number of backup files kept in the repository for each file is limited, and, if so, to how many. The
author also determines whether other team members can delete old backup files when they check a newer version of the
file into the repository and the limit of backups for that file has been exceeded. These settings can be changed by the
administrator using
C1D2HTeamAdmin.exe
.
To change the repository settings
1.
Double-click C1D2HTeamAdmin.exe on page 391.
2.
Select
File > Open Team Project
to connect to the repository. The
Load Remote Project
dialog box will
open.
3.
Select the
Repository Type
. (If necessary, enter your login credentials.)
4.
Select a team project (or choose
Select Team Project
from the drop-down box to browse for a project) and
click
OK
.
5.
Select
Tools > Repository Settings
. The
Repository Settings
dialog box will open. Edit the following:
Limit the number of backups for each file
— Used to set the limit on the number of backups kept for
each file in the repository. The default is 5, but you can change it in the
Number of backups kept
box. If
you do not set a limit, every time a file is checked-in, a new backup file will be created in the repository,
and there is no automatic cleanup of old backup files.
Allow users to delete old backups in check-in
— Select this check box to permit other team members to
delete old backup files when they attempt to check in a newer version of a file and the backup limit for that
file has been exceeded.
Ask user confirmation to delete backups
— Select this check box if you want a confirmation dialog box
to appear when a team member deletes old backup files. This option is only available when the
Allow
users to delete old backups in check-in
check box has been selected.
Click
OK
to close the
Repository Settings
dialog box.
4
Doc-To-Help 2014 User Guide
Working on a Team
395
47
Doc-To-Help 2014 User Guide
Creating a Modular Help System
397
Creating a Modular Help System
A Modular Help system is necessary when you have a collection of several different Help files (and would like to keep
them that way) but would like them to appear to the end user as a single Help system.
There are four common scenarios necessitating a Modular Help system:
Modular software
— Your software application is sold as separate modules with the user purchasing one or
more modules at a time. A modular Help system will contain all the Help files, but only the appropriate Help
files will accompany the purchased modules.
Large documentation sets
— If you wish, you can “chunk” information into several small Help systems and
create a modular system rather than deploy one large Help system. Smaller projects enable streamlined updating
and easier distribution.
Help systems with future Help projects planned
— If you plan to release your Help system in stages, you can
pre-position placeholders for future Help projects before they are released. Instead of distributing the entire
Help system each time you add to the system, you only need to distribute additional Help files. If you didn’t
plan for an addition, you can distribute a new hub Help file along with the new Help files.
Documentation teams sharing responsibilities across one large project
— Modular Help can be a solution
for a large project with many authors. Each Help author is assigned one or more projects. The team leader is
usually charged with the responsibility of maintaining the hub Help project and assembling the entire project.
(You may want to check out Doc-To-Help’s Team Authoring capabilities and use those instead. See Working
on a Team on page 381 for more information.)
Modular Help systems can reference Help files that are not installed (for example, Help for a software module the end
user has not purchased) and still look seamless. The table of contents and index will simply omit the missing information
without displaying error messages. If the user installs the module in the future, the Help will be added to modular system
in the proper position.
Note:
Verify that your software can accommodate context-sensitive calls from multiple .hlp or .chm files
before
creating a modular Help project. If your software can only accommodate context-sensitive calls from one Help file, you
can still create a modular system, but in that case you must place all context-sensitive topics into one Help file.
Modular Help System Deliverables
Modular Help systems are comprised of one hub (or master) Help file and any number of child Help files. The modular
system appears to the user as one integrated Help system, no different than a large single Help file system. The contents
and index are merged at run time, when the Help file is opened. Dynamic links are also created at run time.
The following files are distributed to end users. When you are ready for release, these files should be stored in the
Redistributables
folder of your modular help project. See File Organization on page 399 for more information.
62
398
Creating a Modular Help System
Doc-To-Help 2014 User Guide
HTML Help
Hub project .chm file
All child .chm files
NetHelp
The entire contents of the hub project NetHelp folder. Since NetHelp is uncompiled HTML Help, the number of
files will vary. By default, click on the
index.html
file to open the project. (This file name can be renamed in
the
Default name
field of the
Help Targets
dialog box.)
Eclipse Help
The entire contents of the hub project EclipseHelp folder.
WinHelp
Hub project .cnt file
Hub project .hlp file
All child project .cnt files
All child project .hlp files
Microsoft Help Viewer
See Creating a Modular Help Project for Microsoft Help Viewer Targets.
Note:
When creating a hub project, avoid including spaces in any of the file names. Using spaces in file names will
disable the next/previous functionality of the modular Help system. If your .D2H project file contains spaces you can fix
this without renaming the project by specifying a name with no spaces in the
Base name
field in the
Help Targets
dialog box. See Creating Help Targets on page 133 for more information.
Standardizing Modular Help
In order for your modular project to mesh logically, it's important that all the pieces adhere to a set of standards. You
may want to create standards for the following:
Source and Target templates and/or cascading style sheets
Styles, and how they are used
Help window definitions (each project should use the same Windows)
Indexing conventions (keywords and groups)
Use of graphics and graphics format
Tone and style of writing
Map numbering for context-sensitive help
If you are using a centralized glossary, each project should not have terms in its local glossary; all items should be stored
in a central glossary (in the hub project).
71
Doc-To-Help 2014 User Guide
Creating a Modular Help System
399
File Organization
Good file organization makes it easier to manage your modular hub project and avoid errors.
Your file system should include:
A folder for the entire system
A subfolder for the hub project
A subfolder for each child help project
A subfolder to store the end-user project
redistributables
For example:
If your project has multiple authors, it is best to store the project on a network drive.
Creating a Hub Project
The hub (or master) project ties all of the child projects together. It should be a small project, but can contain information
that does not change often (such as a welcome message and company contact information) if you wish.
Before creating your project, set up your file system for the entire modular system. See File Organization on page 399
for more information.
If you create a new child project in the future that is not part of your original hub project, simply add it to the hub
project, and distribute both the new hub project and child project to the end user.
To set up a hub project
1.
Create your hub project. The project name should contain no spaces.
2.
Open the
Project Settings
dialog box. (See Setting Project Properties on page 182 for more information.)
3.
Select the
Is modular hub project
check box to make this a Modular Hub Project.
4.
Close the
Project Settings
dialog box.
5.
Open the hub project document and create placeholder topics for each of the child files you wish to associate
with the hub. There are several ways to structure this file, but you should only choose one. (The placeholder topics
will later be mapped to the child topics. This is done by editing the
Topic Properties
.) Document Structure
options:
Heading 1 placeholder topics only
One Heading 1, followed by placeholder topics (Heading 2’s)
One Heading 1, followed by content in Body Text, then the placeholder topics (Heading 2’s)
One Heading 1, followed by one Heading 2 and Body Text content, then the placeholder topics (Heading
2’s)
6.
To disable any automatic related links that may be displayed in the hub project, in the Topics tab, Related
Topics ribbon group on page 118, select the
Hide Subtopic Links
check box for each topic.
7.
Click the
Build Target
button to build the file.
8.
Add at least two index entries (one must be a keyword) to the project.
9.
Open the
Help Targets
dialog box. (See Creating Help Targets on page 133 for more information.)
113
400
Creating a Modular Help System
Doc-To-Help 2014 User Guide
10.
Choose the Help Target (can be HTML Help, NetHelp, Eclipse Help, or WinHelp) on the left. The hub project,
and all of the child projects, must use the same Help Target.
11.
Select the
Binary Index
check box. (HTML Help only)
12.
Clear the
Binary TOC
check box. (HTML Help only)
13.
Click the
Build Target
button to build the file.
To map placeholder topics to child topics
1.
Verify that all of your child projects are in the proper place in your modular system. See File Organization on
page 399 for more information.
2.
Open your hub project.
3.
Select a placeholder topic in the
Topics
window. Right-click on it and choose
Properties
. The
Topic
Properties
dialog box will open.
4.
Edit the
Topic Properties
. The properties changed will vary depending on the target of the entire modular
project.
For
HTML Help
targets, you need to specify the
Module File
(.chm) and
Contents file
(.hhc) fields of the
child project for the placeholder topic. (The .chm and .hhc can be found in the child project’s HTMLHelp
folder.)
For
NetHelp Classic
targets, you need to specify the
Module file
(.npj) field of the child project for the
placeholder topic. (The .npj file can be found in the child project’s NetHelp\ProjectInfo folder.)
For
NetHelp 2.0
and
Eclipse Help
targets, you need to specify the
Module file
field of the child project for
the placeholder topic. The
Settings.xml
file is used and can be found in the child project’s NetHelp or
EclipseHelp folder.
For
WinHelp
targets, you need to specify the
Module file
(.hlp) and
Contents file
(.cnt) fields of the child
project for the placeholder topic. If you wish, you can use the
Title
field to enter a different name for child
Help file (useful if two projects have the same name). (The .hlp and .cnt files can be found in the child
project’s Help folder.)
5.
Map all additional placeholder topics.
6.
Rebuild the project by clicking the
Rebuild
button. Click the
View Target
button to view the project.
Doc-To-Help automatically creates the TOC structure based on the order of the placeholders in the hub source
document. Each placeholder topic will be a “book” in the hub project TOC.
Note:
For
HTML Help
and
WinHelp
projects, you will need to place copies of the child project files (.chm for HTML
Help; .hlp and.cnt for WinHelp) in the same folder as the hub project files to view the complete modular project.
Whenever you do a full
Rebuild Target
(as opposed to a
Build Target
) those child files will be overwritten in the hub
project folder and must be replaced.
Note:
For
NetHelp
projects, all projects in the modular help system must be created with the same version of Doc-To-
Help. Please note that all of the projects must build the same version of NetHelp — NetHelp Classic or NetHelp 2.0.
Creating a Child Project
Child projects are tied together with the hub project (see Creating a Hub Project on page 399). There are no special
mappings in child projects, just a few settings and other options that need to be handled. You can create as many child
projects as needed.
Documents you may be interested
Documents you may be interested
