StyleCleanup Script Documentation - BCLibCoop/nnels-a11y-publishing GitHub Wiki
Instructional Videos:
https://app.box.com/s/0gbm9x889qxlwfu1ky9uf8bh09wp4py3 https://app.box.com/s/mjrfys89fcfmdra9gwoiyyc04zxen5li https://app.box.com/s/tll0ypljvghmzsse1e1bjrhvg5fwzxxl
Downloading
To download a release version, right-click the link below, and save or open in new window:
If you opened in a new window, you'll have to save the window from your browser. Make sure to use a file name extension .jsx. Some browsers will try to force a .txt or .jsx.txt file name extension.
Make sure to only run this script on A COPY of an original document. The script will make irreversible changes to the document.
When run, this script will
- generate a report in a human-readable text file using Markdown markup
- create some new paragraph and character styles.
You will then need to use InDesign to either collapse or rename various styles prior to an export.
The report file will appear next to the InDesign file, but with an .md extension.
If the InDesign file is MyFile.indd, the report will be saved in MyFile.md.
IMPORTANT If you happen to open an InDesign file created with an older version of InDesign than yours, you MUST re-save the InDesign file first before running the script. This will upgrade the old document to the your version of InDesign.
More info about installing scripts:
https://indesignsecrets.com/how-to-install-scripts-in-indesign.php
Collapsing Styles
The second part of the cleanup method is to use InDesign.
The script cannot really decide what is relevant and what not, but it makes it easier to clean up and remove irrelevant styling.
You can delete a character style or paragraph style, and InDesign will show a dialog window and ask you whether you want to replace it with another existing style.
On the same dialog window, you should also deselect the option Preserve Formatting, otherwise you'll be reverting the affected text style runs to a manual override.
I call this operation 'collapsing' styles. If you have Style1 and Style2, then delete Style2 replacing it with Style1 without preserving formatting, you've collapse the two styles into just Style1.
Converting Manual Overrides
The first part of the cleanup method, before collapsing any styles, is to create named styles for any manual overrides in the text.
In what follows:
- InDesign creator = person who made the InDesign file
- Ebook creator = person who is converting the InDesign file to an Ebook
If there is some body text, and the InDesign creator manually applied some Italic to a bit of the text, the script will detect this, and create a named style for it (e.g. ArtificialCharStyle_123).
If the InDesign creator made more of the same manual changes, then all will be mapped to the same named style. All such manual Italic will become ArtificialCharStyle_123.
The Ebook creator can run the script, which will remove all manual overrides by the InDesign creator (either for paragraphs or for character runs), and replace them with an artificial style.
The appearance of the text will probably change somewhat, and the text will reflow a bit.
This is because the script will purposely ignore some more advanced InDesign features (e.g. tracking) when deciding whether two ranges of text have the same manual style override.
For example, imagine the InDesign creator has applied Italic and also tightened the tracking on one range of body text, then applied Italic without touching the tracking on a different range of body text.
When run by the Ebook creator, the script will use the same artificial style for both ranges of text, and one of the two ranges will take on a different tracking setting than it had before, and text will reflow a bit.
Simplifying Styles And Ranges
In InDesign, paragraphs and characters have many 100s of attributes.
Obvious attributes are things like font, point size, color...
But there are many, many more.
When trying to rationalize the styles and manual style overrides in an InDesign document, we're faced with the issue that very often no two text ranges are styled totally the same. Yet the difference is irrelevant for our purposes (export to Ebook).
That means the script cannot simply compare the style attributes of two ranges or styles to decide whether they are 'the same' or not.
To cope with that problem, I've devised a technique where the script is configured to ignore nearly all style attributes and only take into account a very limited number of attributes.
Configuring The Attributes To Consider
If you look in the release version of the StyleCleanup.jsx script, you'll find something like:
var ATTRIBUTES_FOR_STYLE_COMPARISONS = {
ParagraphStyle: {
alignToBaseline: 0,
allowArbitraryHyphenation: 0,
appliedFont: 1,
appliedLanguage: 0,
appliedNumberingList: 0,
... snip (very long list) ...
xOffsetDiacritic: 0,
yOffsetDiacritic: 0
},
CharacterStyle: {
appliedFont: 1,
appliedLanguage: 0,
basedOn: 0,
baselineShift: 0,
capitalization: 1,
characterAlignment: 1,
characterDirection: 1,
characterRotation: 1,
... snip (very long list) ...
verticalScale: 1,
... snip ...
xOffsetDiacritic: 0,
yOffsetDiacritic: 0
}
};
These are lists of attributes. Most of these lines have a 0 at the end - which means: 'ignore'.
A few lines have 1 at the end. This means the attribute on that line is considered relevant.
I've selected the attributes I thought were relevant.
The underlying idea is that my choices are not meant to be cast into stone, and the Ebook creator can adjust things and add or remove attributes to be considered.
The ones I've set to 1 are:
var ATTRIBUTES_FOR_STYLE_COMPARISONS = {
ParagraphStyle: {
appliedFont: 1,
capitalization: 1,
characterAlignment: 1,
characterDirection: 1,
characterRotation: 1,
fillColor: 1,
fillTint: 1,
firstLineIndent: 1,
fontStyle: 1,
horizontalScale: 1,
justification: 1,
lastLineIndent: 1,
leading: 1,
leftIndent: 1,
paragraphJustification: 1,
pointSize: 1,
rightIndent: 1,
ruleAbove: 1,
ruleBelow: 1,
spaceAfter: 1,
spaceBefore: 1,
underline: 1,
verticalScale: 1
},
CharacterStyle: {
appliedFont: 1,
capitalization: 1,
characterAlignment: 1,
characterDirection: 1,
characterRotation: 1,
fillColor: 1,
fillTint: 1,
fontStyle: 1,
horizontalScale: 1,
leading: 1,
pointSize: 1,
underline: 1,
verticalScale: 1
}
};
Calculating A Hash
Using these attributes, the script will calculate a representative text string for each paragraph style, character style, paragraph and text style range. I call this a 'hash'. The advantage of using a hash is that they are easy to compare in a script: rather than painstakingly comparing many attributes, I simply compare two strings to decide whether two style ranges are 'the same'.
This string encodes all the names and values for each of the relevant attributes concatenated together.
When two InDesign elements have the same hash, they are considered to be 'synonymous' (i.e similar enough to be considered 'the same' for our purposes).
What The Script Does
- It will compare all named paragraph styles and character styles and report any such styles that are 'the same'.
So, if a document has two character styles, say Body Emphasis and Sidebar Body Emphasis, the script might report that these two styles look the same, for the purpose of Ebook export.
It is then up to the Ebook creator to decide whether these two styles should be 'collapsed' into one or not.
- It will replace all manual overrides by new paragraph or character styles whose name starts with
Artificial....
Instead of creating a new artificial style for each individual text style range, the script will attempt to keep the number of artificial styles down, and it will re-use the same artificial style for text style ranges that are styled very similarly.
After the script has run, the Ebook creator can inspect each artificial style, rename them if they are relevant, or collapse them with another style if they are not relevant.
Tidbits
To generate a list of paragraph style attributes as seen in CONFIG.jsx,
I opened the sample test document, then ran the following script:
var s = app.activeDocument.stories.item(0);
var p = s.paragraphs.item(0).appliedParagraphStyle;
for (var a in p) {
$.writeln(a);
}
I then sorted the attribute names, and set them all to 0 to start with
For char styles:
var s = app.activeDocument.stories.item(0);
var p = s.paragraphs.item(0).appliedCharacterStyle;
for (var a in p) {
$.writeln(a);
}