data/TWiki/TWikiRenderDotPm.txt,v
changeset 0 414e01d06fd5
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/data/TWiki/TWikiRenderDotPm.txt,v	Sat Jan 26 15:50:53 2008 +0100
     1.3 @@ -0,0 +1,466 @@
     1.4 +head	1.5;
     1.5 +access;
     1.6 +symbols;
     1.7 +locks; strict;
     1.8 +comment	@# @;
     1.9 +
    1.10 +
    1.11 +1.5
    1.12 +date	2008.01.22.03.21.32;	author TWikiContributor;	state Exp;
    1.13 +branches;
    1.14 +next	1.4;
    1.15 +
    1.16 +1.4
    1.17 +date	2007.03.03.14.51.47;	author TWikiContributor;	state Exp;
    1.18 +branches;
    1.19 +next	1.3;
    1.20 +
    1.21 +1.3
    1.22 +date	2007.02.05.00.18.34;	author TWikiContributor;	state Exp;
    1.23 +branches;
    1.24 +next	1.2;
    1.25 +
    1.26 +1.2
    1.27 +date	2007.01.16.04.11.57;	author TWikiContributor;	state Exp;
    1.28 +branches;
    1.29 +next	1.1;
    1.30 +
    1.31 +1.1
    1.32 +date	2006.02.01.12.01.25;	author TWikiContributor;	state Exp;
    1.33 +branches;
    1.34 +next	;
    1.35 +
    1.36 +
    1.37 +desc
    1.38 +@new-topic
    1.39 +@
    1.40 +
    1.41 +
    1.42 +1.5
    1.43 +log
    1.44 +@buildrelease
    1.45 +@
    1.46 +text
    1.47 +@---+ Package =TWiki::Render=
    1.48 +
    1.49 +This module provides most of the actual HTML rendering code in TWiki.
    1.50 +
    1.51 +
    1.52 +%TOC%
    1.53 +
    1.54 +---++ ClassMethod *new* <tt>($session)</tt>
    1.55 +
    1.56 +Creates a new renderer
    1.57 +
    1.58 +
    1.59 +
    1.60 +---++ ObjectMethod *finish* <tt>()</tt>
    1.61 +Break circular references.
    1.62 +
    1.63 +
    1.64 +
    1.65 +---++ ObjectMethod *renderParent* <tt>($web,$topic,$meta,$params) -> $text</tt>
    1.66 +
    1.67 +Render parent meta-data
    1.68 +
    1.69 +
    1.70 +
    1.71 +---++ ObjectMethod *renderMoved* <tt>($web,$topic,$meta,$params) -> $text</tt>
    1.72 +
    1.73 +Render moved meta-data
    1.74 +
    1.75 +
    1.76 +
    1.77 +---++ ObjectMethod *makeAnchorName* <tt>($anchorName,$compatibilityMode) -> $anchorName</tt>
    1.78 +
    1.79 +   * =$anchorName= - the unprocessed anchor name
    1.80 +   * =$compatibilityMode= - SMELL: compatibility with *what*?? Who knows. :-(
    1.81 +
    1.82 +Build a valid HTML anchor name
    1.83 +
    1.84 +
    1.85 +
    1.86 +---++ ObjectMethod *internalLink* <tt>($theWeb,$theTopic,$theLinkText,$theAnchor,$doLink,$doKeepWeb,$hasExplicitLinkLabel) -> $html</tt>
    1.87 +
    1.88 +Generate a link. 
    1.89 +
    1.90 +Note: Topic names may be spaced out. Spaced out names are converted to <nop>WikWords,
    1.91 +for example, "spaced topic name" points to "SpacedTopicName".
    1.92 +   * =$theWeb= - the web containing the topic
    1.93 +   * =$theTopic= - the topic to be link
    1.94 +   * =$theLinkText= - text to use for the link
    1.95 +   * =$theAnchor= - the link anchor, if any
    1.96 +   * =$doLinkToMissingPages= - boolean: false means suppress link for non-existing pages
    1.97 +   * =$doKeepWeb= - boolean: true to keep web prefix (for non existing Web.TOPIC)
    1.98 +   * =$hasExplicitLinkLabel= - boolean: true in case of [[TopicName][explicit link label]] 
    1.99 +
   1.100 +Called by _handleWikiWord and _handleSquareBracketedLink and by Func::internalLink
   1.101 +
   1.102 +Calls _renderWikiWord, which in turn will use Plurals.pm to match fold plurals to equivalency with their singular form 
   1.103 +
   1.104 +SMELL: why is this available to Func?
   1.105 +
   1.106 +
   1.107 +
   1.108 +---++ ObjectMethod *renderFORMFIELD* <tt>(%params,$topic,$web) -> $html</tt>
   1.109 +
   1.110 +Returns the fully rendered expansion of a %FORMFIELD{}% tag.
   1.111 +
   1.112 +
   1.113 +
   1.114 +---++ ObjectMethod *getRenderedVersion* <tt>($text,$theWeb,$theTopic) -> $html</tt>
   1.115 +
   1.116 +The main rendering function.
   1.117 +
   1.118 +
   1.119 +
   1.120 +---++ StaticMethod *verbatimCallBack* <tt></tt>
   1.121 +
   1.122 +Callback for use with putBackBlocks that replaces &lt; and >
   1.123 +by their HTML entities &amp;lt; and &amp;gt;
   1.124 +
   1.125 +
   1.126 +
   1.127 +---++ ObjectMethod *TML2PlainText* <tt>($text,$web,$topic,$opts) -> $plainText</tt>
   1.128 +
   1.129 +Clean up TWiki text for display as plain text without pushing it
   1.130 +through the full rendering pipeline. Intended for generation of
   1.131 +topic and change summaries. Adds nop tags to prevent TWiki 
   1.132 +subsequent rendering; nops get removed at the very end.
   1.133 +
   1.134 +Defuses TML.
   1.135 +
   1.136 +$opts:
   1.137 +   * showvar - shows !%VAR% names if not expanded
   1.138 +   * expandvar - expands !%VARS%
   1.139 +   * nohead - strips ---+ headings at the top of the text
   1.140 +   * showmeta - does not filter meta-data
   1.141 +
   1.142 +
   1.143 +
   1.144 +---++ ObjectMethod *protectPlainText* <tt>($text) -> $tml</tt>
   1.145 +
   1.146 +Protect plain text from expansions that would normally be done
   1.147 +duing rendering, such as wikiwords. Topic summaries, for example,
   1.148 +have to be protected this way.
   1.149 +
   1.150 +
   1.151 +
   1.152 +---++ ObjectMethod *makeTopicSummary* <tt>($theText,$theTopic,$theWeb,$theFlags) -> $tml</tt>
   1.153 +
   1.154 +Makes a plain text summary of the given topic by simply trimming a bit
   1.155 +off the top. Truncates to $TMTRUNC chars or, if a number is specified in $theFlags,
   1.156 +to that length.
   1.157 +
   1.158 +
   1.159 +
   1.160 +---++ ObjectMethod *takeOutBlocks* <tt>(\$text,$tag,\%map) -> $text</tt>
   1.161 +
   1.162 +   * =$text= - Text to process
   1.163 +   * =$tag= - XHTML-style tag.
   1.164 +   * =\%map= - Reference to a hash to contain the removed blocks
   1.165 +
   1.166 +Return value: $text with blocks removed
   1.167 +
   1.168 +Searches through $text and extracts blocks delimited by a tag, appending each
   1.169 +onto the end of the @@buffer and replacing with a token
   1.170 +string which is not affected by TWiki rendering.  The text after these
   1.171 +substitutions is returned.
   1.172 +
   1.173 +Parameters to the open tag are recorded.
   1.174 +
   1.175 +This is _different_ to takeOutProtected, because it requires tags
   1.176 +to be on their own line. it also supports a callback for post-
   1.177 +processing the data before re-insertion.
   1.178 +
   1.179 +
   1.180 +
   1.181 +---++ ObjectMethod *putBackBlocks* <tt>(\$text,\%map,$tag,$newtag,$callBack) -> $text</tt>
   1.182 +
   1.183 +Return value: $text with blocks added back
   1.184 +   * =\$text= - reference to text to process
   1.185 +   * =\%map= - map placeholders to blocks removed by takeOutBlocks
   1.186 +   * =$tag= - Tag name processed by takeOutBlocks
   1.187 +   * =$newtag= - Tag name to use in output, in place of $tag. If undefined, uses $tag.
   1.188 +   * =$callback= - Reference to function to call on each block being inserted (optional)
   1.189 +
   1.190 +Reverses the actions of takeOutBlocks.
   1.191 +
   1.192 +Each replaced block is processed by the callback (if there is one) before
   1.193 +re-insertion.
   1.194 +
   1.195 +Parameters to the outermost cut block are replaced into the open tag,
   1.196 +even if that tag is changed. This allows things like
   1.197 +&lt;verbatim class=''>
   1.198 +to be mapped to
   1.199 +&lt;pre class=''>
   1.200 +
   1.201 +Cool, eh what? Jolly good show.
   1.202 +
   1.203 +And if you set $newtag to '', we replace the taken out block with the valuse itself
   1.204 +   * which i'm using to stop the rendering process, but then at the end put in the html directly
   1.205 +   (for <literal> tag.
   1.206 +
   1.207 +
   1.208 +
   1.209 +---++ ObjectMethod *renderRevisionInfo* <tt>($web,$topic,$meta,$rev,$format) -> $string</tt>
   1.210 +
   1.211 +Obtain and render revision info for a topic.
   1.212 +   * =$web= - the web of the topic
   1.213 +   * =$topic= - the topic
   1.214 +   * =$meta= if specified, get rev info from here. If not specified, or meta contains rev info for a different version than the one requested, will reload the topic
   1.215 +   * =$rev= - the rev number, defaults to latest rev
   1.216 +   * =$format= - the render format, defaults to =$rev - $time - $wikiusername=
   1.217 +=$format= can contain the following keys for expansion:
   1.218 +   | =$web= | the web name |
   1.219 +   | =$topic= | the topic name |
   1.220 +   | =$rev= | the rev number |
   1.221 +   | =$comment= | the comment |
   1.222 +   | =$username= | the login of the saving user |
   1.223 +   | =$wikiname= | the wikiname of the saving user |
   1.224 +   | =$wikiusername= | the web.wikiname of the saving user |
   1.225 +   | =$date= | the date of the rev (no time) |
   1.226 +   | =$time= | the time of the rev |
   1.227 +   | =$min=, =$sec=, etc. | Same date format qualifiers as GMTIME |
   1.228 +
   1.229 +
   1.230 +
   1.231 +---++ ObjectMethod *summariseChanges* <tt>($user,$web,$topic,$orev,$nrev,$tml) -> $text</tt>
   1.232 +
   1.233 +   * =$user= - user (null to ignore permissions)
   1.234 +   * =$web= - web
   1.235 +   * =$topic= - topic
   1.236 +   * =$orev= - older rev
   1.237 +   * =$nrev= - later rev
   1.238 +   * =$tml= - if true will generate renderable TML (i.e. HTML with NOPs. if false will generate a summary suitable for use in plain text (mail, for example)
   1.239 +Generate a (max 3 line) summary of the differences between the revs.
   1.240 +
   1.241 +If there is only one rev, a topic summary will be returned.
   1.242 +
   1.243 +If =$tml= is not set, all HTML will be removed.
   1.244 +
   1.245 +In non-tml, lines are truncated to 70 characters. Differences are shown using + and - to indicate added and removed text.
   1.246 +
   1.247 +
   1.248 +
   1.249 +---++ ObjectMethod *forEachLine* <tt>($text,\&fn,\%options) -> $newText</tt>
   1.250 +
   1.251 +Iterate over each line, calling =\&fn= on each.
   1.252 +\%options may contain:
   1.253 +   * =pre= => true, will call fn for each line in pre blocks
   1.254 +   * =verbatim= => true, will call fn for each line in verbatim blocks
   1.255 +   * =literal= => true, will call fn for each line in literal blocks
   1.256 +   * =noautolink= => true, will call fn for each line in =noautolink= blocks
   1.257 +The spec of \&fn is =sub fn( $line, \%options ) -> $newLine=. The %options
   1.258 +hash passed into this function is passed down to the sub, and the keys
   1.259 +=in_literal=, =in_pre=, =in_verbatim= and =in_noautolink= are set boolean
   1.260 +TRUE if the line is from one (or more) of those block types.
   1.261 +
   1.262 +The return result replaces $line in $newText.
   1.263 +
   1.264 +
   1.265 +
   1.266 +---++ StaticMethod *getReferenceRE* <tt>($web,$topic,%options) -> $re</tt>
   1.267 +
   1.268 +   * $web, $topic - specify the topic being referred to, or web if $topic is
   1.269 +     undef.
   1.270 +   * %options - the following options are available
   1.271 +      * =interweb= - if true, then fully web-qualified references are required.
   1.272 +      * =grep= - if true, generate a GNU-grep compatible RE instead of the
   1.273 +        default Perl RE.
   1.274 +      * =url= - if set, generates an expression that will match a TWiki
   1.275 +        URL that points to the web/topic, instead of the default which
   1.276 +        matches topic links in plain text.
   1.277 +Generate a regular expression that can be used to match references to the
   1.278 +specified web/topic. Note that the resultant RE will only match fully
   1.279 +qualified (i.e. with web specifier) topic names and topic names that
   1.280 +are wikiwords in text. Works for spaced-out wikiwords for topic names.
   1.281 +
   1.282 +The RE returned is designed to be used with =s///=
   1.283 +
   1.284 +
   1.285 +
   1.286 +---++ StaticMethod *replaceTopicReferences* <tt>($text,\%options) -> $text</tt>
   1.287 +
   1.288 +Callback designed for use with forEachLine, to replace topic references.
   1.289 +\%options contains:
   1.290 +   * =oldWeb= => Web of reference to replace
   1.291 +   * =oldTopic= => Topic of reference to replace
   1.292 +   * =newWeb= => Web of new reference
   1.293 +   * =newTopic= => Topic of new reference
   1.294 +   * =inWeb= => the web which the text we are presently processing resides in
   1.295 +   * =fullPaths= => optional, if set forces all links to full web.topic form
   1.296 +For a usage example see TWiki::UI::Manage.pm
   1.297 +
   1.298 +
   1.299 +
   1.300 +---++ StaticMethod *replaceWebReferences* <tt>($text,\%options) -> $text</tt>
   1.301 +
   1.302 +Callback designed for use with forEachLine, to replace web references.
   1.303 +\%options contains:
   1.304 +   * =oldWeb= => Web of reference to replace
   1.305 +   * =newWeb= => Web of new reference
   1.306 +For a usage example see TWiki::UI::Manage.pm
   1.307 +
   1.308 +
   1.309 +
   1.310 +---++ ObjectMethod *replaceWebInternalReferences* <tt>(\$text,\%meta,$oldWeb,$oldTopic)</tt>
   1.311 +
   1.312 +Change within-web wikiwords in $$text and $meta to full web.topic syntax.
   1.313 +
   1.314 +\%options must include topics => list of topics that must have references
   1.315 +to them changed to include the web specifier.
   1.316 +
   1.317 +
   1.318 +
   1.319 +---++ StaticMethod *breakName* <tt>($text,$args) -> $text</tt>
   1.320 +
   1.321 +   * =$text= - text to "break"
   1.322 +   * =$args= - string of format (\d+)([,\s*]\.\.\.)?)
   1.323 +Hyphenates $text every $1 characters, or if $2 is "..." then shortens to
   1.324 +$1 characters and appends "..." (making the final string $1+3 characters
   1.325 +long)
   1.326 +
   1.327 +_Moved from Search.pm because it was obviously unhappy there,
   1.328 +as it is a rendering function_
   1.329 +
   1.330 +
   1.331 +
   1.332 +---++ StaticMethod *protectFormFieldValue* <tt>($value,$attrs) -> $html</tt>
   1.333 +
   1.334 +Given the value of a form field, and a set of attributes that control how
   1.335 +to display that value, protect the value from further processing.
   1.336 +
   1.337 +The protected value is determined from the value of the field after:
   1.338 +   * newlines are replaced with &lt;br> or the value of $attrs->{newline}
   1.339 +   * processing through breakName if $attrs->{break} is defined
   1.340 +   * escaping of $vars if $attrs->{protectdollar} is defined
   1.341 +   * | is replaced with &amp;#124; or the value of $attrs->{bar} if defined
   1.342 +
   1.343 +
   1.344 +@
   1.345 +
   1.346 +
   1.347 +1.4
   1.348 +log
   1.349 +@buildrelease
   1.350 +@
   1.351 +text
   1.352 +@d10 6
   1.353 +a15 3
   1.354 +Creates a new renderer with initial state from preference values
   1.355 +(NEWTOPICBGCOLOR, NEWTOPICFONTCOLOR NEWTOPICLINKSYMBOL
   1.356 + LINKTOOLTIPINFO)
   1.357 +a30 6
   1.358 +---++ ObjectMethod *renderFormField* <tt>($web,$topic,$meta,$params) -> $text</tt>
   1.359 +
   1.360 +Render meta-data for a single formfield
   1.361 +
   1.362 +
   1.363 +
   1.364 +d33 2
   1.365 +a34 2
   1.366 +   * =$anchorName= -
   1.367 +   * =$compatibilityMode= -
   1.368 +d40 1
   1.369 +a40 1
   1.370 +---++ ObjectMethod *internalLink* <tt>($theWeb,$theTopic,$theLinkText,$theAnchor,$doLink,$doKeepWeb) -> $html</tt>
   1.371 +d47 1
   1.372 +a47 1
   1.373 +   * =$theTopic= - the topic to be lunk
   1.374 +d52 1
   1.375 +a113 26
   1.376 +---++ ObjectMethod *takeOutProtected* <tt>(\$text,$re,\%map) -> $text</tt>
   1.377 +
   1.378 +   * =$text= - Text to process
   1.379 +   * =$re= - Regular expression that matches tag expressions to remove
   1.380 +   * =\%map= - Reference to a hash to contain the removed blocks
   1.381 +
   1.382 +Return value: $text with blocks removed
   1.383 +
   1.384 +used to extract from $text comment type tags like &lt;!DOCTYPE blah>
   1.385 +
   1.386 +WARNING: if you want to take out &lt;!-- comments --> you _will_ need to re-write all the takeOuts
   1.387 +	to use a different placeholder
   1.388 +
   1.389 +
   1.390 +
   1.391 +---++ ObjectMethod *putBackProtected* <tt>(\$text,\%map,$callback) -> $text</tt>
   1.392 +
   1.393 +Return value: $text with blocks added back
   1.394 +   * =\$text= - reference to text to process
   1.395 +   * =\%map= - map placeholders to blocks removed by takeOutBlocks
   1.396 +   * =$callback= - Reference to function to call on each block being inserted (optional)
   1.397 +
   1.398 +Reverses the actions of takeOutProtected.
   1.399 +
   1.400 +
   1.401 +
   1.402 +d209 1
   1.403 +d211 4
   1.404 +a214 1
   1.405 +The spec of \&fn is sub fn( \$line, \%options ) -> $newLine; the %options hash passed into this function is passed down to the sub, and the keys =in_pre=, =in_verbatim= and =in_noautolink= are set boolean TRUE if the line is from one (or more) of those block types.
   1.406 +d220 20
   1.407 +a245 1
   1.408 +   * =spacedTopic= => RE matching spaced out oldTopic
   1.409 +a272 14
   1.410 +---++ StaticMethod *renderFormFieldArg* <tt>($meta,$args) -> $text</tt>
   1.411 +
   1.412 +Parse the arguments to a $formfield specification and extract
   1.413 +the relevant formfield from the given meta data.
   1.414 +
   1.415 +   * =args= string containing name of form field
   1.416 +   
   1.417 +In addition to the name of a field =args= can be appended with a commas
   1.418 +followed by a string format (\d+)([,\s*]\.\.\.)?). This supports the formatted
   1.419 +search function $formfield and is used to shorten the returned string or a 
   1.420 +hyphenated string.        
   1.421 +
   1.422 +
   1.423 +
   1.424 +d285 13
   1.425 +@
   1.426 +
   1.427 +
   1.428 +1.3
   1.429 +log
   1.430 +@buildrelease
   1.431 +@
   1.432 +text
   1.433 +@d131 1
   1.434 +a131 1
   1.435 +---++ ObjectMethod *putBackProtected* <tt>(\$text,\%map,$tag,$newtag,$callBack) -> $text</tt>
   1.436 +d136 1
   1.437 +@
   1.438 +
   1.439 +
   1.440 +1.2
   1.441 +log
   1.442 +@buildrelease
   1.443 +@
   1.444 +text
   1.445 +@d282 7
   1.446 +@
   1.447 +
   1.448 +
   1.449 +1.1
   1.450 +log
   1.451 +@buildrelease
   1.452 +@
   1.453 +text
   1.454 +@d17 1
   1.455 +d23 1
   1.456 +d29 1
   1.457 +d47 2
   1.458 +a48 2
   1.459 +SMELL: why can topic be spaced out? is this to support auto squishing of [[Spaced Topic Naming]]?
   1.460 +and [[lowercase Spaced Topic Naming]]
   1.461 +a201 2
   1.462 +   | =$date= | the date of the rev (no time) |
   1.463 +   | =$time= | the full date and time of the rev |
   1.464 +d206 3
   1.465 +d213 1
   1.466 +d244 1
   1.467 +d259 1
   1.468 +d285 1
   1.469 +@