doc/plugins/cutpaste.mdwn

   1 [[!template id=plugin name=toggle author="[[Enrico]]"]]
   2 [[!tag type/chrome]]
   3
   4 With this plugin you can store and recall pieces of text.  It defines three
   5 preprocessing commands:
   6
   7  * `\[[!cut id=name text="text"]]` memorizes the text allowing to recall it
   8    using the given ID.  The text being cut is not included in the output.
   9  * `\[[!copy id=name text="text"]]` memorizes the text allowing to recall it
  10    using the given ID.  The text being cut *is* included in the output.
  11  * `\[[!paste id=name]]` is replaced by the previously memorized text.
  12
  13 The text being cut, copied and pasted can freely include wiki markup, including
  14 more calls to cut, copy and paste.
  15
  16 You do not need to memorize the text before using it: a cut directive can
  17 follow the paste directive that uses its text.  In fact, this is quite useful
  18 to postpone big blocks of text like long annotations and have a more natural
  19 flow.  For example:
  20
  21         This plugin provides three directives:
  22
  23          * \[[!toggle id="cut" text="cut"]] that cuts text
  24          * \[[!toggle id="copy" text="copy"]] that copies text
  25          * \[[!toggle id="paste" text="paste"]] that pastes text
  26
  27         \[[!toggleable id="cut" text="\[[!paste id=cutlongdesc]]"]]
  28         \[[!toggleable id="copy" text="\[[!paste id=copylongdesc]]"]]
  29         \[[!toggleable id="paste" text="\[[!paste id=pastelongdesc]]"]]
  30
  31         \[...some time later...]
  32
  33         \[[!cut id=cutlongdesc text="""
  34            blah blah blah
  35         """]]
  36         \[[!cut id=copylongdesc text="""
  37            blah blah blah
  38         """]]
  39         \[[!cut id=pastelongdesc text="""
  40            blah blah blah
  41         """]]
  42
  43 This can potentially be used to create loops, but ikiwiki is clever and breaks
  44 them.
  45
  46 Since you can paste without using double quotes, copy and paste can be used to
  47 nest directive that require multiline parameters inside each other:
  48
  49         \[[!toggleable id=foo text="""
  50           \[[!toggleable id=bar text="\[[!paste id=baz]]"]]
  51         """]]
  52
  53         \[[!cut id=baz text="""
  54         multiline parameter!
  55         """]]