“Shy” (short for “soft hyphen”) is a character which is ren­der­ed like the hy­phen (or minus) cha­rac­ter if and only if the renderer considers it to be the very last character of a com­pu­ted line and suitable to apply word­brea­king rules. It's a very han­dy feature in wordprocessors star­ting in the very ear­ly days of PC text­pro­ces­sing¹⁾ where it can be in­ser­ted into the text usu­al­ly by short­keys like Shift- or Ctrl-.

Using soft hyphens is a great way get a smoother word breaking and line wrap. This is im­por­tant especially (but not only) when using a justified lay­out/for­mat whe­re wide spaces bet­ween words not only look quite ug­ly but make the text ac­tu­ally less legible for hu­man rea­ders.

As far as (X)HTML is involved, the ­ entity has been part of the HTMLlat1 cha­rac­ter set from the very be­gin­ning. But, alas, not all brow­sers actually im­ple­ment the standards²⁾. Some, how­ever, do (like e.g. Ope­ra) and even the out­da­ted M$IE tries to³⁾. So­me brow­sers just get it plain wrong by treating soft hy­phens like ordinary ones⁴⁾.

Personally I don't care much for browsers which do the wrong thing. But, of course, your point of view may be different. Any­way, this plugin offers the op­por­tu­ni­ty to use soft hyphens with you wiki pages.

To add a soft hyphen insert \- (i.e. a backslash followed by a hy­phen/mi­nus cha­rac­ter) where­ever you want (and the gram­mar of your language allows) to op­tio­nal­ly⁵⁾ break a word. For example:

Soft hyphens are a great way get smoo\-ther word brea\-kings.

This plugin will replace your \- markup by the appropriate UTF-8 cha­rac­ter se­quen­ce which will then in turn in­ter­pre­ted by the rea­der's brow­ser ac­cor­ding to its respective grade of stan­dards compliance.

For demonstration purposes I’ve inserted quite a few soft hyphens in this do­cu­ment. If your brow­ser sup­ports en­lar­ging the font si­ze/gra­de on-the-fly (with Opera just press the + key on the num-pad) try it. — Another way to test is ma­king your browser win­dow smal­ler/wi­der.

Watch for the line en­dings. If your current browser got it right you should see some­where⁶⁾ a word split up by a soft hyphen. Possibly you have to try se­ve­ral zooms (120%, 140%, 160% etc.) un­til you actu­ally no­tice some­thing. — But even if you don’t see any effect at all⁷⁾ the rea­ders of your Do­ku­Wiki in­stal­la­tion may use bet­ter brow­sers.

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

• http://dev.mwat.de/dw/syntax_plugin_shy.zip (~2KB)

Here comes the GPLed PHP source⁸⁾ for those who'd like to scan it be­fore actu­ally in­stal­ling it:

<?php
if (! class_exists('syntax_plugin_shy')) {
  if (! defined('DOKU_PLUGIN')) {
    if (! defined('DOKU_INC')) {
      define('DOKU_INC', realpath(dirname(__FILE__) . '/../../') . '/');
    } // if
    define('DOKU_PLUGIN', DOKU_INC . 'lib/plugins/');
  } // if
  // Include parent class:
  require_once(DOKU_PLUGIN . 'syntax.php');
 
/**
 * <tt>syntax_plugin_shy.php </tt>- A PHP4 class that implements
 * a <tt>DokuWiki</tt> plugin for so-called 'soft hyphens'.
 *
 * <p>
 * Usage:<br>
 * <tt>\\-</tt><br>
 * to insert a socalled "soft hyphen".
 * </p><pre>
 *  Copyright (C) 2007 DFG/M.Watermann, D-10247 Berlin, FRG
 *      All rights reserved
 *    EMail : &lt;support@mwat.de&gt;
 * </pre>
 * <div class="disclaimer">
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either
 * <a href="http://www.gnu.org/licenses/gpl.html">version 3</a> of the
 * License, or (at your option) any later version.<br>
 * This software is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See the GNU General Public License for more details.
 * </div>
 * @author <a href="mailto:support@mwat.de">Matthias Watermann</a>
 * @version <tt>$Id: syntax_plugin_shy.php,v 1.3 2007/08/15 12:36:19 matthias Exp $</tt>
 * @since created 05-Jan-2007
 */
class syntax_plugin_shy extends DokuWiki_Syntax_Plugin {
 
  /**
   * @publicsection
   */
  //@{
 
  /**
   * Tell the parser whether the plugin accepts syntax mode
   * <tt>$aMode</tt> within its own markup.
   *
   * @param $aMode String The requested syntaxmode.
   * @return Boolean <tt>FALSE</tt> always.
   * @public
   * @see getAllowedTypes()
   */
  function accepts($aMode) {
    return FALSE;
  } // accepts()
 
  /**
   * Connect lookup pattern to lexer.
   *
   * @param $aMode String The desired rendermode.
   * @public
   * @see render()
   */
  function connectTo($aMode) {
    // Only match markup inside words:
    $this->Lexer->addSpecialPattern('(?<![\x20-\x2F\x5C])\x5C\x2D',
      $aMode, plugin_shy);
  } // connectTo()
 
  /**
   * Get an associative array with plugin info.
   *
   * <p>
   * The returned array holds the following fields:
   * <dl>
   * <dt>author</dt><dd>Author of the plugin</dd>
   * <dt>email</dt><dd>Email address to contact the author</dd>
   * <dt>date</dt><dd>Last modified date of the plugin in
   * <tt>YYYY-MM-DD</tt> format</dd>
   * <dt>name</dt><dd>Name of the plugin</dd>
   * <dt>desc</dt><dd>Short description of the plugin (Text only)</dd>
   * <dt>url</dt><dd>Website with more information on the plugin
   * (eg. syntax description)</dd>
   * </dl>
   * @return Array Information about this plugin class.
   * @public
   * @static
   */
  function getInfo() {
    return array(
      'author' =>  'Matthias Watermann',
      'email' =>  'support@mwat.de',
      'date' =>  '2007-08-15',
      'name' =>  'Soft Hyphen Syntax Plugin',
      'desc' =>  'Include soft hyphens in wiki pages.',
      'url' =>  'http://www.dokuwiki.org/plugin:shy');
  } // getInfo()
 
  /**
   * Where to sort in?
   *
   * @return Integer <tt>176</tt>.
   * @public
   * @static
   */
  function getSort() {
    return 176;
  } // getSort()
 
  /**
   * Get the type of syntax this plugin defines.
   *
   * @return String <tt>'substition'</tt> (i.e. 'substitution').
   * @public
   * @static
   */
  function getType() {
    return 'substition';  // sic! should be __substitution__
  } // getType()
 
  /**
   * Handler to prepare matched data for the rendering process.
   *
   * <p>
   * The <tt>$aState</tt> parameter gives the type of pattern
   * which triggered the call to this method.
   * </p>
   * @param $aMatch String The text matched by the patterns.
   * @param $aState Integer The lexer state for the match.
   * @param $aPos Integer The character position of the matched text.
   * @param $aHandler Object Reference to the Doku_Handler object.
   * @return Integer The given <tt>$aState</tt> value.
   * @public
   * @see render()
   * @static
   */
  function handle($aMatch, $aState, $aPos, &$aHandler) {
    return $aState;  // nothing more to do here ...
  } // handle()
 
  /**
   * Handle the actual output creation.
   *
   * <p>
   * The method checks for the given <tt>$aFormat</tt> and returns
   * <tt>FALSE</tt> when a format isn't supported. <tt>$aRenderer</tt>
   * contains a reference to the renderer object which is currently
   * handling the rendering. The contents of <tt>$aData</tt> is the
   * return value of the <tt>handle()</tt> method.
   * </p>
   * @param $aFormat String The output format to generate.
   * @param $aRenderer Object A reference to the renderer object.
   * @param $aData Integer The state value returned by <tt>handle()</tt>.
   * @return Boolean <tt>TRUE</tt> always.
   * @public
   * @see handle()
   */
  function render($aFormat, &$aRenderer, &$aData) {
    if (DOKU_LEXER_SPECIAL == $aData) {
      // No test of '$aFormat' needed here:
      // The raw UTF-8 character sequence is the same anyway.
      $aRenderer->doc .= chr(194) . chr(173);
    } // if
    return TRUE;
  } // render()
 
  //@}
} // class syntax_plugin_shy
} // if
//Setup VIM: ex: et ts=2 enc=utf-8 :
?>

2007-08-15:
* added GPL link and fixed some doc problems;

2007-01-06:
+ initial release;

Matthias Watermann 2007-08-15

• BOMfix Plugin – ignore Byte-Order-Mark characters in your pages
• Code Syntax Plugin – use syntax highlighting of code fragments in your pages
• Definition List Syntax Plugin – use the only complete definition lists in your pages
• Diff Syntax Plugin – use highlighting of diff files (aka “patches”) in your pages⁹⁾
• HR Syntax Plugin – use horizontal rules in nested block elements of your pages
• LANGuage Syntax Plugin – markup different languages in your pages
• Lists Syntax Plugin – use the only complete un-/ordered lists in your pages
• NBSP Syntax Plugin – use Non-Breakable-Spaces in your pages
• NsToC Syntax Plugin – use automatically generated namespace indices
• Shy Syntax Plugin – use soft hyphens in your pages
• Tip Syntax Plugin – add hint areas to your pages

Hints, comments, suggestions …

Hi! I have a chemical name (((1-Methyl-2-(5-methyl-3-oxazolidin­yl)\-eth­oxy)\-meth­oxy)\-meth­oxy)\-metha­nol and I want to put soft hyphens in indicated places. Unfortunately it doesn't work, while inside “normal” words everything is OK. Is there any solution? — Rimas