OOXML Hacking: Managing Styles

Are you managing styles in your Word documents? A hallmark of a professionally-created template is the appearance of the Quick Style Gallery. If I open a template and see this:

Not Managing Styles

I realize the person who constructed the file doesn’t know better or doesn’t care. The clue are the 4 zombie styles on the right side. If you expand the gallery, you’ll see 8 more zombie styles. These 12 are automatically generated in every new installation of Word. Nobody uses them, they just clutter the interface. If you’re managing styles, you’ll make them disappear.

These 12 can’t be deleted, they are termed built-in styles and the Delete button is disabled in the style management dialog. But in Word for Windows, there is a Style Management panel called Recommended, where you can Hide them or optionally apply Hide Until Used. This last attribute keeps the style out of the Quick Style Gallery until the first time you apply it in a document, at which time it becomes visible.

But where is the Recommended panel in Word for Mac? Did someone Hide that too? No, it’s just not an option for Mac users. Microsoft left it out (speculate at will). But all is not lost: You can still manage style visibility on the Mac, you just have to do it with XML Hacking. New hackers should read XML Hacking: An Introduction and XML Hacking: Editing in macOS before trying these steps.

When you first open an Office XML field, the content is linearized and difficult to read. In BBEdit, apply Test>Apply Text Filter>run_tidy, an add-on script for BBEdit that you can download here. Voila! Readable XML!


Managing Styles with XML Editing

Word styles are stored in word/styles.xml and word/stylesWithEffects.xml. Word 2007/2008 reads styles.xml while Word 2010/2011 and later use stylesWithEffects.xml, so whatever changes you make, do them to both files. Word doesn’t always create a styleWithEffects.xml part, so if there isn’t one in your file, just edit styles.xml. Word’s built-in styles are in the w:latentStyles part. Let’s work on that first, then deal with custom styles.

The style order in the XML file has nothing to do with the order of styles in the user interface, so it’s best to search for them. Start with the Title style. The default listing looks like this: (You may see a somewhat different collection of tags from different Word versions.)

<w:lsdException w:name="Title" w:semiHidden="0" w:uiPriority="10" w:unhideWhenUsed="0" w:qFormat="1"/>
The Styles list: a good place to display occasionally-required typestyles.
Managing Styles: the master Styles List

To make this style disappear from the Quick Style Gallery, but still appear on the Styles list, just delete the w:qFormat="1" tag. If you want to remove a style not only from the Quick Style Gallery, but also from the master list of recommended styles, then don’t bother with w:qFormat="1", just remove w:semiHidden="0". Finally, to give the style the ability to remain on the Styles list, then be added to the Quick Style Gallery when it is first used, leave the other tags as is and change w:unhideWhenUsed="0" to w:unhideWhenUsed="1".

Besides the Title style, the other zombie styles you’ll probably want to remove are:

Subtitle
Subtle Emphasis
Emphasis
Intense Emphasis
Strong
Quote
Intense Quote
Subtle Reference
Intense Reference
Book Title and
List Paragraph

Another useful edit you can make to styles is to change the number beside w:uiPriority. Decreasing this number moves a style up the list, while increasing it moves it down. You may have noticed that editing w:uiPriority in the w:latentStyles has no effect on the position of Normal style. See Custom Styles below to solve this.

For all styles that have the same level number, they are displayed in alphabetical order. I usually rank them in the order they are likely to be used, with the body text and headings at the top, followed by bulleted, numbered and lettered styles. Often you’ll have styles that serve a function in a Word file, like unique styles that are referenced by StyleRef fields. If the user doesn’t need to apply a style, hide it. The simpler you make their interface, the fewer mistakes they can make.

The styles/stylesWithEffects XML parts contain a list of exceptions. There are many styles that remain invisible until you add an exception to the list. As an example, if you want to make the Body Text style to be at the left end of the Quick Style Gallery, you would first copy and paste the exception for Normal, then change the name to Body Text. The w:uiPriority=0 tag will ensure Body Text pops to the left end.


Managing Styles: Custom Styles

To manage custom and special styles, scroll down below the latentStyles section. Here you’ll see more verbose XML like this:

