X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/3c6da7d518bd03a5c09d19fbe3fa57e400cec1a7..486076c94367a40ff6a5e2476d98b87cd8d64f96:/doc/todo/conditional_text_based_on_ikiwiki_features.mdwn?ds=sidebyside

diff --git a/doc/todo/conditional_text_based_on_ikiwiki_features.mdwn b/doc/todo/conditional_text_based_on_ikiwiki_features.mdwn
index 3cefc97a2..0d0f66da4 100644
--- a/doc/todo/conditional_text_based_on_ikiwiki_features.mdwn
+++ b/doc/todo/conditional_text_based_on_ikiwiki_features.mdwn
@@ -1,16 +1,128 @@
-I'd like to see some way to conditionally include wiki text based on whether the wiki enables or disables certain features.  For example, [[helponformatting]], could use `\[[if (enabled smiley) """Also, because this wiki has the smiley plugin enabled, you can insert \[[smileys]] and some other useful symbols."""]]`, and a standard template for [[plugins]] pages could check for the given plugin name to print "enabled" or "disabled".
+I'd like to see some way to conditionally include wiki text based on
+whether the wiki enables or disables certain features.  For example,
+[[ikiwiki/formatting]], could use `\[[!if (enabled smiley) """Also, because
+this wiki has the smiley plugin enabled, you can insert \[[smileys]] and
+some other useful symbols."""]]`, and a standard template for [[plugins]]
+pages could check for the given plugin name to print "enabled" or
+"disabled".
 
 Some potentially useful conditionals:
 
 * `enabled pluginname`
 * `disabled pluginname`
-* `any pagespec`: true if any of the pages in the [[PageSpec]] exist
-* `all pagespec`: true if all of the pages in the [[PageSpec]] exist
-* `no pagespec` or `none pagespec`: true if none of the pages in the [[PageSpec]] exist
+* `any pagespec`: true if any of the pages in the [[ikiwiki/PageSpec]] exist
+* `all pagespec`: true if all of the pages in the [[ikiwiki/PageSpec]] exist
+* `no pagespec` or `none pagespec`: true if none of the pages in the [[ikiwiki/PageSpec]] exist
 * `thispage pagespec`: true if pagespec includes the page getting rendered (possibly one including the page with this content on it).
 * `sourcepage pagespec`: true if pagespec includes the page corresponding to the file actually containing this content, rather than a page including it.
 * `included`: true if included on another page, via [[plugins/inline]], [[plugins/sidebar]], [[plugins/contrib/navbar]], etc.
 
-You may or may not want to include boolean operations (`and`, `or`, and `not`); if you do, you could replace `disabled` with `not enabled`, and `no pagespec` or `none pagespec` with `not any pagespec` (but you may want to keep the aliases for simplicity anyway).  You also may or may not want to include an `else` clause; if so, you could label the text used if true as `then`.
+You may or may not want to include boolean operations (`and`, `or`, and
+`not`); if you do, you could replace `disabled` with `not enabled`, and `no
+pagespec` or `none pagespec` with `not any pagespec` (but you may want to
+keep the aliases for simplicity anyway).  You also may or may not want to
+include an `else` clause; if so, you could label the text used if true as
+`then`.
 
