DokuWiki

It's better when it's simple

User Tools

Site Tools

Trace:
plugin:textinsert

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
plugin:textinsert [2018-05-27 00:34] – [Installation] Klap-inplugin:textinsert [2022-08-30 01:16] (current) – compatible Igor 82.64.33.11
Line 1: Line 1:
-====== textinsert Plugin ======+====== TextInsert Plugin ======
  
 ---- plugin ---- ---- plugin ----
Line 6: Line 6:
 email      : turnermm02@shaw.ca email      : turnermm02@shaw.ca
 type       : syntax type       : syntax
-lastupdate : 2017-12-07 +lastupdate : 2019-10-03 
-compatible : Anteater, Rincewind, Angua, Adora Belle, Weatherwax, Binky, Ponder Stibbons, Hrun,detritus,"Elenor Of Tsort" ,Greebo+compatible : Anteater, Rincewind, Angua, Adora Belle, Weatherwax, Binky, Ponder Stibbons, Hrun,detritus,"Elenor Of Tsort" ,Greebo, Hogfather, Igor
 depends    :  depends    : 
 conflicts  :  conflicts  : 
-similar    : easyvar, replace, kixovar, fields, macros+similar    : easyvar, replace, kixovar, fields, macros, phpwikify
 tags       : replace, macro, entities, entity tags       : replace, macro, entities, entity
  
-downloadurl: https://github.com/turnermm/TextInsert/tarball/master+downloadurl: https://github.com/turnermm/TextInsert/zipball/master
 bugtracker : https://github.com/turnermm/TextInsert/issues bugtracker : https://github.com/turnermm/TextInsert/issues
-sourcerepo : https://github.com/turnermm/TextInsert/+sourcerepo : https://github.com/turnermm/TextInsert
 donationurl: http://mturner.org/userfiles/donate.php  donationurl: http://mturner.org/userfiles/donate.php 
 ---- ----
  
 ===== Installation ===== ===== Installation =====
