diff options
Diffstat (limited to 'doc/plugins')
135 files changed, 3415 insertions, 517 deletions
diff --git a/doc/plugins/404.mdwn b/doc/plugins/404.mdwn index ad332ee04..bf033202a 100644 --- a/doc/plugins/404.mdwn +++ b/doc/plugins/404.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=404 author="[[Simon_McVittie|smcv]]"]] -[[!tag type/useful]] +[[!tag type/web]] This plugin lets you use the IkiWiki CGI script as an Apache 404 handler, to give the behaviour of various other wiki engines where visiting a @@ -13,8 +13,4 @@ file: (The path here needs to be whatever the path is to the ikiwiki.cgi from the root of your web server.) -Or put something like this in the wiki's Lighttpd (>=1.4.17) configuration file: - - server.error-handler-404 = "/ikiwiki.cgi" - diff --git a/doc/plugins/404/discussion.mdwn b/doc/plugins/404/discussion.mdwn new file mode 100644 index 000000000..5a8e8ed85 --- /dev/null +++ b/doc/plugins/404/discussion.mdwn @@ -0,0 +1,3 @@ +With Apache, if you have a page foo/bar/baz but no foo/bar, and if you've +disabled `Indexes` option, you'll end up with a `403` response for foo/bar. +The 404 plugin doesn't try to handle that. But it should. -- [[Jogo]] diff --git a/doc/plugins/aggregate.mdwn b/doc/plugins/aggregate.mdwn index e2efcd83f..75123d923 100644 --- a/doc/plugins/aggregate.mdwn +++ b/doc/plugins/aggregate.mdwn @@ -1,13 +1,17 @@ [[!template id=plugin name=aggregate author="[[Joey]]"]] -[[!tag type/useful]] +[[!tag type/special-purpose]] This plugin allows content from other feeds to be aggregated into the wiki. To specify feeds to aggregate, use the [[ikiwiki/directive/aggregate]] [[ikiwiki/directive]]. -The [[meta]] and [[tag]] plugins are also recommended. Either the -[[htmltidy]] or [[htmlbalance]] plugin is suggested, since feeds can easily -contain html problems, some of which these plugins can fix. +## requirements + +The [[meta]] and [[tag]] plugins are also recommended to be used with this +one. Either the [[htmltidy]] or [[htmlbalance]] plugin is suggested, since +feeds can easily contain html problems, some of which these plugins can fix. + +## triggering aggregation You will need to run ikiwiki periodically from a cron job, passing it the --aggregate parameter, to make it check for new posts. Here's an example @@ -15,6 +19,11 @@ crontab entry: */15 * * * * ikiwiki --setup my.wiki --aggregate --refresh +The plugin updates a file `.ikiwiki/aggregatetime` with the unix time stamp +when the next aggregation run could occur. (The file may be empty, if no +aggregation is required.) This can be integrated into more complex cron +jobs or systems to trigger aggregation only when needed. + Alternatively, you can allow `ikiwiki.cgi` to trigger the aggregation. You should only need this if for some reason you cannot use cron, and instead want to use a service such as [WebCron](http://webcron.org). To enable @@ -39,3 +48,10 @@ plugin as well as aggregate itself, since feed entries will be stored as HTML, and as first-class wiki pages -- each one generates a separate HTML page in the output, and they can even be edited. This option is provided only for backwards compatability. + +## cookies + +The `cookiejar` option can be used to configure how [[!cpan LWP::UserAgent]] +handles cookies. The default is to read them from a file +`~/.ikiwiki/cookies`, which can be populated using standard perl cookie +tools like [[!cpan HTTP::Cookies]]. diff --git a/doc/plugins/aggregate/discussion.mdwn b/doc/plugins/aggregate/discussion.mdwn index 1a9844577..028775ec8 100644 --- a/doc/plugins/aggregate/discussion.mdwn +++ b/doc/plugins/aggregate/discussion.mdwn @@ -89,3 +89,49 @@ New bug: new posts aren't getting displayed (or cached for aggregation). After f >>> mind having a copy to investigate. --[[Joey]] >>>> Didn't think of that, will keep a copy if there's a next time. -- [[schmonz]] + +----- + +In a corporate environment where feeds are generally behind +authentication, I need to prime the aggregator's `LWP::UserAgent` +with some cookies. What I've done is write a custom plugin to populate +`$config{cookies}` with an `HTTP::Cookies` object, plus this diff: + + --- /var/tmp/pkg/lib/perl5/vendor_perl/5.10.0/IkiWiki/Plugin/aggregate.pm 2010-06-24 13:03:33.000000000 -0400 + +++ aggregate.pm 2010-06-24 13:04:09.000000000 -0400 + @@ -488,7 +488,11 @@ + } + $feed->{feedurl}=pop @urls; + } + - my $res=URI::Fetch->fetch($feed->{feedurl}); + + my $res=URI::Fetch->fetch($feed->{feedurl}, + + UserAgent => LWP::UserAgent->new( + + cookie_jar => $config{cookies}, + + ), + + ); + if (! $res) { + $feed->{message}=URI::Fetch->errstr; + $feed->{error}=1; + +It works, but I have to remember to apply the diff whenever I update +ikiwiki. Can you provide a more elegant means of allowing cookies and/or +the user agent to be programmatically manipulated? --[[schmonz]] + +> Ping -- is the above patch perhaps acceptable (or near-acceptable)? -- [[schmonz]] + +>> Pong.. I'd be happier with a more 100% solution that let cookies be used +>> w/o needing to write a custom plugin to do it. --[[Joey]] + +>>> According to LWP::UserAgent, for the common case, a complete +>>> and valid configuration for `$config{cookies}` would be `{ file => +>>> "$ENV{HOME}/.cookies.txt" }`. In the more common case of not needing +>>> to prime one's cookies, `cookie_jar` can be `undef` (that's the +>>> default). In my less common case, the cookies are generated by +>>> visiting a couple magic URLs, which would be trivial to turn into +>>> config options, except that these particular URLs rely on SPNEGO +>>> and so LWP::Authen::Negotiate has to be loaded. So I think adding +>>> `$config{cookies}` (and using it in the aggregate plugin) should +>>> be safe, might help people in typical cases, and won't prevent +>>> further enhancements for less typical cases. --[[schmonz]] + +>>>> Ok, done. Called it cookiejar. --[[Joey]] diff --git a/doc/plugins/amazon_s3.mdwn b/doc/plugins/amazon_s3.mdwn index 331dc4acf..7fe60cb8d 100644 --- a/doc/plugins/amazon_s3.mdwn +++ b/doc/plugins/amazon_s3.mdwn @@ -22,9 +22,10 @@ This plugin uses the following settings in the setup file: set it to "foo", then the url will be "http://foo.s3.amazonaws.com/wiki/". * `amazon_s3_prefix` - A prefix to prepend to each page name. - The default is "wiki/". Note that due to S3 limitations (lack of support - for uploading a root key), it is not possible to set the prefix to an - empty string. + The default is "wiki/". Note: In order to host your site at the root, + it needs to be set to "", and you'll have to + [read this](http://aws.typepad.com/aws/2011/02/host-your-static-website-on-amazon-s3.html) + for details about configuring your S3 bucket as a website. * `amazon_s3_location` - Optionally, this can be set to control which datacenter to use. For example, set it to "EU" to for Europe. * `amazon_s3_dupindex` - Normally, when `usedirs` is enabled, @@ -33,7 +34,8 @@ This plugin uses the following settings in the setup file: "index.html" in their names to work, you can enable this option. Then each index.html file will be stored in S3 *twice*, under both names. This will use more disk and bandwidth, and is not recommended unless you really - need it for some reason. + need it for some reason. These days, it's probably better to configure + your S3 bucket as a website. Note that you should still set `destdir` in the setup file. The files that are uploaded to Amazon S3 will still be written to the destdir, too. diff --git a/doc/plugins/autoindex.mdwn b/doc/plugins/autoindex.mdwn index 03e2d12f3..e1cfe1157 100644 --- a/doc/plugins/autoindex.mdwn +++ b/doc/plugins/autoindex.mdwn @@ -1,7 +1,10 @@ [[!template id=plugin name=autoindex core=0 author="[[Joey]]"]] -[[!tag type/useful]] +[[!tag type/special-purpose]] This plugin searches for [[SubPages|ikiwiki/subpage]] with a missing parent page, and generates the parent pages. The generated page content is -controlled by the `autoindex.tmpl` [[template|wikitemplates]], which by +controlled by the `autoindex.tmpl` [[template|templates]], which by default, uses a [[map]] to list the SubPages. + +The `autoindex_commit` setting is enabled by default, and causes +pages generated by autoindex to be checked into version control. diff --git a/doc/plugins/autoindex/discussion.mdwn b/doc/plugins/autoindex/discussion.mdwn index 2d6b6f1f0..76d09cd3c 100644 --- a/doc/plugins/autoindex/discussion.mdwn +++ b/doc/plugins/autoindex/discussion.mdwn @@ -1,6 +1,13 @@ Would it be possible to add an option to only generate the index files for the html output and not place the markdown files in the wiki source? +> Or better still, add a mechanism for ikiwiki to hold transient source +> pages in memory and render them as if they existed, without actually +> writing them out, as [[JoeRayhawk]] suggests below? I think +> add_autofile would be the way to do this. +> I've added this to [[todo]] as [[todo/autoindex should use add__95__autofile]] +> and [[todo/transient_pages]]. --[[smcv]] + The reason being that I have a lot of directories which need to be autoindexed, but I would prefer if the index files didn't clutter up my git repository. @@ -15,6 +22,8 @@ If you just don't want to clutter your git repo, below it's a patch does the fol * If you set autoindex_commit to 1 (this is the default), auto-generated index files will be put in the repo provided you enabled rcs backend. +[[!toggle id="patch-for-autoindex_commit" text="patch for autoindex_commit"]] +[[!toggleable id="patch-for-autoindex_commit" text=""" <pre> --- autoindex.pm.orig 2009-10-01 17:13:51.000000000 +0800 +++ autoindex.pm 2009-10-01 17:21:09.000000000 +0800 @@ -58,6 +67,18 @@ If you just don't want to clutter your git repo, below it's a patch does the fol gettext("automatic index generation"), undef, undef); </pre> - +"""]] Warning: I guess this patch may work, but I *haven't tested it yet*. -- [[weakish]] + +------ + +`autoindex_commit => 0` would be nice, but uncommited files are definitely not. +<pre> +remote: From /srv/git/test3 +remote: 3047077..1df636c master -> origin/master +remote: error: Untracked working tree file 'test.mdwn' would be overwritten by merge. Aborting +remote: 'git pull --prune origin' failed: at /usr/share/perl5/IkiWiki/Plugin/git.pm line 201. +</pre> + +It'd be nice if we were able to notice directories with no associated compilable markup files and compile a simple map directive straight to HTML without any intermediate markup file being involved at all. -- JoeRayhawk diff --git a/doc/plugins/blogspam.mdwn b/doc/plugins/blogspam.mdwn index a13b6e8f4..c158316d4 100644 --- a/doc/plugins/blogspam.mdwn +++ b/doc/plugins/blogspam.mdwn @@ -23,7 +23,7 @@ you can check whether the interaction with blogspam.net works. The `blogspam_pagespec` setting is a [[ikiwiki/PageSpec]] that can be used to configure which pages are checked for spam. The default is to check all edits. If you only want to check [[comments]] (not wiki page edits), -set it to "postcomment(*)". +set it to "postcomment(*)". Posts by admins are never checked for spam. By default, the blogspam.net server is used to do the spam checking. To change this, the `blogspam_server` option can be set to the url for a diff --git a/doc/plugins/calendar.mdwn b/doc/plugins/calendar.mdwn index bc1bc6c71..76e718a3b 100644 --- a/doc/plugins/calendar.mdwn +++ b/doc/plugins/calendar.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=calendar author="[[ManojSrivastava]]"]] -[[!tag type/chrome]] +[[!tag type/widget]] This plugin provides a [[ikiwiki/directive/calendar]] [[ikiwiki/directive]]. The directive displays a calendar, similar to the typical calendars shown on @@ -14,6 +14,7 @@ customization. * `month-calendar` - The month calendar as a whole. * `month-calendar-head` - The head of the month calendar (ie,"March"). +* `month-calendar-arrow` - Arrow pointing to previous/next month. * `month-calendar-day-head` - A column head in the month calendar (ie, a day-of-week abbreviation). * `month-calendar-day-noday`, `month-calendar-day-link`, @@ -27,6 +28,7 @@ customization. weekends. * `year-calendar` - The year calendar as a whole. * `year-calendar-head` - The head of the year calendar (ie, "2007"). +* `year-calendar-arrow` - Arrow pointing to previous/next year. * `year-calendar-subhead` - For example, "Months". * `year-calendar-month-link`, `year-calendar-month-nolink`, `year-calendar-month-future`, `year-calendar-this-month` - The month diff --git a/doc/plugins/calendar/discussion.mdwn b/doc/plugins/calendar/discussion.mdwn index 9d57b7a1e..6fc21e8ee 100644 --- a/doc/plugins/calendar/discussion.mdwn +++ b/doc/plugins/calendar/discussion.mdwn @@ -1,6 +1,23 @@ It would be nice if the "month" type calendar could collect all of the matching pages on a given date in some inline type way. --[[DavidBremner]] +> I agree, but I have not come up with good html to display them. Seems +> it might need some sort of popup. + Is it possible to get the calendar to link to pages based not on their timestamp (as I understand that it does now, or have I misunderstood this?) and instead on for example their location in a directory hierarchy. That way the calendar could be used as a planning / timeline device which I think would be great. --[[Alexander]] -I would like the ability to specify relative previous months. This way I could have a sidebar with the last three months by specifying no month, then 'month="-1"' and 'month="-2"'. Negative numbers for the month would otherwise be invalid, so this shouldn't produce any conflicts with expected behavior. (Right?) -- [[StevenBlack]] +I would like the ability to specify relative previous months. This way I +could have a sidebar with the last three months by specifying no month, +then 'month="-1"' and 'month="-2"'. Negative numbers for the month would +otherwise be invalid, so this shouldn't produce any conflicts with expected +behavior. (Right?) -- [[StevenBlack]] + +> Great idea! Just implemented that and also relative years. --[[Joey]] + +Anyone know of a way to generate a link to the previous and next calendar pages for archive browsing? In the worst case, that requires regenerating pages on either side of the current one when something is inserted in the history, and I can't quite figure that much out. --[[JasonRiedy]] + +> Well, the calendar directive puts such links on the calendars. They're +> the arrows to either side of the month or year at the top. --[[Joey]] + +>> Thanks. I either missed them or they appeared on an upgrade. I might make them a bit more obvious with +>> "Previous Month" / "Next Month" links above and below the text. Someday.--[[JasonRiedy]] diff --git a/doc/plugins/color.mdwn b/doc/plugins/color.mdwn index dbb8b870c..d639bf563 100644 --- a/doc/plugins/color.mdwn +++ b/doc/plugins/color.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=color core=0 author="[[ptecza]]"]] -[[!tag type/chrome]] +[[!tag type/widget]] This plugin provides a [[ikiwiki/directive/color]] [[ikiwiki/directive]]. The directive can be used to color a piece of text on a page. diff --git a/doc/plugins/comments.mdwn b/doc/plugins/comments.mdwn index 7e2232411..48b6c6ae7 100644 --- a/doc/plugins/comments.mdwn +++ b/doc/plugins/comments.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=comments author="[[Simon_McVittie|smcv]]"]] -[[!tag type/useful]] +[[!tag type/web]] This plugin adds "blog-style" comments. Unlike the wiki-style freeform Discussion pages, these comments are posted by a simple form, cannot later @@ -14,8 +14,8 @@ authorship should hopefully be unforgeable by CGI users. The intention is that on a non-wiki site (like a blog) you can lock all pages for admin-only access, then allow otherwise unprivileged (or perhaps even anonymous) users to comment on posts. See the documentation of the -[[lockedit]] and [[anonok]] pages for details on locking down a wiki so -users can only post comments. +[[opendiscussion]], [[lockedit]] and [[anonok]] pages for details on locking +down a wiki so readers can only post comments. Individual comments are stored as internal-use pages named something like `page/comment_1`, `page/comment_2`, etc. These pages internally use a @@ -45,8 +45,11 @@ There are some global options for the setup file: ## comment moderation If you enable the [[blogspam]] plugin, comments that appear spammy will be -held for moderation. Wiki admins can access the comment moderation queue +held for moderation. (Or with the [[moderatedcomments]] plugin, all +comments will be held.) Wiki admins can access the comment moderation queue via a button on their Preferences page. -The comments are stored in `.ikiwiki/comments_pending/`, and can be -deleted, or moved into the wiki's srcdir to be posted. +Comments pending moderation are not checked into revision control. +To find unmoderated comments, `find /your/ikiwiki/srcdir -name '*._comment_pending'` +To manually moderate a comment, just rename the file, removing the +"_pending" from the end, and check it into revision control. diff --git a/doc/plugins/comments/discussion.mdwn b/doc/plugins/comments/discussion.mdwn index 396d1f6d4..3043b0106 100644 --- a/doc/plugins/comments/discussion.mdwn +++ b/doc/plugins/comments/discussion.mdwn @@ -1,3 +1,18 @@ +## Syndication autodiscovery for comment feeds + +A standard `\[[!inline]]` directive adds links to the autogenerated syndication feeds using link tags in the header: + + <link rel="alternate" type="application/rss+xml" title="$title" href="$page.atom" /> + <link rel="alternate" type="application/atom+xml" title="$title" href="$page.atom" /> + +These links aren't added to my pages that include comments even though comments generate syndication feeds. How can I configure the comments plugin to add these links to the header? (These links are required for user-agent autodiscovery of syndication feeds.) --[[anderbubble]] + +## Moderating comments from the CLI + +How do you do this, without using the UI in the Preferences? + +Please put this info on the page. Many thanks --[[Kai Hendry]] + ## Why internal pages? (unresolved) Comments are saved as internal pages, so they can never be edited through the CGI, diff --git a/doc/plugins/conditional.mdwn b/doc/plugins/conditional.mdwn index 95ffb2764..27a99bb7c 100644 --- a/doc/plugins/conditional.mdwn +++ b/doc/plugins/conditional.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=conditional core=1 author="[[Joey]]"]] -[[!tag type/format]] +[[!tag type/special-purpose]] This plugin provides the [[ikiwiki/directive/if]] [[ikiwiki/directive]]. With this directive, you can make text be conditionally displayed on a page. diff --git a/doc/plugins/conditional/discussion.mdwn b/doc/plugins/conditional/discussion.mdwn index 629d05940..6e84fdfc1 100644 --- a/doc/plugins/conditional/discussion.mdwn +++ b/doc/plugins/conditional/discussion.mdwn @@ -1,3 +1,28 @@ +## Conditional broken? + +Using \[\[!if test="tagged(plugin)" then="= Tagged as plugin =" else="*No plugins found*"]] on this wiki *should* present the 'Tagged as plugin' heading, instead it emits 'no plugins found'. Is the conditional plugin currently broken for tags or am I misusing it? Thanks. + +-- Thiana + +> This wiki has no page named "plugin", so nothing links to it; tags are a species of link +> so tagging a large number of pages with a tag that doesn't exist (which change has +> been reverted) doesn't make the pagespec match. It would if the tag's page existed. --[[Joey]] + +>> So if I understand this correctly... Assuming the tags Tag_A and Tag_B, the existence of +>> @wiki-home@/tags/Tag_A.creole, and a number of files with a \[\[!tag Tag_A Tag_B]] the +>> following is correct? +>> +>> * \[\[!if test="tagged(Tag_A)" then="OK" else="Fail"]] => OK +>> * \[\[!if test="tagged(Tag_B)" then="OK" else="Fail"]] => Fail +>> * \[\[!if test="tagged(Tag_A) and tagged(Tag_B)" then="OK" else="Fail"]] => Fail +>> +>> Is that the expected behaviour? If so, that's not what I'm seeing here since they all result +>> in a Fail. If not, what exactly is wrong with those conditionals? Thanks. +>> +>> -- Thiana + +---- + Would there be a way for this plugin to emit fewer blank lines (i.e. *none at all*)? For example, having a look at [this page](http://www.bddebian.com/~wiki/Hurd/)'s sidebar. diff --git a/doc/plugins/contrib.mdwn b/doc/plugins/contrib.mdwn index ac6c1b751..d8199a756 100644 --- a/doc/plugins/contrib.mdwn +++ b/doc/plugins/contrib.mdwn @@ -1,4 +1,4 @@ These plugins are provided by third parties and are not currently included in ikiwiki. See [[install]] for installation help. -[[!map pages="plugins/contrib/* and !*/Discussion"]] +[[!map pages="plugins/contrib/* and !plugins/contrib/*/* and !*/Discussion"]] diff --git a/doc/plugins/contrib/album.mdwn b/doc/plugins/contrib/album.mdwn index 395c99bce..daf16fd3c 100644 --- a/doc/plugins/contrib/album.mdwn +++ b/doc/plugins/contrib/album.mdwn @@ -9,9 +9,11 @@ thoughts about this plugin). This plugin formats a collection of images into a photo album, in the same way as many websites: good examples include the PHP application [Gallery](http://gallery.menalto.com/), Flickr, -and Facebook's Photos "application". I've called it `album` -to distinguish it from [[contrib/gallery|plugins/contrib/gallery]], -although `gallery` might well be a better name for this functionality. +and Facebook's Photos "application". + +I've called it `album` to distinguish it from +[[contrib/gallery|plugins/contrib/gallery]], although `gallery` might well be +a better name for this functionality. The web UI I'm trying to achieve consists of one [HTML page of thumbnails](http://www.pseudorandom.co.uk/2008/2008-03-08-panic-cell-gig/) @@ -26,83 +28,129 @@ individual photos can't be bookmarked in a meaningful way, and the best it can do as a fallback for non-Javascript browsers is to provide a direct link to the image.) -## Writing the viewers +<h2 id="album"><code>album</code> directive</h2> + +Each page containing an `album` directive is treated as a photo album. + +Every image attached to an album or its subpages is considered to be part of +the album. A "viewer" page, with the wiki's default page extension, will be +generated in the [[transient underlay|todo/transient_pages]] to display the +image, if there isn't already a page of the same name as the image: for +instance, if `debconf` is an album and `debconf/tuesday/p100.jpg` exists, +then `debconf/tuesday/p100.mdwn` might be created. + +There's currently a hard-coded list of extensions that are treated as images: +`png`, `gif`, `jpg`, `jpeg` or `mov` files. More image and video types could +be added in future. Videos aren't currently handled very well; +ideally, something like totem-video-thumbnailer would be used. + +The `album` directive also produces an [[ikiwiki/directive/inline]] which +automatically includes all the viewers for this album, except those that +will appear in an <a href="#albumsection">albumsection</a> (if every image +is in a section, then the `album` directive won't have any visible effect). - \[[!albumimage image=foo.jpg album=myalbum - title=... - caption=... - copyright=... - size=... - viewertemplate=... - ]] +The `inline` is in `archive` and `quick` mode, but can include some +extra information about the images, including file size and a thumbnail made +using [[ikiwiki/directive/img]]). The default template is `albumitem.tmpl`, +which takes advantage of these things. -Each viewer contains one `\[[!albumimage]]` directive. This -sets the `image` filename, the `album` in which this image appears, -and an optional `caption`, and can override the `size` at which to -display the image and the `viewertemplate` to use to display the -image. +<h2 id="albumsection"><code>albumsection</code> directive</h2> -It can also have `title`, `copyright` and `date` parameters, which -are short-cuts for [[ikiwiki/directive/meta]] directives. +The `albumsection` directive is used to split an album into sections. It can +only appear on a page that also has the <a href="#album">album</a> directive. + +The `filter` parameter is a [[ikiwiki/PageSpec]] against which viewer pages +are matched. The `albumsection` directive displays all the images that match +the filter, and the `album` directive displays any leftover images, like +this: + + # Holiday photos + + \[[!album]] + <!-- replaced with a list of any uncategorized photos, which might be + empty --> -The viewer can also have any other content, but typically the -directive will be the only thing there. + ## People -Eventually, there will be a specialized CGI user interface to -edit all the photos of an album at once, upload a new photo -(which will attach the photo but also write out a viewer page -for it), or mark an already-uploaded photo as a member of an -album (which is done by writing out a viewer page for it). + \[[!albumsection filter="tagged(people)"]] + <!-- replaced with a list of photos tagged 'people', including + any that are also tagged 'landscapes' --> -The `\[[!albumimage]]` directive is replaced by an + ## Landscapes + + \[[!albumsection filter="tagged(landscapes)"]] + <!-- replaced with a list of photos tagged 'landscapes', including + any that are also tagged 'people' --> + +<h2 id="albumimage"><code>albumimage</code> directive</h2> + +Each viewer page produced by the <a href="#album">album</a> directive +contains an `albumimage` directive, which is replaced by an [[ikiwiki/directive/img]], wrapped in some formatting using a -template (by default `albumviewer.tmpl`). The template can (and -should) also include "next photo", "previous photo" and -"up to gallery" links. +template (by default it's `albumviewer.tmpl`). That template can also include +links to the next photo, the previous photo and the album it's in; the default +template has all of these. -The next/previous links are themselves implemented by -[[inlining|ikiwiki/directive/inline]] the next or previous -photo, using a special template (by default `albumnext.tmpl` -or `albumprev.tmpl`), in `archive`/`quick` mode. +The next/previous links are themselves implemented by evaluating a template, +either `albumnext.tmpl` or `albumprev.tmpl` by default. -> With hindsight, using an inline here is wrong - I should just -> run hooks and fill in the template within the album plugin. -> inline has some specialized functionality that's overkill -> here, and its delayed HTML substitution breaks the ability -> to have previous/up/next links both above and below the -> photo, for instance. --[[smcv]] +The directive can also have parameters: -## Writing the album +* `title`, `copyright` and `date` are short-cuts for the corresponding + [[ikiwiki/directive/meta]] directives -The album contains one `\[[!album]]` directive. It may also -contain any number of `\[[!albumsection]]` directives, for -example the demo album linked above could look like: +* `caption` sets a caption which is displayed in the album and viewer + pages - \[[!album]] - <!-- replaced with one uncategorized photo --> +The viewer page can also have other contents before or after the actual +image viewer. + +## Bugs + +* The plugin doesn't do anything special to handle albums that are subpages + of each other. If, say, `debconf` and `debconf/monday` are both albums, + then `debconf/monday/p100.jpg` will currently be assigned to one or the + other, arbitrarily. + +* The plugin doesn't do anything special to handle photos with similar names. + If you have `p100.jpg` and `p100.png`, one will get a viewer page called + `p100` and the other will be ignored. + +* If there's no `albumimage` in a viewer page, one should probably be appended + automatically. - ## Gamarra +## TODO - \[[!albumsection filter="link(gamarra)"]] - <!-- all the Gamarra photos --> +* The documentation should mention how to replicate the appearance of + `album` and `albumsection` using an `inline` of viewer pages. - ## Smokescreen +* The documentation should mention all the template variables and + all the parameters. - \[[!albumsection filter="link(smokescreen)"]] - <!-- all the Smokescreen photos --> +* The generated viewer page should include most or all of the possible + parameters to the `albumimage` directive, with empty values, as a + template for editing. - ... +* The generated viewer page should extract as much metadata as possible from + the photo's EXIF tags (creation/modification dates, author, title, caption, + copyright). [[smcv]] has a half-written implementation which runs + `scanimage` hooks, and has an `exiftool` plugin using [[!cpan Image::ExifTool]] + as a reference implementation of that hook. -The `\[[!album]]` directive is replaced by an -[[ikiwiki/directive/inline]] which automatically includes every -page that has an `\[[!albumimage]]` directive linking it to this -album, except those that will appear in an `\[[!albumsection]]`. +* There should be an option to reduce the size of photos and write them into + an underlay (perhaps just the transient underlay), for this workflow: -The `inline` is in `archive`/`quick` mode, but includes some -extra information about the images, including file size and a -thumbnail (again, made using [[ikiwiki/directive/img]]). The -default template is `albumitem.tmpl`, which takes advantage -of these things. + * your laptop's local ikiwiki has two underlays, `photos` and `webphotos` + * `photos` contains full resolution photos with EXIF tags + * for each photo that exists in `photos` but not in `webphotos`, the album + plugin automatically resamples it down to a web-compatible resolution + ([[smcv]] uses up to 640x640), optimizes it with `jpegoptim`, strips out + all EXIF tags, and and writes it into the corresponding location + in `webphotos` + * `webphotos` is what you rsync to the web server + * the web server's ikiwiki only has `webphotos` as an underlay -Each `\[[!albumsection]]` is replaced by a similar inline, which -selects a subset of the photos in the album. +* Eventually, there could be a specialized CGI user interface to batch-edit + all the photos of an album (so for each photo, you get an edit box each for + title, author, copyright etc.) - this would work by making programmatic + edits to all the `albumimage` directives. diff --git a/doc/plugins/contrib/album/discussion.mdwn b/doc/plugins/contrib/album/discussion.mdwn index 5c8e74fa6..0356860d8 100644 --- a/doc/plugins/contrib/album/discussion.mdwn +++ b/doc/plugins/contrib/album/discussion.mdwn @@ -46,6 +46,10 @@ secondly: barring the CGI interface for editing the album, which would be great, > > --[[smcv]] +>> In the current version of the branch, the viewer pages are +>> generated automatically if you didn't generate them yourself, +>> so `ikiwiki-album` is no longer needed. --[[smcv]] + i'm new to ikiwiki, apologies if this is dealt with elsewhere. -brush > This plugin is pretty ambitious, and is unfinished, so I'd recommend @@ -60,7 +64,7 @@ code or tried it yet, but here goes. --[[Joey]] * Needing to create the albumimage "viewer" pages for each photo seems like it will become a pain. Everyone will need to come up with their own automation for it, and then there's the question - of how to automate it when uploading attachments. + of how to automate it when uploading attachments. -J > There's already a script (ikiwiki-album) to populate a git > checkout with skeleton "viewer" pages; I was planning to make a @@ -68,9 +72,25 @@ code or tried it yet, but here goes. --[[Joey]] > you (since the requirements for that CGI interface change depending > on the implementation). I agree that this is ugly, though. -s +>> Would you accept a version where the albumimage "viewer" pages +>> could be 0 bytes long, at least until metadata gets added? +>> +>> The more I think about the "binaries as first-class pages" approach, +>> the more subtle interactions I notice with other plugins. I +>> think I'm up to needing changes to editpage, comments, attachment +>> and recentchanges, plus adjustments to img and Render (to reduce +>> duplication when thumbnailing an image with a strange extension +>> while simultaneously changing the extension, and to hardlink/copy +>> an image with a strange extension to a differing target filename +>> with the normal extension, respectively). -s + +>>> Now that we have `add_autofile` I can just create viewer pages +>>> whenever there's an image to view. The current version of the +>>> branch does that. -s + * With each viewer page having next/prev links, I can see how you were having the scalability issues with ikiwiki's data structures - earlier! + earlier! -J > Yeah, I think they're a basic requirement from a UI point of view > though (although they don't necessarily have to be full wikilinks). @@ -80,12 +100,14 @@ code or tried it yet, but here goes. --[[Joey]] >> these can be presence dependencies, which will probably help with >> avoiding rebuilds of a page if the next/prev page is changed. >> (Unless you use img to make the thumbnails for those links, then it ->> would rebuild the thumbnails anyway. Have not looked at the code.) --[[Joey]] +>> would rebuild the thumbnails anyway. Have not looked at the code.) --[[Joey]] + +>>> I do use img. -s * And doesn't each viewer page really depend on every other page in the same albumsection? If a new page is added, the next/prev links may need to be updated, for example. If so, there will be much - unnecessary rebuilding. + unnecessary rebuilding. -J > albumsections are just a way to insert headings into the flow of > photos, so they don't actually affect dependencies. @@ -108,8 +130,13 @@ code or tried it yet, but here goes. --[[Joey]] >> metadata. Er, I mean, I have a cheezy hack in `add_depends` now that does >> it to deal with a similar case. --[[Joey]] +>>> I think I was misunderstanding how early you have to call `add_depends`? +>>> The critical thing I missed was that if you're scanning a page, you're +>>> going to rebuild it in a moment anyway, so it doesn't matter if you +>>> have no idea what it depends on until the rebuild phase. -s + * One thing I do like about having individual pages per image is - that they can each have their own comments, etc. + that they can each have their own comments, etc. -J > Yes; also, they can be wikilinked. I consider those to be > UI requirements. -s @@ -119,11 +146,40 @@ code or tried it yet, but here goes. --[[Joey]] album, but then anyone who can write to any other page on the wiki can add an image to it. 2: I may want an image to appear in more than one album. Think tags. So it seems it would be better to have the album - directive control what pages it includes (a la inline). + directive control what pages it includes (a la inline). -J + +> I'm inclined to fix this by constraining images to be subpages of exactly +> one album: if they're subpages of 2+ nested albums then they're only +> considered to be in the deepest-nested one (i.e. longest URL), and if +> they're not in any album then that's a usage error. This would +> also make prev/next links sane. -s + +>> The current version constrains images to be in at most one album, +>> choosing one arbitrarily (dependent on scan order) if albums are +>> nested. -s + +> If you want to reference images from elsewhere in the wiki and display +> them as if in an album, then you can use an ordinary inline with +> the same template that the album would use, and I'll make sure the +> templates are set up so this works. -s + +>> Still needs documenting, I've put it on the TODO list on the main +>> page. -s + +> (Implementation detail: this means that an image X/Y/Z/W/V, where X and +> Y are albums, Z does not exist and W exists but is not an album, +> would have a content dependency on Y, a presence dependency on Z +> and a content dependency on W.) +> +> Perhaps I should just restrict to having the album images be direct +> subpages of the album, although that would mean breaking some URLs +> on the existing website I'm doing all this work for... -s -> See note above about pagespecs not being very safe early on. -> You did merge my inline-with-pagenames feature, which is safe to use -> at scan time, though. +>> The current version of the branch doesn't have this restriction; +>> perhaps it's a worthwhile simplification, or perhaps it's too +>> restrictive? I fairly often use directory hierarchies like +>> `a_festival/saturday/foo.jpg` within an album, which makes +>> it very easy to write `albumsection` filters. -s * Putting a few of the above thoughts together, my ideal album system seems to be one where I can just drop the images into a directory and @@ -132,20 +188,69 @@ code or tried it yet, but here goes. --[[Joey]] etc. (Real pity we can't just put arbitrary metadata into the images themselves.) This is almost pointing toward making the images first-class wiki page sources. Hey, it worked for po! :) But the metadata and editing - problems probably don't really allow that. + problems probably don't really allow that. -J > Putting a JPEG in the web form is not an option from my point of > view :-) but perhaps there could just be a "web-editable" flag supplied > by plugins, and things could be changed to respect it. -> + +>> Replying to myself: would you accept patches to support +>> `hook(type => 'htmlize', editable => 0, ...)` in editpage? This would +>> essentially mean "this is an opaque binary: you can delete it +>> or rename it, and it might have its own special editing UI, but you +>> can never get it in a web form". +>> +>> On the other hand, that essentially means we need to reimplement +>> editpage in order to edit the sidecar files that contain the metadata. +>> Having already done one partial reimplementation of editpage (for +>> comments) I'm in no hurry to do another. +>> +>> I suppose another possibility would be to register hook +>> functions to be called by editpage when it loads and saves the +>> file. In this case, the loading hook would be to discard +>> the binary and use filter() instead, and the saving conversion +>> would be to write the edited content into the metadata sidecar +>> (creating it if necessary). +>> +>> I'd also need to make editpage (and also comments!) not allow the +>> creation of a file of type albumjpg, albumgif etc., which is something +>> I previously missed; and I'd need to make attachment able to +>> upload-and-rename. +>> -s + +>>> I believe the current branch meets your requirements, by having +>>> first-class wiki pages spring into existence using `add_autofile` +>>> to be viewer pages for photos. -s + > In a way, what you really want for metadata is to have it in the album > page, so you can batch-edit the whole lot by editing one file (this > does mean that editing the album necessarily causes each of its viewers > to be rebuilt, but in practice that happens anyway). -s -> ->> Yes, that would make some sense.. It also allows putting one image in ->> two albums, with different caption etc. (Maybe for different audiences.) + +>> Replying to myself: in practice that *doesn't* happen anyway. Having +>> the metadata in the album page is somewhat harmful because it means +>> that changing the title of one image causes every viewer in the album +>> to be rebuilt, whereas if you have a metadata file per image, only +>> the album itself, plus the next and previous viewers, need +>> rebuilding. So, I think a file per image is the way to go. >> +>> Ideally we'd have some way to "batch-edit" the metadata of all +>> images in an album at once, except that would make conflict +>> resolution much more complicated to deal with; maybe just +>> give up and scream about mid-air collisions in that case? +>> (That's apparently good enough for Bugzilla, but not really +>> for ikiwiki). -s + +>>> This is now in the main page's TODO list; if/when I implement this, +>>> I intend to make it a specialized CGI interface. -s + +>> Yes, [all metadata in one file] would make some sense.. It also allows putting one image in +>> two albums, with different caption etc. (Maybe for different audiences.) +>> --[[Joey]] + +>>> Eek. No, that's not what I had in mind at all; the metadata ends up +>>> in the "viewer" page, so it's necessarily the same for all albums. -s + >> It would probably be possible to add a new dependency type, and thus >> make ikiwiki smart about noticing whether the metadata has actually >> changed, and only update those viewers where it has. But the dependency @@ -154,7 +259,8 @@ code or tried it yet, but here goes. --[[Joey]] ---- -Trying to use the "special extension" design: +'''I think the "special extension" design is a dead-end, but here's what +happened when I tried to work out how it would work. --[[smcv]]''' Suppose that each viewer is a JPEG-or-GIF-or-something, with extension ".albumimage". We have a gallery "memes" with three images, badger, @@ -164,23 +270,26 @@ mushroom and snake. > etc as the htmlize extensions. May need some fixes to ikiwiki to support > that. --[[Joey]] +>> foo.albumjpg (etc.) for images, and foo._albummeta (with +>> `keepextension => 1`) for sidecar metadata files, seems viable. -s + Files in git repo: * index.mdwn * memes.mdwn -* memes/badger.albumimage (a renamed JPEG) +* memes/badger.albumjpg (a renamed JPEG) * memes/badger/comment_1._comment * memes/badger/comment_2._comment -* memes/mushroom.albumimage (a renamed GIF) -* memes/mushroom.meta (sidecar file with metadata) -* memes/snake.albumimage (a renamed video) +* memes/mushroom.albumgif (a renamed GIF) +* memes/mushroom._albummeta (sidecar file with metadata) +* memes/snake.albummov (a renamed video) Files in web content: * index.html * memes/index.html * memes/96x96-badger.jpg (from img) -* memes/96x96-mushroom.jpg (from img) +* memes/96x96-mushroom.gif (from img) * memes/96x96-snake.jpg (from img, hacked up to use totem-video-thumbnailer :-) ) * memes/badger/index.html (including comments) * memes/badger.jpg @@ -200,10 +309,28 @@ way to get them rendered anyway. > the image, as well as eg, smiley trying to munge it in sanitize. > --[[Joey]] +>> As long as nothing has a filter() hook that assumes it's already +>> text... filters are run in arbitrary order. We seem to be OK so far +>> though. +>> +>> If this is the route I take, I propose to have the result of filter() +>> be the contents of the sidecar metadata file (empty string if none), +>> with the `\[[!albumimage]]` directive (which no longer requires +>> arguments) prepended if not already present. This would mean that +>> meta directives in the metadata file would work as normal, and it +>> would be possible to insert text both before and after the viewer +>> if desired. The result of filter() would also be a sensible starting +>> point for editing, and the result of editing could be diverted into +>> the metadata file. -s + do=edit&page=memes/badger needs to not put the JPG in a text box: somehow divert or override the normal edit CGI by telling it that .albumimage files are not editable in the usual way? +> Something I missed here is that editpage also needs to be told that +> creating new files of type albumjpg, albumgif etc. is not allowed +> either! -s + Every image needs to depend on, and link to, the next and previous images, which is a bit tricky. In previous thinking about this I'd been applying the overly strict constraint that the ordered sequence of pages in each @@ -217,6 +344,9 @@ in order. > memoization to avoid each image in an album building the same list. > I sense that I may be missing a subtelty though. --[[Joey]] +>> I think I was misunderstanding how early you have to call `add_depends` +>> as mentioned above. -s + Perhaps restricting to "the images in an album A must match A/*" would be useful; then the unordered superset could just be "A/*". Your "albums via tags" idea would be nice too though, particularly for feature @@ -233,6 +363,9 @@ album, or something? > Ugh, yeah, that is a problem. Perhaps wanting to support that was just > too ambitious. --[[Joey]] +>> I propose to restrict to having images be subpages of albums, as +>> described above. -s + Requiring renaming is awkward for non-technical Windows/Mac users, with both platforms' defaults being to hide extensions; however, this could be circumvented by adding some sort of hook in attachment to turn things into @@ -244,13 +377,28 @@ extensions visible is a "don't do that then" situation :-) > with an extension. (Or allow specifying a full pagespec, > but I hesitate to seriously suggest that.) --[[Joey]] +>> I think that might be a terrifying idea for another day. If we can +>> mutate the extension during the `attach` upload, that'd be enough; +>> I don't think people who are skilled enough to use git/svn/..., +>> but not skilled enough to tell Explorer to show file extensions, +>> represent a major use case. -s + Ideally attachment could also be configured to upload into a specified underlay, so that photos don't have to be in your source-code control (you might want that, but I don't!). +> Replying to myself: perhaps best done as an orthogonal extension +> to attach? -s + +> Yet another non-obvious thing this design would need to do is to find +> some way to have each change to memes/badger._albummeta show up as a +> change to memes/badger in `recentchanges`. -s + Things that would be nice, and are probably possible: * make the "Edit page" link on viewers divert to album-specific CGI instead - of just failing or not appearing + of just failing or not appearing (probably possible via pagetemplate) + * some way to deep-link to memes/badger.jpg with a wikilink, without knowing a - priori that it's secretly a JPEG + priori that it's secretly a JPEG (probably harder than it looks - you'd + have to make a directive for it and it's probably not worth it) 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.mdwn b/doc/plugins/contrib/field.mdwn new file mode 100644 index 000000000..dce2d891c --- /dev/null +++ b/doc/plugins/contrib/field.mdwn @@ -0,0 +1,196 @@ +[[!template id=plugin name=field author="[[rubykat]]"]] +[[!tag type/meta]] +[[!toc]] +## NAME + +IkiWiki::Plugin::field - front-end for per-page record fields. + +## SYNOPSIS + + # activate the plugin + add_plugins => [qw{goodstuff field ....}], + + # simple registration + field_register => [qw{meta}], + + # simple registration with priority + field_register => { + meta => 'last' + foo => 'DD' + }, + + # allow the config to be queried as a field + field_allow_config => 1, + + # flag certain fields as "tags" + field_tags => { + BookAuthor => '/books/authors', + BookGenre => '/books/genres', + MovieGenre => '/movies/genres', + } + +## DESCRIPTION + +This plugin is meant to be used in conjunction with other plugins +in order to provide a uniform interface to access per-page structured +data, where each page is treated like a record, and the structured data +are fields in that record. This can include the meta-data for that page, +such as the page title. + +Plugins can register a function which will return the value of a "field" for +a given page. This can be used in a few ways: + +* In page templates; all registered fields will be passed to the page template in the "pagetemplate" processing. +* In PageSpecs; the "field" function can be used to match the value of a field in a page. +* In SortSpecs; the "field" function can be used for sorting pages by the value of a field in a page. +* By other plugins, using the field_get_value function, to get the value of a field for a page, and do with it what they will. + +## CONFIGURATION OPTIONS + +The following options can be set in the ikiwiki setup file. + +**field_allow_config** + + field_allow_config => 1, + +Allow the $config hash to be queried like any other field; the +keys of the config hash are the field names. + +**field_register** + + field_register => [qw{meta}], + + field_register => { + meta => 'last' + foo => 'DD' + }, + +A hash of plugin-IDs to register. The keys of the hash are the names of the +plugins, and the values of the hash give the order of lookup of the field +values. The order can be 'first', 'last', 'middle', or an explicit order +sequence between 'AA' and 'ZZ'. If the simpler type of registration is used, +then the order will be 'middle'. + +This assumes that the plugins in question store data in the %pagestatus hash +using the ID of that plugin, and thus the field values are looked for there. + +This is the simplest form of registration, but the advantage is that it +doesn't require the plugin to be modified in order for it to be +registered with the "field" plugin. + +**field_tags** + + field_tags => { + BookAuthor => '/books/authors', + BookGenre => '/books/genres', + MovieGenre => '/movies/genres', + } + +A hash of fields and their associated pages. This provides a faceted +tagging system. + +The way this works is that a given field-name will be associated with a given +page, and the values of that field will be linked to sub-pages of that page. + +For example: + + BookGenre: SF + +will link to "/books/genres/SF", with a link-type of "bookgenre". + +## PageSpec + +The `field` plugin provides a few PageSpec functions to match values +of fields for pages. + +* field + * **field(*name* *glob*)** + * field(bar Foo\*) will match if the "bar" field starts with "Foo". +* destfield + * **destfield(*name* *glob*)** + * as for "field" but matches against the destination page (i.e when the source page is being included in another page). +* field_item + * **field_item(*name* *glob*)** + * field_item(bar Foo) will match if one of the values of the "bar" field is "Foo". +* destfield_item + * **destfield_item(*name* *glob*)** + * as for "field_item" but matches against the destination page. +* field_tagged + * **field_tagged(*name* *glob*)** + * like `tagged`, but this uses the tag-bases and link-types defined in the `field_tags` configuration option. +* destfield_tagged + * **destfield_tagged(*name* *glob*)** + * as for "field_tagged" but matches against the destination page. + +## SortSpec + +The "field" SortSpec function can be used to sort a page depending on the value of a field for that page. This is used for directives that take sort parameters, such as **inline** or **report**. + +field(*name*) + +For example: + +sort="field(bar)" will sort by the value og the "bar" field. + +## FUNCTIONS + +### field_register + +field_register(id=>$id); + +Register a plugin as having field data. The above form is the simplest, where +the field value is looked up in the %pagestatus hash under the plugin-id. + +Additional Options: + +**call=>&myfunc** + +A reference to a function to call rather than just looking up the value in the +%pagestatus hash. It takes two arguments: the name of the field, and the name +of the page. It is expected to return (a) an array of the values of that field +if "wantarray" is true, or (b) a concatenation of the values of that field +if "wantarray" is not true, or (c) undef if there is no field by that name. + + sub myfunc ($$) { + my $field = shift; + my $page = shift; + + ... + + return (wantarray ? @values : $value); + } + +**first=>1** + +Set this to be called first in the sequence of calls looking for values. Since +the first found value is the one which is returned, ordering is significant. +This is equivalent to "order=>'first'". + +**last=>1** + +Set this to be called last in the sequence of calls looking for values. Since +the first found value is the one which is returned, ordering is significant. +This is equivalent to "order=>'last'". + +**order=>$order** + +Set the explicit ordering in the sequence of calls looking for values. Since +the first found value is the one which is returned, ordering is significant. + +The values allowed for this are "first", "last", "middle", or a two-character +ordering-sequence between 'AA' and 'ZZ'. + +### field_get_value($field, $page) + + my @values = field_get_value($field, $page); + + my $value = field_get_value($field, $page); + +Returns the values of the field for that page, or undef if none is found. +Note that it will return an array of values if you ask for an array, +and a scalar value if you ask for a scalar. + +## DOWNLOAD + +* browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/field.pm> +* git repo at git://github.com/rubykat/ikiplugins.git diff --git a/doc/plugins/contrib/field/discussion.mdwn b/doc/plugins/contrib/field/discussion.mdwn new file mode 100644 index 000000000..6161f80df --- /dev/null +++ b/doc/plugins/contrib/field/discussion.mdwn @@ -0,0 +1,407 @@ +Having tried out `field`, some comments (from [[smcv]]): + +The general concept looks great. + +The `pagetemplate` hook seems quite namespace-polluting: on a site containing +a list of books, I'd like to have an `author` field, but that would collide +with IkiWiki's use of `<TMPL_VAR AUTHOR>` for the author of the *page* +(i.e. me). Perhaps it'd be better if the pagetemplate hook was only active for +`<TMPL_VAR FIELD_AUTHOR>` or something? (For those who want the current +behaviour, an auxiliary plugin would be easy.) + +> No, please. The idea is to be *able* to override field names if one wishes to, and choose, for yourself, non-colliding field names if one wishes not to. I don't wish to lose the power of being able to, say, define a page title with YAML format if I want to, or to write a site-specific plugin which calculates a page title, or other nifty things. +>It's not like one is going to lose the fields defined by the meta plugin; if "author" is defined by \[[!meta author=...]] then that's what will be found by "field" (provided the "meta" plugin is registered; that's what the "field_register" option is for). +>--[[KathrynAndersen]] + +>> Hmm. I suppose if you put the title (or whatever) in the YAML, then +>> "almost" all the places in IkiWiki that respect titles will do the +>> right thing due to the pagetemplate hook, with the exception being +>> anything that has special side-effects inside `meta` (like `date`), +>> or anything that looks in `$pagestate{foo}{meta}` directly +>> (like `map`). Is your plan that `meta` should register itself by +>> default, and `map` and friends should be adapted to +>> work based on `getfield()` instead of `$pagestate{foo}{meta}`, then? + +>>> Based on `field_get_value()`, yes. That would be my ideal. Do you think I should implement that as an ikiwiki branch? --[[KathrynAndersen]] + +>>>> This doesn't solve cases where certain fields are treated specially; for +>>>> instance, putting a `\[[!meta permalink]]` on a page is not the same as +>>>> putting it in `ymlfront` (in the latter case you won't get your +>>>> `<link>` header), and putting `\[[!meta date]]` is not the same as putting +>>>> `date` in `ymlfront` (in the latter case, `%pagectime` won't be changed). +>>>> +>>>> One way to resolve that would be to have `ymlfront`, or similar, be a +>>>> front-end for `meta` rather than for `field`, and call +>>>> `IkiWiki::Plugin::meta::preprocess` (or a refactored-out function that's +>>>> similar). +>>>> +>>>> There are also some cross-site scripting issues (see below)... --[[smcv]] + +>> (On the site I mentioned, I'm using an unmodified version of `field`, +>> and currently working around the collision by tagging books' pages +>> with `bookauthor` instead of `author` in the YAML.) --s + +>> Revisiting this after more thought, the problem here is similar to the +>> possibility that a wiki user adds a `meta` shortcut +>> to [[shortcuts]], or conversely, that a plugin adds a `cpan` directive +>> that conflicts with the `cpan` shortcut that pages already use. (In the +>> case of shortcuts, this is resolved by having plugin-defined directives +>> always win.) For plugin-defined meta keywords this is the plugin +>> author's/wiki admin's problem - just don't enable conflicting plugins! - +>> but it gets scary when you start introducing things like `ymlfront`, which +>> allow arbitrary, wiki-user-defined fields, even ones that subvert +>> other plugins' assumptions. +>> +>> The `pagetemplate` hook is particularly alarming because page templates are +>> evaluated in many contexts, not all of which are subject to the +>> htmlscrubber or escaping; because the output from `field` isn't filtered, +>> prefixed or delimited, when combined with an arbitrary-key-setting plugin +>> like `ymlfront` it can interfere with other plugins' expectations +>> and potentially cause cross-site scripting exploits. For instance, `inline` +>> has a `pagetemplate` hook which defines the `FEEDLINKS` template variable +>> to be a blob of HTML to put in the `<head>` of the page. As a result, this +>> YAML would be bad: +>> +>> --- +>> FEEDLINKS: <script>alert('code injection detected')</script> +>> --- +>> +>> (It might require a different case combination due to implementation +>> details, I'm not sure.) +>> +>> It's difficult for `field` to do anything about this, because it doesn't +>> know whether a field is meant to be plain text, HTML, a URL, or something +>> else. +>> +>> If `field`'s `pagetemplate` hook did something more limiting - like +>> only emitting template variables starting with `field_`, or from some +>> finite set, or something - then this would cease to be a problem, I think? +>> +>> `ftemplate` and `getfield` don't have this problem, as far as I can see, +>> because their output is in contexts where the user could equally well have +>> written raw HTML directly; the user can cause themselves confusion, but +>> can't cause harmful output. --[[smcv]] + +From a coding style point of view, the `$CamelCase` variable names aren't +IkiWiki style, and the `match_foo` functions look as though they could benefit +from being thin wrappers around a common `&IkiWiki::Plugin::field::match` +function (see `meta` for a similar approach). + +I think the documentation would probably be clearer in a less manpage-like +and more ikiwiki-like style? + +> I don't think ikiwiki *has* a "style" for docs, does it? So I followed the Perl Module style. And I'm rather baffled as to why having the docs laid out in clear sections... make them less clear. --[[KathrynAndersen]] + +>> I keep getting distracted by the big shouty headings :-) +>> I suppose what I was really getting at was that when this plugin +>> is merged, its docs will end up split between its plugin +>> page, [[plugins/write]] and [[ikiwiki/PageSpec]]; on some of the +>> contrib plugins I've added I've tried to separate the docs +>> according to how they'll hopefully be laid out after merge. --s + +If one of my branches from [[todo/allow_plugins_to_add_sorting_methods]] is +accepted, a `field()` cmp type would mean that [[plugins/contrib/report]] can +stop reimplementing sorting. Here's the implementation I'm using, with +your "sortspec" concept (a sort-hook would be very similar): if merged, +I think it should just be part of `field` rather than a separate plugin. + + # Copyright © 2010 Simon McVittie, released under GNU GPL >= 2 + package IkiWiki::Plugin::fieldsort; + use warnings; + use strict; + use IkiWiki 3.00; + use IkiWiki::Plugin::field; + + sub import { + hook(type => "getsetup", id => "fieldsort", call => \&getsetup); + } + + sub getsetup () { + return + plugin => { + safe => 1, + rebuild => undef, + }, + } + + package IkiWiki::SortSpec; + + sub cmp_field { + if (!length $_[0]) { + error("sort=field requires a parameter"); + } + + my $left = IkiWiki::Plugin::field::field_get_value($_[0], $a); + my $right = IkiWiki::Plugin::field::field_get_value($_[0], $b); + + $left = "" unless defined $left; + $right = "" unless defined $right; + return $left cmp $right; + } + + 1; + +---- + +Disclaimer: I've only looked at this plugin and ymlfront, not other related +stuff yet. (I quite like ymlfront, so I looked at this as its dependency. :) +I also don't want to annoy you with a lot of design discussion +if your main goal was to write a plugin that did exactly what you wanted. + +My first question is: Why we need another plugin storing metadata +about the page, when we already have the meta plugin? Much of the +complication around the field plugin has to do with it accessing info +belonging to the meta plugin, and generalizing that to be able to access +info stored by other plugins too. (But I don't see any other plugins that +currently store such info). Then too, it raises points of confusion like +smcv's discuission of field author vs meta author above. --[[Joey]] + +> The point is exactly in the generalization, to provide a uniform interface for accessing structured data, no matter what the source of it, whether that be the meta plugin or some other plugin. + +> There were a few reasons for this: + +>1. In converting my site over from PmWiki, I needed something that was equivalent to PmWiki's Page-Text-Variables (which is how PmWiki implements structured data). +>2. I also wanted an equivalent of PmWiki's Page-Variables, which, rather than being simple variables, are the return-value of a function. This gives one a lot of power, because one can do calculations, derive one thing from another. Heck, just being able to have a "basename" variable is useful. +>3. I noticed that in the discussion about structured data, it was mired down in disagreements about what form the structured data should take; I wanted to overcome that hurdle by decoupling the form from the content. +>4. I actually use this to solve (1), because, while I do use ymlfront, initially my pages were in PmWiki format (I wrote (another) unreleased plugin which parses PmWiki format) including PmWiki's Page-Text-Variables for structured data. So I needed something that could deal with multiple formats. + +> So, yes, it does cater to mostly my personal needs, but I think it is more generally useful, also. +> --[[KathrynAndersen]] + +>> Is it fair to say, then, that `field`'s purpose is to take other +>> plugins' arbitrary per-page data, and present it as a single +>> merged/flattened string => string map per page? From the plugins +>> here, things you then use that merged map for include: +>> +>> * sorting - stolen by [[todo/allow_plugins_to_add_sorting_methods]] +>> * substitution into pages with Perl-like syntax - `getfield` +>> * substitution into wiki-defined templates - the `pagetemplate` +>> hook +>> * substitution into user-defined templates - `ftemplate` +>> +>> As I mentioned above, the flattening can cause collisions (and in the +>> `pagetemplate` case, even security problems). +>> +>> I wonder whether conflating Page Text Variables with Page Variables +>> causes `field` to be more general than it needs to be? +>> To define a Page Variable (function-like field), you need to write +>> a plugin containing that Perl function; if we assume that `field` +>> or something resembling it gets merged into ikiwiki, then it's +>> reasonable to expect third-party plugins to integrate with whatever +>> scaffolding there is for these (either in an enabled-by-default +>> plugin that most people are expected to leave enabled, like `meta` +>> now, or in the core), and it doesn't seem onerous to expect each +>> plugin that wants to participate in this mechanism to have code to +>> do so. While it's still contrib, `field` could just have a special case +>> for the meta plugin, rather than the converse? +>> +>> If Page Text Variables are limited to being simple strings as you +>> suggest over in [[forum/an_alternative_approach_to_structured_data]], +>> then they're functionally similar to `meta` fields, so one way to +>> get their functionality would be to extend `meta` so that +>> +>> \[[!meta badger="mushroom"]] +>> +>> (for an unrecognised keyword `badger`) would store +>> `$pagestate{$page}{meta}{badger} = "mushroom"`? Getting this to +>> appear in templates might be problematic, because a naive +>> `pagetemplate` hook would have the same problem that `field` combined +>> with `ymlfront` currently does. +>> +>> One disadvantage that would appear if the function-like and +>> meta-like fields weren't in the same namespace would be that it +>> wouldn't be possible to switch a field from being meta-like to being +>> function-like without changing any wiki content that referenced it. +>> +>> Perhaps meta-like fields should just *be* `meta` (with the above +>> enhancement), as a trivial case of function-like fields? That would +>> turn `ymlfront` into an alternative syntax for `meta`, I think? +>> That, in turn, would hopefully solve the special-fields problem, +>> by just delegating it to meta. I've been glad of the ability to define +>> new ad-hoc fields with this plugin without having to write an extra plugin +>> to do so (listing books with a `bookauthor` and sorting them by +>> `"field(bookauthor) title"`), but that'd be just as easy if `meta` +>> accepted ad-hoc fields? +>> +>> --[[smcv]] + +>>> Your point above about cross-site scripting is a valid one, and something I +>>> hadn't thought of (oops). + +>>> I still want to be able to populate pagetemplate templates with field, because I +>>> use it for a number of things, such as setting which CSS files to use for a +>>> given page, and, as I said, for titles. But apart from the titles, I +>>> realize I've been setting them in places other than the page data itself. +>>> (Another unreleased plugin, `concon`, uses Config::Context to be able to +>>> set variables on a per-site, per-directory and a per-page basis). + +>>> The first possible solution is what you suggested above: for field to only +>>> set values in pagetemplate which are prefixed with *field_*. I don't think +>>> this is quite satisfactory, since that would still mean that people could +>>> put un-scrubbed values into a pagetemplate, albeit they would be values +>>> named field_foo, etc. --[[KathrynAndersen]] + +>>>> They can already do similar; `PERMALINK` is pre-sanitized to +>>>> ensure that it's a "safe" URL, but if an extremely confused wiki admin was +>>>> to put `COPYRIGHT` in their RSS/Atom feed's `<link>`, a malicious user +>>>> could put an unsafe (e.g. Javascript) URL in there (`COPYRIGHT` *is* +>>>> HTML-scrubbed, but "javascript:alert('pwned!')" is just text as far as a +>>>> HTML sanitizer is concerned, so it passes straight through). The solution +>>>> is to not use variables in situations where that variable would be +>>>> inappropriate. Because `field` is so generic, the definition of what's +>>>> appropriate is difficult. --[[smcv]] + +>>> An alternative solution would be to classify field registration as "secure" +>>> and "insecure". Sources such as ymlfront would be insecure, sources such +>>> as concon (or the $config hash) would be secure, since they can't be edited +>>> as pages. Then, when doing pagetemplate substitution (but not ftemplate +>>> substitution) the insecure sources could be HTML-escaped. +>>> --[[KathrynAndersen]] + +>>>> Whether you trust the supplier of data seems orthogonal to whether its value +>>>> is (meant to be) interpreted as plain text, HTML, a URL or what? +>>>> +>>>> Even in cases where you trust the supplier, you need to escape things +>>>> suitably for the context, not for security but for correctness. The +>>>> definition of the value, and the context it's being used in, changes the +>>>> processing you need to do. An incomplete list: +>>>> +>>>> * HTML used as HTML needs to be html-scrubbed if and only if untrusted +>>>> * URLs used as URLs need to be put through `safeurl()` if and only if +>>>> untrusted +>>>> * HTML used as plain text needs tags removed regardless +>>>> * URLs used as plain text are safe +>>>> * URLs or plain text used in HTML need HTML-escaping (and URLs also need +>>>> `safeurl()` if untrusted) +>>>> * HTML or plain text used in URLs need URL-escaping (and the resulting +>>>> URL might need sanitizing too?) +>>>> +>>>> I can't immediately think of other data types we'd be interested in beyond +>>>> text, HTML and URL, but I'm sure there are plenty. + +>>>>> But isn't this a problem with anything that uses pagetemplates? Or is +>>>>> the point that, with plugins other than `field`, they all know, +>>>>> beforehand, the names of all the fields that they are dealing with, and +>>>>> thus the writer of the plugin knows which treatment each particular field +>>>>> needs? For example, that `meta` knows that `title` needs to be +>>>>> HTML-escaped, and that `baseurl` doesn't. In that case, yes, I see the problem. +>>>>> It's a tricky one. It isn't as if there's only ever going to be a fixed set of fields that need different treatment, either. Because the site admin is free to add whatever fields they like to the page template (if they aren't using the default one, that is. I'm not using the default one myself). +>>>>> Mind you, for trusted sources, since the person writing the page template and the person providing the variable are the same, they themselves would know whether the value will be treated as HTML, plain text, or a URL, and thus could do the needed escaping themselves when writing down the value. + +>>>>> Looking at the content of the default `page.tmpl` let's see what variables fall into which categories: + +>>>>> * **Used as URL:** BASEURL, EDITURL, PARENTLINKS->URL, RECENTCHANGESURL, HISTORYURL, GETSOURCEURL, PREFSURL, OTHERLANGUAGES->URL, ADDCOMMENTURL, BACKLINKS->URL, MORE_BACKLINKS->URL +>>>>> * **Used as part of a URL:** FAVICON, LOCAL_CSS +>>>>> * **Needs to be HTML-escaped:** TITLE +>>>>> * **Used as-is (as HTML):** FEEDLINKS, RELVCS, META, PERCENTTRANSLATED, SEARCHFORM, COMMENTSLINK, DISCUSSIONLINK, OTHERLANGUAGES->PERCENT, SIDEBAR, CONTENT, COMMENTS, TAGS->LINK, COPYRIGHT, LICENSE, MTIME, EXTRAFOOTER + +>>>>> This looks as if only TITLE needs HTML-escaping all the time, and that the URLS all end with "URL" in their name. Unfortunately the FAVICON and LOCAL_CSS which are part of URLS don't have "URL" in their name, though that's fair enough, since they aren't full URLs. + +>>>>> --K.A. + +>>>> One reasonable option would be to declare that `field` takes text-valued +>>>> fields, in which case either consumers need to escape +>>>> it with `<TMPL_VAR FIELD_FOO ESCAPE=HTML>`, and not interpret it as a URL +>>>> without first checking `safeurl`), or the pagetemplate hook needs to +>>>> pre-escape. + +>>>>> Since HTML::Template does have the ability to do ESCAPE=HTML/URL/JS, why not take advantage of that? Some things, like TITLE, probably should have ESCAPE=HTML all the time; that would solve the "to escape or not to escape" problem that `meta` has with titles. After all, when one *sorts* by title, one doesn't really want HTML-escaping in it; only when one uses it in a template. -- K.A. + +>>>> Another reasonable option would be to declare that `field` takes raw HTML, +>>>> in which case consumers need to only use it in contexts that will be +>>>> HTML-scrubbed (but it becomes unsuitable for using as text - problematic +>>>> for text-based things like sorting or URLs, and not ideal for searching). +>>>> +>>>> You could even let each consumer choose how it's going to use the field, +>>>> by having the `foo` field generate `TEXT_FOO` and `HTML_FOO` variables? +>>>> --[[smcv]] + +>>>>> Something similar is already done in `template` and `ftemplate` with the `raw_` prefix, which determines whether the variable should have `htmlize` run over it first before the value is applied to the template. Of course, that isn't scrubbing or escaping, because with those templates, the scrubbing is done afterwards as part of the normal processing. + +>>> Another problem, as you point out, is special-case fields, such as a number of +>>> those defined by `meta`, which have side-effects associated with them, more +>>> than just providing a value to pagetemplate. Perhaps `meta` should deal with +>>> the side-effects, but use `field` as an interface to get the values of those special fields. + +>>> --[[KathrynAndersen]] + +----- + +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/flattr.mdwn b/doc/plugins/contrib/flattr.mdwn new file mode 100644 index 000000000..e9b4bf857 --- /dev/null +++ b/doc/plugins/contrib/flattr.mdwn @@ -0,0 +1,48 @@ +[[!template id=plugin name=flattr author="[[jaywalk]]"]] + +[flattr.com](http://flattr.com/) is a flatrate micropayment service, which revolves around the idea of having flattr buttons everywhere that people visiting your site can use to "flattr" you. + +This plugin makes it easier to put flattr buttons in ikiwiki. It supports both the static kind as well as the counting dynamic javascript version. The dynamic version does not work if [[htmlscrubber|/plugins/htmlscrubber]] is active on the page. + +The dynamic button does not require creation of the page on flattr before being added to a page, the static one does. + +I wrote some notes on [jonatan.walck.se](http://jonatan.walck.se/software/ikiwiki/plugin/flattr/) and put the source here: [flattr.pm](http://jonatan.walck.se/software/ikiwiki/flattr.pm) + +This plugin is licensed under [CC0](http://creativecommons.org/publicdomain/zero/1.0/) (public domain). + +Note that there is now a [[plugins/flattr]] plugin bundled with ikiwiki. It +is less configurable, not supporting static buttons, but simpler to use. + +# Usage # + + # [[!flattr args]] where args are in the form of arg=value. + # Possible args: + # type - static or dynamic. Defaults to static. + + # vars in static mode: + # -------------------- + # Required: + # url - URL to flattr page, + # e.g. http://flattr.com/thing/1994/jaywalks-weblog + # Optional: + # style - Set to compact for compact button. + + # vars in dynamic mode: + # --------------------- + # Required: + # None. + # Optional: + # uid - Set the default in the plugin, override if needed. + # title - The title defaults to $wikiname/some/path (like on the top of + # the wiki). + # desc - A description of the content. Defaults to " ". + # cat - Category, this can be text, images, video, audio, software or + # rest. Defaults to text. + # lang - Language, list of available choises is on + # https://flattr.com/support/integrate/languages. Defaults to en_GB. + # tag - A list of comma separated tags. Empty per default. + # url - URL to thing to flattred, + # e.g. http://jonatan.walck.se/weblog + # style - Set it to compact to get the small button, big for any other + # value including empty. + diff --git a/doc/plugins/contrib/flattr/discussion.mdwn b/doc/plugins/contrib/flattr/discussion.mdwn new file mode 100644 index 000000000..586139e9c --- /dev/null +++ b/doc/plugins/contrib/flattr/discussion.mdwn @@ -0,0 +1,9 @@ +FWIW, it is possible for a plugin like this to add javascript to pages that +are protected by htmlscrubber. Just return a token in your preprocess hook, +and then have a format hook that replaces the token with the javascript. +--[[Joey]] + +> Thanks, That's good to know. I'll try to continue the development of this +> plugin later, for now I just needed it to work. :) It will most likely +> evolve as my page does too. +> --[[jaywalk]] diff --git a/doc/plugins/contrib/ftemplate.mdwn b/doc/plugins/contrib/ftemplate.mdwn new file mode 100644 index 000000000..d82867f94 --- /dev/null +++ b/doc/plugins/contrib/ftemplate.mdwn @@ -0,0 +1,25 @@ +[[!template id=plugin name=ftemplate author="[[rubykat]]"]] +[[!tag type/meta type/format]] + +This plugin provides the [[ikiwiki/directive/ftemplate]] directive. + +This is like the [[ikiwiki/directive/template]] directive, with the addition +that one does not have to provide all the values in the call to the template, +because ftemplate can query structured data ("fields") using the [[field]] +plugin. + +## Activate the plugin + + add_plugins => [qw{goodstuff ftemplate ....}], + +## PREREQUISITES + + IkiWiki + IkiWiki::Plugin::field + HTML::Template + Encode + +## DOWNLOAD + +* browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/ftemplate.pm> +* git repo at git://github.com/rubykat/ikiplugins.git diff --git a/doc/plugins/contrib/ftemplate/discussion.mdwn b/doc/plugins/contrib/ftemplate/discussion.mdwn new file mode 100644 index 000000000..1e0bca5d8 --- /dev/null +++ b/doc/plugins/contrib/ftemplate/discussion.mdwn @@ -0,0 +1,33 @@ +I initially thought this wasn't actually necessary - the combination +of [[plugins/template]] with [[plugins/contrib/field]]'s `pagetemplate` +hook ought to provide the same functionality. However, `template` +doesn't run `pagetemplate` hooks; a more general version of this +plugin would be to have a variant of `template` that runs `pagetemplate` +hooks (probably easiest to just patch `template` to implement a +second directive, or have a special parameter `run_hooks="yes"`, +or something). + +> I got the impression that `pagetemplate` hooks are intended to be completely independent of `template` variables; page-template is for the actual `page.tmpl` template, while `template` is for other templates which are used inside the page content. So I don't understand why one would need a run_hooks option. --[[KathrynAndersen]] + +>> `Render`, `inline`, `comments` and `recentchanges` run `pagetemplate` +>> hooks, as does anything that uses `IkiWiki::misctemplate`. From that +>> quick survey, it seems as though `template` is the only thing that +>> uses `HTML::Template` but *doesn't* run `pagetemplate` hooks? +>> +>> It just seems strange to me that `field` needs to have its own +>> variant of `template` (this), its own variant of `inline` (`report`), +>> and so on - I'd tend to lean more towards having `field` +>> enhance the existing plugins. I'm not an ikiwiki committer, +>> mind... Joey, your opinion would be appreciated! --[[smcv]] + +>>> I did it that way basically because I needed the functionality ASAP, and I didn't want to step on anyone's toes, so I made them as separate plugins. If Joey wants to integrate the functionality into IkiWiki proper, I would be very happy, but I don't want to put pressure on him. --[[KathrynAndersen]] + +Another missing thing is that `ftemplate` looks in +the "system" templates directories, not just in the wiki, but that +seems orthogonal (and might be a good enhancement to `template` anyway). +--[[smcv]] + +> Yes, I added that because I wanted the option of not having to make all my templates work as wiki pages also. --[[KathrynAndersen]] + +>> Joey has added support for +>> [[todo/user-defined_templates_outside_the_wiki]] now. --s diff --git a/doc/plugins/contrib/ftemplate/ikiwiki/directive/ftemplate.mdwn b/doc/plugins/contrib/ftemplate/ikiwiki/directive/ftemplate.mdwn new file mode 100644 index 000000000..3009fc830 --- /dev/null +++ b/doc/plugins/contrib/ftemplate/ikiwiki/directive/ftemplate.mdwn @@ -0,0 +1,106 @@ +The `ftemplate` directive is supplied by the [[!iki plugins/contrib/ftemplate desc=ftemplate]] plugin. + +This is like the [[ikiwiki/directive/template]] directive, with the addition +that one does not have to provide all the values in the call to the template, +because ftemplate can query structured data ("fields") using the +[[plugins/contrib/field]] plugin. + +Templates are files that can be filled out and inserted into pages in +the wiki, by using the ftemplate directive. The directive has an id +parameter that identifies the template to use. + +Additional parameters can be used to fill out the template, in +addition to the "field" values. Passed-in values override the +"field" values. + +There are two places where template files can live. One is in the /templates +directory on the wiki. These templates are wiki pages, and can be edited from +the web like other wiki pages. + +The second place where template files can live is in the global +templates directory (the same place where the page.tmpl template lives). +This is a useful place to put template files if you want to prevent +them being edited from the web, and you don't want to have to make +them work as wiki pages. + +### EXAMPLES + +#### Example 1 + +PageA: + + \[[!meta title="I Am Page A"]] + \[[!meta description="A is for Apple."]] + \[[!meta author="Fred Nurk"]] + \[[!ftemplate id="mytemplate"]] + +Template "mytemplate": + + # <TMPL_VAR NAME="TITLE"> + by <TMPL_VAR NAME="AUTHOR"> + + **Summary:** <TMPL_VAR NAME="DESCRIPTION"> + +This will give: + + <h1>I Am Page A</h1> + <p>by Fred Nurk</p> + <p><strong>Summary:</strong> A is for Apple. + +#### Example 2: Overriding values + +PageB: + + \[[!meta title="I Am Page B"]] + \[[!meta description="B is for Banana."]] + \[[!meta author="Fred Nurk"]] + \[[!ftemplate id="mytemplate" title="Bananananananas"]] + +This will give: + + <h1>Bananananananas</h1> + <p>by Fred Nurk</p> + <p><strong>Summary:</strong> B is for Banana. + +#### Example 3: Loops + +(this example uses the [[plugins/contrib/ymlfront]] plugin) + +Page C: + + --- + BookAuthor: Georgette Heyer + BookTitle: Black Sheep + BookGenre: + - Historical + - Romance + --- + \[[ftemplate id="footemplate"]] + + I like this book. + +Template "footemplate": + + # <TMPL_VAR BOOKTITLE> + by <TMPL_VAR BOOKAUTHOR> + + <TMPL_IF BOOKGENRE>( + <TMPL_LOOP GENRE_LOOP><TMPL_VAR BOOKGENRE> + <TMPL_UNLESS __last__>, </TMPL_UNLESS> + </TMPL_LOOP> + )</TMPL_IF> + +This will give: + + <h1>Black Sheep</h1> + <p>by Georgette Heyer</p> + + <p>(Historical, Romance)</p> + + <p>I like this book.</p> + +### LIMITATIONS + +One cannot query the values of fields on pages other than the current +page. If you want to do that, check out the [[plugins/contrib/report]] +plugin. diff --git a/doc/plugins/contrib/getfield.mdwn b/doc/plugins/contrib/getfield.mdwn new file mode 100644 index 000000000..0a92894f1 --- /dev/null +++ b/doc/plugins/contrib/getfield.mdwn @@ -0,0 +1,131 @@ +[[!template id=plugin name=getfield author="[[rubykat]]"]] +[[!tag type/meta type/format]] +[[!toc]] +## NAME + +IkiWiki::Plugin::getfield - query the values of fields + +## SYNOPSIS + + # activate the plugin + add_plugins => [qw{goodstuff getfield ....}], + +## DESCRIPTION + +This plugin provides a way of querying the meta-data (data fields) of a page +inside the page content (rather than inside a template) This provides a way to +use per-page structured data, where each page is treated like a record, and the +structured data are fields in that record. This can include the meta-data for +that page, such as the page title. + +This plugin is meant to be used in conjunction with the [[field]] plugin. + +### USAGE + +One can get the value of a field by using special markup in the page. +This does not use directive markup, in order to make it easier to +use the markup inside other directives. There are four forms: + +* {{$*fieldname*}} + + This queries the value of *fieldname* for the source page. + + For example: + + \[[!meta title="My Long and Complicated Title With Potential For Spelling Mistakes"]] + # {{$title}} + + When the page is processed, this will give you: + + <h1>My Long and Complicated Title With Potential For Spelling Mistakes</h1> + +* {{$*pagename*#*fieldname*}} + + This queries the value of *fieldname* for the page *pagename*. + + For example: + + On PageFoo: + + \[[!meta title="I Am Page Foo"]] + + Stuff about Foo. + + On PageBar: + + For more info, see \[[{{$PageFoo#title}}|PageFoo]]. + + When PageBar is displayed: + + <p>For more info, see <a href="PageFoo">I Am Page Foo</a>.</p> + +* {{+$*fieldname*+}} + + This queries the value of *fieldname* for the destination page; that is, + the value when this page is included inside another page. + + For example: + + On PageA: + + \[[!meta title="I Am Page A"]] + # {{+$title+}} + + Stuff about A. + + On PageB: + + \[[!meta title="I Am Page B"]] + \[[!inline pagespec="PageA"]] + + When PageA is displayed: + + <h1>I Am Page A</h1> + <p>Stuff about A.</p> + + When PageB is displayed: + + <h1>I Am Page B</h1> + <p>Stuff about A.</p> + +* {{+$*pagename*#*fieldname*+}} + + This queries the value of *fieldname* for the page *pagename*; the + only difference between this and {{$*pagename*#*fieldname*}} is + that the full name of *pagename* is calculated relative to the + destination page rather than the source page. + + I can't really think of a reason why this should be needed, but + this format has been added for completeness. + +### No Value Found + +If no value is found for the given field, then the field name is returned. + +For example: + +On PageFoo: + + \[[!meta title="Foo"]] + My title is {{$title}}. + + My description is {{$description}}. + +When PageFoo is displayed: + + <p>My title is Foo.</p> + + <p>My description is description.</p> + +This is because "description" hasn't been defined for that page. + +### More Examples + +Listing all the sub-pages of the current page: + + \[[!map pages="{{$page}}/*"]] + +## DOWNLOAD + +* browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/getfield.pm> +* git repo at git://github.com/rubykat/ikiplugins.git diff --git a/doc/plugins/contrib/getfield/discussion.mdwn b/doc/plugins/contrib/getfield/discussion.mdwn new file mode 100644 index 000000000..5f7fffead --- /dev/null +++ b/doc/plugins/contrib/getfield/discussion.mdwn @@ -0,0 +1,32 @@ +## Templating, and other uses + +Like you mentioned in [[ftemplate]] IIRC, it'll only work on the same page. If it can be made to work anywhere, or from a specific place in the wiki - configurable, possibly - you'll have something very similar to mediawiki's templates. I can already think of a few uses for this combined with [[template]] ;) . --[[SR|users/simonraven]] + +> Yes, I mentioned "only current page" in the "LIMITATIONS" section. + +> What do you think would be a good syntax for querying other pages? +> It needs to resolve to a single page, though I guess using "bestlink" to find the closest page would mean that one didn't have to spell out the whole page. + +>> I don't know the internals very well, I think that's how other plugins do it. *goes to check* Usually it's a `foreach` loop, and use a `pagestate{foo}` to check the page's status/state. There's also some stuff like 'pagespec_match_list($params{page}` ... they do slightly different thing depending on need. --[[SR|users/simonraven]] + +>>> No, I meant what markup I should use; the actual implementation probably wouldn't be too difficult. + +>>> The current markup is {{$*fieldname*}}; what you're wanting, perhaps it should be represented like {{$*pagename*:*fieldname*}}, or {{$*pagename*::*fieldname*}} or something else... +>>> -- [[KathrynAndersen]] + +>>>> Oh. Hmm. I like your idea actually, or alternately, in keeping more with other plugins, doing it like {{pagename/fieldname}}. The meaning of the separator is less clear with /, but avoids potential issues with filename clashes that have a colon in them. It also keeps a certain logic - at least to me. Either way, I think both are good choices. [[SR|users/simonraven]] + +>>>>> What about using {{pagename#fieldname}}? The meaning of the hash in URLs sort of fits with what is needed here (reference to a 'named' thing within the page) and it won't conflict with actual hash usages (unless we expect different named parts of pages to define different values for the same field ...) +>>>>> -- [[Oblomov]] +>>>>>> That's a good one too. --[[simonraven]] +>>>>>>> Done! I used {{$*pagename*#*fieldname*}} for the format. -- [[users/KathrynAndersen]] + + +> I'm also working on a "report" plugin, which will basically apply a template like [[ftemplate]] does, but to a list of pages given from a pagespec, rather than the current page. + +> -- [[users/KathrynAndersen]] + +>> Ooh, sounds nice :) . --[[SR|users/simonraven]] + +>>> I've now released the [[plugins/contrib/report]] plugin. I've been using it on my site; the holdup on releasing was because I hadn't yet written the docs for it. I hope you find it useful. +>>> -- [[users/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/highlightcode.mdwn b/doc/plugins/contrib/highlightcode.mdwn index 8abb76583..f1df204bb 100644 --- a/doc/plugins/contrib/highlightcode.mdwn +++ b/doc/plugins/contrib/highlightcode.mdwn @@ -1,6 +1,8 @@ [[!template id=plugin name=highlightcode author="[[sabr]]"]] [[!tag type/format]] +(An alternative to this plugin, [[plugins/highlight]], is now provided with IkiWiki. --[[smcv]]) + A small plugin to allow Ikiwiki to display source files complete with syntax highlighting. Files with recognized extensions (i.e. my-file.cpp) are be rendered just like any other Ikiwiki page. You can even edit your source files with Ikiwiki's editor. It uses the Syntax::Highlight::Engine::Kate Perl module to do the highlighting. diff --git a/doc/plugins/contrib/ikiwiki/directive/ymlfront.mdwn b/doc/plugins/contrib/ikiwiki/directive/ymlfront.mdwn new file mode 100644 index 000000000..1a01834f8 --- /dev/null +++ b/doc/plugins/contrib/ikiwiki/directive/ymlfront.mdwn @@ -0,0 +1,17 @@ +The `ymlfront` directive is supplied by the [[!iki plugins/contrib/ymlfront desc=ymlfront]] plugin. + +This directive allows the user to define arbitrary meta-data in YAML format. + + \[[!ymlfront data=""" + foo: fooness + bar: The Royal Pigeon + baz: 2 + """]] + +There is one argument to this directive. + +* **data:** + 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 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/justlogin.mdwn b/doc/plugins/contrib/justlogin.mdwn new file mode 100644 index 000000000..90645b9ef --- /dev/null +++ b/doc/plugins/contrib/justlogin.mdwn @@ -0,0 +1,52 @@ +This plugin has been abandoned while still in development. Currently it does bring up the login page and the login page does, with proper credentials, log in the user, but the returning page goes to prefs. I have no idea why. I decided to go in another direction so if someone wants to take over then please do so. Otherwise I have no problem if this page needs to be deleted. [[users/justint/]] + +Place this code into a page: + +<form action="http://portable.local/cgi-bin/ikiwiki.cgi" method="get"> + +<input type="hidden" name="do" value="justlogin" /> + +<input type="submit" value="Login" /></form> + +This is the plugin so far: +#!/usr/bin/perl + # Bring up a login page that returns to the calling page + package IkiWiki::Plugin::justlogin; + + use warnings; + use strict; + use IkiWiki 3.00; + + sub import { + hook(type => "sessioncgi", id => "justlogin", call => \&sessioncgi); + } + + sub sessioncgi ($$) { + my $q=shift; + my $session=shift; + + debug("jl sessioncgi1 running."); + + if ($q->param("do") eq "justlogin") { + debug("jl do=justlogin running."); + if (! defined $session->param("name") ) { + debug("jl param!defined running."); + $session->param("postsignin" => $ENV{HTTP_REFERER} ); + $session->param("do" => "justgoback" ); + IkiWiki::cgi_signin($q, $session); + IkiWiki::cgi_savesession($session); + } + exit; + } elsif ($session->param("do") eq "justgoback") { + debug("jl justgoback running."); + my $page=$q->param("postsignin"); + $session->clear("postsignin"); + $session->clear("do"); + IkiWiki::cgi_savesession($session); + IkiWiki::redirect($q, $page); + exit; + } + } + + 1 + diff --git a/doc/plugins/contrib/mediawiki.mdwn b/doc/plugins/contrib/mediawiki.mdwn index 7bf1ba0df..13c2d04b2 100644 --- a/doc/plugins/contrib/mediawiki.mdwn +++ b/doc/plugins/contrib/mediawiki.mdwn @@ -1,7 +1,10 @@ [[!template id=plugin name=mediawiki author="[[sabr]]"]] [[!tag type/format]] -[The Mediawiki plugin](http://u32.net/Mediawiki_Plugin/) allows ikiwiki to -process pages written using MediaWiki markup. +The Mediawiki plugin allows ikiwiki to process pages written using MediaWiki +markup. -Available at <http://alcopop.org/~jon/mediawiki.pm> +Available at <http://github.com/jmtd/mediawiki.pm>. + +This plugin originally lived at <http://u32.net/Mediawiki_Plugin/>, but that +website has disappeared. diff --git a/doc/plugins/contrib/pod.mdwn b/doc/plugins/contrib/pod.mdwn new file mode 100644 index 000000000..97a9c648a --- /dev/null +++ b/doc/plugins/contrib/pod.mdwn @@ -0,0 +1,38 @@ +[[!template id=plugin name=pod author="[[rubykat]]"]] +[[!tag type/format]] +## NAME + +IkiWiki::Plugin::pod - process pages written in POD format. + +## SYNOPSIS + +In the ikiwiki setup file, enable this plugin by adding it to the +list of active plugins. + + add_plugins => [qw{goodstuff pod ....}], + +## DESCRIPTION + +IkiWiki::Plugin::pod is an IkiWiki plugin enabling ikiwiki to +process pages written in POD ([Plain Old Documentation](http://en.wikipedia.org/wiki/Plain_Old_Documentation)) format. +This will treat files with a `.pod` or `.pm` extension as files +which contain POD markup. + +## OPTIONS + +The following options can be set in the ikiwiki setup file. + +* **pod_index:** If true, this will generate an index (table of contents) for the page. +* **pod_toplink:** The label to be used for links back to the top of the page. If this is empty, then no top-links will be generated. + +## PREREQUISITES + + IkiWiki + Pod::Xhtml + IO::String + +## DOWNLOAD + +* browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/pod.pm> +* git repo at git://github.com/rubykat/ikiplugins.git + diff --git a/doc/plugins/contrib/pod/discussion.mdwn b/doc/plugins/contrib/pod/discussion.mdwn new file mode 100644 index 000000000..9187b1350 --- /dev/null +++ b/doc/plugins/contrib/pod/discussion.mdwn @@ -0,0 +1,14 @@ +My one concern about this plugin is the `=for` markup in POD. + +> Some format names that formatters currently are known to +> accept include "roff", "man", "latex", "tex", "text", and "html". + +I don't know which of these [[!cpan Pod::Xhtml]] supports. If it currently +supports, or later support latex, that could be problimatic since that +could maybe be used to include files or run code. --[[Joey]] + +> I don't know, either; the documentation for [[!cpan Pod:Xhtml]] is silent on this subject. --[[KathrynAndersen]] + +>> I'm afraid the only approach is to audit the existing code in the perl +>> module(s), and then hope nothing is added to them later that opens a +>> security hole. --[[Joey]] diff --git a/doc/plugins/contrib/postal.mdwn b/doc/plugins/contrib/postal.mdwn index b2f875393..c522f8bcb 100644 --- a/doc/plugins/contrib/postal.mdwn +++ b/doc/plugins/contrib/postal.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=postal author="[[DavidBremner]]"]] -[[!tag type/useful]] +[[!tag type/special-purpose]] The `postal` plugin allows users to send mail to a special address to comment on a page. It uses the [[mailbox]] diff --git a/doc/plugins/contrib/report.mdwn b/doc/plugins/contrib/report.mdwn new file mode 100644 index 000000000..0bd5392c6 --- /dev/null +++ b/doc/plugins/contrib/report.mdwn @@ -0,0 +1,26 @@ +[[!template id=plugin name=report author="[[rubykat]]"]] +[[!tag type/meta type/format]] +IkiWiki::Plugin::report - Produce templated reports from page field data. + +This plugin provides the [[ikiwiki/directive/report]] directive. This enables +one to report on the structured data ("field" values) of multiple pages; the +output is formatted via a template. This depends on the +[[plugins/contrib/field]] plugin. + + +## Activate the plugin + + # activate the plugin + add_plugins => [qw{goodstuff report ....}], + +## PREREQUISITES + + IkiWiki + IkiWiki::Plugin::field + HTML::Template + Encode + +## DOWNLOAD + +* browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/report.pm> +* git repo at git://github.com/rubykat/ikiplugins.git diff --git a/doc/plugins/contrib/report/discussion.mdwn b/doc/plugins/contrib/report/discussion.mdwn new file mode 100644 index 000000000..e23a4ced4 --- /dev/null +++ b/doc/plugins/contrib/report/discussion.mdwn @@ -0,0 +1,75 @@ +Wow, this plugin does a lot... it seems to be `inline` (but without the feeds +or the ability to not have `archive="yes"`), plus part of +[[plugins/contrib/trail]], plus some sorting, plus an ingenious workaround +for template evaluation being relatively stateless. + +A large part of this plugin would just fall off if one of the versions of +"[[todo/allow_plugins_to_add_sorting_methods]]" was merged, which was a +large part of the idea of that feature request :-) To make use of that +you'd have to use `pagespec_match_list` in the trail case too, but that's +easy enough - just add `list => [@the_trail_pages]` to the arguments. + +Another large part would fall off if this plugin required, and internally +invoked, `inline` (like my `comments` plugin does) - `inline` runs +`pagetemplate` hooks, and in particular, it'll run the `field` hook. +Alternatively, this plugin could invoke `pagetemplate` hooks itself, +removing the special case for `field`. + +Perhaps the `headers` thing could migrate into inline somehow? That might +lead to making inline too big, though. + +> I think inline is *already* too big, honestly. --[[KathrynAndersen]] + +>> A fair point; perhaps my complaint should be that *inline* does +>> too many orthogonal things. I suppose the headers feature wouldn't +>> really make sense in an inline that didn't have `archive="yes"`, +>> so it'd make sense to recommend this plugin as a replacement +>> for inlining with archive=yes (for which I now realise "inline" +>> is the wrong verb anyway :-) ) --s + +>>> I think *inline* would be a bit less unwieldy if there was some way of factoring out the feed stuff into a separate plugin, but I don't know if that's possible. --K.A. + +Is the intention that the `trail` part is a performance hack, or a way +to select pages? How does it relate to [[todo/wikitrails]] or +[[plugins/contrib/trail]]? --[[smcv]] + +> The `trail` part is *both* a performance hack, and a way to select pages. I have over 5000 pages on my site, I need all the performance hacks I can get. +> For the performance hack, it is a way of reducing the need to iterate through every single page in the wiki in order to find matching pages. +> For the way-to-select-pages, yes, it is intended to be similar to [[todo/wikitrails]] and [[plugins/contrib/trail]] (and will be more similar with the new release which will be happening soon; it will add prev_* and next_* variables). +> The idea is that, rather than having to add special "trail" links on PageA to indicate that a page is part of the trail, +> it takes advantage of the `%links` hash, which already contains, for each page, an array of the links from that page to other pages. No need for special markup, just use what's there; a trail is defined as "all the pages linked to from page X", and since it's an array, it has an order already. +> But to avoid that being too limiting, one can use a `pages=...` pagespec to filter that list to a subset; only the pages one is interested in. +> And one can also sort it, if one so desires. +> --[[KathrynAndersen]] + +>> That's an interesting approach to trails; I'd missed the fact that +>> links are already ordered. +>> +>> This does have the same problems as tags, though: see +>> [[bugs/tagged()_matching_wikilinks]] and +>> [[todo/matching_different_kinds_of_links]]. I suppose the question +>> now is whether new code should be consistent with `tag` (and +>> potentially be fixed at the same time as tag itself), or try to +>> avoid those problems? +>> +>> The combination of `trail` with another pagespec in this plugin +>> does provide a neat way for it to work around having unwanted +>> pages in the report, by limiting by a suitable tag or subdirectory +>> or something. --s + +>>> Either that, or somehow combine tagging with fields, such that one could declare a tag, and it would create both a link and a field with a given value. (I've been working on something like that, but it still has bugs). +>>> That way, the test for whether something is tagged would be something like "link(tag/foo) and field(tag foo)". +>>> --K.A. + +>>>> I can see that this'd work well for 1:1 relationships like next +>>>> and previous, but I don't think that'd work for pages with more than +>>>> one tag - as far as I can see, `field`'s data model is that each +>>>> page has no more than one value for each field? +>>>> [[todo/Matching_different_kinds_of_links]] has some thoughts about +>>>> how it could be implemented, though. --s + +>>>>> You have a point there. I'm not sure what would be better: to add the concept of arrays/sets to `field`, or to think of tags as a special case. Problem is, I find tags as they currently exist to be too limiting. I prefer something that can be used for Faceted Tagging <http://en.wikipedia.org/wiki/Faceted_classification>; that is, things like Author:Fred Nurk, Genre:Historical, Rating:Good, and so on. Of course, that doesn't mean that each tag is limited to only one value, either; just to take the above examples, something might have more than one author, or have multiple genres (such as Historical + Romance). + +>>>>> It might be that adding arrays to the `field` plugin is a good way to go: after all, even though field=value is the most common, with the flexibility of things like YAML, one could define all sorts of things. What I'm not so sure about is how to return the values when queried, since some things would be expecting scalars all the time. Ah, perhaps I could use wantarray? +>>>>> Is there a way of checking a HTML::Template template to see if it expecting an array for a particular value? +>>>>> --[[KathrynAndersen]] diff --git a/doc/plugins/contrib/report/ikiwiki/directive/report.mdwn b/doc/plugins/contrib/report/ikiwiki/directive/report.mdwn new file mode 100644 index 000000000..df88b33ad --- /dev/null +++ b/doc/plugins/contrib/report/ikiwiki/directive/report.mdwn @@ -0,0 +1,171 @@ +[[!toc]] +The `report` directive is supplied by the [[!iki plugins/contrib/report desc=report]] plugin. + +This enables one to report on the structured data ("field" values) of +multiple pages; the output is formatted via a template. This depends +on the [[plugins/contrib/field]] plugin. + +The pages to report on are selected by a PageSpec given by the "pages" +parameter. The template is given by the "template" parameter. +The template expects the data from a single page; it is applied +to each matching page separately, one after the other. + +Additional parameters can be used to fill out the template, in +addition to the "field" values. Passed-in values override the +"field" values. + +There are two places where template files can live. One is in the +/templates directory on the wiki. These templates are wiki pages, and +can be edited from the web like other wiki pages. + +The second place where template files can live is in the global +templates directory (the same place where the page.tmpl template lives). +This is a useful place to put template files if you want to prevent +them being edited from the web, and you don't want to have to make +them work as wiki pages. + +## OPTIONS + +**template**: The template to use for the report. + +**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 +of) the pages which that page links to; the "pages" pagespec in this +case, rather than selecting pages from the entire wiki, will select +pages from within the set of pages given by the trail page. + +Additional space-separated trail pages can be given in this option. +For example: + + trail="animals/cats animals/dogs" + +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. + +This is useful in combination with "prev_" and "next_" variables to +make a navigation trail. +If the current page doesn't match the pagespec, then no pages will +be reported on. + +### Headers + +An additional option is the "headers" option. This is a space-separated +list of field names which are to be used as headers in the report. This +is a way of getting around one of the limitations of HTML::Template, that +is, not being able to do tests such as +"if this-header is not equal to previous-header". + +Instead, that logic is performed inside the plugin. The template is +given parameters "HEADER1", "HEADER2" and so on, for each header. +If the value of a header field is the same as the previous value, +then HEADER**N** is set to be empty, but if the value of the header +field is new, then HEADER**N** is given that value. + +#### Example + +Suppose you're writing a blog in which you record "moods", and you +want to display your blog posts by mood. + + \[[!report template="mood_summary" + pages="blog/*" + sort="Mood Date title" + headers="Mood"]] + +The "mood_summary" template might be like this: + + <TMPL_IF NAME="HEADER1"> + ## <TMPL_VAR NAME="HEADER1"> + </TMPL_IF> + ### <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 +with large numbers of pages; most people probably won't need them. + +**doscan**: + +Whether this report should be called in "scan" mode; if it is, then +the pages which match the pagespec are added to the list of links from +this page. This can be used by *another* report by setting this +page to be a "trail" page in *that* report. +It is not possible to use "trail" and "doscan" at the same time. +By default, "doscan" is false. + +## TEMPLATE PARAMETERS + +The templates are in HTML::Template format, just as [[plugins/template]] and +[[ftemplate]] are. The parameters passed in to the template are as follows: + +### Fields + +The structured data from the current matching page. This includes +"title" and "description" if they are defined. + +### Common values + +Values known for all pages: "page", "destpage". Also "basename" (the +base name of the page). + +### Passed-in values + +Any additional parameters to the report directive are passed to the +template; a parameter will override the matching "field" value. +For example, if you have a "Mood" field, and you pass Mood="bad" to +the report, then that will be the Mood which is given for the whole +report. + +Generally this is useful if one wishes to make a more generic +template and hide or show portions of it depending on what +values are passed in the report directive call. + +For example, one could have a "hide_mood" parameter which would hide +the "Mood" section of your template when it is true, which one could +use when the Mood is one of the headers. + +### Prev_ And Next_ Items + +Any of the above variables can be prefixed with "prev_" or "next_" +and that will give the previous or next value of that variable; that is, +the value from the previous or next page that this report is reporting on. +This is mainly useful for a "here_only" report. + +### Headers + +See the section on Headers. + +### First and Last + +If this is the first page-record in the report, then "first" is true. +If this is the last page-record in the report, then "last" is true. diff --git a/doc/plugins/contrib/screenplay.pm.mdwn b/doc/plugins/contrib/screenplay.pm.mdwn new file mode 100644 index 000000000..5ff082da5 --- /dev/null +++ b/doc/plugins/contrib/screenplay.pm.mdwn @@ -0,0 +1,320 @@ +This plugin works for me. It follows the standard for a movie screenplay pretty closely, I am not aware of any errors in format. Please let me know if you find any. + +Right now all it does is display your pages properly in a web browser. What I would like to add is the ability to output a file that could easily be printed once the screenplay is finished. We keep all the scenes we work on in one folder and eventually we will want to print a script out of that folder. It would be great if an up to date PDF or TXT script could be put in the folder when a scene is saved. I will do it, it just isn't a priority yet. + +I am not a published writer and not an authority on script formatting. I got what I know out of a book. + +Briefly, you type a command on a line, like ".d", then on the next line (for the dialog command) you type a person's name. Then you hit return again and write the words he is supposed to speak out all on one line. When you save your document this simple text will become a properly formatted script. + +Thank you Joey for having me here. + +###Headings: + Most headings should begin with a transition. The list of valid commands is: + .fi => FADE IN: a gradual transition from a solid color to an image + .fo => FADE OUT. + .ftb => FADE TO BLACK. + .ftw => FADE TO WHITE. + .ct => CUT TO: indicates an instantaneous shift from one shot to the next + .shot => lack of an explicit transition assumes a cut + .hct => HARD CUT TO: describes a jarring transition + .qct => QUICK CUT TO: describes a cut sooner than expected + .tct => TIME CUT TO: emphasizes time passing + .mct => MATCH CUT TO: image in first shot visually or thematically matches image in second + .dt => DISSOLVE TO: gradual transition from image to another implies passage of time. + .rdt => RIPPLE DISSOLVE TO: indicates transition into daydream or imagination + .wt => WIPE TO: new image slides over top of last one + + Example transition: + + .fi (or any transition command) <= Writes a transition line, except .shot which omits it. + type shot heading here <= this line will be capitalized + First direction. <= these lines are not capitalized. + Second direction. + Third direction, etc... + + Direction without a shot heading: + .dir + First direction. + Second direction. + Third direction, etc... + + Some items aren't implemented in dialogue yet: + 1) you must watch that you don't leave a " -- " dangling on a line by itself, + instead, carry the last word onto the line with a dash + 2) observe lyrical line endings in dialogue by indenting wrapped lines by two spaces + 3) you must watch that the four line limit for parenthetical direction is not exceeded + + Example dialogue: + + .d + char name <= this line will be capitalized + this is what he's saying <= Dialogue + raises hand to wave <= Parenthetical direction + this is more of what he's saying <= Dialogue + this is going to be in parenthesis <= Parenthetical direction + this is more of what he's saying, etc... <= Dialogue + + .note + Allows you to add a temporary note to a script without getting an error. + All notes need to be removed eventually because they are a format violation. + + + + ###name this file screenplay.pm and pop it in your Plugin folder. Then you need to add the plugin to your Ikiwiki setup file. + + #!/usr/bin/perl + # Screenplay markup language + package IkiWiki::Plugin::screenplay; + + use warnings; + use strict; + use IkiWiki 3.00; + use Text::Format; + use Log::Log4perl qw(:easy); + Log::Log4perl->easy_init($INFO); + #Log::Log4perl->easy_init($ERROR); + + sub import { + hook(type => "getsetup", id => "screenplay", call => \&getsetup); + hook(type => "htmlize", id => "screenplay", call => \&htmlize, longname => "Screenplay"); + } + + sub getsetup () { + return + plugin => { + safe => 1, + rebuild => 1, # format plugin + section => "format", + }, + } + + sub htmlize (@) { + #set up variables and fill with defaults + my %params=@_; + my $content = $params{content}; + my @lines = split(/\r\n|\r|\n/, $content); + my @chunk; + my @formatted; + my $current_line = shift(@lines); + my $current_command = ""; + my $current_chunk = ""; + + while (scalar(@lines) > 0) { + until ( &dot_command($current_line) || scalar(@lines) == 0 ) { + #skip spaces; mark bad lines + unless ( &blank_line($current_line) ) { + push(@formatted, "<br />"); + push(@formatted, &no_command($current_line)); + } + $current_line = shift(@lines); + } + + #Exit while loop if we're out of lines + last if (scalar(@lines) == 0); + + #set command for chunk + $current_command = $current_line; + $current_line = shift(@lines); + + #get chunk, i.e. all text up to next blank line or a dot command. + until (substr($current_line,0,1) eq '.' || $current_line =~ m// || $current_line =~ m/^\s*$/) { + push(@chunk,$current_line); + $current_line = shift(@lines); + last unless defined $current_line; + } + + #Start with a blank line unless unneeded. + if (scalar(@formatted) > 0 ) { + push(@formatted, "<br />"); + } + + #remaining lines are not commands. + if (scalar(@chunk)) { + $current_chunk = shift(@chunk); + if ($current_command eq ".shot") { + push(@formatted, &indent(&chunk(uc($current_chunk),57),17)); + while (scalar(@chunk)) { + $current_chunk = shift(@chunk); + push(@formatted, "<br />"); + push(@formatted, &indent(&chunk($current_chunk,57),17)); + } + + } elsif ($current_command eq ".note") { + push(@formatted, "NOTE:<br />"); + push(@formatted, &chunk($current_chunk,75)); + while (scalar(@chunk)) { + $current_chunk = shift(@chunk); + push(@formatted, "<br />"); + push(@formatted, &chunk($current_chunk,75)); + } + + } elsif ($current_command eq ".dir") { + push(@formatted, &indent(&chunk($current_chunk,57),17)); + while (scalar(@chunk)) { + $current_chunk = shift(@chunk); + push(@formatted, "<br />"); + push(@formatted, &indent(&chunk($current_chunk,57),17)); + } + + } elsif ($current_command eq ".d") { + push(@formatted, &indent(&chunk(uc($current_chunk),32),41)); + $current_chunk = shift(@chunk); + push(@formatted, &indent(&chunk($current_chunk,34),27)); + while (scalar(@chunk) / 2 >= 1 ) { + $current_chunk = shift(@chunk); + push(@formatted, &indent(&chunk(&pd($current_chunk),19),34)); + $current_chunk = shift(@chunk); + push(@formatted, &indent(&chunk($current_chunk,34),27)); + } + + } elsif ($current_command eq ".pd") { + push(@formatted, &indent(&chunk(uc($current_chunk),32),41)); + $current_chunk = shift(@chunk); + push(@formatted, &indent(&chunk(&pd($current_chunk),19),34)); + $current_chunk = shift(@chunk); + push(@formatted, &indent(&chunk($current_chunk,34),27)); + while (scalar(@chunk) / 2 >= 1 ) { + $current_chunk = shift(@chunk); + push(@formatted, &indent(&chunk(&pd($current_chunk),19),34)); + $current_chunk = shift(@chunk); + push(@formatted, &indent(&chunk($current_chunk,34),27)); + } + + } elsif ($current_command =~ m/^\.(fi|fo|ct|hct|qct|tct|mct|dt|rdt)$/) { + if ($current_command eq ".fi") { + push(@formatted, &indent(&chunk(uc("FADE IN:"),20),17)); + } elsif ($current_command eq ".fo") { + push(@formatted, &indent(&chunk(uc("FADE OUT:"),20),60)); + } elsif ($current_command eq ".ct") { + push(@formatted, &indent(&chunk(uc("CUT TO:"),20),60)); + } elsif ($current_command eq ".hct") { + push(@formatted, &indent(&chunk(uc("HARD CUT TO:"),20),60)); + } elsif ($current_command eq ".qct") { + push(@formatted, &indent(&chunk(uc("QUICK CUT TO:"),20),60)); + } elsif ($current_command eq ".tct") { + push(@formatted, &indent(&chunk(uc("TIME CUT TO:"),20),60)); + } elsif ($current_command eq ".mct") { + push(@formatted, &indent(&chunk(uc("MATCH CUT TO:"),20),60)); + } elsif ($current_command eq ".dt") { + push(@formatted, &indent(&chunk(uc("DISSOLVE TO:"),20),60)); + } elsif ($current_command eq ".rdt") { + push(@formatted, &indent(&chunk(uc("RIPPLE DISSOLVE TO:"),20),60)); + } elsif ($current_command eq ".wt") { + push(@formatted, &indent(&chunk(uc("WIPE TO:"),20),60)); + } + push(@formatted, &indent(&chunk(uc($current_chunk),57),17)); + while (scalar(@chunk)) { + $current_chunk = shift(@chunk); + push(@formatted, "<br />"); + push(@formatted, &indent(&chunk($current_chunk,57),17)); + } + + } + #mark the rest of the chunk as 'no command' + if (scalar(@chunk)) { + $current_chunk = shift(@chunk); + push(@formatted, &no_command($current_chunk)); + } + + } + } + my @content; + my $i = 0; + $current_line = ""; + while (scalar(@formatted)) { + $i++; + $current_line = shift(@formatted); + if ( $i % 60 == 0 ) { + push(@content, &indent($i/60 . ".<br />",72) ); + } + push(@content, $current_line); + } + $content = join("\r\n",@content); + return $content; + } + + sub blank_line { + my $line = shift(@_); + my $ret = 0; + + if ($line =~ m// || $line =~ m/^\s*$/) { + $ret = 1; + } else { + $ret = 0; + } + + return $ret; + } + + sub chunk () { + my $unchunked = shift(@_); + my $columns = shift(@_); + my $text = new Text::Format; + $text->rightFill(1); + $text->columns($columns); + $text->firstIndent(0); + $text->tabstop(0); + $text->extraSpace(1); + my @chunked = split /\n/, $text->format($unchunked); + my @formatted; + foreach (@chunked) { + push(@formatted, $_ . "<br />"); + } + return @formatted; + } + + sub dot_command { + my $line = shift(@_); + my $ret = 0; + + if ($line =~ m/^\.(ct|dir|dt|d|fi|fo|hct|mct|note|pd|qct|rdt|shot|tct)$/) { + $ret = 1; + } else { + $ret = 0; + } + + return $ret; + } + + sub indent () { + my @unindented = @_; + my $spaces = pop @unindented; + my @indented; + foreach (@unindented) { + push(@indented, " " x $spaces . $_); + } + return @indented; + } + + sub no_command () { + my $line = shift(@_); + my $text = new Text::Format; + $text->rightFill(1); + $text->columns(68); + $text->firstIndent(0); + $text->tabstop(0); + $text->extraSpace(1); + my @chunked = split /\n/, $text->format($line); + my @formatted; + push(@formatted, ("NO COMMAND: ")); + foreach (@chunked) { + push(@formatted, ( $_ . "<br />" )); + } + return @formatted; + } + + sub pd () { + my @chunk = @_; + # add '(' to top item + my $line = "(" . shift(@chunk); + unshift(@chunk, $line); + + # add ')' to bottom item + $line = pop(@chunk) . ")"; + push(@chunk, $line); + + return @chunk; + } + + 1 + 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/tracking.mdwn b/doc/plugins/contrib/tracking.mdwn new file mode 100644 index 000000000..06d4120cd --- /dev/null +++ b/doc/plugins/contrib/tracking.mdwn @@ -0,0 +1,30 @@ +[[!template id=plugin name=tracking author="[[BerndZeimetz]]"]] +[[!toc]] +[[!tag plugins]] [[!tag patch]] [[!tag wishlist]] + +## NAME + +IkiWiki::Plugin::tracking - enable google/piwik visitor tracking + +## SYNOPSIS + + # activate the plugin + add_plugins => [qw{goodstuff tracking ....}], + + # to use Piwik: + piwik_id => '1', + piwik_https_url => "https://ssl.example.com/piwik/", + piwik_http_url => "http://www.example.com/piwik/", + + # to use Google Analytics: + google_analytics_id => "UA-xxxxxx-x" + +## DESCRIPTION + +This plugin includes the necessary tracking codes for Piwik and/or Google Analytics on all pages. Tracking codes will only be included if the necessary config options are set. The plugin could be enhanced to support goals/profiles and similar things, but I do not plan to do so. + +## DOWNLOAD + +* single files: [tracking.pm](http://git.recluse.de/?p=users/bzed/ikiwiki.git;a=blob;f=IkiWiki/Plugin/tracking.pm;hb=refs/heads/tracking) [piwik.tmpl](http://git.recluse.de/?p=users/bzed/ikiwiki.git;a=blob;f=templates/piwik.tmpl;hb=refs/heads/tracking) [google_analytics.tmpl](http://git.recluse.de/?p=users/bzed/ikiwiki.git;a=blob;f=templates/google_analytics.tmpl;hb=refs/heads/tracking) +* browse repository: <http://git.recluse.de/?p=users/bzed/ikiwiki.git;a=shortlog;h=refs/heads/tracking> +* git repo: `git://git.recluse.de/users/bzed/ikiwiki.git` or <http://git.recluse.de/repos/users/bzed/ikiwiki.git> (Use the tracking branch) diff --git a/doc/plugins/contrib/unixauth.mdwn b/doc/plugins/contrib/unixauth.mdwn index 137195139..c97312b59 100644 --- a/doc/plugins/contrib/unixauth.mdwn +++ b/doc/plugins/contrib/unixauth.mdwn @@ -1,7 +1,7 @@ [[!template id=plugin name=unixauth core=0 author="[[schmonz]]"]] [[!tag type/auth]] -[[!template id=gitbranch branch=schmonz author="[[schmonz]]"]] +[[!template id=gitbranch branch=unixauth author="[[schmonz]]"]] This plugin authenticates users against the Unix user database. It presents a similar UI to [[plugins/passwordauth]], but simpler, as there's no need to be able to register or change one's password. diff --git a/doc/plugins/contrib/xslt.mdwn b/doc/plugins/contrib/xslt.mdwn new file mode 100644 index 000000000..80c956c58 --- /dev/null +++ b/doc/plugins/contrib/xslt.mdwn @@ -0,0 +1,39 @@ +[[!template id=plugin name=xslt author="[[rubykat]]"]] +[[!tag type/chrome]] +## NAME + +IkiWiki::Plugin::xslt - ikiwiki directive to process an XML file with XSLT + +## SYNOPSIS + +\[[!xslt file="data1.xml" stylesheet="style1.xsl"]] + +## DESCRIPTION + +IkiWiki::Plugin::xslt is an IkiWiki plugin implementing a directive +to process an input XML data file with XSLT, and output the result in +the page where the directive was called. + +It is expected that the XSLT stylesheet will output valid HTML markup. + +## OPTIONS + +There are two arguments to this directive. + +* **file:** + The file which contains XML data to be processed. This file *must* have a `.xml` extension (`filename.xml`). This file is searched for using the usual IkiWiki mechanism, thus finding the file first in the same directory as the page, then in the directory above, and so on. + +* **stylesheet:** + The file which contains XSLT stylesheet to apply to the XML data. This file *must* have a `.xsl` extension (`filename.xsl`). This file is searched for using the usual IkiWiki mechanism, thus finding the file first in the same directory as the page, then in the directory above, and so on. + +## PREREQUISITES + + IkiWiki + XML::LibXML + XML::LibXSLT + +## DOWNLOAD + +* browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/xslt.pm> +* git repo at git://github.com/rubykat/ikiplugins.git + diff --git a/doc/plugins/contrib/xslt/discussion.mdwn b/doc/plugins/contrib/xslt/discussion.mdwn new file mode 100644 index 000000000..72cce083c --- /dev/null +++ b/doc/plugins/contrib/xslt/discussion.mdwn @@ -0,0 +1,49 @@ +## security + +I'm curious what the security implications of having this plugin on a +publically writable wiki are. + +First, it looks like the way it looks up the stylesheet file will happily +use a regular .mdwn wiki page as the stylsheet. Which means any user can +create a stylesheet and have it be used, without needing permission to +upload arbitrary files. That probably needs to be fixed; one way would be +to mandate that the `srcfile` has a `.xsl` extension. + +Secondly, if an attacker is able to upload a stylesheet file somehow, could +this be used to attack the server where it is built? I know that xslt is +really a full programming language, so I assume at least DOS attacks are +possible. Can it also read other arbitrary files, run other programs, etc? +--[[Joey]] + +> For the first point, agreed. It should probably check that the data file has a `.xml` extension also. Have now fixed. + +> For the second point, I think the main concern would be resource usage. XSLT is a pretty limited language; it can read other XML files, but it can't run other programs so far as I know. + +> -- [[KathrynAndersen]] + +>> XSLT is, indeed, a Turing-complete programming language. + However, [XML::LibXSLT][] provides a set of functions to help + to minimize the damage that may be caused by running a random + program. + +>> In particular, `max_depth ()` allows for the maximum + recursion depth to be set, while + `read_file ()`, `write_file ()`, `create_dir ()`, + `read_net ()` and `write_net ()` + are the callbacks that allow any of the possible file + operations to be denied. + +>> To be honest, I'd prefer for the `read_file ()` callback to + only grant access to the files below the Ikiwiki source + directory, and for all the `write_`… and + …`_net` callbacks to deny the access unconditionally. + +>> One more wishlist item: allow the set of locations to take + `.xsl` files from to be preconfigured, so that, e. g., + one could allow (preasumably trusted) system stylesheets, + while disallowing any stylesheets that are placed on the Wiki + itself. + +>> — Ivan Shmakov, 2010-03-28Z. + +[XML::LibXSLT]: http://search.cpan.org/~PAJAS/XML-LibXSLT/LibXSLT.pm diff --git a/doc/plugins/contrib/ymlfront.mdwn b/doc/plugins/contrib/ymlfront.mdwn new file mode 100644 index 000000000..2805be04f --- /dev/null +++ b/doc/plugins/contrib/ymlfront.mdwn @@ -0,0 +1,143 @@ +[[!template id=plugin name=ymlfront author="[[rubykat]]"]] +[[!tag type/meta]] +[[!toc]] +## NAME + +IkiWiki::Plugin::ymlfront - add YAML-format data to a page + +## SYNOPSIS + + # 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 +page by prefixing the page with a YAML-format document. This also provides +the [[ikiwiki/directive/ymlfront]] directive, which enables one to put +YAML-formatted data inside a standard IkiWiki [[ikiwiki/directive]]. + +This is a way to create per-page structured data, where each page is +treated like a record, and the structured data are fields in that record. This +can include the meta-data for that page, such as the page title. + +This plugin is meant to be used in conjunction with the [[field]] plugin. + +## DETAILS + +There are three formats for adding YAML data to a page. These formats +should not be mixed - the result is undefined. + +1. ymlfront directive + + See [[ikiwiki/directive/ymlfront]] for more information. + +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 outside the delimiters, + both before and after. That will be htmlized using the page-type of the page-file. + +### Accessing the Data + +There are a few ways to access the given YAML data. + +* [[getfield]] plugin + + The **getfield** plugin can display the data as individual variable values. + + For example: + + --- + title: Foo does not work + Urgency: High + Status: Assigned + AssignedTo: Fred Nurk + Version: 1.2.3 + --- + # {{$title}} + + **Urgency:** {{$Urgency}}\\ + **Status:** {{$Status}}\\ + **Assigned To:** {{$AssignedTo}}\\ + **Version:** {{$Version}} + + When running on the Sprongle system, the Foo function returns incorrect data. + +* [[ftemplate]] plugin + + The **ftemplate** plugin is like the [[plugins/template]] plugin, but it is also aware of [[field]] values. + + For example: + + --- + title: Foo does not work + Urgency: High + Status: Assigned + AssignedTo: Fred Nurk + Version: 1.2.3 + --- + \[[!ftemplate id="bug_display_template"]] + + When running on the Sprongle system, the Foo function returns incorrect data. + +* [[report]] plugin + + The **report** plugin is like the [[ftemplate]] plugin, but it reports on multiple pages, rather than just the current page. + +* write your own plugin + + In conjunction with the [[field]] plugin, you can write your own plugin to access the data. + +## PREREQUISITES + + IkiWiki + IkiWiki::Plugin::field + YAML::Any + +## DOWNLOAD + +* browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/ymlfront.pm> +* git repo at git://github.com/rubykat/ikiplugins.git diff --git a/doc/plugins/contrib/ymlfront/discussion.mdwn b/doc/plugins/contrib/ymlfront/discussion.mdwn new file mode 100644 index 000000000..b122294bb --- /dev/null +++ b/doc/plugins/contrib/ymlfront/discussion.mdwn @@ -0,0 +1,31 @@ +Now that I have implemented a \[[!ymlfront ...]] directive, I would like to remove support for the old "---" delimited format, because + +* it is fragile (easily breakable) +* 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 diff --git a/doc/plugins/creole/discussion.mdwn b/doc/plugins/creole/discussion.mdwn index 38ee2bd78..7f47c2c97 100644 --- a/doc/plugins/creole/discussion.mdwn +++ b/doc/plugins/creole/discussion.mdwn @@ -12,4 +12,11 @@ I've installed Text::WikiCreole 0.05 and enabled the plugin, but I get an error >>> forgot, done now --[[Joey]] +--- +## External Links + I'm moving over a really stinkingly old UseMod and creole seems the nearest match. I've worked out that Bare /Subpage links need to become \[\[Subpage\]\], and Top/Sub links need to be \[\[Top/Sub\]\] (or \[\[Top/Sub|Top/Sub\]\], to display in exactly the same way), but I'm stuck on generic hyperlinks. The creole cheat sheet says I should be able to do \[\[http://url.path/foo|LinkText\]\], but that comes out as a link to create the "linktext" page, and Markdown-style \[Link Text\](http://url.path/foo) just gets rendered as is. Any suggestions? --[[schmonz]] + +> Was this problem ever solved? -- Thiana + +>> Not by me. If I were looking at the problem now, with fresh eyes, I'd probably bite the bullet and just convert everything to Markdown. --[[schmonz]] diff --git a/doc/plugins/cutpaste.mdwn b/doc/plugins/cutpaste.mdwn index f74f8a269..ea3665c44 100644 --- a/doc/plugins/cutpaste.mdwn +++ b/doc/plugins/cutpaste.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=cutpaste author="[[Enrico]]"]] -[[!tag type/chrome]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/cut]], [[ikiwiki/directive/copy]] and [[ikiwiki/directive/paste]] diff --git a/doc/plugins/date.mdwn b/doc/plugins/date.mdwn new file mode 100644 index 000000000..2a33f014c --- /dev/null +++ b/doc/plugins/date.mdwn @@ -0,0 +1,6 @@ +[[!template id=plugin name=date author="[[Joey]]"]] +[[!tag type/widget]] + +This plugin provides the [[ikiwiki/directive/date]] +[[ikiwiki/directive]], which provides a way to display an arbitrary date +in a page. diff --git a/doc/plugins/ddate.mdwn b/doc/plugins/ddate.mdwn index 741606a6e..17bb16cff 100644 --- a/doc/plugins/ddate.mdwn +++ b/doc/plugins/ddate.mdwn @@ -1,6 +1,7 @@ [[!template id=plugin name=ddate author="[[Joey]]"]] [[!tag type/fun]] [[!tag type/date]] +[[!tag type/chrome]] Enables use of Discordian dates. `--timeformat` can be used to change the date format; see `ddate(1)`. diff --git a/doc/plugins/discussion.mdwn b/doc/plugins/discussion.mdwn index 854307a98..d47fa4718 100644 --- a/doc/plugins/discussion.mdwn +++ b/doc/plugins/discussion.mdwn @@ -34,3 +34,9 @@ Any objections to listing plugins alphabetically rather than by creation date? >> "recently changed" list with the 10 most recently changed plugins >> at the top. That would allow what you suggested, but still allow >> the main list to be alphabetical. -- [[Will]] + +### `themes.pm` instead of `themes.mdwn` + +Could someone please change the filename. I cannot fix this using the Web interface. Somebody step in please. --[[PaulePanter]] + +> Oops, not the first time I've made that mistake! --[[Joey]] diff --git a/doc/plugins/editpage.mdwn b/doc/plugins/editpage.mdwn index b830e51aa..346ee7c78 100644 --- a/doc/plugins/editpage.mdwn +++ b/doc/plugins/editpage.mdwn @@ -1,4 +1,5 @@ [[!template id=plugin name=editpage core=1 author="[[Joey]]"]] +[[!tag type/web]] This plugin allows editing wiki pages in the web interface. It's enabled by default if [[cgi]] is enabled; disable it if you want cgi for other things diff --git a/doc/plugins/edittemplate.mdwn b/doc/plugins/edittemplate.mdwn index 85dfdfc2d..c19ecd858 100644 --- a/doc/plugins/edittemplate.mdwn +++ b/doc/plugins/edittemplate.mdwn @@ -2,5 +2,5 @@ [[!tag type/web]] This plugin provides the [[ikiwiki/directive/edittemplate]] [[ikiwiki/directive]]. -This directive allows registering template pages, that provide default -content for new pages created using the web frontend. +This directive allows registering [[template|templates]] pages, that +provide default content for new pages created using the web frontend. diff --git a/doc/plugins/filecheck.mdwn b/doc/plugins/filecheck.mdwn index f4563d58e..b038bc433 100644 --- a/doc/plugins/filecheck.mdwn +++ b/doc/plugins/filecheck.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=filecheck core=0 author="[[Joey]]"]] -[[!tag type/useful]] +[[!tag type/special-purpose]] This plugin enhances the regular [[ikiwiki/PageSpec]] syntax with some additional tests, for things like file size, mime type, and virus @@ -7,7 +7,8 @@ status. These tests are mostly useful for the [[attachment]] plugin, and are documented [[here|ikiwiki/pagespec/attachment]]. This plugin will use the [[!cpan File::MimeInfo::Magic]] perl module, if -available, for mimetype checking. +available, for mimetype checking. It falls back to using the `file` command +if necessary for hard to detect files. The `virusfree` [[PageSpec|ikiwiki/pagespec/attachment]] requires that ikiwiki be configured with a virus scanner program via the `virus_checker` diff --git a/doc/plugins/filecheck/discussion.mdwn b/doc/plugins/filecheck/discussion.mdwn index f91950b7d..f3f3c4ffd 100644 --- a/doc/plugins/filecheck/discussion.mdwn +++ b/doc/plugins/filecheck/discussion.mdwn @@ -15,3 +15,71 @@ if ::magic() returns undef? --[[DavidBremner]] >> for ::default >>> Applied + +--- + +At first I need to thank you for ikiwiki - it is what I was always looking +for - coming from a whole bunch of wiki engines, this is the most +intelligent and least bloated one. + +My question is about the [[plugins/attachment]] plugin in conjunction with +[[plugins/filecheck]]: I am using soundmanger2 js-library for having +attached media files of all sorts played inline a page. + +To achieve this soundmanager2 asks for an id inside a ul-tag surrounding +the a-tag. I was wondering if the Insert Link button could be provided with +a more elegant solution than to have this code snippet to be filled in by +hand every time you use it to insert links for attached media files. And in +fact there apparently is a way in attachment.pm. + +While I can see that it is not needed for everyone inserting links to +attached media files to have ul- and li-tags surrounding the link itself as +well as being supplied with an id fill in, for me it would be the most +straight forward solution. Pitty is I don't have the time to wrap my head +around perl to write a patch myself. Is there any way to have this made an +option which can be called via templates? + +For sure I would like to donate for such a patch as well as I will do it +for ikiwiki anyway, because it is such a fine application. + +If you are not familiar with soundmanager2: It is a very straight forward +solution to inline mediafiles, using the usual flash as well as html5 +solutions (used by soundcloud.com, freesound.org and the like). Worth a +look anyway [schillmania.com](http://www.schillmania.com/) + +Boris + +> The behavior of "Insert Links" is currently hardcoded to support images +> and has a fallback for other files. What you want is a +> [[todo/generic_insert_links]] that can insert a template directive. +> Then you could make a template that generates the html needed for +> soundmanager2. I've written down a design at +> [[todo/generic_insert_links]]; I am currently very busy and not sure +> when I will get around to writing it, but with it on the todo list +> I shouldn't forget. --[[Joey]] +> +> You could make a [[ikiwiki/directive/template]] for soundmanager2 +> now, and manually insert the template directive for now +> when you want to embed a sound file. Something like this: + + \[[!template id=embed_mp3 file=your.mp3]] + +> Then in templates/embed_mp3.mdwn, something vaguely like this: + + <ul id="foo"> + <a href="<TMPL_VAR FILE>">mp3</a> + </ul> + +>> Thanks a lot - looking forward to [[todo/generic_insert_links]] - I am using the [[ikiwiki/directive/template]] variant also adding a name vaiable, it looks like this and is working fine: + + <ul class="playlist"> + <li> + <a href="<TMPL_VAR FILE>"><TMPL_VAR NAME></a> + </li> + </ul> + +>> Calling it: + + \[[!template id=embedmedia.tmpl file=../Tinas_Gonna_Have_A_Baby.mp3 name="Tina's Gonna Have A Baby" ]] + +>> BTW your Flattr button doesn't seem to work properly - or it is Flattr itself that doesn't- clicking it won't let ikiwiki show up on my Dashboard. diff --git a/doc/plugins/flattr.mdwn b/doc/plugins/flattr.mdwn new file mode 100644 index 000000000..5da279518 --- /dev/null +++ b/doc/plugins/flattr.mdwn @@ -0,0 +1,9 @@ +[[!template id=plugin name=flattr author="[[Joey]]"]] +[[!tag type/web]] + +[Flattr](http://flattr.com/) is a social micropayment platform. +This plugin allows easily adding Flattr buttons to pages, +using the [[ikiwiki/directive/flattr]] directive. + +This plugin has a configuration setting. `flattr_userid` can be set +to either your numeric flatter userid, or your flattr username. diff --git a/doc/plugins/format.mdwn b/doc/plugins/format.mdwn index 91e707fcf..b41d365aa 100644 --- a/doc/plugins/format.mdwn +++ b/doc/plugins/format.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=format core=0 author="[[Joey]]"]] -[[!tag type/format]] +[[!tag type/widget]] This plugin allows mixing different page formats together, by embedding text formatted one way inside a page formatted another way. This is done diff --git a/doc/plugins/fortune.mdwn b/doc/plugins/fortune.mdwn index 9966f456d..3cb125ac1 100644 --- a/doc/plugins/fortune.mdwn +++ b/doc/plugins/fortune.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=fortune author="[[Joey]]"]] [[!tag type/fun]] +[[!tag type/widget]] This plugin implements the [[ikiwiki/directive/fortune]] [[ikiwiki/directive]]. This directive uses the `fortune` program to insert a fortune into the page. diff --git a/doc/plugins/getsource.mdwn b/doc/plugins/getsource.mdwn index 20040ccee..d5404a628 100644 --- a/doc/plugins/getsource.mdwn +++ b/doc/plugins/getsource.mdwn @@ -1,4 +1,5 @@ [[!template id=plugin name=getsource author="[[Will_Uther|Will]]"]] +[[!tag type/web]] This plugin adds a "Source" link to the top of each page that uses the CGI to display the page's source. diff --git a/doc/plugins/getsource/discussion.mdwn b/doc/plugins/getsource/discussion.mdwn new file mode 100644 index 000000000..3e985948b --- /dev/null +++ b/doc/plugins/getsource/discussion.mdwn @@ -0,0 +1,3 @@ +It would be very cool if this plugin was enabled by default. One of the best ways to learn how to do various advanced things is to be able to "view source" on other wiki's which do things you like. -- [[AdamShand]] + +This plugin requires the cgi plugin. If you run a static site, you may check the [[repolist]] plugin. -- [[weakish]] diff --git a/doc/plugins/goodstuff/discussion.mdwn b/doc/plugins/goodstuff/discussion.mdwn new file mode 100644 index 000000000..4ccea4ad4 --- /dev/null +++ b/doc/plugins/goodstuff/discussion.mdwn @@ -0,0 +1,8 @@ +### What is the syntax for enabling plugins in the setup file? + +Here is an example snippet from a working setup file: + + <pre> + # plugins to add to the default configuration + add_plugins => ['goodstuff'], +</pre> diff --git a/doc/plugins/google.mdwn b/doc/plugins/google.mdwn index 7c61e637b..349c278ee 100644 --- a/doc/plugins/google.mdwn +++ b/doc/plugins/google.mdwn @@ -5,8 +5,7 @@ This plugin adds a search form to the wiki, using google's site search. Google is asked to search for pages in the domain specified in the wiki's `url` configuration parameter. Results will depend on whether google has -indexed the site, and how recently. Also, if the same domain has other -content, outside the wiki's content, it will be searched as well. +indexed the site, and how recently. The [[search]] plugin offers full text search of only the wiki, but requires that a search engine be installed on your site. diff --git a/doc/plugins/google/discussion.mdwn b/doc/plugins/google/discussion.mdwn index babc919d2..e664f5723 100644 --- a/doc/plugins/google/discussion.mdwn +++ b/doc/plugins/google/discussion.mdwn @@ -4,3 +4,22 @@ This is not very good since the default ikiwiki templates produce XHTML instead of HTML. > Fixed, thanks for the patch! --[[Joey]] + +It works to pass the whole wiki baseurl to Google, not just the +domain, and appears to be legal. I've got a wiki that'd benefit +(it's a few directories down from the root). Can the plugin be +tweaked to do this? --[[schmonz]] + +> Done. --[[Joey]] + +The main page said: + +> Also, if the same domain has other content, outside the wiki's +> content, it will be searched as well. + +Is it still true now? (Or this statement is out of date?) --[weakish] + +[weakish]: http://weakish.pigro.net + +> I checked, and it's never been true; google is given the url to the top +> of the wiki and only searches things in there. --[[Joey]] diff --git a/doc/plugins/goto.mdwn b/doc/plugins/goto.mdwn index 9c401c5d2..8e1de7a10 100644 --- a/doc/plugins/goto.mdwn +++ b/doc/plugins/goto.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=goto author="[[Simon_McVittie|smcv]]"]] -[[!tag type/useful]] +[[!tag type/web]] This plugin adds a `do=goto` mode for the IkiWiki CGI script. It's mainly for internal use by the [[404]], [[comments]] and [[recentchanges]] diff --git a/doc/plugins/graphviz.mdwn b/doc/plugins/graphviz.mdwn index b89f16b59..d57d7dc94 100644 --- a/doc/plugins/graphviz.mdwn +++ b/doc/plugins/graphviz.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=graphviz author="[[JoshTriplett]]"]] -[[!tag type/chrome type/format]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/graph]] [[ikiwiki/directive]]. This directive allows embedding [graphviz](http://www.graphviz.org/) graphs in a @@ -22,4 +22,4 @@ Some example graphs: [[!graph src="a -- b -- c -- a;" prog="circo" type="graph"]] """]] -This plugin uses the [[!cpan Digest::SHA1]] perl module. +This plugin uses the [[!cpan Digest::SHA]] perl module. diff --git a/doc/plugins/haiku.mdwn b/doc/plugins/haiku.mdwn index 74eac1c29..448733d95 100644 --- a/doc/plugins/haiku.mdwn +++ b/doc/plugins/haiku.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=haiku author="[[Joey]]"]] [[!tag type/fun]] +[[!tag type/widget]] This plugin provides a [[ikiwiki/directive/haiku]] [[ikiwiki/directive]]. The directive allows inserting a randomly generated haiku into a wiki page. diff --git a/doc/plugins/htmlscrubber.mdwn b/doc/plugins/htmlscrubber.mdwn index c59b46e14..080575c46 100644 --- a/doc/plugins/htmlscrubber.mdwn +++ b/doc/plugins/htmlscrubber.mdwn @@ -32,10 +32,11 @@ other HTML-related functionality, such as whether [[meta]] allows potentially unsafe HTML tags. The `htmlscrubber_skip` configuration setting can be used to skip scrubbing -of some pages. Set it to a [[ikiwiki/PageSpec]], such as "!*/Discussion", -and pages matching that can have all the evil CSS, JavsScript, and unsafe -html elements you like. One safe way to use this is to use [[lockedit]] to -lock those pages, so only admins can edit them. +of some pages. Set it to a [[ikiwiki/PageSpec]], such as +"posts/* and !comment(*) and !*/Discussion", and pages matching that can have +all the evil CSS, JavsScript, and unsafe html elements you like. One safe +way to use this is to use [[lockedit]] to lock those pages, so only admins +can edit them. ---- diff --git a/doc/plugins/httpauth.mdwn b/doc/plugins/httpauth.mdwn index 11ed223e7..0eda5554f 100644 --- a/doc/plugins/httpauth.mdwn +++ b/doc/plugins/httpauth.mdwn @@ -2,8 +2,34 @@ [[!tag type/auth]] This plugin allows HTTP basic authentication to be used to log into the -wiki. To use the plugin, your web server should be set up to perform HTTP -basic authentiation for at least the directory containing `ikiwiki.cgi`. -The authenticated user will be automatically signed into the wiki. +wiki. -This plugin is included in ikiwiki, but is not enabled by default. +## fully authenticated wiki + +One way to use the plugin is to configure your web server to require +HTTP basic authentication for any access to the directory containing the +wiki (and `ikiwiki.cgi`). The authenticated user will be automatically +signed into the wiki. This method is suitable only for private wikis. + +## separate cgiauthurl + +To use httpauth for a wiki where the content is public, and where +the `ikiwiki.cgi` needs to be usable without authentication (for searching, +or logging in using other methods, and so on), you can configure a separate +url that is used for authentication, via the `cgiauthurl` option in the setup +file. This url will then be redirected to when a user chooses to log in using +httpauth. + +A typical setup is to make an `auth` subdirectory, and symlink `ikiwiki.cgi` +into it. Then configure the web server to require authentication only for +access to the `auth` subdirectory. Then `cgiauthurl` is pointed at this +symlink. + +## using only httpauth for some pages + +If you want to only use httpauth for editing some pages, while allowing +other authentication methods to be used for other pages, you can +configure `httpauth_pagespec` in the setup file. This makes Edit +links on pages that match the [[ikiwiki/PageSpec]] automatically use +the `cgiauthurl`, and prevents matching pages from being edited by +users authentication via other methods. diff --git a/doc/plugins/img.mdwn b/doc/plugins/img.mdwn index 114438765..a6cd90f28 100644 --- a/doc/plugins/img.mdwn +++ b/doc/plugins/img.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=img author="Christian Mock"]] -[[!tag type/chrome]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/img]] [[ikiwiki/directive]]. While ikiwiki supports inlining full-size images by making a diff --git a/doc/plugins/inline.mdwn b/doc/plugins/inline.mdwn index 6c3282576..3eb849fdb 100644 --- a/doc/plugins/inline.mdwn +++ b/doc/plugins/inline.mdwn @@ -1,4 +1,5 @@ [[!template id=plugin name=inline core=1 author="[[Joey]]"]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/inline]] [[ikiwiki/directive]], which allows including one wiki page diff --git a/doc/plugins/link.mdwn b/doc/plugins/link.mdwn index 6adbf3eae..7dfa50de4 100644 --- a/doc/plugins/link.mdwn +++ b/doc/plugins/link.mdwn @@ -1,4 +1,5 @@ [[!template id=plugin name=link core=1 author="[[Joey]]"]] [[!tag type/link]] -This plugin implements standard [[WikiLinks|ikiwiki/wikilink]]. +This plugin implements standard [[WikiLinks|ikiwiki/wikilink]] and links to +external pages. diff --git a/doc/plugins/linkmap.mdwn b/doc/plugins/linkmap.mdwn index 89cb9d8ae..7e51cd935 100644 --- a/doc/plugins/linkmap.mdwn +++ b/doc/plugins/linkmap.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=linkmap author="[[Joey]]"]] [[!tag type/meta]] +[[!tag type/widget]] [[!tag type/slow]] This plugin provides the [[ikiwiki/directive/linkmap]] [[ikiwiki/directive]]. diff --git a/doc/plugins/listdirectives.mdwn b/doc/plugins/listdirectives.mdwn index 2d9bce01d..df854de52 100644 --- a/doc/plugins/listdirectives.mdwn +++ b/doc/plugins/listdirectives.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=listdirectives author="Will"]] [[!tag type/meta]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/listdirectives]] [[ikiwiki/directive]], which inserts a list of currently available diff --git a/doc/plugins/localstyle.mdwn b/doc/plugins/localstyle.mdwn new file mode 100644 index 000000000..70a909d68 --- /dev/null +++ b/doc/plugins/localstyle.mdwn @@ -0,0 +1,12 @@ +[[!template id=plugin name=localstyle author="[[Joey]]"]] +[[!tag type/chrome]] + +This plugin allows styling different sections of a wiki using different +versions of the local.css [[CSS]] file. Normally this file is read from the +top level of the wiki, but with this plugin enabled, standard +[[ikiwiki/subpage/LinkingRules]] are used to find the closest local.css +file to each page. + +So, for example, to use different styling for page `foo`, as well as all +of its [[SubPages|ikiwiki/subpage]], such as `foo/bar`, create a +`foo/local.css`. diff --git a/doc/plugins/lockedit.mdwn b/doc/plugins/lockedit.mdwn index c8f64ea47..681163203 100644 --- a/doc/plugins/lockedit.mdwn +++ b/doc/plugins/lockedit.mdwn @@ -12,14 +12,9 @@ to lock. For example, you could choose to lock all pages created before 2006, or all pages that are linked to from the page named "locked". More usually though, you'll just list some names of pages to lock. -One handy thing to do if you're using ikiwiki for your blog is to lock -"* and !*/Discussion". This prevents others from adding to or modifying -posts in your blog, while still letting them comment via the Discussion -pages. - -Alternatively, if you're using the [[comments]] plugin, you can lock -"!postcomment(*)" to allow users to comment on pages, but not edit anything -else. +If you want to lock down a blog so only you can post to it, you can just +lock "*", and enable the [[opendiscussion]] plugin, so readers can still post +[[comments]]. Wiki administrators can always edit locked pages. The [[ikiwiki/PageSpec]] can specify that some pages are not locked for some users. For example, diff --git a/doc/plugins/lockedit/discussion.mdwn b/doc/plugins/lockedit/discussion.mdwn index b058b2b07..867fc6a51 100644 --- a/doc/plugins/lockedit/discussion.mdwn +++ b/doc/plugins/lockedit/discussion.mdwn @@ -1,21 +1,18 @@ -This plugin not only locks pages but ensures too a user is logged in. This seems to me redundant with signedit. I propose : +This plugin not only locks pages but ensures too a user is logged in. This +seems to me redundant with signedit. I propose [removing the if block that +calls needsignin ]. - sub canedit ($$) { - my $page=shift; - my $cgi=shift; - my $session=shift; - - my $user=$session->param("name"); - return undef if defined $user && IkiWiki::is_admin($user); - - if (defined $config{locked_pages} && length $config{locked_pages} && - pagespec_match($page, $config{locked_pages}, - user => $session->param("name"), - ip => $ENV{REMOTE_ADDR}, - )) { - return sprintf(gettext("%s is locked and cannot be edited"), - htmllink("", "", $page, noimageinline => 1)); - } - - return undef; - } +> That was added because the most typical reason for being unable to edit a +> page is that you are not logged in. And without the jump to logging the +> user in, there is no way for the user to log in, without navigating away +> from the page they were trying to edit. --[[Joey]] + +>> Ok, but the problem is that when you don't want any signin form you end up +>> with a lone login button. That might happend if you lock pages only on IP +>> adresses, if you use another cookie from another webapp... + +>> That happends to me and I had to reimplement lockedit in my private auth +>> plugin. + +>> Perhaps you could return undef on that case and let another plugin do the +>> needsignin call ? -- [[Jogo]] diff --git a/doc/plugins/map.mdwn b/doc/plugins/map.mdwn index 8f5a9f15e..b164d5ca8 100644 --- a/doc/plugins/map.mdwn +++ b/doc/plugins/map.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=map author="Alessandro Dotti Contra"]] -[[!tag type/meta]] +[[!tag type/meta type/widget]] This plugin provides the [[ikiwiki/directive/map]] [[ikiwiki/directive]], which generates a hierarchical page map for the wiki. diff --git a/doc/plugins/map/discussion.mdwn b/doc/plugins/map/discussion.mdwn index 2f7b140d6..54c921b0f 100644 --- a/doc/plugins/map/discussion.mdwn +++ b/doc/plugins/map/discussion.mdwn @@ -1,7 +1,7 @@ I'm wanting a [[map]] (with indentation levels) showing page _titles_ instead of page 'names'. As far as I can see, this is not an option with existing plugins - I can get a list of pages using [[inline]] and -appropriate [[wikitemplates]], but that has no indentation and therefore +appropriate [[templates]], but that has no indentation and therefore doesn't show structure well. The quick way is to modify the map plugin to have a 'titles' option. The diff --git a/doc/plugins/mirrorlist.mdwn b/doc/plugins/mirrorlist.mdwn index b371e8eb7..aedc1f4a0 100644 --- a/doc/plugins/mirrorlist.mdwn +++ b/doc/plugins/mirrorlist.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=mirror author="[[Joey]]"]] -[[!tag type/special-purpose]] +[[!tag type/web]] This plugin allows adding links a list of mirrors to each page in the wiki. For each mirror, a name and an url should be specified. Pages are diff --git a/doc/plugins/moderatedcomments.mdwn b/doc/plugins/moderatedcomments.mdwn new file mode 100644 index 000000000..f9466e833 --- /dev/null +++ b/doc/plugins/moderatedcomments.mdwn @@ -0,0 +1,12 @@ +[[!template id=plugin name=moderatedcomments author="[[Joey]]"]] +[[!tag type/auth]] + +This plugin causes [[comments]] to be held for manual moderation. +Admins can access the comment moderation queue via their preferences page. + +By default, all comments made by anyone who is not an admin will be held +for moderation. The `moderate_pagespec` setting can be used to specify a +[[ikiwiki/PageSpec]] to match comments and users who should be moderated. +For example, to avoid moderating comments from logged-in users, set +`moderate_pagespec` to "`!user(*)`". Or to moderate everyone except for +admins, set it to "`!admin(*)`". diff --git a/doc/plugins/more.mdwn b/doc/plugins/more.mdwn index e9a971289..a0664e843 100644 --- a/doc/plugins/more.mdwn +++ b/doc/plugins/more.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=more author="Ben"]] -[[!tag type/format]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/more]] [[ikiwiki/directive]], which is a way to have a "more" link on a post in a blog, that leads to the diff --git a/doc/plugins/opendiscussion.mdwn b/doc/plugins/opendiscussion.mdwn index b2ba68bf7..3b5ab4858 100644 --- a/doc/plugins/opendiscussion.mdwn +++ b/doc/plugins/opendiscussion.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=opendiscussion author="[[Joey]]"]] [[!tag type/auth]] -This plugin allows editing of Discussion pages by anonymous users who have -not logged into the wiki. +This plugin allows editing of Discussion pages, and posting of comments, +even when the [[lockedit]] plugin has been configured to otherwise prevent +editing. diff --git a/doc/plugins/openid.mdwn b/doc/plugins/openid.mdwn index 91fc7cddc..f3b3abfbb 100644 --- a/doc/plugins/openid.mdwn +++ b/doc/plugins/openid.mdwn @@ -11,17 +11,22 @@ The [[!cpan LWPx::ParanoidAgent]] perl module is used if available, for added security. Finally, the [[!cpan Crypt::SSLeay]] perl module is needed to support users entering "https" OpenID urls. -This plugin has a configuration option. You can set `--openidsignup` -to the url of a third-party site where users can sign up for an OpenID. If -it's set, the signin page will link to that site. - -This plugin supports the -[myopenid.com affiliate program](http://myopenid.com/affiliate_welcome), -which can be used to help users sign up for an OpenID and log into your -site in a single, unified process. When you create the affiliate, specify a -login url like `http://example.com/ikiwiki.cgi?do=continue`. Once the -affiliate is created, set `openidsignup` to point to the affiliate's signup -url. - This plugin is enabled by default, but can be turned off if you want to only use some other form of authentication, such as [[passwordauth]]. + +## options + +These options do not normally need to be set, but can be useful in +certian setups. + +* `openid_realm` can be used to control the scope of the openid request. + It defaults to the `cgiurl` (or `openid_cgiurl` if set); only allowing + ikiwiki's [[CGI]] to authenticate. If you have multiple ikiwiki instances, + or other things using openid on the same site, you may choose to put them + all in the same realm to improve the user's openid experience. It is an + url pattern, so can be set to eg "http://*.example.com/" + +* `openid_cgiurl` can be used to cause a different than usual `cgiurl` + to be used when doing openid authentication. The `openid_cgiurl` must + point to an ikiwiki [[CGI]], and it will need to match the `openid_realm` + to work. diff --git a/doc/plugins/openid/discussion.mdwn b/doc/plugins/openid/discussion.mdwn index 39e947b82..a88da8b9d 100644 --- a/doc/plugins/openid/discussion.mdwn +++ b/doc/plugins/openid/discussion.mdwn @@ -19,3 +19,8 @@ It looks like OpenID 2.0 (the only supported by Yahoo) is not supported in ikiwi -- Ivan Z. They have more on OpenID 2.0 in [their FAQ](http://developer.yahoo.com/openid/faq.html). --Ivan Z. + +---- +I'm trying to add a way to query the data saved by the OpenID plugin from outside of ikiwiki, to see what identity the user has been authenticated as, if any. I'm thinking of designating some directories as internal pages and check the identity against a list in a mod_perl access hook. I would also write a CGI script that would return a JSON formatted reply to tell if the user is authenticated for those pages and query it with AJAX and only render links to the internal pages if the user would have access to them. That's just a couple of ideas I'm working on first, but I can imagine that there's any number of other tricks that people could implement with that sort of a thing. + +Also, this isn't really specific to OpenID but to all auth plugins, but I'm going to use only OpenID for authentication so that's what I'm targeting right now. I suppose that would be worth its own TODO item. --[[kaol]] diff --git a/doc/plugins/orphans.mdwn b/doc/plugins/orphans.mdwn index e403c2d18..09ad0a51d 100644 --- a/doc/plugins/orphans.mdwn +++ b/doc/plugins/orphans.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=orphans author="[[Joey]]"]] [[!tag type/meta]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/orphans]] [[ikiwiki/directive]], which generates a list of possibly orphaned pages -- diff --git a/doc/plugins/pagecount.mdwn b/doc/plugins/pagecount.mdwn index a56027e60..71872fae8 100644 --- a/doc/plugins/pagecount.mdwn +++ b/doc/plugins/pagecount.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=pagecount author="[[Joey]]"]] [[!tag type/meta]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/pagecount]] [[ikiwiki/directive]], which displays the number of pages diff --git a/doc/plugins/pagestats.mdwn b/doc/plugins/pagestats.mdwn index c3eba6363..347e39a89 100644 --- a/doc/plugins/pagestats.mdwn +++ b/doc/plugins/pagestats.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=pagestats author="Enrico Zini"]] -[[!tag type/meta type/tags]] +[[!tag type/meta type/tags type/widget]] This plugin provides the [[ikiwiki/directive/pagestats]] [[ikiwiki/directive]], which can generate stats about how pages link to diff --git a/doc/plugins/pagetemplate.mdwn b/doc/plugins/pagetemplate.mdwn index 53f069d0d..8254e14c5 100644 --- a/doc/plugins/pagetemplate.mdwn +++ b/doc/plugins/pagetemplate.mdwn @@ -3,8 +3,4 @@ This plugin provides the [[ikiwiki/directive/pagetemplate]] [[ikiwiki/directive]], which allows a page to be displayed -using a different [[template|wikitemplates]] than the default. - -This plugin can only use templates that are already installed in -`/usr/share/ikiwiki/templates` (or wherever ikiwiki is configured to look for -them). You can choose to use any .tmpl files in that directory. +using a different [[template|templates]] than the default. diff --git a/doc/plugins/parentlinks.mdwn b/doc/plugins/parentlinks.mdwn index ef262a30c..c2d364bef 100644 --- a/doc/plugins/parentlinks.mdwn +++ b/doc/plugins/parentlinks.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=parentlinks core=1 author="[[intrigeri]]"]] -[[!tag type/link]] +[[!tag type/link type/chrome]] This plugin generates the links to a page's parents that typically appear at the top of a wiki page. diff --git a/doc/plugins/po.mdwn b/doc/plugins/po.mdwn index f3b70b5f7..f91e44ea3 100644 --- a/doc/plugins/po.mdwn +++ b/doc/plugins/po.mdwn @@ -49,15 +49,15 @@ Supported languages `po_master_language` is used to set the "master" language in `ikiwiki.setup`, such as: - po_master_language => { 'code' => 'en', 'name' => 'English' } + po_master_language => 'en|English' `po_slave_languages` is used to set the list of supported "slave" languages, such as: - po_slave_languages => { 'fr' => 'Français', - 'es' => 'Español', - 'de' => 'Deutsch', - } + po_slave_languages => [ 'fr|Français', + 'es|Español', + 'de|Deutsch', + ] Decide which pages are translatable ----------------------------------- @@ -117,23 +117,25 @@ serve any page in the client's preferred language, if available. Add 'Options MultiViews' to the wiki directory's configuration in Apache. -When `usedirs` is enabled, one has to set `DirectoryIndex index` for -the wiki context. +When `usedirs` is enabled, you should also set `DirectoryIndex index`. -Setting `DefaultLanguage LL` (replace `LL` with your default MIME -language code) for the wiki context can help to ensure -`bla/page/index.en.html` is served as `Content-Language: LL`. +These settings are also recommended, in order to avoid serving up rss files +as index pages: + + AddType application/rss+xml;qs=0.8 .rss + AddType application/atom+xml;qs=0.8 .atom For details, see [Apache's documentation](http://httpd.apache.org/docs/2.2/content-negotiation.html). lighttpd -------- -lighttpd unfortunately does not support content negotiation. +Recent versions of lighttpd should be able to use +`$HTTP["language"]` to configure the translated pages to be served. -**FIXME**: does `mod_magnet` provide the functionality needed to - emulate this? +See [Lighttpd Issue](http://redmine.lighttpd.net/issues/show/1119) +TODO: Example Usage ===== @@ -197,7 +199,7 @@ enabled, "slave" pages therefore link to the "master" page's discussion page. Likewise, "slave" pages are not supposed to have sub-pages; -[[WikiLinks|wikilink]] that appear on a "slave" page therefore link to +[[WikiLinks|ikiwiki/wikilink]] that appear on a "slave" page therefore link to the master page's sub-pages. Translating @@ -212,16 +214,16 @@ preferred `$EDITOR`, without needing to be online. Markup languages support ------------------------ -[[Markdown|mdwn]] is well supported. Some other markup languages supported -by ikiwiki mostly work, but some pieces of syntax are not rendered -correctly on the slave pages: +[[Markdown|mdwn]] and [[html]] are well supported. Some other markup +languages supported by ikiwiki mostly work, but some pieces of syntax +are not rendered correctly on the slave pages: * [[reStructuredText|rst]]: anonymous hyperlinks and internal cross-references * [[wikitext]]: conversion of newlines to paragraphs * [[creole]]: verbatim text is wrapped, tables are broken -* [[html]] and LaTeX: not supported yet; the dedicated po4a modules - could be used to support them, but they would need a security audit +* LaTeX: not supported yet; the dedicated po4a module + could be used to support it, but it would need a security audit * other markup languages have not been tested. Security @@ -234,95 +236,14 @@ When using po4a older than 0.35, it is recommended to uninstall `Text::WrapI18N` (Debian package `libtext-wrapi18n-perl`), in order to avoid a potential denial of service. -TODO +BUGS ==== -Better links ------------- - -Once the fix to -[[bugs/pagetitle_function_does_not_respect_meta_titles]] from -[[intrigeri]]'s `meta` branch is merged into ikiwiki upstream, the -generated links' text will be optionally based on the page titles set -with the [[meta|plugins/meta]] plugin, and will thus be translatable. -It will also allow displaying the translation status in links to slave -pages. Both were implemented, and reverted in commit -ea753782b222bf4ba2fb4683b6363afdd9055b64, which should be reverted -once [[intrigeri]]'s `meta` branch is merged. - -An integration branch, called `meta-po`, merges [[intrigeri]]'s `po` -and `meta` branches, and thus has this additional features. - -Language display order ----------------------- - -Jonas pointed out that one might want to control the order that links to -other languages are listed, for various reasons. Currently, there is no -order, as `po_slave_languages` is a hash. It would need to be converted -to an array to support this. (If twere done, twere best done quickly.) ---[[Joey]] - -Pagespecs ---------- - -I was suprised that, when using the map directive, a pagespec of "*" -listed all the translated pages as well as regular pages. That can -make a big difference to an existing wiki when po is turned on, -and seems generally not wanted. -(OTOH, you do want to match translated pages by -default when locking pages.) --[[Joey]] - -Edit links on untranslated pages --------------------------------- - -If a page is not translated yet, the "translated" version of it -displays wikilinks to other, existing (but not yet translated?) -pages as edit links, as if those pages do not exist. - -That's really confusing, especially as clicking such a link -brings up an edit form to create a new, english page. - -This is with po_link_to=current or negotiated. With default, it doesn't -happen.. - -Also, this may only happen if the page being linked to is coming from an -underlay, and the underlays lack translation to a given language. ---[[Joey]] +[[!inline pages="bugs/po:* and !bugs/done and !link(bugs/done) and !bugs/*/*" +feeds=no actions=no archive=yes show=0]] -Double commits of po files --------------------------- - -When adding a new english page, the po files are created, committed, -and then committed again. The second commit makes this change: - - -"Content-Type: text/plain; charset=utf-8\n" - -"Content-Transfer-Encoding: ENCODING" - +"Content-Type: text/plain; charset=UTF-8\n" - +"Content-Transfer-Encoding: ENCODING\n" - -Same thing happens when a change to an existing page triggers a po file -update. --[[Joey]] - -Ugly messages with empty files ------------------------------- - -If there are empty .mdwn files, the po plugin displays some ugly messages. - -Translation of directives -------------------------- - -If a translated page contains a directive, it may expand to some english -text, or text in whatever single language ikiwiki is configured to "speak". - -Maybe there could be a way to switch ikiwiki to speaking another language -when building a non-english page? Then the directives would get translated. - -(We also will need this in order to use translated templates, when they are -available.) - -Documentation -------------- +TODO +==== -Maybe write separate documentation depending on the people it targets: -translators, wiki administrators, hackers. This plugin may be complex -enough to deserve this. +[[!inline pages="todo/po:* and !todo/done and !link(todo/done) and !todo/*/*" +feeds=no actions=no archive=yes show=0]] diff --git a/doc/plugins/po/discussion.mdwn b/doc/plugins/po/discussion.mdwn index ab822e76c..50998e822 100644 --- a/doc/plugins/po/discussion.mdwn +++ b/doc/plugins/po/discussion.mdwn @@ -150,6 +150,23 @@ The following analysis was done with his help. variables; according to [[Joey]], this is "Freaky code, but seems ok due to use of `quotementa`". +##### Locale::Po4a::Xhtml + +* does not run any external program +* does not build regexp's from untrusted variables + +=> Seems safe as far as the `includessi` option is disabled; the po +plugin explicitly disables it. + +Relies on Locale::Po4a::Xml` to do most of the work. + +##### Locale::Po4a::Xml + +* does not run any external program +* the `includeexternal` option makes it able to read external files; + the po plugin explicitly disables it +* untrusted variables are escaped when used to build regexp's + ##### Text::WrapI18N `Text::WrapI18N` can cause DoS @@ -513,7 +530,7 @@ finish it at some point in the first quarter of 2009. --[[intrigeri]] >>>> >>>>> Done. --[[intrigeri]] >>> -> * I'm very fearful of the `add_depends` in `postscan`. +> * I'm very fearful of the `add_depends` in `indexhtml`. > Does this make every page depend on every page that links > to it? Won't this absurdly bloat the dependency pagespecs > and slow everything down? And since nicepagetitle is given @@ -627,28 +644,6 @@ daring a timid "please pull"... or rather, please review again :) >>> need improvements to the deletion UI to de-confuse that. It's fine to >>> put that off until needed --[[Joey]] >> -> * Re the meta title escaping issue worked around by `change`. -> I suppose this does not only affect meta, but other things -> at scan time too. Also, handling it only on rebuild feels -> suspicious -- a refresh could involve changes to multiple -> pages and trigger the same problem, I think. Also, exposing -> this rebuild to the user seems really ugly, not confidence inducing. -> -> So I wonder if there's a better way. Such as making po, at scan time, -> re-run the scan hooks, passing them modified content (either converted -> from po to mdwn or with the escaped stuff cheaply de-escaped). (Of -> course the scan hook would need to avoid calling itself!) -> -> (This doesn't need to block the merge, but I hope it can be addressed -> eventually..) -> -> --[[Joey]] ->> ->> I'll think about it soon. ->> ->> --[[intrigeri]] ->> ->>> Did you get a chance to? --[[Joey]] * As discussed at [[todo/l10n]] the templates needs to be translatable too. They should be treated properly by po4a using the markdown option - at least with my diff --git a/doc/plugins/poll.mdwn b/doc/plugins/poll.mdwn index 510f67798..099cb399c 100644 --- a/doc/plugins/poll.mdwn +++ b/doc/plugins/poll.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=poll author="[[Joey]]"]] -[[!tag type/web]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/poll]] [[ikiwiki/directive]], which allows inserting an online poll into a page. diff --git a/doc/plugins/polygen.mdwn b/doc/plugins/polygen.mdwn index 6045c1ec9..f9cea1f4d 100644 --- a/doc/plugins/polygen.mdwn +++ b/doc/plugins/polygen.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=polygen author="Enrico Zini"]] [[!tag type/fun]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/polygen]] [[ikiwiki/directive]], which allows inserting text generated by polygen into a wiki page. diff --git a/doc/plugins/postsparkline.mdwn b/doc/plugins/postsparkline.mdwn index c81f91bdc..b0733e343 100644 --- a/doc/plugins/postsparkline.mdwn +++ b/doc/plugins/postsparkline.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=postsparkline author="[[Joey]]"]] -[[!tag type/chrome]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/postsparkline]] [[ikiwiki/directive]]. It uses the [[sparkline]] plugin to create a sparkline of diff --git a/doc/plugins/prettydate.mdwn b/doc/plugins/prettydate.mdwn index 11ad4252f..149b7c29c 100644 --- a/doc/plugins/prettydate.mdwn +++ b/doc/plugins/prettydate.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=prettydate author="[[Joey]]"]] [[!tag type/date]] +[[!tag type/chrome]] Enabling this plugin changes the dates displayed on pages in the wiki to a format that is nice and easy to read. Examples: "late Wednesday evening, diff --git a/doc/plugins/progress.mdwn b/doc/plugins/progress.mdwn index e1b560cc8..20736d18c 100644 --- a/doc/plugins/progress.mdwn +++ b/doc/plugins/progress.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=progress author="[[Will]]"]] -[[!tag type/meta]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/progress]] [[ikiwiki/directive]], which generates a progress bar. diff --git a/doc/plugins/rawhtml/discussion.mdwn b/doc/plugins/rawhtml/discussion.mdwn index e63e4acb9..9ed8230ba 100644 --- a/doc/plugins/rawhtml/discussion.mdwn +++ b/doc/plugins/rawhtml/discussion.mdwn @@ -2,4 +2,6 @@ Is there anyway to allow this only on locked pages? I'd like to be able to do r > Not at the moment. Long-term, ikiwiki needs some general permission mechanisms that encompass this sort of issue. --[[JoshTriplett]] ->> Thanks. Bummer though, looking forward to when this is possible. :-) -- Adam.
\ No newline at end of file +>> Thanks. Bummer though, looking forward to when this is possible. :-) -- Adam. + +> Well, this plugin is different from the [[html]] plugin. It **copies** html files. So users cannot do raw HTML via cgi. Thus it is safe in most cases. -- weakish diff --git a/doc/plugins/recentchanges.mdwn b/doc/plugins/recentchanges.mdwn index 9375296a4..6fff18e8a 100644 --- a/doc/plugins/recentchanges.mdwn +++ b/doc/plugins/recentchanges.mdwn @@ -1,10 +1,13 @@ [[!template id=plugin name=recentchanges core=1 author="[[Joey]]"]] +[[!tag type/meta]] This plugin examines the [[revision_control_system|rcs]] history and generates a page describing each recent change made to the wiki. These pages can be joined together with [[inline]] to generate the [[RecentChanges]] page. +This plugin also currently handles web-based reversion of changes. + Typically only the RecentChanges page will use the pages generated by this plugin, but you can use it elsewhere too if you like. It's used like this: diff --git a/doc/plugins/recentchangesdiff.mdwn b/doc/plugins/recentchangesdiff.mdwn index a7b113ade..57299f92d 100644 --- a/doc/plugins/recentchangesdiff.mdwn +++ b/doc/plugins/recentchangesdiff.mdwn @@ -1,4 +1,5 @@ [[!template id=plugin name=recentchangesdiff core=0 author="[[Joey]]"]] +[[!tag type/meta]] This plugin extends the [[recentchanges]] plugin, adding a diff for each change. The diffs are by default hidden from display on the recentchanges diff --git a/doc/plugins/relativedate.mdwn b/doc/plugins/relativedate.mdwn index 3ada0864b..d6e8eb08b 100644 --- a/doc/plugins/relativedate.mdwn +++ b/doc/plugins/relativedate.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=relativedate author="[[Joey]]"]] [[!tag type/date]] +[[!tag type/chrome]] This plugin lets dates be displayed in relative form. Examples: "2 days ago", "1 month and 3 days ago", "30 minutes ago". Hovering over the date will @@ -8,9 +9,3 @@ cause a tooltip to pop up with the absolute date. This only works in browsers with javascript enabled; other browsers will show the absolute date instead. Also, this plugin can be used with other plugins like [[prettydate]] that change how the absolute date is displayed. - -If this plugin is enabled, you may also add relative dates to pages in the -wiki, by using html elements in the "relativedate" class. For example, this -will display as a relative date: - - <span class="relativedate">Tue Jan 20 12:00:00 EDT 2009</span> diff --git a/doc/plugins/rename.mdwn b/doc/plugins/rename.mdwn index ddaede8b0..abb361329 100644 --- a/doc/plugins/rename.mdwn +++ b/doc/plugins/rename.mdwn @@ -2,7 +2,8 @@ [[!tag type/web]] This plugin allows pages or other files to be renamed using the web -interface. +interface. Following Unix tradition, renaming also allows moving to a +different directory. Users can only rename things that they are allowed to edit or upload. diff --git a/doc/plugins/repolist.mdwn b/doc/plugins/repolist.mdwn index 9b3a7575e..efd9c9352 100644 --- a/doc/plugins/repolist.mdwn +++ b/doc/plugins/repolist.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=repolist author="[[Joey]]"]] -[[!tag type/useful]] +[[!tag type/web]] This plugin allows you to configure ikiwiki with the location of [[rcs]] repositories for your wiki's source. This is done via the diff --git a/doc/plugins/rst/discussion.mdwn b/doc/plugins/rst/discussion.mdwn index 38fbed6d6..c84a6218e 100644 --- a/doc/plugins/rst/discussion.mdwn +++ b/doc/plugins/rst/discussion.mdwn @@ -61,8 +61,8 @@ but the backlinks don't show up. I converted one of my pages to rst: -Before: http://kaizer.se/wiki/kupfer-mdwn -After: http://kaizer.se/wiki/kupfer-rst +Before: <http://kaizer.se/wiki/kupfer-mdwn> +After: <http://kaizer.se/wiki/kupfer-rst> I need help on a couple of points @@ -71,3 +71,11 @@ I need help on a couple of points * Can we include this in ikiwiki's rst if it is not too hairy? --ulrik + + +---- + +> The main problem with more sophisticated RST support is that ikiwiki turns +preprocessor directives into raw HTML and reST hates inline HTML. + +Is it possible for ikiwiki to store preprocessor directives in memory, and replace them with place holders, then do the rst process. After the rst processing, process the preprocessor directives and replace place holders. --[[weakish]] diff --git a/doc/plugins/rsync.mdwn b/doc/plugins/rsync.mdwn index db7fcb4f7..e48886168 100644 --- a/doc/plugins/rsync.mdwn +++ b/doc/plugins/rsync.mdwn @@ -1,4 +1,5 @@ [[!template id=plugin name=rsync author="[[schmonz]]"]] +[[!tag type/special-purpose]] This plugin allows ikiwiki to push generated pages to another host by running a command such as `rsync`. @@ -7,7 +8,7 @@ The command to run is specified by setting `rsync_command` in your setup file. The command will be run in your destdir, so something like this is a typical command: - rsync => 'rsync -qa --delete . user@host:/path/to/docroot/', + rsync_command => 'rsync -qa --delete . user@host:/path/to/docroot/', If using rsync over ssh, you will need to enable noninteractive ssh login to the remote host. It's also a good idea to specify the exact command line diff --git a/doc/plugins/rsync/discussion.mdwn b/doc/plugins/rsync/discussion.mdwn index 6bf7a3826..ef0fa9967 100644 --- a/doc/plugins/rsync/discussion.mdwn +++ b/doc/plugins/rsync/discussion.mdwn @@ -47,6 +47,8 @@ The wiki now lives on (1), and clicking "edit" just works. --[[schmonz]] >> a DVCS (of which I've got at least one other), and possibly for >> other uses not yet imagined. ;-) --[[schmonz]] +>>> I'm now using this plugin for an additional purpose. One of the aforementioned wikis (there are actually two) can only be read by trusted users, the list of which is kept in an `.htaccess` file. I added it to git as `htaccess.txt`, enabled the [[plugins/txt]] plugin, and in my `rsync_command` script, have it copied to the destdir as `.htaccess` before calling `rsync`. Now my users (who aren't tech-savvy, but are trustworthy) can edit the access list directly in the wiki. This idea might also be useful for wikis not using `rsync` at all. --[[schmonz]] + ---- Revew: --[[Joey]] diff --git a/doc/plugins/search.mdwn b/doc/plugins/search.mdwn index 92cc5945a..e95739cf3 100644 --- a/doc/plugins/search.mdwn +++ b/doc/plugins/search.mdwn @@ -4,7 +4,7 @@ This plugin adds full text search to ikiwiki, using the [xapian](http://xapian.org/) engine, its [omega](http://xapian.org/docs/omega/overview.html) frontend, and the -[[!cpan Search::Xapian]], [[!cpan Digest::SHA1]], and [[!cpan HTML::Scrubber]] +[[!cpan Search::Xapian]], [[!cpan Digest::SHA]], and [[!cpan HTML::Scrubber]] perl modules. The [[ikiwiki/searching]] page describes how to write search queries. diff --git a/doc/plugins/shortcut.mdwn b/doc/plugins/shortcut.mdwn index cca1f4bdd..1e8e85ed8 100644 --- a/doc/plugins/shortcut.mdwn +++ b/doc/plugins/shortcut.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=shortcut author="[[Joey]]"]] -[[!tag type/format]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/shortcut]] [[ikiwiki/directive]]. It allows external links to commonly linked to sites to be made diff --git a/doc/plugins/shortcut/discussion.mdwn b/doc/plugins/shortcut/discussion.mdwn index 4e11ce08c..2e2b1b281 100644 --- a/doc/plugins/shortcut/discussion.mdwn +++ b/doc/plugins/shortcut/discussion.mdwn @@ -9,4 +9,10 @@ Maybe use the `default_pageext` is better than hardcode .mdwn? > done, it will use `default_pageext` now --[[Joey]] +--- +Instead of modifying the [[basewiki]]'s [[shortcuts]] file for local needs -- +thus copying it at some point and losing continuity with upstream enhancements -- +what about handling a `shortcuts-local.mdwn` or `shortcuts/local.mdwn` (if such +a file exists in the wiki), and additionally process that one. Possibily a +conditional `\[[!inline]]` could be used. --[[tschwinge]] diff --git a/doc/plugins/sidebar.mdwn b/doc/plugins/sidebar.mdwn index 4e356d65a..012733456 100644 --- a/doc/plugins/sidebar.mdwn +++ b/doc/plugins/sidebar.mdwn @@ -1,24 +1,27 @@ [[!template id=plugin name=sidebar author="Tuomo Valkonen"]] [[!tag type/chrome]] -If this plugin is enabled, then a sidebar is added to pages in the wiki. -The content of the sidebar is simply the content of a page named -"sidebar" (ie, create a "sidebar.mdwn"). +This plugin allows adding a sidebar to pages in the wiki. + +By default, and unless the `global_sidebars` setting is turned off, +a sidebar is added to all pages in the wiki. The content of the sidebar +is simply the content of a page named "sidebar" (ie, create a "sidebar.mdwn"). Typically this will be a page in the root of the wiki, but it can also be a [[ikiwiki/SubPage]]. In fact, this page, [[plugins/sidebar|plugins/sidebar]], will be treated as a sidebar for the [[plugins]] page, and of all of its SubPages, if the plugin is enabled. -Note that to disable a sidebar for a [[ikiwiki/SubPage]] of a page that has -a sidebar, you can create a sidebar page that is completely empty. This -will turn off the sidebar altogether. +There is also a [[ikiwiki/directive/sidebar]] directive that can be used +to provide a custom sidebar content for a page. + +---- -Warning: Any change to the sidebar will cause a rebuild of the whole wiki, -since every page includes a copy that has to be updated. This can -especially be a problem if the sidebar includes an [[ikiwiki/directive/inline]] -directive, since any changes to pages inlined into the sidebar -will change the sidebar and cause a full wiki rebuild. +Warning: Any change to the sidebar page will cause a rebuild of the whole +wiki, since every page includes a copy that has to be updated. This can +especially be a problem if the sidebar includes an +[[ikiwiki/directive/inline]] directive, since any changes to pages inlined +into the sidebar will change the sidebar and cause a full wiki rebuild. Instead, if you include a [[ikiwiki/directive/map]] directive on the sidebar, and it does not use the `show` parameter, only adding or removing pages diff --git a/doc/plugins/sortnaturally.mdwn b/doc/plugins/sortnaturally.mdwn new file mode 100644 index 000000000..a16381946 --- /dev/null +++ b/doc/plugins/sortnaturally.mdwn @@ -0,0 +1,6 @@ +[[!template id=plugin name=sortnaturally core=1 author="[[chrysn]], [[smcv]]"]] +[[!tag type/meta]] + +This plugin provides the `title_natural` [[ikiwiki/pagespec/sorting]] +order, which uses [[!cpan Sort::Naturally]] to sort numbered pages in a +more natural order. diff --git a/doc/plugins/sparkline.mdwn b/doc/plugins/sparkline.mdwn index bcc5daec6..83e24a27d 100644 --- a/doc/plugins/sparkline.mdwn +++ b/doc/plugins/sparkline.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=sparkline author="[[Joey]]"]] -[[!tag type/chrome]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/sparkline]] [[ikiwiki/directive]], which allows for easily embedding sparklines into @@ -16,7 +16,7 @@ to use the plugin, you will need: php can find it when `sparkline/Sparkline.php` is required. * The GD PHP module used by the Sparkline library. * A "php" program in the path, that can run standalone php programs. -* [[!cpan Digest::SHA1]] +* [[!cpan Digest::SHA]] On a Debian system, this can be accomplished by installing these packages: `libsparkline-php` `php5-gd` `php5-cli` `libdigest-sha1-perl` diff --git a/doc/plugins/table.mdwn b/doc/plugins/table.mdwn index 7b080acda..fe66f90a8 100644 --- a/doc/plugins/table.mdwn +++ b/doc/plugins/table.mdwn @@ -1,8 +1,8 @@ [[!template id=plugin name=table author="[[VictorMoral]]"]] -[[!tag type/format]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/table]] [[ikiwiki/directive]]. It can build HTML tables from data in CSV (comma-separated values) -or DSV (delimiter-separated values) format. +or DSV ([delimiter-separated values](http://en.wikipedia.org/wiki/Delimiter-separated_values)) format. It needs the perl module [[!cpan Text::CSV]] for the CSV data. diff --git a/doc/plugins/tag.mdwn b/doc/plugins/tag.mdwn index 8ff70a069..1d6bfbdd9 100644 --- a/doc/plugins/tag.mdwn +++ b/doc/plugins/tag.mdwn @@ -8,6 +8,16 @@ These directives allow tagging pages. It also provides the `tagged()` [[ikiwiki/PageSpec]], which can be used to match pages that are tagged with a specific tag. +The `tagbase` setting can be used to make tags default to being put in a +particular subdirectory. + +The `tag_autocreate` setting can be used to control whether new tag pages +are created as needed. It defaults to being done only if a `tagbase` is +set. + +The `tag_autocreate_commit` setting is enabled by default, and causes +new tag pages to be checked into version control. + [[!if test="enabled(tag)" then=""" This wiki has the tag plugin enabled, so you'll see a note below that this page is tagged with the "tags" tag. diff --git a/doc/plugins/tag/discussion.mdwn b/doc/plugins/tag/discussion.mdwn index 03dcb7b2f..dfd749252 100644 --- a/doc/plugins/tag/discussion.mdwn +++ b/doc/plugins/tag/discussion.mdwn @@ -28,3 +28,4 @@ See [[todo/auto-create tag pages according to a template]] -- Jeremy Schultz <jeremy.schultz@uleth.ca> +`tag_autocreate` can now enable this. --[[Joey]] diff --git a/doc/plugins/template.mdwn b/doc/plugins/template.mdwn index 3485fe64c..8d17e2825 100644 --- a/doc/plugins/template.mdwn +++ b/doc/plugins/template.mdwn @@ -1,7 +1,7 @@ [[!template id=plugin name=template author="[[Joey]]"]] -[[!tag type/format]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/template]] [[ikiwiki/directive]]. With this plugin, you can set up templates, and cause them to be filled out -and inserted into pages in the wiki. It's documented and existing templates -are listed in the [[templates]] page. +and inserted into pages in the wiki. Existing templates are listed in the +[[templates]] page. diff --git a/doc/plugins/testpagespec.mdwn b/doc/plugins/testpagespec.mdwn index dabcb0bec..8180d5d4b 100644 --- a/doc/plugins/testpagespec.mdwn +++ b/doc/plugins/testpagespec.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=testpagespec author="[[Joey]]"]] -[[!tag type/useful]] +[[!tag type/special-purpose]] This plugin provides a [[ikiwiki/directive/testpagespec]] [[ikiwiki/directive]]. The directive allows testing a [[ikiwiki/PageSpec]] to see if it matches a diff --git a/doc/plugins/teximg.mdwn b/doc/plugins/teximg.mdwn index ae052837f..f3cade85f 100644 --- a/doc/plugins/teximg.mdwn +++ b/doc/plugins/teximg.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=teximg author="[[PatrickWinnertz]]"]] -[[!tag type/chrome type/slow]] +[[!tag type/widget type/slow]] This plugin provides a [[ikiwiki/directive/teximg]] [[ikiwiki/directive]], that renders LaTeX formulas into images. diff --git a/doc/plugins/theme.mdwn b/doc/plugins/theme.mdwn new file mode 100644 index 000000000..ebbb0be8e --- /dev/null +++ b/doc/plugins/theme.mdwn @@ -0,0 +1,11 @@ +[[!template id=plugin name=theme author="[[Joey]]"]] +[[!tag type/web]] + +The theme plugin allows easily applying a theme to your wiki, by +configuring the `theme` setting in the setup file with the name of a theme +to use. The themes you can choose from are all subdirectories, typically +inside `/usr/share/ikiwiki/themes/`. See [[themes]] for an overview +of the themes included in ikiwiki. + +You can set the theme via the **theme** option in your config file (after +enabling the plugin). Refresh the wiki after changing it to see the changes. diff --git a/doc/plugins/theme/discussion.mdwn b/doc/plugins/theme/discussion.mdwn new file mode 100644 index 000000000..67a2bf46a --- /dev/null +++ b/doc/plugins/theme/discussion.mdwn @@ -0,0 +1,26 @@ +### What license do themes need to have for distribution? + +Could someone specify what license the themes need to have to get +distributed in ikiwiki or Debian? The current included theme seem to be +under the GPLv2. Does the [Creative Commons Attribution 3.0 Unported +License](http://creativecommons.org/licenses/by/3.0/) also work. This way a +lot of free CSS templates could be included, e. g. from +[freecsstemplates.org](http://www.freecsstemplates.org/). --PaulePanter + +> Paule, I'd love it if you did that! The only hard requirement on themes +> included in ikiwiki is that they need to be licensed with a [DFSG +> compatable license](https://wiki.debian.org/DFSGLicenses). CC-BY-SA 3.0 +> is DFSG; CC-BY is apparently being accepted by Debian too. +> +> As a soft requirement, I may exersise some discretion about themes that +> require obtrusive attributions links be included on every page of a +> site using the theme. While probably DFSG, that adds a requirement +> that ikiwiki itself does not require. --[[Joey]] + +### Once one has enabled the 'theme' plugin in the setup file, how does one use themes? + +Choose one of the [[themes]] which are bundled with ikiwiki and configure ikiwiki to use it by setting this in your setup file, eg. + + theme => 'blueview', + +-- [[AdamShand]] diff --git a/doc/plugins/toc.mdwn b/doc/plugins/toc.mdwn index 2b7686681..a0ad3a5d0 100644 --- a/doc/plugins/toc.mdwn +++ b/doc/plugins/toc.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=toc author="[[Joey]]"]] -[[!tag type/chrome]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/toc]] [[ikiwiki/directive]], which adds a table of contents to a page. diff --git a/doc/plugins/toggle.mdwn b/doc/plugins/toggle.mdwn index 69ac613e0..d1500eba0 100644 --- a/doc/plugins/toggle.mdwn +++ b/doc/plugins/toggle.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=toggle author="[[Joey]]"]] -[[!tag type/chrome]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/toggle]] and [[ikiwiki/directive/toggleable]] [[directives|ikiwiki/directive]]. diff --git a/doc/plugins/transient.mdwn b/doc/plugins/transient.mdwn new file mode 100644 index 000000000..b7dd11906 --- /dev/null +++ b/doc/plugins/transient.mdwn @@ -0,0 +1,24 @@ +[[!template id=plugin name=transient author="[[Simon_McVittie|smcv]]" core=yes]] +[[!tag type/special-purpose]] + +The `transient` plugin adds an underlay in `.ikiwiki/transient`, which is +intended for pages that are automatically created and should not be committed +to the [[RCS]]. It works in the same way as the [[basewiki]] and the underlays +set up by the [[plugins/underlay]] plugin, so if a page in the transient +underlay is edited via the web, the edited version is committed to the RCS +as usual. Unlike other underlays, if a page in the transient underlay is +superseded by an edited version in the RCS, the old transient version +is deleted automatically. + +This plugin is mostly useful as something that other plugins can depend on: + +* [[plugins/aggregate]] writes aggregated posts into the transient underlay +* [[plugins/autoindex]] can be configured to auto-create missing + pages that have a [[ikiwiki/subpage]] or an [[plugins/attachment]], but not + commit them, in which case they go in the transient underlay +* [[plugins/comments]] can be configured to not commit comments: if so, it + puts them in the transient underlay +* [[plugins/recentchanges]] writes new changes into the transient underlay +* [[plugins/tag]] can be configured to auto-create missing + tag pages but not commit them, in which case they go in the transient + underlay diff --git a/doc/plugins/txt.mdwn b/doc/plugins/txt.mdwn index 420898d09..a3087c9e0 100644 --- a/doc/plugins/txt.mdwn +++ b/doc/plugins/txt.mdwn @@ -12,3 +12,8 @@ The only exceptions are that [[WikiLinks|ikiwiki/WikiLink]] and [[directives|ikiwiki/directive]] are still expanded by ikiwiki, and that, if the [[!cpan URI::Find]] perl module is installed, URLs in the txt file are converted to hyperlinks. + +---- + +As a special case, a file `robots.txt` will be copied intact into the +`destdir`, as well as creating a wiki page named "robots". diff --git a/doc/plugins/type/chrome.mdwn b/doc/plugins/type/chrome.mdwn index d3f0eb3d3..a1c6d0728 100644 --- a/doc/plugins/type/chrome.mdwn +++ b/doc/plugins/type/chrome.mdwn @@ -1 +1 @@ -These plugins affect the look and feel of the wiki. +These plugins affect the look and feel of the overall wiki. diff --git a/doc/plugins/type/useful.mdwn b/doc/plugins/type/useful.mdwn deleted file mode 100644 index 92fcf5af1..000000000 --- a/doc/plugins/type/useful.mdwn +++ /dev/null @@ -1 +0,0 @@ -These plugins perform various miscellaneous useful functions. diff --git a/doc/plugins/type/widget.mdwn b/doc/plugins/type/widget.mdwn new file mode 100644 index 000000000..875829d0b --- /dev/null +++ b/doc/plugins/type/widget.mdwn @@ -0,0 +1,2 @@ +These plugins allow inserting various things into pages via a +[[ikiwiki/directive]]. diff --git a/doc/plugins/typography.mdwn b/doc/plugins/typography.mdwn index 030ef8052..9ff6c4ffd 100644 --- a/doc/plugins/typography.mdwn +++ b/doc/plugins/typography.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=typography author="[[Roktas]]"]] -[[!tag type/format]] +[[!tag type/chrome]] This plugin, also known as [SmartyPants](http://daringfireball.net/projects/smartypants/), translates diff --git a/doc/plugins/underlay.mdwn b/doc/plugins/underlay.mdwn index f7eafee7c..0cf819472 100644 --- a/doc/plugins/underlay.mdwn +++ b/doc/plugins/underlay.mdwn @@ -1,20 +1,14 @@ [[!template id=plugin name=underlay author="[[Simon_McVittie|smcv]]"]] -[[!tag type/useful]] +[[!tag type/special-purpose]] -This plugin adds an `add_underlays` option to the setup file. -Its value is a list of underlay directories whose content is added to the wiki. +This plugin adds an `add_underlays` option to the setup file. Its value is +a list of underlay directories whose content is added to the wiki. Multiple underlays are normally set up automatically by other plugins (for -instance, the images used by the [[plugins/smiley]] plugin), but they can also be -used as a way to pull in external files that you don't want in revision control, -like photos or software releases. +instance, the images used by the [[plugins/smiley]] plugin), but they can +also be used as a way to pull in external files that you don't want in +revision control, like photos or software releases. -Directories in `add_underlays` should usually be absolute. If relative, they're -interpreted as relative to the parent directory of the basewiki underlay, which -is probably not particularly useful in this context. - --- - -This plugin also adds an `add_templates` option to the setup file. -Its value is a list of template directories to look for template files in, -if they are not present in the `templatedir`. +Directories in `add_underlays` should usually be absolute. If relative, +they're interpreted as relative to the parent directory of the basewiki +underlay, which is probably not particularly useful in this context. diff --git a/doc/plugins/version.mdwn b/doc/plugins/version.mdwn index 43027bdd7..326a2e7ce 100644 --- a/doc/plugins/version.mdwn +++ b/doc/plugins/version.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=version author="[[Joey]]"]] [[!tag type/meta]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/version]] [[ikiwiki/directive]], which inserts the current version diff --git a/doc/plugins/websetup.mdwn b/doc/plugins/websetup.mdwn index f1756ba8f..a20a32489 100644 --- a/doc/plugins/websetup.mdwn +++ b/doc/plugins/websetup.mdwn @@ -2,7 +2,7 @@ [[!tag type/web]] This plugin allows wiki admins to configure the wiki using a web interface, -rather than editing the setup file directly. A "Wiki Setup" button is added +rather than editing the setup file directly. A "Setup" button is added to the admins' preferences page. Warning: This plugin rewrites your setup file. Any comments or unusual @@ -16,7 +16,8 @@ enabled and disabled using it too. Some settings are not considered safe enough to be manipulated over the web; these are still shown, by default, but cannot be modified. To hide them, set `websetup_show_unsafe` to false in the setup file. A few settings have too complex a data type to be -configured via the web. +configured via the web. To mark additional settings as unsafe, you can +list them in `websetup_unsafe`. Plugins that should not be enabled/disabled via the web interface can be listed in `websetup_force_plugins` in the setup file. diff --git a/doc/plugins/wmd.mdwn b/doc/plugins/wmd.mdwn index dc9a30703..96c6e2e6c 100644 --- a/doc/plugins/wmd.mdwn +++ b/doc/plugins/wmd.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=wmd author="[[Will]]"]] -[[!tag type/chrome]] +[[!tag type/web]] [WMD](http://wmd-editor.com/) is a What You See Is What You Mean editor for [[mdwn]]. This plugin makes WMD be used for editing pages in the wiki. diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index c72418c3c..f0f79ebc7 100644 --- a/doc/plugins/write.mdwn +++ b/doc/plugins/write.mdwn @@ -1,10 +1,86 @@ -Ikiwiki's plugin interface allows all kinds of useful [[plugins]] to be +lkiwiki's plugin interface allows all kinds of useful [[plugins]] to be written to extend ikiwiki in many ways. Despite the length of this page, it's not really hard. This page is a complete reference to everything a plugin might want to do. There is also a quick [[tutorial]]. +[[!template id="note" text=""" +Ikiwiki is a compiler + +One thing to keep in mind when writing a plugin is that ikiwiki is a wiki +*compiler*. So plugins influence pages when they are built, not when they +are loaded. A plugin that inserts the current time into a page, for +example, will insert the build time. + +Also, as a compiler, ikiwiki avoids rebuilding pages unless they have +changed, so a plugin that prints some random or changing thing on a page +will generate a static page that won't change until ikiwiki rebuilds the +page for some other reason, like the page being edited. + +The [[tutorial]] has some other examples of ways that ikiwiki being a +compiler may trip up the unwary. +"""]] + [[!toc levels=2]] +## Highlevel view of ikiwiki + +Ikiwiki mostly has two modes of operation. It can either be running +as a compiler, building or updating a wiki; or as a cgi program, providing +user interface for editing pages, etc. Almost everything ikiwiki does +is accomplished by calling various hooks provided by plugins. + +### compiler + +As a compiler, ikiwiki starts by calling the `refresh` hook. Then it checks +the wiki's source to find new or changed pages. The `needsbuild` hook is +then called to allow manipulation of the list of pages that need to be +built. + +Now that it knows what pages it needs to build, ikiwiki runs two +compile passes. First, it runs `scan` hooks, which collect metadata about +the pages. Then it runs a page rendering pipeline, by calling in turn these +hooks: `filter`, `preprocess`, `linkify`, `htmlize`, `indexhtml`, +`pagetemplate`, `sanitize`, `format`. + +After all necessary pages are built, it calls the `change` hook. Finally, +if a page is was deleted, the `delete` hook is called, and the files that +page had previously produced are removed. + +### cgi + +The flow between hooks when ikiwiki is run as a cgi is best illustrated by +an example. + +Alice browses to a page and clicks Edit. + +* Ikiwiki is run as a cgi. It assigns Alice a session cookie, and, + by calling the `auth` hooks, sees that she is not yet logged in. +* The `sessioncgi` hooks are then called, and one of them, + from the [[editpage]] plugin, notices that the cgi has been told "do=edit". +* The [[editpage]] plugin calls the `canedit` hook to check if this + page edit is allowed. The [[signinedit]] plugin has a hook that says not: + Alice is not signed in. +* The [[signinedit]] plugin then launches the signin process. A signin + page is built by calling the `formbuilder_setup` hook. + +Alice signs in with her openid. + +* The [[openid]] plugin's `formbuilder` hook sees that an openid was + entered in the signin form, and redirects to Alice's openid provider. +* Alice's openid provider calls back to ikiwiki. The [[openid]] plugin + has an `auth` hook that finishes the openid signin process. +* Signin complete, ikiwiki returns to what Alice was doing before; editing + a page. +* Now all the `canedit` hooks are happy. The [[editpage]] plugin calls + `formbuilder_setup` to display the page editing form. + +Alice saves her change to the page. + +* The [[editpage]] plugin's `formbuilder` hook sees that the Save button + was pressed, and calls the `checkcontent` and `editcontent` hooks. + Then it saves the page to disk, and branches into the compiler part + of ikiwiki to refresh the wiki. + ## Types of plugins Most ikiwiki [[plugins]] are written in perl, like ikiwiki. This gives the @@ -31,16 +107,20 @@ they're the same as far as how they hook into ikiwiki. This document will explain how to write both sorts of plugins, albeit with an emphasis on perl plugins. -## Considerations +## Plugin interface -One thing to keep in mind when writing a plugin is that ikiwiki is a wiki -*compiler*. So plugins influence pages when they are built, not when they -are loaded. A plugin that inserts the current time into a page, for -example, will insert the build time. Also, as a compiler, ikiwiki avoids -rebuilding pages unless they have changed, so a plugin that prints some -random or changing thing on a page will generate a static page that won't -change until ikiwiki rebuilds the page for some other reason, like the page -being edited. +To import the ikiwiki plugin interface: + + use IkiWiki '3.00'; + +This will import several variables and functions into your plugin's +namespace. These variables and functions are the ones most plugins need, +and a special effort will be made to avoid changing them in incompatible +ways, and to document any changes that have to be made in the future. + +Note that IkiWiki also provides other variables and functions that are not +exported by default. No guarantee is made about these in the future, so if +it's not exported, the wise choice is to not use it. ## Registering plugins @@ -68,20 +148,21 @@ In roughly the order they are called. This allows for plugins to perform their own processing of command-line options and so add options to the ikiwiki command line. It's called during -command line processing, with @ARGV full of any options that ikiwiki was +command line processing, with `@ARGV` full of any options that ikiwiki was not able to process on its own. The function should process any options it -can, removing them from @ARGV, and probably recording the configuration -settings in %config. It should take care not to abort if it sees +can, removing them from `@ARGV`, and probably recording the configuration +settings in `%config`. It should take care not to abort if it sees an option it cannot process, and should just skip over those options and -leave them in @ARGV. +leave them in `@ARGV`. ### checkconfig hook(type => "checkconfig", id => "foo", call => \&checkconfig); This is useful if the plugin needs to check for or modify ikiwiki's -configuration. It's called early in the startup process. The -function is passed no values. It's ok for the function to call +configuration. It's called early in the startup process. `%config` +is populated at this point, but other state has not yet been loaded. +The function is passed no values. It's ok for the function to call `error()` if something isn't configured right. ### refresh @@ -96,10 +177,15 @@ function is passed no values. hook(type => "needsbuild", id => "foo", call => \&needsbuild); -This allows a plugin to manipulate the list of files that need to be -built when the wiki is refreshed. The function is passed a reference to an -array of files that will be rebuilt, and can modify the array, either -adding or removing files from it. +This allows a plugin to observe or even manipulate the list of files that +need to be built when the wiki is refreshed. + +As its first parameter, the function is passed a reference to an array of +files that will be built. It should return an array reference that is a +modified version of its input. It can add or remove files from it. + +The second parameter passed to the function is a reference to an array of +files that have been deleted. ### scan @@ -117,8 +203,8 @@ value is ignored. hook(type => "filter", id => "foo", call => \&filter); -Runs on the raw source of a page, before anything else touches it, and can -make arbitrary changes. The function is passed named parameters "page", +Runs on the full raw source of a page, before anything else touches it, and +can make arbitrary changes. The function is passed named parameters "page", "destpage", and "content". It should return the filtered content. ### preprocess @@ -201,11 +287,22 @@ like `Makefile` that have no extension. If `hook` is passed an optional "longname" parameter, this value is used when prompting a user to choose a page type on the edit page form. +### indexhtml + + hook(type => "indexhtml", id => "foo", call => \&indexhtml); + +This hook is called once the page has been converted to html (but before +the generated html is put in a template). The most common use is to +update search indexes. Added in ikiwiki 2.54. + +The function is passed named parameters "page", "destpage", and "content". +Its return value is ignored. + ### pagetemplate hook(type => "pagetemplate", id => "foo", call => \&pagetemplate); -[[Templates|wikitemplates]] are filled out for many different things in +[[Templates]] are filled out for many different things in ikiwiki, like generating a page, or part of a blog page, or an rss feed, or a cgi. This hook allows modifying the variables available on those templates. The function is passed named parameters. The "page" and @@ -221,11 +318,20 @@ a new custom parameter to the template. hook(type => "templatefile", id => "foo", call => \&templatefile); -This hook allows plugins to change the [[template|wikitemplates]] that is +This hook allows plugins to change the [[template|templates]] that is used for a page in the wiki. The hook is passed a "page" parameter, and -should return the name of the template file to use, or undef if it doesn't -want to change the default ("page.tmpl"). Template files are looked for in -/usr/share/ikiwiki/templates by default. +should return the name of the template file to use (relative to the +template directory), or undef if it doesn't want to change the default +("page.tmpl"). + +### pageactions + + hook(type => "pageactions", id => "foo", call => \&pageactions); + +This hook allows plugins to add arbitrary actions to the action bar on a +page (next to Edit, RecentChanges, etc). The hook is passed a "page" +parameter, and can return a list of html fragments to add to the action +bar. ### sanitize @@ -237,17 +343,6 @@ modify the body of a page after it has been fully converted to html. The function is passed named parameters: "page", "destpage", and "content", and should return the sanitized content. -### postscan - - hook(type => "postscan", id => "foo", call => \&postscan); - -This hook is called once the full page body is available (but before the -format hook). The most common use is to update search indexes. Added in -ikiwiki 2.54. - -The function is passed named parameters "page" and "content". Its return -value is ignored. - ### format hook(type => "format", id => "foo", call => \&format); @@ -455,7 +550,13 @@ The data returned is a list of `%config` options, followed by a hash describing the option. There can also be an item named "plugin", which describes the plugin as a whole. For example: - return + return + plugin => { + description => "description of this plugin", + safe => 1, + rebuild => 1, + section => "misc", + }, option_foo => { type => "boolean", description => "enable foo?", @@ -470,11 +571,6 @@ describes the plugin as a whole. For example: safe => 1, rebuild => 0, }, - plugin => { - description => "description of this plugin", - safe => 1, - rebuild => 1, - }, * `type` can be "boolean", "string", "integer", "pagespec", or "internal" (used for values that are not user-visible). The type is @@ -495,36 +591,38 @@ describes the plugin as a whole. For example: the plugin) will require a wiki rebuild, false if no rebuild is needed, and undef if a rebuild could be needed in some circumstances, but is not strictly required. +* `section` can optionally specify which section in the config file + the plugin fits in. The convention is to name the sections the + same as the tags used for [[plugins|plugin]] on this wiki. ### genwrapper hook(type => "genwrapper", id => "foo", call => \&genwrapper); This hook is used to inject C code (which it returns) into the `main` -function of the ikiwiki wrapper when it is being generated. +function of the ikiwiki wrapper when it is being generated. -## Plugin interface +The code runs before anything else -- in particular it runs before +the suid wrapper has sanitized its environment. -To import the ikiwiki plugin interface: +### disable - use IkiWiki '3.00'; + hook(type => "disable", id => "foo", call => \&disable); -This will import several variables and functions into your plugin's -namespace. These variables and functions are the ones most plugins need, -and a special effort will be made to avoid changing them in incompatible -ways, and to document any changes that have to be made in the future. +This hook is only run when a previously enabled plugin gets disabled +during ikiwiki setup. Plugins can use this to perform cleanups. -Note that IkiWiki also provides other variables and functions that are not -exported by default. No guarantee is made about these in the future, so if -it's not exported, the wise choice is to not use it. +## Exported variables + +Several variables are exported to your plugin when you `use IkiWiki;` -### %config +### `%config` A plugin can access the wiki's configuration via the `%config` hash. The best way to understand the contents of the hash is to look at your ikiwiki setup file, which sets the hash content to configure the wiki. -### %pagestate +### `%pagestate` The `%pagestate` hash can be used by plugins to save state that they will need next time ikiwiki is run. The hash holds per-page state, so to set a value, @@ -542,7 +640,7 @@ When pages are deleted, ikiwiki automatically deletes their pagestate too. Note that page state does not persist across wiki rebuilds, only across wiki updates. -### %wikistate +### `%wikistate` The `%wikistate` hash can be used by a plugin to store persistant state that is not bound to any one page. To set a value, use @@ -551,23 +649,53 @@ serialize, `$key` is any string you like, and `$id` must be the same as the "id" parameter passed to `hook()` when registering the plugin, so that the state can be dropped if the plugin is no longer used. -### Other variables +### `%links` + +The `%links` hash can be used to look up the names of each page that +a page links to. The name of the page is the key; the value is an array +reference. Do not modify this hash directly; call `add_link()`. + + $links{"foo"} = ["bar", "baz"]; -If your plugin needs to access data about other pages in the wiki. It can -use the following hashes, using a page name as the key: +### `%typedlinks` -* `%links` lists the names of each page that a page links to, in an array - reference. -* `%destsources` contains the name of the source file used to create each - destination file. -* `%pagesources` contains the name of the source file for each page. +The `%typedlinks` hash records links of specific types. Do not modify this +hash directly; call `add_link()`. The keys are page names, and the values +are hash references. In each page's hash reference, the keys are link types +defined by plugins, and the values are hash references with link targets +as keys, and 1 as a dummy value, something like this: -Also, the `%IkiWiki::version` variable contains the version number for the -ikiwiki program. + $typedlinks{"foo"} = { + tag => { short_word => 1, metasyntactic_variable => 1 }, + next_page => { bar => 1 }, + }; -### Library functions +Ordinary [[WikiLinks|ikiwiki/WikiLink]] appear in `%links`, but not in +`%typedlinks`. -#### `hook(@)` +### `%pagesources` + +The `%pagesources` has can be used to look up the source filename +of a page. So the key is the page name, and the value is the source +filename. Do not modify this hash. + + $pagesources{"foo"} = "foo.mdwn"; + +### `%destsources` + +The `%destsources` hash records the name of the source file used to +create each destination file. The key is the output filename (ie, +"foo/index.html"), and the value is the source filename that it was built +from (eg, "foo.mdwn"). Note that a single source file may create multiple +destination files. Do not modify this hash directly; call `will_render()`. + + $destsources{"foo/index.html"} = "foo.mdwn"; + +## Library functions + +Several functions are exported to your plugin when you `use IkiWiki;` + +### `hook(@)` Hook into ikiwiki's processing. See the discussion of hooks above. @@ -576,12 +704,12 @@ named `no_override` is supported, If it's set to a true value, then this hook will not override any existing hook with the same id. This is useful if the id can be controled by the user. -#### `debug($)` +### `debug($)` Logs a debugging message. These are supressed unless verbose mode is turned on. -#### `error($;$)` +### `error($;$)` Aborts with an error message. If the second parameter is passed, it is a function that is called after the error message is printed, to do any final @@ -595,37 +723,42 @@ In other hooks, error() is a fatal error, so use with care. Try to avoid dying on bad input when building a page, as that will halt the entire wiki build and make the wiki unusable. -#### `template($;@)` +### `template($;@)` -Creates and returns a [[!cpan HTML::Template]] object. The first parameter -is the name of the file in the template directory. The optional remaining +Creates and returns a [[!cpan HTML::Template]] object. (In a list context, +returns the parameters needed to construct the obhect.) + +The first parameter is the name of the template file. The optional remaining parameters are passed to `HTML::Template->new`. -#### `htmlpage($)` +Normally, the template file is first looked for in the templates/ subdirectory +of the srcdir. Failing that, it is looked for in the templatedir. -Passed a page name, returns the base name that will be used for a the html -page created from it. (Ie, it appends ".html".) +Wiki pages can be used as templates. This should be done only for templates +which it is safe to let wiki users edit. Enable it by passing a filename +with no ".tmpl" extension. Template pages are normally looked for in +the templates/ directory. If the page name starts with "/", a page +elsewhere in the wiki can be used. -Use this when constructing the filename of a html file. Use `urlto` when -generating a link to a page. +If the template is not found, or contains a syntax error, an error is thrown. -### `deptype(@)` +### `template_depends($$;@)` -Use this function to generate ikiwiki's internal representation of a -dependency type from one or more of these keywords: +Use this instead of `template()` if the content of a template is being +included into a page. This causes the page to depend on the template, +so it will be updated if the template is modified. -* `content` is the default. Any change to the content - of a page triggers the dependency. -* `presence` is only triggered by a change to the presence - of a page. -* `links` is only triggered by a change to the links of a page. - This includes when a link is added, removed, or changes what - it points to due to other changes. It does not include the - addition or removal of a duplicate link. +Like `template()`, except the second parameter is the page. -If multiple types are specified, they are combined. +### `htmlpage($)` -#### `pagespec_match_list($$;@)` +Passed a page name, returns the base name that will be used for a the html +page created from it. (Ie, it appends ".html".) + +Use this when constructing the filename of a html file. Use `urlto` when +generating a link to a page. + +### `pagespec_match_list($$;@)` Passed a page name, and [[ikiwiki/PageSpec]], returns a list of pages in the wiki that match the [[ikiwiki/PageSpec]]. @@ -646,7 +779,10 @@ Additional named parameters can be specified: * `filter` is a reference to a function, that is called and passed a page, and returns true if the page should be filtered out of the list. * `sort` specifies a sort order for the list. See - [[ikiwiki/PageSpec/sorting]] for the avilable sort methods. + [[ikiwiki/PageSpec/sorting]] for the avilable sort methods. Note that + if a sort method is specified that depends on the + page content (such as 'meta(foo)'), the deptype needs to be set to + a content dependency. * `reverse` if true, sorts in reverse. * `num` if nonzero, specifies the maximum number of matching pages that will be returned. @@ -656,7 +792,7 @@ Additional named parameters can be specified: Any other named parameters are passed on to `pagespec_match`, to further limit the match. -#### `add_depends($$;$)` +### `add_depends($$;$)` Makes the specified page depend on the specified [[ikiwiki/PageSpec]]. @@ -664,7 +800,7 @@ By default, dependencies are full content dependencies, meaning that the page will be updated whenever anything matching the PageSpec is modified. This can be overridden by passing a `deptype` value as the third parameter. -#### `pagespec_match($$;@)` +### `pagespec_match($$;@)` Passed a page name, and [[ikiwiki/PageSpec]], returns a true value if the [[ikiwiki/PageSpec]] matches the page. @@ -678,7 +814,23 @@ The most often used is "location", which specifies the location the PageSpec should match against. If not passed, relative PageSpecs will match relative to the top of the wiki. -#### `bestlink($$)` +### `deptype(@)` + +Use this function to generate ikiwiki's internal representation of a +dependency type from one or more of these keywords: + +* `content` is the default. Any change to the content + of a page triggers the dependency. +* `presence` is only triggered by a change to the presence + of a page. +* `links` is only triggered by a change to the links of a page. + This includes when a link is added, removed, or changes what + it points to due to other changes. It does not include the + addition or removal of a duplicate link. + +If multiple types are specified, they are combined. + +### `bestlink($$)` Given a page and the text of a link on the page, determine which existing page that link best points to. Prefers pages under a @@ -686,7 +838,7 @@ subdirectory with the same name as the source page, failing that goes down the directory tree to the base looking for matching pages, as described in [[ikiwiki/SubPage/LinkingRules]]. -#### `htmllink($$$;@)` +### `htmllink($$$;@)` Many plugins need to generate html links and add them to a page. This is done by using the `htmllink` function. The usual way to call @@ -712,8 +864,9 @@ control some options. These are: * anchor - set to make the link include an anchor * rel - set to add a rel attribute to the link * class - set to add a css class to the link +* title - set to add a title attribute to the link -#### `readfile($;$)` +### `readfile($;$)` Given a filename, reads and returns the entire file. @@ -722,7 +875,7 @@ in binary mode. A failure to read the file will result in it dying with an error. -#### `writefile($$$;$$)` +### `writefile($$$;$$)` Given a filename, a directory to put it in, and the file's content, writes a file. @@ -750,7 +903,7 @@ generally the directory parameter is a trusted toplevel directory like the srcdir or destdir, and any subdirectories of this are included in the filename parameter. -#### `will_render($$)` +### `will_render($$)` Given a page name and a destination file name (not including the base destination directory), register that the page will result in that file @@ -766,34 +919,34 @@ Ikiwiki uses this information to automatically clean up rendered files when the page that rendered them goes away or is changed to no longer render them. will_render also does a few important security checks. -#### `pagetype($)` +### `pagetype($)` Given the name of a source file, returns the type of page it is, if it's a type that ikiwiki knowns how to htmlize. Otherwise, returns undef. -#### `pagename($)` +### `pagename($)` Given the name of a source file, returns the name of the wiki page that corresponds to that file. -#### `pagetitle($)` +### `pagetitle($)` Give the name of a wiki page, returns a version suitable to be displayed as the page's title. This is accomplished by de-escaping escaped characters in the page name. "_" is replaced with a space, and '__NN__' is replaced by the UTF character with code NN. -#### `titlepage($)` +### `titlepage($)` This performs the inverse of `pagetitle`, ie, it converts a page title into a wiki page name. -#### `linkpage($)` +### `linkpage($)` This converts text that could have been entered by the user as a [[ikiwiki/WikiLink]] into a wiki page name. -#### `srcfile($;$)` +### `srcfile($;$)` Given the name of a source file in the wiki, searches for the file in the source directory and the underlay directories (most recently added @@ -803,7 +956,7 @@ Normally srcfile will fail with an error message if the source file cannot be found. The second parameter can be set to a true value to make it return undef instead. -#### `add_underlay($)` +### `add_underlay($)` Adds a directory to the set of underlay directories that ikiwiki will search for files. @@ -811,33 +964,48 @@ search for files. If the directory name is not absolute, ikiwiki will assume it is in the parent directory of the configured underlaydir. -#### `displaytime($;$)` +### `displaytime($;$$)` Given a time, formats it for display. The optional second parameter is a strftime format to use to format the time. -#### `gettext` +If the third parameter is true, this is the publication time of a page. +(Ie, set the html5 pubdate attribute.) + +### `gettext` This is the standard gettext function, although slightly optimised. -#### `urlto($$;$)` +### `ngettext` + +This is the standard ngettext function, although slightly optimised. + +### `urlto($;$$)` Construct a relative url to the first parameter from the page named by the second. The first parameter can be either a page name, or some other destination file, as registered by `will_render`. -If the third parameter is passed and is true, an absolute url will be -constructed instead of the default relative url. +Provide a second parameter whenever possible, since this leads to better +behaviour for the [[plugins/po]] plugin and `file:///` URLs. + +If the second parameter is not specified (or `undef`), the URL will be +valid from any page on the wiki, or from the CGI; if possible it'll +be a path starting with `/`, but an absolute URL will be used if +the wiki and the CGI are on different domains. -#### `newpagefile($$)` +If the third parameter is passed and is true, the url will be a fully +absolute url. This is useful when generating an url to publish elsewhere. + +### `newpagefile($$)` This can be called when creating a new page, to determine what filename to save the page to. It's passed a page name, and its type, and returns the name of the file to create, relative to the srcdir. -#### `targetpage($$;$)` +### `targetpage($$;$)` Passed a page and an extension, returns the filename that page will be rendered to. @@ -846,11 +1014,31 @@ Optionally, a third parameter can be passed, to specify the preferred filename of the page. For example, `targetpage("foo", "rss", "feed")` will yield something like `foo/feed.rss`. -#### `add_link($$)` +### `add_link($$;$)` This adds a link to `%links`, ensuring that duplicate links are not added. Pass it the page that contains the link, and the link text. +An optional third parameter sets the link type. If not specified, +it is an ordinary [[ikiwiki/WikiLink]]. + +### `add_autofile($$$)` + +Sometimes you may want to add a file to the `srcdir` as a result of content +of other pages. For example, [[plugins/tag]] pages can be automatically +created as needed. This function can be used to do that. + +The three parameters are the filename to create (relative to the `srcdir`), +the name of the plugin, and a callback function. The callback will be +called if it is appropriate to automatically add the file, and should then +take care of creating it, and doing anything else it needs to (such as +checking it into revision control). Note that the callback may not always +be called. For example, if an automatically added file is deleted by the +user, ikiwiki will avoid re-adding it again. + +This function needs to be called during the scan hook, or earlier in the +build process, in order to add the file early enough for it to be built. + ## Miscellaneous ### Internal use pages @@ -888,16 +1076,20 @@ token, that will be passed into `rcs_commit` when committing. For example, it might return the current revision ID of the file, and use that information later when merging changes. -#### `rcs_commit($$$;$$)` +#### `rcs_commit(@)` + +Passed named parameters: `file`, `message`, `token` (from `rcs_prepedit`), +and `session` (optional). -Passed a file, message, token (from `rcs_prepedit`), user, and ip address. Should try to commit the file. Returns `undef` on *success* and a version of the page with the rcs's conflict markers on failure. -#### `rcs_commit_staged($$$)` +#### `rcs_commit_staged(@)` + +Passed named parameters: `message`, and `session` (optional). -Passed a message, user, and ip address. Should commit all staged changes. -Returns undef on success, and an error message on failure. +Should commit all staged changes. Returns undef on success, and an +error message on failure. Changes can be staged by calls to `rcs_add`, `rcs_remove`, and `rcs_rename`. @@ -940,7 +1132,9 @@ The data structure returned for each change is: { rev => # the RCSs id for this commit - user => # name of user who made the change, + user => # user who made the change (may be an openid), + nickname => # short name for user (optional; not an openid), + committype => # either "web" or the name of the rcs, when => # time when the change was made, message => [ @@ -957,19 +1151,30 @@ The data structure returned for each change is: ], } -#### `rcs_diff($)` +#### `rcs_diff($;$)` + +The first parameter is the rev from `rcs_recentchanges`. +The optional second parameter is how many lines to return (default: all). -The parameter is the rev from `rcs_recentchanges`. Should return a list of lines of the diff (including \n) in list -context, and the whole diff in scalar context. +context, and a string containing the whole diff in scalar context. #### `rcs_getctime($)` This is used to get the page creation time for a file from the RCS, by looking it up in the history. +If the RCS cannot determine a ctime for the file, return 0. + +#### `rcs_getmtime($)` + +This is used to get the page modification time for a file from the RCS, by +looking it up in the history. + It's ok if this is not implemented, and throws an error. +If the RCS cannot determine a mtime for the file, return 0. + #### `rcs_receive()` This is called when ikiwiki is running as a pre-receive hook (or @@ -979,9 +1184,9 @@ sense to implement for all RCSs. It should examine the incoming changes, and do any sanity checks that are appropriate for the RCS to limit changes to safe file adds, -removes, and changes. If something bad is found, it should exit -nonzero, to abort the push. Otherwise, it should return a list of -files that were changed, in the form: +removes, and changes. If something bad is found, it should die, to abort +the push. Otherwise, it should return a list of files that were changed, +in the form: { file => # name of file that was changed @@ -994,6 +1199,28 @@ files that were changed, in the form: The list will then be checked to make sure that each change is one that is allowed to be made via the web interface. +#### `rcs_preprevert($)` + +This is called by the revert web interface. It is passed a RCS-specific +change ID, and should determine what the effects would be of reverting +that change, and return the same data structure as `rcs_receive`. + +Like `rcs_receive`, it should do whatever sanity checks are appropriate +for the RCS to limit changes to safe changes, and die if a change would +be unsafe to revert. + +#### `rcs_revert($)` + +This is called by the revert web interface. It is passed a named +parameter rev that is the RCS-specific change ID to revert. + +It should try to revert the specified rev, and leave the reversion staged +so `rcs_commit_staged` will complete it. It should return undef on _success_ +and an error message on failure. + +This hook and `rcs_preprevert` are optional, if not implemented, no revert +web interface will be available. + ### PageSpec plugins It's also possible to write plugins that add new functions to @@ -1017,6 +1244,24 @@ For example, "backlink(foo)" is influenced by the contents of page foo; they match; "created_before(foo)" is influenced by the metadata of foo; while "glob(*)" is not influenced by the contents of any page. +### Sorting plugins + +Similarly, it's possible to write plugins that add new functions as +[[ikiwiki/pagespec/sorting]] methods. To achieve this, add a function to +the IkiWiki::SortSpec package named `cmp_foo`, which will be used when sorting +by `foo` or `foo(...)` is requested. + +The names of pages to be compared are in the global variables `$a` and `$b` +in the IkiWiki::SortSpec package. The function should return the same thing +as Perl's `cmp` and `<=>` operators: negative if `$a` is less than `$b`, +positive if `$a` is greater, or zero if they are considered equal. It may +also raise an error using `error`, for instance if it needs a parameter but +one isn't provided. + +The function will also be passed one or more parameters. The first is +`undef` if invoked as `foo`, or the parameter `"bar"` if invoked as `foo(bar)`; +it may also be passed additional, named parameters. + ### Setup plugins The ikiwiki setup file is loaded using a pluggable mechanism. If you look diff --git a/doc/plugins/write/external.mdwn b/doc/plugins/write/external.mdwn index e30bf2ff3..a3fbe8a2c 100644 --- a/doc/plugins/write/external.mdwn +++ b/doc/plugins/write/external.mdwn @@ -1,7 +1,7 @@ External plugins are standalone, executable programs, that can be written in any language. When ikiwiki starts up, it runs the program, and -communicates with it using [XML RPC][xmlrpc]. If you want to [[write]] an external -plugin, read on.. +communicates with it using [XML RPC][xmlrpc]. If you want to [[write]] an +external plugin, read on.. [xmlrpc]: http://www.xmlrpc.com/ @@ -85,8 +85,8 @@ language as part of their XML RPC interface. XML RPC has a limitation that it does not have a way to pass undef/NULL/None. There is an extension to the protocol that supports this, -but it is not yet available in the [[!cpan XML::RPC]] library used by -ikiwiki. +but it is not yet available in all versions of the [[!cpan XML::RPC]] library +used by ikiwiki. Until the extension is available, ikiwiki allows undef to be communicated over XML RPC by passing a sentinal value, a hash with a single key "null" |