-Syntax could vary greatly here, both for the [[PreprocessorDirective]] and for the condition itself.
+Syntax could vary greatly here, both for the
+[[ikiwiki/Directive]] and for the condition itself.
+
+> I think this is a good thing to consider, although conditionals tend to
+> make everything a lot more complicated, so I also want to KISS, and not
+> use too many of them.
+> 
+> I'd probably implement this using the same method as pagespecs, so 'and',
+> 'or', '!', and paren groupings work.
+> 
+> It could be thought of as simply testing to see if a pagespec matches
+> anything, using a slightly expanded syntax for the pagespec, which would
+> also allow testing for things like link(somepage),
+> created_before(somepage), etc.
+> 
+> That also gives us your "any pagespec" for free: "page or page or page".
+> And for "all pagespec", you can do "page and page and page". 
+> 
+> For plugins testing, maybe just use "enabled(name)"?
+> 
+> I'm not sure what the use cases are for thispage, sourcepage, and
+> included. I don't know if the included test is even doable. I'd be
+> inclined to not bother with these three unless there are use cases I'm
+> not seeing.
+> 
+> As to the syntax, to fit it into standard preprocessor syntax, it would
+> need to look something like this:
+>
+>	\[[!if test="enabled(smiley)" """foo"""]]
+> 
+> --[[Joey]]
+
+>> [[ikiwiki/PageSpec]] syntax seems perfect, and your proposed syntax for the `if`
+>> [[ikiwiki/Directive]] looks fine to me.
+>>
+>> [[ikiwiki/PageSpec]]s don't give you `none` for free, since `!foo/*` as a boolean
+>> would mean "does any page not matching `foo/*` exist", not "does `foo/*`
+>> match nothing"; however, I don't really care much about `none`, since I
+>> just threw it in while brainstorming, and I don't know any compelling use
+>> cases for it.
+>>
+>> `enabled(pluginname)` will work perfectly, and `!enabled(pluginname)`
+>> makes `disabled` unnecessary.
+>>
+>> A few use cases for `included`, which I would really like to see:
+>>
+>> * On the sidebar page, you could say something like \[[!if test="!included"
+>>   """This page, without this help message, appears as a sidebar on all
+>>   pages."""]].  The help text would then only appear on the sidebar page
+>>   itself, not the sidebar included on all pages.
+>>
+>> * On [[blog]] entries, you could use `included` to implement a cut.
+>>   (Please don't take that as an argument against. :) ) For instance, you
+>>   could use included rather than [[plugins/toggle]] for the detailed
+>>   changelogs of ikiwiki, or to embed an image as a link in the feed rather
+>>   than an embedded image.
+>>
+>> Some use cases for `thispage`:
+>>
+>> * You could use `thispage` to include or exclude parts of the sidebar based
+>>   on the page you include it in.  You can already use subpages/sidebar for
+>>   subpages/*, but `thispage` seems more flexible, makes it trivial to have
+>>   common portions rather than using [[plugins/inline]] with the `raw`
+>>   option, and keeps the sidebar in one place.
+>>
+>> * You could use `thispage` to implement multiple different feeds for the
+>>   same content with slightly different presentation.  For instance, using
+>>   templates for image inclusion, you could offer a feed with image links
+>>   and a feed with embedded images. Similarly, using templates for cuts, you
+>>   could offer a feed with cuts and a feed with full content in every post.
+>>
+>> I don't have any particular attachment to `sourcepage`.  It only makes
+>> sense as part of a template, since otherwise you know the source page when
+>> typing in the if.
+>>
+>> --[[JoshTriplett]]
+
+This is now completely [[todo/done]]! See [[plugins/conditional]].
+
+--[[Joey]]
+
+> You rock mightily. --[[JoshTriplett]]
+
+Is there a way to test features other than plugins? For example,
+to add to [[ikiwiki/Markdown]] something like
+
+    \[[!if test="enabled(multimarkdown)" then="You can also use..."]]
+
+(I tried it like that just to see if it would work, but I wasn't that lucky.)
+--ChapmanFlack
+
+> No, not supported. I really think that trying to conditionalise text on a
+> page for multimarkdown is a path to madness or unreadability though.
+> Perhaps it would be better to have .mmdwn files that can only contain
+> multimarkdown? --[[Joey]]
+
+>> Really, there was only one (or maybe two) pages I had in mind as appropriate
+>> places for conditional text based on multimarkdown—the underlay pages
+>> for 'markdown' and maybe also 'formatting', because those are the pages you
+>> look at when you're trying to find out how to mark stuff up for the wiki, so
+>> if MM is enabled, they need to at least mention it and have a link to the
+>> MM syntax guide.--ChapmanFlack