Building Targets in Batch Mode

You may build targets in batch mode from the command line through a special executable program, C1D2HBatch.exe.

If you need to start a build from Windows Services (such as the Task Scheduler or TFS Build), you should use a different executable, C1D2HAgent.exe. See Building Targets Using Windows Services.

Both of these executables are located in C:\Program Files (x86)\MadCap Software\DocToHelp.

The commands are as follows:

Command

Description

Example

c1d2hbatch –build

Rebuilds the current target entirely.

c1d2hbatch -build "c:\D2H Projects\StyleGuide\StyleGuide.d2h" "StyleGuide NetHelp" -p

c1d2hbatch –make

Updates the current target.

c1d2hbatch -make "c:\D2H Projects\StyleGuide\StyleGuide.d2h" "StyleGuide Manual"

c1d2hbatch –build or make
-lLogFile (optional)

Saves the build log file with a specific name, rather than the default name, which is equal to the current date and time.

c1d2hbatch  -build "c:\D2H Projects\StyleGuide\StyleGuide.d2h" "StyleGuide Manual" -lmyfilename.log

Build log will be stored in the Temp\BuildLogs directory.

Note There is currently only one flag allowed in 'flags': -p, enabling the output of progress messages.

All error and log messages are sent to the console standard output and have the following format:

  • For errors aborting compilation:

    D2H:fatal error:[error code]: [message text]

    The [error code] is a numeric error code.

  • For logged user errors, compilation continues and every log error is output to the Output window:

    D2H:log error document:[document name]

    D2H:log error topic:[topic title]

    D2H:log error message:[severity]:[message text]

    The [document name] and [topic title] can be empty, depending on the nature of the error.

    The [severity] will be listed as one of the following three strings: "note," "warning," or "error."

  • A log message, for information only, shows what document is currently compiling, what action is being performed, and so on:

    D2H:log:[message text]

  • A progress message appears only if the -p flag is present:

    D2H:progress:[done]/[total]

    Here [done] is an integer number indicating how many steps of the currently performed action have been completed so far.

    The [total] is an integer number indicating the total number of steps in the currently performed action.

  • A progress completion message indicates that the current action has been completed, and it appears only if the -p flag is present:

    D2H:progress:done

  • An unresolved links list is the output at the end of a successful build when the -build or -make commands are used. Every unresolved link is output to the Output window:

    D2H:unresolved link text:[link text]

    D2H:unresolved link style:[style name]

    D2H:unresolved link topic:[topic title]

    D2H:unresolved link document:[document name]

  • For a successful build:

    D2H:succeeded

  • For a failed build:

    D2H:failed

  • The last message before Doc-To-Help batch mode exits:

    D2H:exit

Note In Windows 7 and later, C1D2HBatch.exe must be run as administrator, or it will always throw an exception. If you run it directly, start it with "Run as Administrator," available in Windows 7/8 in the context menu of the C1D2HBatch.exe file. If you run it from a command line prompt, open the command line window with "Run as Administrator." If you run it from a script or a program, make sure the script or program runs as administrator.