JustHyp

Summary: Client-side multilingual text hyphenation and margin filling (full justify).
Version: 0.1.0 (14-Nov-2012)
Prerequisites: PmWiki 2.2.1 or later, Javascript enabled on browser (gracefully degrades).
Status: Active, alpha
Maintainer: SteP
Demo:
License: GPL license.
Users: (view? / edit)
Discussion: JustHyp-Talk

Questions answered by this recipe

  • How can I fill paragraphs as tightly as possible?
  • How can I hyphenate multiple languages in the same page?
  • Is there an automatic way to hyphenate words?

All sections are optional, you can remove those that do not apply to your recipe, and add new ones.

Description

JustHyp uses Hyphenator.js to hyphenate blocks of page text. It supports multiple languages. JustHyp also sets CSS styles to justify the page text.

When JustHyp is enabled by default all page text is hyphenated and justified. If you want to format just some text use markup (:justhypblock:).

Some browsers display hyphenated text incorrectly, so hyphenation is disabled by default for such browsers. Justification is always enabled for all browsers.

Acknowledgments

This cookbook would not be possible without Mathias Nater's excellent hyphenation script (version 4.1.0) which is the gist of what this cookbook provides. Browser detection is based on Peter-Paul Koch's BrowserDetect.js as of 2011-08-05. JustHyp liberally reuses code from Dave Gilbert's excellent BlogIt cookbook. I am indebted to all testers who report browser-dependent issues and document supported versions. There are just too many browser combinations for me to test alone.

Download and Install

  1. Download the archive file and unzip it into PmWiki's top folder.
  2. Add to your local config.php or farmconfig.php files:
    include_once("$FarmD/cookbook/justhyp.php");
  3. Optionally customize cookbook settings before including justhyp.php.
    1. If your site uses multilanguage cookbooks it is recommended to set at least:
      $jh_Lang = '{$Lang}'; #set by MultiLanguageViews/MultiLanguage cookbooks
    2. If your site loads jQuery before justhyp.php you can reuse the existing jQuery by setting:
      $jh_Load_jQuery = 0; #reuse a previously loaded instance such as BlogIt's
  4. Optionally add suitable translations for 'Fit text' and 'Test browser' to your local XL page.

Configuration

Optionally you may customize cookbook behavior by changing any of its user settings before including the cookbook file.

User Settings

$jh_JustHyp_EnabledEnable(1)/disable(0) JustHyp cookbook. Test in wiki pages with (:if enabled jh_JustHyp_Enabled:)
$jh_JustEnable(1)/disable(0) text justification altoghether.
$jh_HypEnable(1)/disable(0) text hyphenation altoghether.
$jh_LangLanguage tag denoting the page hyphenation language. If $jh_Lang is {$Lang} [sic] then $jh_Lang is set to the value of PHP variable $Lang. Cookbooks MultiLanguageViews and Multilanguage set variable $Lang.
$jh_ModeSet auto/manual page hyphenation and justification mode. When auto mode (default) is active all HTML tags in $jh_Tags are justified and hyphenated unless they are marked with wikistyles (or contained in elements marked) %nojust% and %nohyp% respectively. When manual mode is active no tags are changed but the ones marked (or contained in elements marked) %just% and %hyp% respectively.

Advanced User Settings

General
$jh_ActionsAn array of PmWiki actions for which the cookbook is enabled, browse is the default value. Note that the default setting disables the cookbook when page editing and previewing takes place (action edit). Hyphenating edited text is undesirable because it would scatter invisible hyphens (­) in your source text, which would then be littered upon saving the page.
$jh_ButtonDown, $jh_ButtonUpUp/down toggle button image URLs.
$jh_CookieUnique cookie name prefix.
$jh_HyphenatorJsUrlURL of alternate Hyphenator.js file. JustHyp bundles and uses the standard Hyphenator.js file so there is no need to set this value. However, if you have optimized hyphenator you may set this variable to the path of the optimized file.
$jh_Load_jQueryBy default JustHyp loads its bundled jQuery.js file. If your wiki configuration loads a different jQuery.js before JustHyp you can skip loading JustHyp's jQuery by setting $jh_LoadjQuery = 0.
$jh_NoHypBrowsersList of known incompatible browsers for which hyphenation is disabled. The default setting excludes all versions of Opera and unknown versions of Safari.
$jh_cjusthyp, $jh_cjust, $jh_chypReserved class names, default justhyp, just, hyp. If you change these you need to change justhyp.css accordingly.
$jh_MinWordLengthDo not hyphenate words shorter than this limit, default 4. The higher this number the faster the hyphenation phase but potentially the less compact the resulting text.
  
