Hyphenation

Hyphenation Dictionaries

The Oxygen XML Author Eclipse plugin provides built-in hyphenation patterns for the following languages:

Code	Language
da	Danish
de	German
de_CH	German (Switzerland)
en	English
en-GB	English (Great Britain)
es	Spanish
fr	French
it	Italian
nb	Norwegian Bokmål
nl	Dutch
ro	Romanian
ru	Russian
sv	Swedish
th	Thai
pt	Portuguese
da	Danish

The built-in hyphenation pattern license terms are listed in the XML files in the [CHEMISTRY_INSTALL_DIR]/config/hyph folder. Most of them comply with the LaTex distribution policy.

Installing New Hyphenation Dictionaries

Oxygen XML Author Eclipse plugin uses the TeX hyphenation dictionaries converted to XML by the OFFO project: https://sourceforge.net/projects/offo/.

The .xml files allow you to access the licensing terms and you can use them as a starting point to create customized dictionaries (see How to Alter a Hyphenation Dictionary).

The .hyp files are the compiled dictionaries that the Oxygen XML Author Eclipse plugin actually uses.

One simple way to add more dictionaries:

Download and extract the offo-hyphenation-compiled.zip file. This file is a bundle of many dictionary files.
Copy the fop-hyph.jar file to the [OXYGEN_INSTALL_DIR]/lib directory.
If you just need a single dictionary, place the .hyp or .xml file in the [OXYGEN_INSTALL_DIR]/config/hyph directory (create that directory if it is missing).

How to Alter a Hyphenation Dictionary

You can copy the dictionaries you need to change in another directory, then use the -hyph-dir parameter to refer them inside your transformation.

Each file is named with the language code and has the following structure:

<hyphenation-info>

<hyphen-min before="2" after="3"/>

<exceptions>
o-mni-bus
...
</exceptions>

<patterns>
préémi3nent.
proémi3nent.
surémi3nent.
....
</patterns>

</hyphenation-info>

To change the behavior of the hyphenation, you can modify either the patterns or the exceptions sections:

exceptions: Contains the list of words that are not processed using the patterns, each on a single line. Each of the words should indicate the hyphenation points using the hyphen ("-") character. If a word does not contain this character, it will not be hyphenated.
For example, o-mni-bus will match the omnibus word and will indicate two possible hyphenation points.

Note: Compound words (i.e. e-mail) cannot be controlled by exception words.
patterns: Contains the list of patterns, each on a single line. A pattern is a word fragment, not a word. The numbers from the patterns indicate how desirable a hyphen is at that position.
For example, tran3s2act indicates that the possible hyphenation points are "tran-s-act" and the preferable point is the first one, having the higher score of "3".

How to Enable Hyphenation for Entire Map

To enable hyphenation for your entire map:

Make sure you set an @xml:lang attribute on the root of your map, or set the default.language parameter in the transformation.
In your customization CSS, add:
```
:root {
    hyphens: auto;
}
```
To except certain elements from being hyphenated, use hyphens:none. The following example excludes the <keyword> elements from being hyphenated:
```
*[class ~= "topic/keyword"] {
    hyphens: none;
}
```

How to Enable/Disable Hyphenation for an Element

Make sure you set an @xml:lang attribute on the root of your map, or set the default.language parameter in the transformation.
You have two options to control hyphenation inside an XML element:
CSS Approach

Use the hyphens property.
For example, if you want to enable hyphenation in codeblocks:
```
*[class~="pr-d/codeblock"] {
    hyphens: auto;
}
```
If you want to disable hyphenation inside tables:
```
*[class~="topic/table"] {
    hyphens: none;
}
```
Attribute Approach

Use the @outputclass="hyphens" or @outputclass="no-hyphens" attributes/values.
For example, if you want to enable hyphenation in codeblocks:
```
<codeblock outputclass="hyphens">
  ...
</codeblock>
```
If you want to disable hyphenation inside tables:
```
<table outputclass="no-hyphens" ...>
  ...
</table>
```
Note: The default built-in CSS enables hyphenation for tables:
```
*[class ~= "topic/table"] {
    hyphens: auto;
}
```

How to Define Hyphenation for a Specific Word

Create a new hyphenation dictionary.
Add the word under the <exceptions> section using hard hyphen symbols between its segments.
To make sure the words from your document match against the ones from the "exceptions", make sure that you add capitalized/lower case variants as well.

How to Force or Avoid Line Breaks at Hyphens

It is possible to force or avoid line breaks inside words with hyphens (U+2010). This can be useful, for example, inside tables that have product references if you want the display to remain on a single line (or to split it on multiple lines). To achieve this, you can use the -oxy-break-line-at-hyphens property:

The accepted values are:

auto: Words are hyphenated automatically according to an algorithm that is driven by a hyphenation dictionary. This can lead to line breaks at hyphens.
avoid: Words are still hyphenated automatically except no line break will occur on hyphens.
always: Words are still hyphenated automatically except line breaks will be forced on hyphens.

Example:

Suppose you have a products table like this:

<table>
  <row>
    <cell>Product-1233-55-88</cell>
    <cell>120</cell>
  <row>
  <row>
    <cell>Product-1244-66-99</cell>
    <cell>112</cell>
  <row>
</table>

and the following rule in a CSS stylesheet:

table {
  -oxy-break-line-at-hyphens: avoid;
}

In the output, the list of product references will be displayed in a single line. On the contrary, setting the property value to always, will force a break after each hyphen.