DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:shy

Shy Syntax PlugIn

Compatible with DokuWiki

2005-07-13+

plugin Use soft hyphens.

Last updated on
2007-08-15
Provides
Syntax

This extension has not been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues.

Tagged with html, hyphen, utf-8

“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­sing1) 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 standards2). Some, how­ever, do (like e.g. Ope­ra) and even the out­da­ted M$IE tries to3). So­me brow­sers just get it plain wrong by treating soft hy­phens like ordinary ones4).

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.

Usage

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­ly5) 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­where6) 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 all7) the rea­ders of your Do­ku­Wiki in­stal­la­tion may use bet­ter brow­sers.

Installation

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

Plugin Source

Here comes the GPLed PHP source8) 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 :
?>

Changes

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

2007-01-06:
+ initial release;

Matthias Watermann 2007-08-15

See also

Plugins by the same author

Discussion

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

1)
and made its way even into bloated monsters like M$-Office
2)
one notable example for ignoring soft hyphens is Mozilla/Firefox
3)
albeit with sometimes surprising results like word parts showing up twice or not at all
4)
older versions of Konqueror are an example – but I didn't check for quite a while how far the KHTML folks ma­na­ged to clean up their mess
5)
i.e. if it will be the very last character of a line computed by the renderer (the brow­ser's ren­de­ring en­gi­ne in this case).
6)
Because the actual location of such a change depends on many facts (such as screen width and re­so­lu­tion, se­lec­ted font fa­mi­ly, ab­so­lu­te si­ze of ren­de­red texts etc.) I can’t predict the exact place.
7)
most probably be­cau­se your browser doesn’t implement the HTMLlat1 entities pro­perly
8)
The comments within the source file are suitable for the OSS doxygen tool, a do­cu­men­ta­tion sy­stem for C++, C, Java, Ob­jec­tive-C, Python, IDL and to some extent PHP, C#, and D. — Since I'm working with dif­fe­rent pro­gram­ming lan­gua­ges it's a great ease to have one tool that handles the docs for all of them.
9)
obsoleted by incorporating its ability into the Code plugin
plugin/shy.txt · Last modified: 2018-06-05 23:45 by Klap-in