<w:style w:type="paragraph" w:default="1" w:styleId="Normal">
  <w:name w:val="Normal"/>
  <w:uiPriority w:val="1"/>
  <w:qFormat/>
  <w:rsid w:val="00AB271F"/>
</w:style>

Here’s where you can change the order of Normal. Because this XML part comes after the Normal entry in latentStyles, it over-rides those settings. Any style set to 0 will appear to the left of Normal in the Style Gallery and above Normal in the Styles List.

Here’s what a custom style looks like:

<w:style w:type="paragraph" w:customStyle="1" w:styleId="Code">
  <w:name w:val="Code"/>
  <w:basedOn w:val="Normal"/>
  <w:uiPriority w:val="6"/>
  <w:qFormat/>
  <w:rsid w:val="00A12E2B"/>
  <w:pPr>
    <w:spacing w:after="0" w:line="240" w:lineRule="auto"/>
  </w:pPr>
  <w:rPr>
    <w:rFonts w:ascii="Bitstream Vera Sans Mono" w:hAnsi="Bitstream Vera Sans Mono"/>
  </w:rPr>
</w:style>

While you could edit all attributes of the style here, it’s easier to do through the user interface. But you can change the order, here set to 6.

Save the XML file. If you’re using BBEdit, you’re done. If you’re working with another editor, re-zip [Content_Types].xml plus the folders. Change the ending of the resulting Zip file to .docx and click on the Use .docx button when OS X asks. Open the file and check out the beautifully clean Quick Style Gallery, thanks to you managing styles!

This is a complex topic, so don’t feel bad if it’s hard to get working as expected. If you’re on a deadline, Brandwares can do this for you. Just email me at production@brandwares.com.

OOXML Hacking: Editing in macOS

Note: I’ve included the original article text to describe the background issues about XML editing in macOS, but to retain your sanity, be sure to follow the May 2016 and July 2018 updates at the end and use a text editor that doesn’t require unzipping and rezipping the files

When you’re hand-editing Office files in Windows, it’s pretty straight-forward: unzip file > edit > rezip, you’re done. Editing in macOS requires a couple of extra precautions. This is because the graphical user interface adds Mac attributes to files and plants hidden files in folders. Office will not tolerate either of these:

Editing in macOS - The Open XML file cannot be opened because there are problems with the contents. Details The file is corrupt and cannot be opened.

XML error message in 2008


Editing in macOS - The Open XML file cannot be opened because there are problems with the contents or the file name might contain invalid characters (for example, \/). Details The file is corrupt and cannot be opened.

XML error message in 2011


Editing in macOS - The Open XML file cannot be opened because there are problems with the contents or the file name might contain invalid characters (for example, \/). Details The file is corrupt and cannot be opened.

XML error message in 2016

If you use macOS’s Archive Utility to unzip or zip the files, Word will refuse to open the resulting file. On top of that, if you look in any of the folders using the Finder, a hidden .DS_Store file will be created in the folder. When re-zipped, Word will not accept the extra file and again report an XML error. The solution to these issues is to use the command line, like the Unix warrior you want to be! Remember to run each Terminal command by pressing the Return key after typing the command.

A valuable utility for this is OpenTerminalHere. Open any Finder window, click on OpenTerminalHere and a terminal window opens pointed to the Finder window. So download and install it, then follow these steps to open, edit and re-zip Office files:

  1. Move a copy of the Office document (let’s call it TestDoc.docx) to a separate folder and open that folder in the Finder.
  2. Click on OpenTerminalHere to open a copy of Terminal aimed at the folder.
  3. In the Terminal, type
    unzip TestDoc.docx

    then press Return. The file is unzipped into several folders plus a file called [Content_Types].xml.

  4. Do not look in any of the folders using the Finder, or you’ll have to start over. To examine a folder’s contents, use the Terminal to change the folder, then list the contents:
    cd word

    ls -l
  5. To go back up to the previous folder, type:
    cd ..
  6. To edit the files, open your text editor, then navigate using the File>Open dialog to find the file. Edit the file, then save and close.
  7. When you’re all done, double-check that terminal is pointing at the original folder holding the documents and the expanded folders. If you’re unsure, close terminal, then click on OpenTerminalHere to reopen in the right spot.
  8. In Terminal, re-zip the files with this style of command:
    zip -r RevisedDoc.dotx [Content_Types].xml _rels docProps word

    This example is for Word, but the correct syntax after zip -r is to type the name of the final document, followed by the file and folders, each separated by a space. The file is reassembled into an Office file.

  9. Test that you can open it. If you get an XML error notice, re-read the above steps and try again.

