summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorJoey Hess <joey@gnu.kitenet.net>2010-04-06 22:59:57 -0400
committerJoey Hess <joey@gnu.kitenet.net>2010-04-06 22:59:57 -0400
commitf2a87addc63114edd3e096cff286bc3b19989df3 (patch)
tree59309b8d582403d4f64303ada3565d2cb99f8d92 /doc
parentc0ca1967586234ae4e84e485af53804df2198bcd (diff)
parent1158fe8f4400943d7a24350c6ac8fee6a95c2bed (diff)
Merge branch 'master' of ssh://git.ikiwiki.info/srv/git/ikiwiki.info
Diffstat (limited to 'doc')
-rw-r--r--doc/forum/an_alternative_approach_to_structured_data.mdwn4
-rw-r--r--doc/plugins/contrib/field/discussion.mdwn128
-rw-r--r--doc/todo/optional_underlaydir_prefix.mdwn2
-rw-r--r--doc/users/KathrynAndersen/discussion.mdwn4
4 files changed, 135 insertions, 3 deletions
diff --git a/doc/forum/an_alternative_approach_to_structured_data.mdwn b/doc/forum/an_alternative_approach_to_structured_data.mdwn
index 06c82337a..6e6af8adb 100644
--- a/doc/forum/an_alternative_approach_to_structured_data.mdwn
+++ b/doc/forum/an_alternative_approach_to_structured_data.mdwn
@@ -20,7 +20,9 @@ I think it could be really powerful and useful, especially if it becomes part of
> I agree such a separation makes some sense. But note that the discussion on [[todo/structured_page_data]]
> talks about associating data types with fields for a good reason: It's hard to later develop a good UI for
-> querying or modifying a page's data if all the data has an implicit type "string". --[[Joey]]
+> querying or modifying a page's data if all the data has an implicit type "string". --[[Joey]]
+
+>> I'm not sure that having an implicit type of "string" is really such a bad thing. After all, Perl itself manages with just string and number, and easily converts from one to the other. Strong typing is generally used to (a) restrict what can be done with the data and/or (b) restrict how the data is input. The latter could be done with some sort of validated form, but that, too, could be decoupled from looking up and returning the value of a field. --[[KathrynAndersen]]
## Second Pass
diff --git a/doc/plugins/contrib/field/discussion.mdwn b/doc/plugins/contrib/field/discussion.mdwn
index 646a5f3f4..16b40cf06 100644
--- a/doc/plugins/contrib/field/discussion.mdwn
+++ b/doc/plugins/contrib/field/discussion.mdwn
@@ -21,11 +21,67 @@ behaviour, an auxiliary plugin would be easy.)
>> (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`
@@ -94,6 +150,7 @@ field-etc branch in git://git.pseudorandom.co.uk/git/smcv/ikiwiki.git (gitweb:
--[[smcv]]
> Can do for the field plugin (delete one line? Easy.) Will push when I get to a better connection. --[[KathrynAndersen]]
+>> Done! -K.A.
----
@@ -109,3 +166,72 @@ 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]]
diff --git a/doc/todo/optional_underlaydir_prefix.mdwn b/doc/todo/optional_underlaydir_prefix.mdwn
index dd11d062d..06900a904 100644
--- a/doc/todo/optional_underlaydir_prefix.mdwn
+++ b/doc/todo/optional_underlaydir_prefix.mdwn
@@ -41,4 +41,6 @@ I'm not sure how this would be implemented, but I guess it could be configured s
> `readfile` does not allow reading symlinks. But I don't see much need
> for that.) --[[Joey]]
+>> If you think that enabling symlinks in underlay directories wouldn't be a security issue, then I'm all for it! That would be much simpler to implement, I'm sure. --[[KathrynAndersen]]
+
[[!taglink wishlist]]
diff --git a/doc/users/KathrynAndersen/discussion.mdwn b/doc/users/KathrynAndersen/discussion.mdwn
index 35340b22f..4f2790c39 100644
--- a/doc/users/KathrynAndersen/discussion.mdwn
+++ b/doc/users/KathrynAndersen/discussion.mdwn
@@ -11,7 +11,9 @@ that as a patch to the existing map plugin.) --[[Joey]]
>> One approach commonly used in ikiwiki is to make such optional features
>> be enabled by a switch somewhere, and 'eval q{use Foo}` so the module
->> does not have to be loaded unless the feature is used. --[[Joey]]
+>> does not have to be loaded unless the feature is used. --[[Joey]]
+
+>>> Unfortunately, HTML::LinkList isn't an optional feature for pmap; that's what it uses to create the HTML for the map. --[[KathrynAndersen]]
> The "includepage" plugin I'm not sure whether it is worth releasing or not; it's basically a cut-down version of "inline", because the inline plugin is so complicated and has so many options, I felt more at ease to have something simpler.