Target Selection
$jh_TagsComma-separated list of HTML tags whose content is to be formatted. Default value a,li,span,p.
$jh_TargetsComma-separated list of target DOM elements. The default setting targets all common page content while excluding the sidebar.
$jh_FilterComma-separated list of jQuery selectors that filter elements out of $jh_Targets. The default setting excludes all elements that have HTML class nojusthyp.
$jh_FilterDescendantsExclude also all descendants of filtered targets (default true).
  
Descendants (see also this section)
$jh_AutoNoJustHypComma separated list of jQuery selectors that are automatically excluded from justification and hyphenation in auto mode. Ignored in manual mode. The default setting generically excludes page and group titles, [@...@] markup, and HTML tags code,pre,h1,h2,h3. This setting affects also all descendants of selected elements.
$jh_AutoJustComma separated list of jQuery selectors (and their descendants) that are automatically justified in manual mode. Ignored in automatic mode. Empty by default.
$jh_AutoHypComma separated list of jQuery selectors that are automatically hyphenated in manual mode. Ignored in automatic mode. Empty by default.

Supported Language Hyphenation Patterns

By default JustHyp assumes that the input text is English (en). Set a different language with PHP variable $jh_Lang, which affects the whole page, or markup (:justhypblock lang=LANGUAGE:) ... (:justhypblockend:), which affects just the included text block. You can place different language blocks in the same page.

JustHyp bundles version 4.1.0 of Hyphenator.js which supports the following languages: English (US and GB), German, French, Dutch, Swedish, Spanish, Malayalam, Tamil, Hindi, Oriya, Kannda, Telugu, Bengali, Gujarati and Panjabi, Italian, Finnish, Russian, Polish, Danish, Portuguese, Hungarian, Czech, Ukrainian, Turkish, Armenian, Lithuanian, Slovenian, Latin, Greek (monoton, polyton and ancient), Belarusian, Norwegian, Latvian, Catalan, Serbian Latin script, Esperanto, Estonian.

Usage

Markup

General
(:justhyp mode=auto|manual:)Set page justification and hyphenation mode.
(:justhyp toggle=1 [ text='link text' ] :)Add a text link that toggles justification and hyphenation of the page. It is intended mainly to help users work around browser-dependent copy-paste issues. The link is styled in pub/justhyp/justhyp.css.
(:justhyp toggle=1 button=1 [ text="tooltip" ] :)Add a toggle button instead of a text link. Specify text="tooltip" to set the button tooltip. Change default down/up images by means of cookbook variables.
(:justhyp test=1 [ text='link text' ] :)Add a text link that re-runs the hyphenator while forcing hyphenation regardless of the browser version. It is intended mainly as an aid in testing browser support for hyphenation. The link is styled in pub/justhyp/justhyp.css.
  
BlockA,B
(:justhypblock lang=LANGUAGE:) ... (:justhypblockend:)Set hyphenation language of the delimited text/markup block.
(:justhypblock just=1|0:) ... (:justhypblockend:)Enable(1)/disable(0) justification of the delimited block.
(:justhypblock hyp=1|0:) ... (:justhypend:)Enable(1)/disable(0) hyphenation of the delimited block.
  

Notes
A Block markup cannot be nested.
B When (:justhypblock:) omits options hyp= or just= the default behavior of the current mode is applied for the omitted option.

Page Variables

$jh_JustHypEnabledEnable JustHyp cookbook.
$jh_LangPage hyphenation language.
$jh_ModePage justification and hypenation mode.

Wikistyles

%nojusthyp%Disable justification of the target element and its descendants; disable hyphenation of the target element.
%nojust%Disable justification of the target element and its descendants (automatic mode).
%nohyp%Disable hyphenation of the target element (automatic mode).
%pnohyp%Propagating %nohyp - Disable hyphenation of the target element and its descendants.
%just%Enable justification of the target element and its descendants (manual mode).
%hyp%Enable hyphenation of the target element (manual mode).

Examples

example 1 · example 2

Advanced Topics

Browser Support