Please note: these editing techniques are required when editing in macOS with Word, PowerPoint and Excel documents and templates, plus Office Theme files (the kind exported from PowerPoint that combine all Theme elements.

If, on the other hand, you are editing a Font Theme or a Color Theme, those are simple XML files. They don’t need to be unzipped or re-zipped and Office doesn’t seem to care about macOS attributes attached to them. These plain XML files don’t need to be handled through the terminal, just use the Finder.

Next time, we’ll be looking at managing Word styles in macOS. Finally, a way to get rid of the zombie styles automatically created by Word! Happy hacking!


March 2016 Update

An alternative to working entirely in Terminal is to work on a network or USB disk where creation od .DS_Store files has been turned off. On a network disk, open Terminal in your choice of folder and run the command:

defaults write com.apple.desktopservices DSDontWriteNetworkStores true

To use a USB disk, run this command instead:

defaults write com.apple.desktopservices DSDontWriteUSBStores true

While this will prevent future generation of the .DS_Store files in that folder and any subfolders, it’s very likely you already have such files, since they’re created almost as soon as you view a folder’s contents in the Finder. In addition, some important XML parts are hidden and need to be revealed. So while Terminal is open, run:

defaults write com.apple.finder AppleShowAllFiles YES

followed by:

killall Finder

The second line restarts the finder to force a refresh of the view. Now you can see any .DS_Store files and delete them before re-zipping the files into an Office document. You’ll have still have to do the zipping in Terminal. Also, no .DS_Store files means OpenTerminalHere doesn’t work, so you’ll have to navigate manually via Terminal commands. Now you know why this is a lame alternative.

If you try this technique, you can always restore the clean file view by running:

defaults write com.apple.finder AppleShowAllFiles NO
killall Finder

Once you’ve created this OOXML editing drive, you can use the command-line zip utility to unzip the files. But there’s also a very useful GUI utility that works better than Archive Utility with Office files. Visit the App Store and get The Unarchiver. Then use it to unzip and expand the Office file.


Editing in macOS – May 2016 Update

BBEdit 11 and better has the ability to open and edit Office files directly, avoiding all of the above hassle when editing in macOS. BBEdit has a 30-day free trial with all features included. While older versions of BBEdit used Tidy to format text, that utility has been retired. The BBEdit programmers have written a script to format XML in human-readable form. You can download it from here, please be sure to read the installation instructions first: Click to download XML Tidy Script for BBEdit

Here’s your working procedure:

  1. Open your Office file in BBEdit 11 or later. In the left-hand pane, you’ll see a folder tree of the files contained within, so no unzipping is required
  2. Select the file you want to edit. The file opens in the main BBEdit window, displaying two lines. The first is the XML header, the second is the actual content.
  3. Click at the left end of the second line.
  4. Choose Text>Apply Text Filter>run_tidy.
  5. Make your edits and save. It’s not necessary to linearize the XML. The Office program will do that anyway the first time you save it. However, if you like to leave things exactly the way you found them, click in from of the first line of content (after the header line), choose Markup>Utilities>Format…, change the Mode to Compact and click on the Format button. Save the file and test your editing in macOS.


Editing in macOS – July 2018 Update

Technology marches on! If you use the Chrome browser, there is a free XML editing alternative that avoids unzipping and rezipping files. Open this link in Chrome: OOXML Tools and download the free plugin. After installation, click on the OOXML icon to the right of the browser address bar. Drag your Office files onto the browser window to begin editing. When you’re finished, click on the Save button, then the Download button in the upper left corner and give the new file an appropriate name. Chrome will place the new file in your Downloads folder and leave the original file untouched. OOXML’s EMF/WMF bug has been fixed, so download the most recent version. Thanks to Bram Alkema of the Netherlands for informing us about OOXML Tools.

Please note, for any OOXML Hacking that requires adding new XML parts (Ribbon mods, creating SuperThemes), BBEdit and OOXML Tools will not work. You’ll have to use the March 2016 update solution and create a network or USB disk set up for XML editing.

We’re experts in XML hacking, so you don’t have to be. Contact me at production@brandwares.com with the details of what you need hacked.

OOXML Hacking: Font Themes

Font themes are one of the simpler theme elements in Open Office XML, but for some baffling reason, Mac Office users can’t create one. It’s odd enough that the only Mac program that can create a color theme is PowerPoint, but even it can’t provide an escape from Calibri and Arial! So I’m going to show you how to do it on your own.

Let’s start with a dead-simple font theme. Here’s the minimal file that Office will read:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<a:fontScheme xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" name="Test">
  <a:majorFont>
    <a:latin typeface="Arial"/>
    <a:ea typeface=""/>
    <a:cs typeface=""/>
  </a:majorFont>
  <a:minorFont>
    <a:latin typeface="Arial"/>
    <a:ea typeface=""/>
    <a:cs typeface=""/>
  </a:minorFont>
</a:fontScheme>

Important Note: If you copy and paste this sample, you must change the non-breaking space characters to ordinary spaces. I need to use non-breaking spaces to format an HTML page, but Office will refuse to display your font theme if you don’t search and replace them with regular spaces.

You can create this in any text editor, including TextEdit in plain text mode (don’t try this with an rtf file). However, by default TextEdit will change the necessary straight quotes to smart quotes, producing a file that Office will not recognize. If you’re using TextEdit, make sure you visit both TextEdit>Preferences and Edit>Substitutions and turn off Smart Quotes in both locations. A better alternative is the free version of BBEdit. When you visit this link, click on the Download link to get the free version. If you do any significant amount of XML editing, the paid version of BBEdit is well worth the $50 price tag.

The most common font theme problem is using smart quotes (Hex 201C + 201D, Decimal 8220 + 8221) other than plain straight quotes (Hex 22, Decimal 34). But you can also ruin a font theme by using non-breaking spaces (Hex A0, Decimal 160) instead of regular spaces (Hex 20, Decimal 32). Even though a font theme is encoded in UTF-8, you should only use plain ASCII characters for the text. XML has a low tolerance for non-standard characters.

Now that you’re set up to edit, copy and paste the font theme file. The <a:latin> tag is the standard font for your theme. <a:majorFont> is for headings and <a:minorFont> for text. Fill in <a:ea> with a font that supports Chinese or Japanese (ea stands for East Asian), if you want to support those languages. The <a:cs> tag stands for complex scripts: Arabic, Thai, Hebrew and many more. For more detail on non-European language support in font themes, please see my article XML Hacking: Font Themes Complete. Or you can just leave those tags blank if you have a predictable user base that won’t require them.

A common mistake is to get too specific with the font name in font themes. The name is only the base font name as displayed in Powerpoint’s font menu. “Open Sans” will work, but “Open Sans Extrabold” will cause Word 2011 to display a blank space where the font theme should be, while Word 2016 will simply ignore the entire file.

Save the file as a text file with a .xml ending and give it the name you want to appear in the user interface. “Brandwares.xml” will appear in the Font Theme menu as Brandwares.

For Office 2016 or 2019, save this file to Users/YourUserName/Library/Group Containers/UBF8T346G9.Office/User Content/Themes/Theme Fonts. For Office 2011, save it to Users/YourUserName/Library/Application Support/Microsoft/Office/User Templates/My Themes/Theme Fonts. In current versions of OS X, the user Library is hidden by default. To open it, hold down the Alt key, while clicking on the Go menu and choosing Library.

Once it’s correctly installed, it will show in PowerPoint’s Slide Master view under the Fonts dropdown. A new Custom group will appear at the top of the list, with your font theme in it. Once you apply it and a color theme to a presentation, you can save as a theme file and distribute that to your users, it will contain the font theme you just created. Happy hacking!


Font Themes – An Alternate Method

March 2017 edit: If you have any problems creating a font theme from scratch, here’s a workaround. Open an existing font theme that come with Office and edit the font names to the ones you want to use. These files are the verbose style discussed in this article: XML Hacking: Font Themes Complete. For most uses, you only need to set the a:latin font in the a:majorfont and a:minorfont sections. Here’s where you can find the Microsoft Font Themes:

Office 2011 for Mac – Open Applications/Microsoft Office 2011/Office/Media/Office Themes/Theme Fonts and copy any of the XML files.

Office 2016 or 2019 for Mac – Open Applications, then right-click on Microsoft PowerPoint and choose Show Package Contents. Open Contents/Resources/Office Themes/Theme Colors and copy any of the XML files in there.

Here are the locations for 32-bit versions of Windows. If you’re using a 64-bit version of Windows, check the same path inside C:\Program Files (x86).

Office 2007 for Windows – Open C:\Program Files\Microsoft Office\Document Themes 12\Theme Fonts.

Office 2010 for Windows – Open C:\Program Files\Microsoft Office\Document Themes 14\Theme Fonts.

Office 2013 for Windows – Open C:\Program Files\Microsoft Office\root\Document Themes 15\Theme Fonts.

Office 2016 or 2019 for Windows – Open C:\Program Files\Microsoft Office\root\Document Themes 16\Theme Fonts.

Too complicated? We can help! Brandwares is a full service template creation service for all Office programs. Contact me at production@brandwares.com

OOXML Hacking: Table Styles Complete

Custom Table Styles are probably one of the more detailed hacks you’ll have to write. See the constructions details in my previous post. Besides the basic table format, there are 6 optional format layers you need to at least consider. In a minimal table style, you’ll need to include at least the Header Row, First Column and Banded Rows. Most users will expect to see these options. Total Rows, Last Columns and Banded Columns are less requested, you only need to include them if a design or client specifically requires them.

As mentioned in part 1, if you haven’t hacked XML before, please read XML Hacking: An Introduction. If you’re using a Mac, you should also read XML Hacking: Editing in OS X. In addition, an essential companion to this pair of articles is the post on setting Default Table Text, which is set in a different XML component..

Let’s take a look at how our work appears in the PowerPoint interface. First, we’ll insert a plain vanilla table. By default this takes on colors and fonts from the current PowerPoint theme:

Default Table Style

Next, we choose the Table Tools>Design tab, open the Table Styles gallery. Up at the top a new Custom section has appeared with our new custom table style:

Select Custom Table Style

Select the custom table style and the default table changes to match our design. This screen shot has all formatting options turned off, so effectively we are seeing the Whole Table formatting only.

All Table Style Options Off

Table Style Options: Banded Rows and Header

Using the options panel in the upper left corner, we can add some of optional formatting layers we created in XML. First, let’s turn on banded rows. If you remember, we only formatted odd-numbered rows, so the banding only changes rows 1 and 3 in our example:

Table Style Banded Rows

Next, we’ll leave banded rows on and also add the Header row. This row doesn’t count as part of the table body, so the banding moves down 1 row:

Banded Rows and Header

Table Style Options: First and Last Columns

Next, we’ll turn off banded rows, leave the Header as is and add the first column:

Table Style Header Row and First Column

Here’s the table with First and Last Columns checked:

Table Style First and Last Columns

Table Style Options: Header and Total

And finally, Header and Total Rows:

Table Style Header and Total Rows

As you can see, with some pre-planning, one table style can cover quite a few related table looks. The layer options for different features make the table useful for many different purposes and the options panel makes it fast and easy for users to try different combinations. This feature is a major advance over tables in PowerPoint 2003 and earlier, which were quite crude by comparison.Table styles a similar way in Word, PowerPoint and Excel. While Word and Excel include table style editors in their interface, PowerPoint needs to be hacked to create them. Sadly, the table style specs for the different parograms are dissferent, so it’s not possible to trasfer tables style OOXML among Word, Excel and PowerPoint.

Table Styles: What You Can’t Do

You cannot set vertical cell/row alignment or cell margins in default taxt table text or a table style. It would have been possible given the OOXML spec, but Microsoft just didn’t bother.

Of course, if the process is too complex, we’re here to help. The current price on a custom table style is US$120. Just email me production@brandwares.com