Docs update; new compiler config

README.textile

@@ -0,0 +1,249 @@
+h1. soo_plugin_display
+
+This is a plugin for "Textpattern":http://textpattern.com. Plugin authors can display code, help text, and other aspects of plugins directly from Textpattern.
+
+* "Support forum topic":https://forum.textpattern.io/viewtopic.php?id=31866
+* "Author site":http://ipsedixit.net/txp/109/soo_plugin_display
+* "GitHub":https://github.com/jsoo/soo_plugin_display
+
+notextile. <div id="toc">
+
+h2. Contents
+
+* "Overview":#overview
+* "Usage":#usage
+* "Tags":#tags
+** "soo_plugin_display":#soo_plugin_display
+** "soo_plugin_author_uri, soo_plugin_version, soo_plugin_description":#soo_plugin_author_uri
+** "soo_plugin_author, soo_plugin_name":#soo_plugin_author
+** "soo_plugin_size":#soo_plugin_size
+** "soo_plugin_help":#soo_plugin_help
+** "soo_plugin_code":#soo_plugin_code
+* "Examples":#examples
+* "Preferences":#preferences
+* "History":#history
+
+notextile. </div>
+
+h2(#overview). Overview
+
+Display information about installed plugins.
+
+h2(#usage). Usage
+
+The @soo_plugin_display@ tag works as a container or with a form that retrieves most of the txp_plugin fields for the plugin specified in the @name@ attribute. Place any of the other tags (@soo_plugin_author@, etc.) inside the container or form to display your choice of fields.
+
+If @name@ is left blank (the %(default)default%), @soo_plugin_display@ will retrieve all plugins (optionally restricted by plugin prefix or status). In this case the plugin code and help will *not* be retrieved, so @soo_plugin_code@ and @soo_plugin_help@ will not produce output.
+
+The plugin is compatible with "soo_plugin_pref":http://ipsedixit.net/txp/92/soo_plugin_pref, allowing you to adjust some of the default tag attribute values.
+
+h2(#tags). Tags
+
+All tags (except for @soo_plugin_display@) %(required)must% be in a @soo_plugin_display@ container or form to produce output. 
+
+h3(#soo_plugin_display). soo_plugin_display
+
+Retrieve a named plugin or a list of plugins; iterate over each plugin with the tag contents or specified form.
+
+pre.. <txp:soo_plugin_display form="foo" />    <!-- use with a form -->
+
+<txp:soo_plugin_display>                 <!-- or as a container -->
+	...
+</txp:soo_plugin_display>
+
+h4. Attributes
+
+* @name@ _(plugin name)_ Plugin to display. If blank (the %(default)default%), retrieve a list of plugins (<dfn>list mode</dfn>)
+* @form@ _(Txp form name)_ Form to display output. If empty, container tag required for output. %(default)Default% is empty (can be changed in prefs).
+
+The remaining attributes are effective only in list mode (i.e., when @name@ is left blank).
+
+* @prefix@ _(plugin author prefix)_ select only plugins with this prefix
+* @show_inactive@ _(boolean)_ %(default)default% "0", whether to include inactive plugins
+* @sort@ _(MySQL sort value)_ %(default)default% "name asc" (in addition to column names, "size" is also available for sorting)
+* @wraptag@ _(HTML tag name, without brackets)_
+* @break@ _(HTML tag name, without brackets)_
+* @class@ _(HTML class attribute)_ applied to @wraptag@
+* @html_id@ _(HTML ID attribute)_ applied to @wraptag@
+
+h3(#soo_plugin_author_uri). soo_plugin_author_uri, soo_plugin_version, soo_plugin_description
+
+No attributes: each simply displays the corresponding field straight from @txp_plugin@.
+
+pre. <txp:soo_plugin_author_uri />
+<txp:soo_plugin_version />
+<txp:soo_plugin_description />
+
+h3(#soo_plugin_author). soo_plugin_author, soo_plugin_name
+
+As above, but these accept an optional @link@ attribute.
+
+pre. <txp:soo_plugin_author />
+<txp:soo_plugin_name />
+
+h4. Attributes
+
+* @link@ _(boolean)_ whether to make output a link to the plugin author's website, %(default)default% "1"
+
+h3(#soo_plugin_size). soo_plugin_size
+
+Display the plugin's installed code size in KB (counting 1 character = 1 byte)
+
+pre. <txp:soo_plugin_size />
+
+h4. Attributes
+
+* @format@ _(text)_ %(default)default% '{size}&amp;nbsp;KB', can be changed in prefs.
+
+The plugin outputs the value of @format@, first replacing any occurrences of '{size}' with the size in KB.
+
+h3(#soo_plugin_help). soo_plugin_help
+
+Display the plugin's help text.
+
+pre. <txp:soo_plugin_help />
+
+%(warning)Does not work in list mode% (i.e., when @soo_plugin_display@ has a blank @name@ attribute).
+
+h4. Attributes
+
+* @strip_style@ _(boolean)_ whether or not to remove any leading @<style>@ element (%(default)default% "1", can be changed in prefs)
+* @strip_title@ _(boolean)_ whether or not to remove any leading @<h1>@ element (%(default)default% "1", can be changed in prefs)
+* @section_id@ _(HTML id value)_ start display from identified header element, continue till next header of same or lower level
+* @h_plus@ _(integer)_ transpose HTML header levels by this amount
+
+@strip_style@ looks for an opening @<style>@ tag at the very start of the Help section. @strip_title@ looks for the first occurence of @<h1>@. Both do a non-greedy match looking for the closing tag.
+
+With @section_id@, display begins from the HTML header element with the specified id. Display continues till the next HTML header with the same or lower level (@<h2>@ considered lower than @<h3>@, for example) or until the end if no such header is found.
+
+@h_plus@ can be helpful when breaking a long help text into several web pages, in conjuction with @section_id@. For example, @h_plus="-2"@ will transpose all @h6@ elements to @h4@, all @h5@ elements to @h3@, etc.
+
+h3(#soo_plugin_code). soo_plugin_code
+
+Display plugin source code, by %(default)default% the whole thing, or selected code determined by the @function@ and/or @php_class@ attributes.
+
+pre. <txp:soo_plugin_code />
+
+%(warning)Does not work in list mode% (i.e., when @soo_plugin_display@ has a blank @name@ attribute).
+
+h4. Attributes
+
+* @class@ _(html class name)_ for wrapping &lt;code&gt; and &lt;pre&gt; elements
+* @html_id@ _(html id name)_ for wrapping &lt;code&gt; and &lt;pre&gt; elements
+* @tab_stop@ _(integer)_ length of tab stop
+* @function@ _(text)_ Show only this function. Use in combination with @php_class@ to show only this method.
+* @php_class@ _(text)_ Show only this PHP class
+* @highlight@ _(boolean)_ whether or not to add syntax highlighting to output. %(default)Default% "1", add highlighting (can be changed in prefs).
+
+The remaining attributes are effective only when highlighting is enabled.
+
+* @show_line_numbers@ _(text)_ If set, text to append to each line number. If blank, do not show line numbers. %(default)default% ":" (can be changed in prefs).
+* @reindex_lines@ _(integer)_ With @function@ and/or @php_class@, renumber lines starting from the value given. %(default)Default% "0", do not reindex. 
+
+The function/class search isn't thorough, and is based on my coding style. In the case of a function (outside a class) or class, it simply stops at the first non-indented closing brace ("}") that occurs after the function or class name. Same for a method (function inside a class) but with the closing brace indented one tab.
+
+Tabs are converted to spaces, to stay aligned with tab stops as set in plugin preferences or the @tag_stop@ attribute.
+
+h5. Highlighting
+
+The code highlighting is based on the PHP @highlight_string()@ function. The @style@ declarations produced by @highlight_string()@ are replaced by @class@ declarations. The important ones:
+
+* @php_comment@ comments
+* @php_keyword@ keywords, operators, brackets, semicolons, etc.
+* @php_default@ function names (including core PHP functions)
+* @php_string@ strings
+
+Everything will be in a @span@ with one of those class names. The whole thing is wrapped in a @code@ element.
+
+If you prefer to use javascript-based highlighting, such as the excellent "SyntaxHighlighter":http://alexgorbatchev.com/SyntaxHighlighter/, set @highlight="0"@ (or do this in prefs) to get raw (although still HTML-escaped) code output. In this case line numbers will not be added.
+
+h2(#examples). Examples
+
+h3. List all active plugins as a table
+
+showing plugin author (as a link to the plugin author's website) and description
+
+pre. <txp:soo_plugin_display wraptag="table" break="tr">
+<td><txp:soo_plugin_name /></td><td><txp:soo_plugin_description /></td>
+</txp:soo_plugin_display>
+
+h3. Display plugin help
+
+pre. <txp:soo_plugin_display name="soo_image">
+<txp:soo_plugin_help />
+</txp:soo_plugin_display>
+
+h3. Display full source code
+
+leaving off the line numbers
+
+pre. <txp:soo_plugin_display name="soo_plugin_pref">
+<txp:soo_plugin_code show_line_numbers="" />
+</txp:soo_plugin_display>
+
+h3. Display a single method
+
+renumbering the lines, starting from 1
+
+pre. <txp:soo_plugin_display name="soo_txp_obj">
+<txp:soo_plugin_code php_class="soo_html" function="tag" reindex_lines="1" />
+</txp:soo_plugin_display>
+
+h2(#preferences). Preferences
+
+If you have the "soo_plugin_pref":http://ipsedixit.net/txp/92/soo_plugin_pref preference management system installed, you can adjust some of the default tag attribute values. Preference settings:
+
+* Default value for @soo_plugin_display@'s @form@ attribute
+* Default value for @soo_plugin_help@'s @strip_style@ attribute
+* Default value for @soo_plugin_help@'s @strip_title@ attribute
+* Default value for @soo_plugin_size@'s @format@ attribute
+* Default value for @soo_plugin_code@'s @highlight@ attribute
+* Default value for @soo_plugin_code@'s @show_line_numbers@ attribute
+* Default value for @soo_plugin_code@'s @tab_stop@ attribute
+
+h2(#history). Version History
+
+h3. 0.2.4 (2017-02-15)
+
+* Textpattern 4.6 compatibility update
+
+h3. 0.2.2 (12/20/2010), 0.2.3 (12/27/2010)
+
+* Code cleaning only
+
+h3. 0.2.1 (9/17/2010)
+
+* Improved function/class pattern matching in @soo_plugin_code@.
+
+h3. 0.2.0 (7/11/2010)
+
+* New @highlight@ attribute for @soo_plugin_code@, allows you to disable the standard syntax highlighting and output raw (but HTML-escaped) code.
+* Bug fix: @soo_plugin_code@ now handles multi-line comments correctly.
+
+%(warning)Note:% If you are upgrading from an earlier version, note that @soo_plugin_code@ has some other format changes (e.g., highlighted output is now wrapped in a @pre@ element), so some CSS changes might be needed.
+
+h3. 0.1.4 (7/4/2010)
+
+* @soo_plugin_help@ output can have HTML header levels transposed, using the @h_plus@ attribute
+
+h3. 0.1.3 (9/27/2009)
+
+* For @soo_plugin_code@, tab to space conversion now maintains tab-stop alignment
+
+h3. 0.1.2 (9/26/2009)
+
+* New attribute for @soo_plugin_help@:
+** @section_id@, start output from header element with specified HTML id, continuing until next header element with same or lower level
+
+h3. 0.1.1 (9/22/2009)
+
+* Fixed: SQL bug in list mode
+
+h3. 0.1 (9/18/2009)
+
+* Display most fields straight from the @txp_plugin@ table. Also,
+** plugin name or author name can be automatically linked to plugin author's website
+** @soo_plugin_help@ has options for stripping title and style first
+** @soo_plugin_size@ shows installed code size
+** @soo_plugin_code@ can display complete code or by function/class
+** compatible with *soo_plugin_pref* preference management system

config-dist.php

@@ -0,0 +1,24 @@
+<?php
+
+// Compiler configuration for a Textpattern plugin source file.
+// 
+// Uncomment the 'path' line and add the correct path to the plugin compiler.
+// 
+// Optionally, uncomment the 'helpfile' line and add the relative path to a 
+// separate help file (e.g., 'README.md').
+//
+// If you are using a separate help file and it is in Textile or Markdown 
+// format, uncomment the appropriate 'parser' line. You will have to install
+// the parser yourself, per the instructions in the config file for zem_tpl.php.
+// (NB: Parsedown is a parser for GitHub-flavoured Markdown.)
+// https://github.com/erusev/parsedown
+// https://github.com/textile/php-textile
+
+$compiler_cfg = array(
+#     'path'     => 'path/to/textpattern-plugin-template/zem_tpl.php',
+#     'helpfile' => 'README.md',
+#     'parser'   => 'textile',
+#     'parser'   => 'parsedown',
+);
+
+?>