Some browsers have issues in displaying hyphenated text and/or copy-pasting hyphenated text (a.k.a. safecopying) as follows:

  • Hyphenation issues: not showing ­ hyphens at end of line and/or showing &8203; invisible hyphens
  • Safecopy issues: copying ­ and/or &8203; to the clipboard and consequently pasting such characters into other applications.

Since hyphenation issues affect the look of the page, this cookbook does not perform hyphenation for browsers which have recognized hyphenation issues. For testing purposes hyphenation can be forced by means of markup (:justhyp test=1:).

Since safecopy issues are less important because they do not affect the look of the page but instead affect copying and pasting text from the browser into other applications, this cookbook leaves hyphenation on for browsers which have safecopy issues. For clipboard usability purposes hyphenation and justification can be toggled by means of markup (:justhyp toggle=1:).

Potentially any browser/OS pair could have issues in dealing with hyphenated text, so combinations need to be tested one by one. Such testing relies on users' reports and is summarized in the work-in-progress table below. When reporting new issues please include the output of markup (:justhyp test=2:). It is also useful to report no issues, that is when a browser/OS pair works correctly both for hyphenating and safecopying. Feel free to edit the table below to add new data.

edit this table

Tested Platform/OS Tested Browser (:justhyp test=2:) Issue Type Issue Description Support Status

(:cellnr:)platform/OS(:cell:)browser(:cell:)test=2(:cell:)hyp/copy/none(:cell:)desc(:cell:)status

Windows Firefox 3.6 `Windows`Firefox`3.6` hypOK copyOK 20121001 Firefox just&hyp enabled on all platforms.
Windows Iron 22 ids as Chrome `Windows`Chrome`22` hypOK copyOK 20121001 Chrome just&hyp enabled on all platforms.
Windows IE 9 `Windows`Explorer`9` hypOK copyOK 20121001 Internet Explorer 9 just&hyp enabled.
Windows IE 7 `Windows`Explorer`7` hypOK copyOK 20121001 Internet Explorer 7 just&hyp enabled.
Windows IE 6 `Windows`Explorer`6` various issues 20121001 Internet Explorer 6 just&hyp disabled.
Windows Opera 12 `Windows`Opera`12.1` on 20121108 hyp In Opera 12.1 justification seems to work but justifying hyphenated text results in jagged right margin. 20121108 Opera hyp disabled on all platforms.
Windows Opera 10,11 `Windows`Opera`10.x` or 11.x hyp Opera hides ­ and shows ​. 20121001 Opera hyp disabled on all platforms.
Windows Opera 10,11 `Windows`Opera`10.x` or 11.x copyOK 20121001 see hyp issue.
iPod touch 1st gen iOS 3.2 Opera mini 6.0.1 (10.54) `?o`Opera`10.54` copyOK 20121001 see hyp issue.
Windows QtWeb ids as Safari `Windows`Safari`?v` hyp QtWeb hides ­ and shows ​. 20121001 Safari is disabled on all platforms for which detecting browser version isn't possible (?v).
iPod touch 1st gen iOS 3.2 Safari 4 `iPhone/iPod`Safari`???` copy 20121001 see QtWeb issue
iPad 1st gen iOS 4.2 Safari 5 `?o`Safari`???` copy 20121001 see QtWeb issue

Optimizing Hyphenator

The Hyphenator website includes information on how to merge and pack selected language patterns and Hyphenator.js into a single, smaller file. If you have created such a file you can use it in place of the bundled Hyphenator.js by setting PHP variable $jh_HyphenatorJsPath.

Fixing Hyphenation Exceptions

For now you can manually specify (fix) how a word is to be hyphenated by writing ­ at each break point like this: man­u­script. Further methods to fix hyphenation may be added in the future.

Affecting Descendants

This is a short explanation of how descendant elements are affected when justification/hyphenation is applied to their containing ancestors. This might be changed in the future.

Automatic Mode

  • Initially justification is applied to hyphenated elements (targets)
  • Justification always propagates to targets' descendants
  • Hyphenation affects direct targets only when it is applied as wikystyle or CSS class (no)hyp
  • Justification propagates to descendants when it is applied automatically or by markup (:justhypblock hyp=1|0:) or as wikystyle/CSS class pnohyp.

Manual Mode

Not implemented and probably will not be.

TODO

Notes

Change log / Release notes

2012-11-14: first alpha release.

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

See also

Hyphenopoly

Contributors

Comments

See discussion at JustHyp-Talk

User notes? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.