-Search and install ​the plugin using the [[plugin:extension|Extension ​Manager]].  If you cannot use the Dokuwiki download Manager to install this plugin, install it manually. Refer to [[:plugin_installation_instructions#manual instructions]] for how to install plugins manually.+ 
 +Search and install ​the plugin using the [[plugin:extension|Extension ​Manager]].  If you cannot use the DokuWiki download Manager to install this plugin, install it manually. Refer to [[:plugin_installation_instructions#manual instructions]] for how to install plugins manually.
  
  
 ===== Examples/Usage ===== ===== Examples/Usage =====
 +
  
 This plugin provides an administrative panel where you enter macro names and their substitution texts.  These are saved in the meta directory (in ''meta/macros/macros.ser''). In farms, you can choose to have a database for each animal (see: [[#configuration_and_settings]]). You can save individual words, and strings of text, including lengthy paragraphs.  The substitutions accept html, quotation marks and other punctuation.  The macro names can accept spaces, dots, underscores and hyphens.    This plugin provides an administrative panel where you enter macro names and their substitution texts.  These are saved in the meta directory (in ''meta/macros/macros.ser''). In farms, you can choose to have a database for each animal (see: [[#configuration_and_settings]]). You can save individual words, and strings of text, including lengthy paragraphs.  The substitutions accept html, quotation marks and other punctuation.  The macro names can accept spaces, dots, underscores and hyphens.   
Line 32: Line 34:
   All Roads Lead to "Here" except for the ones which don't   All Roads Lead to "Here" except for the ones which don't
  
-The textinsert plugin will allow you to create macros for extended texts. You can create paragraph length texts with HTML markup which have to be repeated, for instance, as instructions at the tops of pages.  If you want the HTML to be rendered as such, then the macro name must have the _HTML suffix: +The textinsert plugin will allow you to create macros for extended texts. You can create paragraph length texts with HTML markup which has to be repeated on multiple pages.  If you want the HTML to be rendered as such, then the macro name must have the _HTML suffix: 
  
-   Macro_HTML    +  Macro_HTML    
  
 **Note**: The underscore is required. **Note**: The underscore is required.
 +==== Basic Syntax ==== 
 +     #@MACRO_NAME@# 
 ==== Macro Inclusions ==== ==== Macro Inclusions ====
  
-Some of the functionality of this plugin at its simplest can be implemented with Dokuwiki's own entities facility: [[:entities]]. But for complex substitutions and for control over where and how substitutions are made, textinsert offers a wide variety of solutions and techniques. +Some of the functionality of this plugin at its simplest can be implemented with DokuWiki's own entities facility: [[:entities]]. But for complex substitutions and for control over where and how substitutions are made, Textinsert offers a wide variety of solutions and techniques. 
  
 One advantage of TextInsert comes when dealing with extended blocks of text and with its ability to include other macros inside the primary macro definition. That is, it can accept: One advantage of TextInsert comes when dealing with extended blocks of text and with its ability to include other macros inside the primary macro definition. That is, it can accept:
Line 47: Line 50:
   MACRO_2  a second macro   MACRO_2  a second macro
  
-The result with syntax #@MACRO_1@# is: +The result of using ''#@MACRO_1@#'' is: 
-    This macro can include a second macro inside it. +  This macro can include a second macro inside it. 
-    +
 It accepts only one level of macro inclusion, so that if MACRO_3 were included in MACRO_2, MACRO_3 would not be rendered.  If an include macro requires treatment as HTML, then the primary macro must be named as an HTML macro. It accepts only one level of macro inclusion, so that if MACRO_3 were included in MACRO_2, MACRO_3 would not be rendered.  If an include macro requires treatment as HTML, then the primary macro must be named as an HTML macro.
  
 ==== Entity Inclusions ==== ==== Entity Inclusions ====
-TextInsert will also accept entities in its macro definitions.  These are defined in dokuwiki/conf/entities.conf and dokuwiki/conf/entities.local.conf.  Entities will be replaced in included macros as well as in the primary macro.  For instance, if MACRO_2 above were defined as follows, using Dokuwiki's long dash entity: + 
-   MACRO_2  a second---macro---+TextInsert will also accept entities in its macro definitions.  These are defined in dokuwiki/conf/entities.conf and dokuwiki/conf/entities.local.conf.  Entities will be replaced in included macros as well as in the primary macro.  For instance, if MACRO_2 above were defined as follows, using DokuWiki's long dash entity: 
 +  MACRO_2  a second---macro---
 The final result would be: This macro can include a second---macro---inside it. The final result would be: This macro can include a second---macro---inside it.
        
            
 ==== Standard Namespace Macros ==== ==== Standard Namespace Macros ====
-Textinsert will accept namespace macros as used in Dokuwiki namespace templates. See [[:namespace_templates|Namespace Templates]] for the list of these.  Textinsert can accept all but the MAIL and NAME macros, which go out of scope when the page is saved.  Like regular textinsert macros these can also be embedded in other textinsert macros; see [[#macro_inclusions]].  For instance, a macro named current_user and a user named jack:+ 
 +Textinsert will accept namespace replacement patterns, as used in DokuWiki namespace templates. See [[:namespace_templates#replacement_patterns|Namespace Templates]] for the list of these.  Textinsert can accept all but the MAIL and NAME macros, which go out of scope when the page is saved.  Like regular textinsert macros these can also be embedded in other textinsert macros; see [[#macro_inclusions]].  For instance, a macro named current_user and a user named jack:
  
 ^ Macro         ^ Definition                        ^ ^ Macro         ^ Definition                        ^
Line 67: Line 72:
  
 There is a configuration option which governs whether or not standard namespace macros are accepted.  It is set to true by default. There is a configuration option which governs whether or not standard namespace macros are accepted.  It is set to true by default.
 +
 +=== _ID_ and _NS_: Pseudo Namespace Macros for Sidebars===
 +
 +When used in a sidebar the standard namespace macro ''ID'' resolves to the id of the sidebar page.  To get the id of the currently displayed page, use instead ''_ID_'', of the currently displayed namespace ''_NS_''.  These macros can also be used for [[#macro_inclusions]]. So, for instance if you wanted to display the result as a wiki link, you could do this:
 +
 +<code html>
 +<a href="/mywiki/doku.php?id=#@_ID_@#" class="wikilink1">#@_ID_@#</a>
 +</code>
 +
 +If you use ''_ID_'' or ''_NS_'' in your sidebar, then you must also insert the ''%%~~NOCACHE~~%%'' macro into the page so that the ID updates with each change of page.   See [[wiki:syntax#control_macros]].    
  
 ==== Example of Multi Paragraph Text Block ==== ==== Example of Multi Paragraph Text Block ====
Line 72: Line 87:
 If you want to create multi-pragraph blocks, then you need  to use the HTML paragraph tag, <P>. . .</P>. The textinsert plugin will accept paragraphs like the the following, which is the introductory header found on the textinsert administration page: If you want to create multi-pragraph blocks, then you need  to use the HTML paragraph tag, <P>. . .</P>. The textinsert plugin will accept paragraphs like the the following, which is the introductory header found on the textinsert administration page:
  
-<code>+<code html>
 <H2>Info</H2> <H2>Info</H2>
 <p> <p>
Line 94: Line 109:
 ==== Screen Shot of Edit Panel ==== ==== Screen Shot of Edit Panel ====
  
-{{http://www.mturner.org/userfiles/info.png}}+{{https://i.imgur.com/8zMF7Ik.png}}
  
 ===== Syntax ===== ===== Syntax =====
Line 114: Line 129:
 ===== Parameter Interpolation ===== ===== Parameter Interpolation =====
  
-==== Syntax ====+==== Basic Syntax ====
  
 Macro Definition as defined on page: Macro Definition as defined on page:
-    #@macro_name~param1,param2,param3. . .param<n>~@#+  #@macro_name~param1,param2,param3. . .param<n>~@#
 Replacement String defined in Macro database:     Replacement String defined in Macro database:    
-    string %1 more string %2 . . .%<n>+  string %1 more string %2 . . .%<n>
  
 %1 will be replaced by param1,%2 by param2, etc. %1 will be replaced by param1,%2 by param2, etc.
Line 127: Line 142:
 | Mountain_Ranges  | In Europe there are the %1, in North America the %2 and in South America the %3  | | Mountain_Ranges  | In Europe there are the %1, in North America the %2 and in South America the %3  |
  
-    #@Mountain_Ranges~Alps,Rockies,Andes~@#    +  #@Mountain_Ranges~Alps,Rockies,Andes~@#    
 **Result:** ''In Europe there are the Alps, in North America the Rockies and in South America the Andes'' **Result:** ''In Europe there are the Alps, in North America the Rockies and in South America the Andes''
 +
 +==== DokuWiki Basic Text Formatting Syntax ====
 +
 +Parameters may use the [[wiki:syntax#basic_text_formatting| basic text formatting syntax]]: bold,italic, etc.  The one exception is the internal newline.  If you need this you must use ''\n''.
 +
 +==== Multi-line Syntax ====
 +<code>
 +#@Macro_name~
 +parameter one, //comment one
 +parameter two, // comment two
 +parameter three,
 +parameter four
 +.
 +.
 +parameter <n>
 +~@#
 +</code>
 +
 +Comments are allowed but not included in the final output. 
 +
 +**Example:** \\ 
 +<code>
 +#@Mountain_Ranges~
 +Alps, //Switzerland
 +Rockies, // U.S. and Canada
 +Andes  
 +~@#
 +</code>
 +
 +The final result will be the same as for the single line syntax, as shown above in the example for the [[#basic_syntax]].
 +
 +"Multi-line" also means that parameters and  parameter format can continue across line boundaries:
 +
 +<code>
 +#@Mountain_Ranges~
 +Alps, //Switzerland
 +
 +Rockies, // U.S. and Canada
 +
 +Andes  
 +or Andean Mountains (Spanish: Cordillera de los Andes)\, which are the 
 +longest continental mountain range in the world\, forming a continuous
 +highland along the western edge of South America. The Andes also have
 +the 2nd most elevated highest peak of any mountain range\, only 
 +behind the Himalayas.
 +
 +~@#
 +</code>
 +
 +In order for this to work, the commas must be escaped, since they represent parameter boundaries: ''\,''.
 +
  
 ===== Language Translation ===== ===== Language Translation =====
  
-This version of textinsert makes translation substitutions based on ISO-derived namespaces.((This is consistent with the scheme used by the [[:plugin:translation|translation]] plugin.)) Macros found in an ISO-derived namespace will be read within the language context specified by the ISO designation.+''textinsert'' makes translation substitutions based on ISO-derived namespaces.((This is consistent with the scheme used by the [[:plugin:translation|translation]] plugin.)) Macros found in an ISO-derived namespace will be read within the language context specified by the ISO designation.  A namespace is defined by the topmost directory: 
 +  -  de:ns1:ns2:page.text \\ The namespace here is ''de'', i.e. German 
 +  - ns1:de:ns:page.txt  \\ The namespace here is ''ns1'', i.e. not an ISO designation   
  
 Macros of this type must use the following syntax: Macros of this type must use the following syntax:
   #@LANG_name@#   #@LANG_name@#
 A default entry for this type of macro must be entered into the textinsert database as ''LANG_name''. The translation strings must be stored in textinsert/lang/<ISO>/lang.php in the $lang array, using 'name' for the key. If you have a macro named ''LANG_greeting'', then in lang.php the entry will be: A default entry for this type of macro must be entered into the textinsert database as ''LANG_name''. The translation strings must be stored in textinsert/lang/<ISO>/lang.php in the $lang array, using 'name' for the key. If you have a macro named ''LANG_greeting'', then in lang.php the entry will be:
-  $lang['greeting']='language_string_for_greeting';+ 
 +<code php> 
 +$lang['greeting'] = 'language_string_for_greeting'; 
 +</code>
    
-If a translation is not found, the default string will be used.    +If a translation is not found, the default string will be used.  
 + 
 +Use of ''lang.php'' is **deprecated**.  See [[#improved_language_localization|improved language localization ]] below for an updated method of storing translations.   
  
 ==== Example ==== ==== Example ====
Line 149: Line 222:
 In each lang.php, you need only a single entry, for instance: In each lang.php, you need only a single entry, for instance:
  
-    $lang['greeting'] = 'Hello from Germany'; +<code> 
 +$lang['greeting'] = 'Hello from Germany'; 
 +</code>
  
 When you include #@LANG_greeting@# in your document, the country identified by the IS0 namespace will be printed with its HTML formatting. When you include #@LANG_greeting@# in your document, the country identified by the IS0 namespace will be printed with its HTML formatting.
  
-  +==== Improved Language Localization ==== 
 + 
 +Using ''lang/<iso>/lang.php'' runs the risk that your macro replacement strings will be lost when the plugin is updated, since ''lang.php'' will be overwritten.  Beginning with the Oct 10, 2019 update, you can write your macro replacement strings to a separate file named ''macros.php'', also in the ''<iso>/lang'' directory: ''<iso>/lang/macros.php''.   For backward compatibility, this update still recognizes the use of ''lang.php'' to hold your replacement strings.  
 + 
 +The format of macros.php must follow this example: 
 +<code php> 
 +    <?php 
 +     $lang_<iso>['key'] = 'replacement string'; 
 +     $lang_<iso>['key'] = 'replacement string';  
 +     . 
 +     .         
 +</code> 
 +To use the earlier example: 
 + 
 +<code php> 
 +<?php 
 +/* textinsert/lang/de/macros.txt */ 
 +$lang_de['greeting'] = 'Hello from Germany';  
 +</code>       
 + 
 ==== Embedding ==== ==== Embedding ====
  
-Translation macros can be included in standard and HTML macros.  They also accept Dokuwiki-defined entities, as described above.  There is no special HTML translation macro.  Any HTML features which appear in a language-based macro will automatically be output as HTML when the macro occurs in a language context.  +Translation macros can be included in standard and HTML macros.  They also accept DokuWiki-defined entities, as described above.  There is no special HTML translation macro.  Any HTML features which appear in a language-based macro will automatically be output as HTML when the macro occurs in a language context.  
  
-^ ^ Macro Name ^ Definition | +^ # ^ Macro Name ^ Definition | 
-|1| LANG_nation | <h2>I live in Canada</h2> |  +|1| LANG_nation | %%<h2>I live in Canada</h2>%% |  
-|2| nation_HTML | #@LANG_nation@# |+|2| nation_HTML | %%#@LANG_nation@#%% |
 |3| LANG_city   | Toronto | |3| LANG_city   | Toronto |
  
 If the default replacement string contains HTML, then you should use form 2 in the above table when not in a language context; otherwise the HTML will appear in your output as plain text and the HTML will be lost. If the default replacement string contains HTML, then you should use form 2 in the above table when not in a language context; otherwise the HTML will appear in your output as plain text and the HTML will be lost.
  
-In a language context, any HTML that you place in your definition will be output as HTML.  Assume this is ths definition for LANG_nation in the lang/de/lang.php:+In a language context, any HTML that you place in your definition will be output as HTML.  Assume this is the definition for LANG_nation in the lang/de/lang.php:
  
-   $lang['nation'] = 'Ich lebe in <b>Kanada</b>';+<code php> 
 +$lang['nation'] = 'Ich lebe in <b>Kanada</b>'; 
 +</code>
        
 In the German namespace, #@LANG_nation@# will be output as HTML: Ich lebe in **Kanada**.  In the German namespace, #@LANG_nation@# will be output as HTML: Ich lebe in **Kanada**. 
Line 173: Line 270:
 It is also possible to include macros in your translations: It is also possible to include macros in your translations:
  
-   $lang['city'] = 'Berlin '; +<code php> 
-   $lang['nation'] = 'Ich lebe in <b>#@LANG_city@#</b>, in Deutschland';+$lang['city'] = 'Berlin '; 
 +$lang['nation'] = 'Ich lebe in <b>#@LANG_city@#</b>, in Deutschland'; 
 +</code>
          
 This results in: Ich lebe in **Berlin**, in Deutschland This results in: Ich lebe in **Berlin**, in Deutschland
- 
-     
  
        
 ===== Configuration and Settings ===== ===== Configuration and Settings =====
 +
 There are two configuration settings. There are two configuration settings.
  
 ^stdreplace|Accept standard macro replacements as used in namespace templates|default: on|  ^stdreplace|Accept standard macro replacements as used in namespace templates|default: on| 
 ^farm|If this is a farm and you and would like each animal to have its own macro database, please select this option; otherwise all animals will share the same, i.e. the farmer's, database|default: off| ^farm|If this is a farm and you and would like each animal to have its own macro database, please select this option; otherwise all animals will share the same, i.e. the farmer's, database|default: off|
- 
  
  
 ===== Development ===== ===== Development =====
  
 +=== Change Log ===
  
- 
-=== Change Log === 
 {{rss>https://github.com/turnermm/textinsert/commits/master.atom date count=10}} {{rss>https://github.com/turnermm/textinsert/commits/master.atom date count=10}}
  
 ===== Discussion ===== ===== Discussion =====
-All questions have been moved to [[plugin:textinsert:discussion]].  Additional questions should use [[https://github.com/turnermm/TextInsert/issues/|github issues]]. Thanks. 
- 
- 
- 
- 
- 
- 
  
 +All earlier questions have been moved to [[plugin:textinsert:discussion]].  Additional questions should use [[https://github.com/turnermm/TextInsert/issues/|github issues]]. Thanks.
  
plugin/textinsert.1527374057.txt.gz · Last modified: 2018-05-27 00:34 by Klap-in
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki

Global DokuWiki Links