43.2.3.1 Constructing file names based on paragraph content

You can specify names for HTML or XML output files by designating a paragraph format to use for this purpose, and listing the format name in the [HtmlStyles] section. The content of each paragraph in this format becomes the base name of a new split part:

To use a paragraph format to name split files, assign the FileName property to the format:

[HtmlStyles]
paratag = FileName

Object ID replaces unusable content

If the content of a paragraph to which you assign the FileName property is empty, or consists only of characters that are not valid for file names, DITA2Go uses the internally assigned object ID of the paragraph for the file name instead (see §27.5.1 Understanding how split and extract files are named), along with any prefix or suffix you specify for file names (see §43.2.3.4 Specifying a file-name prefix or suffix).

Ensure valid file names

These cobbled-together split-file names are guaranteed to consist of valid file-name characters only with the following default setting:

[HTMLOptions]
; UseRawName = No (default, make [HtmlStyles] FileName valid) or Yes
UseRawName = No

When UseRawName=Yes, file names generated from paragraphs retain the full content of the paragraph, including any whitespace and punctuation; that is, unless the paragraph consists only of non-alphanumeric characters, in which case DITA2Go uses the internally assigned object ID of the paragraph for the file name.

When UseRawName=No, all whitespace and punctuation are removed from the file name, unless you set either or both of the following options to Yes; if you set either option, we can no longer guarantee that the generated file names will be valid:

[HTMLOptions]
; When UseRawName=No, allow underscores and spaces to be passed
; through from headings with the FileName property as follows:
; KeepFileNameUnderscores = No (default, remove underscores) or Yes
KeepFileNameUnderscores = Yes
; KeepFileNameSpaces = No (default, remove or change spaces) or Yes
KeepFileNameSpaces = Yes

When KeepFileNameSpaces=No, you can choose to replace each space in the file name with some other character:

[HTMLOptions]
KeepFileNameSpaces = No
; ChangeFileNameSpaces = No (default; if not kept, remove) or 
;  Yes (if not kept, replace with the FileNameSpaceChar, below)
ChangeFileNameSpaces = Yes
; FileNameSpaceChar = character with which to replace spaces,
;  default '_', used if both KeepFileNameSpaces=No and
;  ChangeFileNameSpaces=Yes
FileNameSpaceChar = _

The default replacement character is an underscore. The setting for FileNameSpaceChar takes effect only if both of the following are true:

The only non-alphanumeric character replaced is the space. All other non-alphanumeric characters are removed. For example:

Basic 40/41/42 Chipset

becomes:

Basic_404142_Chipset

The forward slashes are removed.

Previous Topic:  43.2.3 Using paragraph formats to name output files

Next Topic:  43.2.3.2 Basing output file names on existing paragraph formats

Parent Topic:  43.2.3 Using paragraph formats to name output files

Sibling Topics:

43.2.3.2 Basing output file names on existing paragraph formats

43.2.3.3 Creating special paragraph formats to name output files

43.2.3.4 Specifying a file-name prefix or suffix

43.2.3.5 Constructing file names from multiple paragraph formats

43.2.3.6 Preventing duplicate file names based on paragraph formats