diff options
Diffstat (limited to 'doc/plugins/contrib')
| -rw-r--r-- | doc/plugins/contrib/default_content_for___42__copyright__42___and___42__license__42__.mdwn | 11 | ||||
| -rw-r--r-- | doc/plugins/contrib/field/discussion.mdwn | 75 | ||||
| -rw-r--r-- | doc/plugins/contrib/headinganchors/discussion.mdwn | 32 | ||||
| -rw-r--r-- | doc/plugins/contrib/ikiwiki/directive/ymlfront.mdwn | 2 | ||||
| -rw-r--r-- | doc/plugins/contrib/imailhide.mdwn | 65 | ||||
| -rw-r--r-- | doc/plugins/contrib/report/ikiwiki/directive/report.mdwn | 24 | ||||
| -rw-r--r-- | doc/plugins/contrib/texinfo.mdwn | 2 | ||||
| -rw-r--r-- | doc/plugins/contrib/ymlfront.mdwn | 65 | ||||
| -rw-r--r-- | doc/plugins/contrib/ymlfront/discussion.mdwn | 25 |
9 files changed, 282 insertions, 19 deletions
diff --git a/doc/plugins/contrib/default_content_for___42__copyright__42___and___42__license__42__.mdwn b/doc/plugins/contrib/default_content_for___42__copyright__42___and___42__license__42__.mdwn index b9ad3cc8e..16c147b68 100644 --- a/doc/plugins/contrib/default_content_for___42__copyright__42___and___42__license__42__.mdwn +++ b/doc/plugins/contrib/default_content_for___42__copyright__42___and___42__license__42__.mdwn @@ -6,9 +6,9 @@ Someone was just asking for it and I had written these two plugins already some months ago, so I'm now publishing them here. -[`copyright.pm`](http://www.schwinge.homeip.net/~thomas/tmp/copyright.pm) +[`copyright.pm`](http://schwinge.homeip.net/~thomas/tmp/copyright.pm) and -[`license.pm`](http://www.schwinge.homeip.net/~thomas/tmp/license.pm) +[`license.pm`](http://schwinge.homeip.net/~thomas/tmp/license.pm) Usage instructions are found inside the two plugin files. @@ -45,3 +45,10 @@ by ikiwiki are likewise fine. --[[tschwinge]] > and can extend beyond just copyright and license, but has the disadvantage > that it doesn't support setting defaults for a given "subdirectory" > only. --[[smcv]] + +[[!template id=gitbranch branch=smcv/contrib/defcopyright author="[[tschwinge]]"]] + +> For `./gitremotes` convenience (taking the Linus approach to backups :-) ) +> I've added this to my git repository as a branch. No review, approval or +> ownership is implied, feel free to replace this with a branch in any other +> repository --[[smcv]] diff --git a/doc/plugins/contrib/field/discussion.mdwn b/doc/plugins/contrib/field/discussion.mdwn index 191f8b27d..6161f80df 100644 --- a/doc/plugins/contrib/field/discussion.mdwn +++ b/doc/plugins/contrib/field/discussion.mdwn @@ -327,6 +327,81 @@ smcv's discuission of field author vs meta author above. --[[Joey]] ----- +I think the main point is: what is (or should be) the main point of the +field plugin? If it's essentially a way to present a consistent +interface to access page-related structured information, then it makes +sense to have it very general. Plugins registering with fields would +then present ways for recovering the structure information from the page +(`ymlfront`, `meta`, etc), ways to manipulate it (like `meta` does), +etc. + +In this sense, security should be entirely up to the plugins, although +the fields plugin could provide some auxiliary infrastructure (like +determining where the data comes from and raise or lower the security +level accoringly). + +Namespacing is important, and it should be considered at the field +plugin interface level. A plugin should be able to register as +responsible for the processing of all data belonging to a given +namespace, but plugins should be able to set data in any namespace. So +for example, `meta` register are `meta` fields processing, and whatever +method is used to set the data (`meta` directive, `ymlfront`, etc) it +gets a say on what to do with data in its namespace. + +What I'm thinking of is something you could call fieldsets. The nice +thing about them is that, aside from the ones defined by plugins (like +`meta`), it would be possible to define custom ones (with a generic, +default processor) in an appropriate file (like smileys and shortcuts) +with a syntax like: + + [[!fieldset book namespace=book + fields="author title isbn" + fieldtype="text text text"]] + +after which, you coude use + + [[!book author="A. U. Thor" + title="Fields of Iki"]] + +and the data would be available under the book namespace, and thus +as BOOK_AUTHOR, BOOK_TITLE etc in templates. + +Security, in this sense, would be up to the plugin responsible for the +namespace processing (the default handler would HTML-escape text fields +scrub, html fields, safeurl()ify url fields, etc.) + +> So, are you saying that getting a field value is sort of a two-stage process? Get the value from anywhere, and then call the "security processor" for that namespace to "secure" the value? I think "namespaces" are really orthogonal to this issue. What the issue seems to be is: + + * what form do we expect the raw field to be in? (text, URL, HTML) + * what form do we expect the "secured" output to be in? (raw HTML, scrubbed HTML, escaped HTML, URL) + +> Only if we know both these things will we know what sort of security processing needs to be done. + +>> Fieldsets are orthogonal to the security issue in the sense that you can use +>> them without worrying about the field security issue, but they happen to be +>> a rather clean way of answering those two questions, by allowing you to +>> attach preprocessing attributes to a field in a way that the user +>> (supposedly) cannot mingle with. + +> There is also a difference between field values that are used inside pagetemplate, and field values which are used as part of a page's content (e.g. with ftemplate). If you have a TITLE, you want it to be HTML-escaped if you're using it inside pagetemplate, but you don't want it to be HTML-escaped if you're using it inside a page's content. On the other hand, if you have, say, FEEDLINKS used inside pagetemplate, you don't wish it to be HTML-escaped at all, or your page content will be completely stuffed. + +>> Not to talk about the many different ways date-like fields might be need +>> processing. It has already been proposed to solve this problem by exposing +>> the field values under different names depending on the kind or amout of +>> postprocessing they had (e.g. RAW_SOMEFIELD, SOMEFIELD, to which we could add +>> HTML_SOMEFIELD, URL_SOMEFIELD or whatever). Again, fieldsets offer a simple way +>> of letting Ikiwiki know what kind of postprocessing should be offered for +>> that particular field. + +> So, somehow, we have to know the meaning of a field before we can use it properly, which kind of goes against the idea of having something generic. + +>> We could have a default field type (text, for example), and a way to set a +>> different field type (which is what my fieldset proposal was about). + +> --[[KathrynAndersen]] + +----- + I was just looking at HTML5 and wondered if the field plugin should generate the new Microdata tags (as well as the internal structures)? <http://slides.html5rocks.com/#slide19> -- [[Will]] > This could just as easily be done as a separate plugin. Feel free to do so. --[[KathrynAndersen]] diff --git a/doc/plugins/contrib/headinganchors/discussion.mdwn b/doc/plugins/contrib/headinganchors/discussion.mdwn index 91fe04a6d..151af8d92 100644 --- a/doc/plugins/contrib/headinganchors/discussion.mdwn +++ b/doc/plugins/contrib/headinganchors/discussion.mdwn @@ -1 +1,33 @@ Isn't this functionality a part of what [[plugins/toc]] needs and does? Then probably the [[plugins/toc]] plugin's code could be split into the part that implements the [[plugins/contrib/headinganchors]]'s functionality and the TOC generation itself. That will bring more order into the code and the set of available plugins. --Ivan Z. + +--- + +A patch to make it more like MediaWiki: + +<pre>--- headinganchors.pm ++++ headinganchors.pm +@@ -5,6 +5,7 @@ + use warnings; + use strict; + use IkiWiki 2.00; ++use URI::Escape; + + sub import { + hook(type => "sanitize", id => "headinganchors", call => \&headinganchors); +@@ -14,9 +15,11 @@ + my $str = shift; + $str =~ s/^\s+//; + $str =~ s/\s+$//; +- $str = lc($str); +- $str =~ s/[&\?"\'\.,\(\)!]//mig; +- $str =~ s/[^a-z]/_/mig; ++ $str =~ s/\s/_/g; ++ $str =~ s/"//g; ++ $str =~ s/^[^a-zA-Z]/z-/; # must start with an alphabetical character ++ $str = uri_escape_utf8($str); ++ $str =~ s/%/./g; + return $str; + } + </pre> + +--Changaco diff --git a/doc/plugins/contrib/ikiwiki/directive/ymlfront.mdwn b/doc/plugins/contrib/ikiwiki/directive/ymlfront.mdwn index bb4a58fc6..1a01834f8 100644 --- a/doc/plugins/contrib/ikiwiki/directive/ymlfront.mdwn +++ b/doc/plugins/contrib/ikiwiki/directive/ymlfront.mdwn @@ -14,4 +14,4 @@ There is one argument to this directive. The YAML-format data. This should be enclosed inside triple-quotes to preserve the data correctly. If more than one ymlfront directive is given per page, the result is undefined. -Likewise, it is inadvisable to try to mix the "---" ymlfront format with the directive form of the data. +Likewise, it is inadvisable to try to mix the non-directive ymlfront format with the directive form of the data. diff --git a/doc/plugins/contrib/imailhide.mdwn b/doc/plugins/contrib/imailhide.mdwn new file mode 100644 index 000000000..6009aa012 --- /dev/null +++ b/doc/plugins/contrib/imailhide.mdwn @@ -0,0 +1,65 @@ +[[!template id=plugin name=imailhide author="Peter_Vizi"]] +[[!tag type/widget type/html]] + +# Mailhide Plugin for Ikiwiki + +This plugin provides the directive mailhide, that uses the [Mailhide +API][1] to protect email addresses from spammers. + +## Dependencies + +The [Captcha::reCAPTCHA::Mailhide][2] perl module is required for this +plugin. + +## Download + +You can get the source code from [github][3]. + +## Installation + +Copy `imailhide.pm` to `/usr/share/perl/5.10.0/IkiWiki/Plugin` or +`~/.ikiwiki/IkiWiki/Plugin`, and enable it in your `.setup` file + + add_plugins => [qw{goodstuff imailhide ....}], + mailhide_public_key => "8s99vSA99fF11mao193LWdpa==", + mailhide_private_key => "6b5e4545326b5e4545326b5e45453223", + mailhide_default_style => "short", + +## Configuration + +### `mailhide_public_key` + +This is your personal public key that you can get at [Google][4]. + +### `mailhide_private_key` + +This is your personal private key that you can get at [Google][4]. + +### `mailhide_default_style` + +As per the recommendation of the [Mailhide API documentation][5], you +can define this as `short` or `long`. The `short` parameter will +result in `<a href="...">john</a>` links, while the `long` parameter +will result in `joh<a href="...">...</a>@example.com`. + +## Parameters + +### `email` + +*Required.* This is the email addres that you want to hide. + +### `style` + +*Optional.* You can set the style parameter individually for each + `mailhide` call. See `mailhide_default_style` for details. + +## Known Issues + +1. [opening new window when displaying email address][6] + +[1]: http://www.google.com/recaptcha/mailhide/ +[2]: http://search.cpan.org/perldoc?Captcha::reCAPTCHA::Mailhide +[3]: http://github.com/petervizi/imailhide +[4]: http://www.google.com/recaptcha/mailhide/apikey +[5]: http://code.google.com/apis/recaptcha/docs/mailhideapi.html +[6]: http://github.com/petervizi/imailhide/issues#issue/1 diff --git a/doc/plugins/contrib/report/ikiwiki/directive/report.mdwn b/doc/plugins/contrib/report/ikiwiki/directive/report.mdwn index 8f8e6b4e8..df88b33ad 100644 --- a/doc/plugins/contrib/report/ikiwiki/directive/report.mdwn +++ b/doc/plugins/contrib/report/ikiwiki/directive/report.mdwn @@ -30,6 +30,11 @@ them work as wiki pages. **pages**: A PageSpec to determine the pages to report on. +**pagenames**: If given instead of pages, this is interpreted as a +space-separated list of links to pages, and they are shown in exactly the order +given: the sort and pages parameters cannot be used in conjunction with this +one. If they are used, they will be ignored. + **trail**: A page or pages to use as a "trail" page. When a trail page is used, the matching pages are limited to (a subset @@ -45,6 +50,11 @@ For example: This will take the links from both the "animals/cats" page and the "animals/dogs" page as the set of pages to apply the PageSpec to. +**start**: Start the report at the given page-index; the index starts +from zero. + +**count**: Report only on N pages where count=N. + **sort**: A SortSpec to determine how the matching pages should be sorted. **here_only**: Report on the current page only. @@ -86,7 +96,19 @@ The "mood_summary" template might be like this: ### <TMPL_VAR NAME="TITLE"> (<TMPL_VAR NAME="DATE">) \[[<TMPL_VAR NAME="PAGE">]] <TMPL_VAR NAME="DESCRIPTION"> - + +### Multi-page Reports + +Reports can now be split over multiple pages, so that there aren't +too many items per report-page. + +**per_page**: how many items to show per report-page. + +**first_page_is_index**: If true, the first page of the report is just +an index which contains links to the other report pages. +If false, the first page will contain report-content as well as links +to the other pages. + ### Advanced Options The following options are used to improve efficiency when dealing diff --git a/doc/plugins/contrib/texinfo.mdwn b/doc/plugins/contrib/texinfo.mdwn index 595bd27aa..a2769166d 100644 --- a/doc/plugins/contrib/texinfo.mdwn +++ b/doc/plugins/contrib/texinfo.mdwn @@ -8,7 +8,7 @@ This plugin is not neccessarily meant to enable people to write arbitrary wiki pages in the Texinfo format (even though that is possible, of course), but rather to ease collaboration on existing Texinfo documents. -The plugin is available at <http://www.schwinge.homeip.net/~thomas/tmp/texinfo.pm>. +The plugin is available at <http://schwinge.homeip.net/~thomas/tmp/texinfo.pm>. It's very basic at the moment, but will be improved over time. diff --git a/doc/plugins/contrib/ymlfront.mdwn b/doc/plugins/contrib/ymlfront.mdwn index a2c649044..2805be04f 100644 --- a/doc/plugins/contrib/ymlfront.mdwn +++ b/doc/plugins/contrib/ymlfront.mdwn @@ -10,6 +10,9 @@ IkiWiki::Plugin::ymlfront - add YAML-format data to a page # activate the plugin add_plugins => [qw{goodstuff ymlfront ....}], + # configure the plugin + ymlfront_delim => [qw(--YAML-- --YAML--)], + ## DESCRIPTION This plugin provides a way of adding arbitrary meta-data (data fields) to any @@ -25,23 +28,57 @@ This plugin is meant to be used in conjunction with the [[field]] plugin. ## DETAILS -If one is not using the ymlfront directive, the YAML-format data in a page -must be placed at the start of the page and delimited by lines containing -precisely three dashes. The "normal" content of the page then follows. +There are three formats for adding YAML data to a page. These formats +should not be mixed - the result is undefined. -For example: +1. ymlfront directive + + See [[ikiwiki/directive/ymlfront]] for more information. - --- - title: Foo does not work - Urgency: High - Status: Assigned - AssignedTo: Fred Nurk - Version: 1.2.3 - --- - When running on the Sprongle system, the Foo function returns incorrect data. +2. default YAML-compatible delimiter + + By default, the YAML-format data in a page is placed at the start of + the page and delimited by lines containing precisely three dashes. + This is what YAML itself uses to delimit multiple documents. + The "normal" content of the page then follows. + + For example: + + --- + title: Foo does not work + Urgency: High + Status: Assigned + AssignedTo: Fred Nurk + Version: 1.2.3 + --- + When running on the Sprongle system, the Foo function returns incorrect data. + + What will normally be displayed is everything following the second line of dashes. That will be htmlized using the page-type of the page-file. + +3. user-defined delimiter + + Instead of using the default "---" delimiter, the user can define, + in the configuration file, the **ymlfront_delim** value, which is an + array containing two strings. The first string defines the markup for + the start of the YAML data, and the second string defines the markip + for the end of the YAML data. These two strings can be the same, or + they can be different. In this case, the YAML data section is not + required to be at the start of the page, but as with the default, it + is expected that only one data section will be on the page. + + For example: + + --YAML-- + title: Foo does not work + Urgency: High + Status: Assigned + AssignedTo: Fred Nurk + Version: 1.2.3 + --YAML-- + When running on the Sprongle system, the Foo function returns incorrect data. -What will normally be displayed is everything following the second line of dashes. -That will be htmlized using the page-type of the page-file. + What will normally be displayed is everything outside the delimiters, + both before and after. That will be htmlized using the page-type of the page-file. ### Accessing the Data diff --git a/doc/plugins/contrib/ymlfront/discussion.mdwn b/doc/plugins/contrib/ymlfront/discussion.mdwn index b1fd65fff..b122294bb 100644 --- a/doc/plugins/contrib/ymlfront/discussion.mdwn +++ b/doc/plugins/contrib/ymlfront/discussion.mdwn @@ -4,3 +4,28 @@ Now that I have implemented a \[[!ymlfront ...]] directive, I would like to remo * it is non-standard Any objections? + +> Well, I don't have much standing since I have been too lame to integrate +> ymlfront into ikiwiki yet. Buy, my opinion is, I liked the old +> format of putting the YAML literally at the front of the file. It +> seemed to allow parsing the file as YAML, using any arbitrary YAML +> processer. And it was nice how it avoided boilerplate. --[[Joey]] + +>> The old delimited format also has the advantage of being remarkably similar to the +>> [MultiMarkDown](http://fletcherpenney.net/multimarkdown/users_guide/multimarkdown_syntax_guide/) +>> way of including metadata in documents. The only difference is that MMD doesn't expect the +>> triple-dash separators, but I'm thinking about submitting a patch to MMD to actually support +>> that syntax. --GB + +>>> Yes, the idea was to allow the file to be parsed as YAML, you're right. I just found that I tended to have problems when people used "---" for horizontal rules. However, I have also found that trying to keep it solely as an IkiWiki directive doesn't work either, since sometimes the meta-data I need also contained "]]" which broke the parsing of the directive. +>>> So I have decided to go for a compromise, and make the delimiter configurable, rather than hardcoded as "---"; the triple-dash is the default, but it can be configured to be something else instead. I haven't pushed the change yet, but I have written it, and it seems to work. -- [[KathrynAndersen]] + +>>>> I'm not sure about what kind of problems you're meeting with "---" being used +>>>> for horizontal rules: isn't it sufficient to just check that (1) the triple-dash +>>>> is the first thing in the page and (2) there are only YAML-style assignments +>>>> (and no blank lines) between the two markers? Check #2 would also be enough to +>>>> support MMD-style metadata, which means (a) no start marker and (b) empty line +>>>> to mark the end of the metadata block. Would this be supported by the plugin? +>>>> --GB + +>>>>> Since I allow all legal YAML, the only way to check if it is legal YAML is to use the YAML parser, by which time one is already parsing the YAML, so it seems a bit pointless to check before one does so. -- KA |