Navigation: Publishing > Command Line Publishing INI and batch files |
Scroll Prev Top Next More |
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.
Creating batch files for multiple command lines is very simple: 1.Just use a text editor (not a word processor!!) to create a plain text file with the extension .cmd or .bat (CMD is the more modern format). 2.Enter each command line exactly as you would in the command console, one command on each line. 3.Save the batch file and double-click it to execute it. If you are not familiar with Windows batch files you can find plenty of information about how to use them online. |
The easiest way to publish to multiple output formats from the command line is to call predefined publishing tasks created with the Publishing Task Manager using the /TSK= switch. See Automating Publishing Jobs for full instructions on using the Task Manager.
Although it is possible to mix the /TSK= switch with other switches it is easier to manage if you call publishing tasks on individual lines of their own. Unlike other switches, all you need for this switch is the HELPMAN.EXE filename, the project filename and the /TSK= switch with the task and action names. Publishing all the actions in a task:To publish all the actions in a task just include the task name on its own, like this: HELPMAN.EXE D:\Projects\widgets.hmxp /TSK="Daily Build" Publishing single actions in a task:To publish a single actions in a task add the name of the action after the name of the task, separated by a colon (:) character: HELPMAN.EXE D:\Projects\widgets.hmxp /TSK="Daily Build:Full CHM Output" Publishing multiple selected actions in a task:To publish a multiple (but not all) actions in a task use the /TSK= switch multiple times, once for each action. Alternatively, you can also write separate command lines for each action if you like. The result will be the same. HELPMAN.EXE D:\Projects\widgets.hmxp /TSK="Daily Build:Full CHM Output" /TSK="Daily Build:Full HTML Output" |
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 outputThe rules for multiple output 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 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 file name. Specifying the output explicitly allows you to publish to other destinations manually in Help+Manual without worrying about changing the destination of the .INI The first line publishes to HTML Help with a specific output directory and file name. 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. (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 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. •The TSK=Special line additionally executes a publishing task defined in the Publishing Task Manager. This can include a large number of publishing operations and is effectively like calling an additional batch file with all that it contains. •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. |
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.
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:
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 EPUB=project.epub
2) CHM=project.chm EPUB=project.epub KEEPTEMP
Example 1) above keeps the temporary files for both the CHM and EPUB output. Example 2) only keeps the temporary files for the EPUB output. The same applies for log files and debug information. See Syntax reference for more information on the individual switches and parameters. |
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. |
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 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: