Changing the Output File Naming Convention

By default, ePublisher names the generated topic files and rasterized graphics using a basic convention of the form filename.x.y.z.ext, with the following elements:

filename

The name of the source document containing the content.

x

A number representing the document's position in the Document Manager list.

y

A number representing the position of the topic in the sequence of page splits from that document.

z

Graphics only. Represents the position of the graphic in the sequence of images from the given topic.

ext

The appropriate file extension (e.g., 'html') defined in the Style Designer.

This naming convention is defined in a file called names.xsl, located by default in the ePublisher Pro installation direectory, here:

To modify the names used for your generated files, you have two options: insert markers or perform an override.

Option 1: Insert Markers

Out of the box, ePublisher supports several custom marker behaviors. You can insert markers with the 'file name' behavior throughout your source content to define a name for each corresponding topic file. You can even name rasterized graphics by adding a text box to the anchored frame (FrameMaker) or graphic and inserting a filename marker there. See the ePublisher Pro documentation for more information on Filename markers.

Option 2: Perform an Override

Alternately, you can modify the actual naming convention itself, changing the way ePublisher constructs the file names to suit your needs without editing your source documents. You'll need to perform an override on names.xsl and make the appropriate changes there. Follow these steps:

  1. Create a copy of the override file and paste into the appropriate directory in your project folder. Choose one of the following destinations (case-sensitive) in your project folder:

    • [Project folder]/Formats/Shared/common/splits/names.xsl

    • [Project folder]/Targets/[Target name]/Shared/common/splits/names.xsl

  2. Open the new copy of names.xsl in an XML- or text-editing application (e.g., NotePad).

  3. To change the naming of HTML topic pages, modify the "SplitPath" template; for graphics, edit the "FramePath" template. Sample changes are demonstrated below.

  4. Save names.xsl and regenerate your output to apply the changes.

Example

The portion of each template that you'll likely want to modify will look like this (this one is from SplitPath): 

   <xsl:choose>
    <xsl:when test="string-length($VarFileNameHint) &gt; 0">
     <xsl:value-of select="$VarFileNameHint" />
    </xsl:when>

    <xsl:otherwise>
     <xsl:value-of select="wwfilesystem:GetFileNameWithoutExtension($ParamSplit/wwsplits:Document/@path)" />
     <xsl:text>.</xsl:text>
     <xsl:value-of select="$ParamSplit/wwsplits:Document/@position" />
     <xsl:text>.</xsl:text>
     <xsl:value-of select="$ParamSplit/@position" />
    </xsl:otherwise>
   </xsl:choose>

That code simply says, "If a Filename marker exists, use that; otherwise, use the standard naming convention." If, for example, you were interested in using a topic's heading/TOC title as the file name (provided no two topics use the same heading text), you could change it to this: 

   <xsl:choose>
    <xsl:when test="string-length($VarFileNameHint) &gt; 0">
     <xsl:value-of select="$VarFileNameHint" />
    </xsl:when>

    <xsl:otherwise>
     <xsl:value-of select="$ParamSplit/@title" />
    </xsl:otherwise>
   </xsl:choose>

If you have implemented other custom file naming conventions, I encourage you to contribute to this article by adding an example of your names.xsl modification here.

More details sent to "wwp-users" on 2008-02-22

Output file names are set by the following XSL transform:

You can create an "override" for your format to change our default behavior by copying this from from our application area into your project area:

to:

Now, you can modify your project copy of "names.xsl" to obtain your desired behavior.

To change "names.xsl" effectively, you need three pieces of information:

  1. Available data
  2. Where in the XSL the name is set
  3. Overview of the XSL template

1. Available data

2. Where in the XSL the name is set

3. Overview of the XSL template

Additional comment/question

I have attempted to use Option 1 to change the file name, but it does not seem to work. I am using 9.3 with Framemaker 7.0. I used the instructions located at this page: http://www.webworks.com/Technical_Assistance/Online_Manuals/ePublisher_Pro/05_AddingFeatures.7.6.shtml

but to no effect, I still get the auto-generated file names (e.g. overview.1.1.html, overview.1.2.html, etc.). I tried having the marker at the beginning of the header, in the middle, tried target file names with and without spaces, but in vain so far.

Is there something missing from the instructions on the page mentioned above?

Did you configure "Filename" markers in the "Style Designer"?

I sucessfully implemented the code change as an override in my project's names.xsl file. With assistance from Ben A., I now have my output using underscores in the file name using the @title code. This aids our deployment to Unix systems. Ben advised doing this change:

The code would change from:

to:

The translate() function did the trick. This saves adding hundreds of filename markers to our files. Hopefully it will do the same for you.

Regards,

--Allen Beebe

In version 2009.2, I no longer have to use this customization code in names.xsl. Now I use the Target Settings... Files --> Convert spaces to underscores (enabled) and page naming pattern to $H; to generate the same type of filenames that use the soruec file (FrameMaker) topic headings. This feature has made stationery updates much easier.

Regards,

--Allen Beebe

HelpCenter/Tips/CustomFileNames (last edited 2009-08-07 15:12:10 by AllenBeebe)