Merge branch 'dependency-types'

Conflicts:
	doc/todo/dependency_types.mdwn

18 files changed, 124 insertions, 67 deletions

diff --git a/doc/bugs/Inline_doesn__39__t_wikilink_to_pages.mdwn b/doc/bugs/Inline_doesn__39__t_wikilink_to_pages.mdwn
index 32f9f1245..13b80b436 100644
--- a/doc/bugs/Inline_doesn__39__t_wikilink_to_pages.mdwn
+++ b/doc/bugs/Inline_doesn__39__t_wikilink_to_pages.mdwn
@@ -2,10 +2,6 @@ It seems that the [[ikiwiki/directive/inline]] directive doesn't generate wikili
 
 \[[!inline pages="bugs/* and !*/discussion and backlink(bugs)" feeds=no postform=no archive=yes show="10"]]
 
-But here it is:
-
-[[!inline pages="bugs/* and !*/discussion and backlink(bugs)" feeds=no postform=no archive=yes show="10"]]
-
 and note that it only included the 'normal' wikilinks (and also note that this page is not marked done even though the done page is inlined).
 One might also wonder if inline would make this page link to any internal links on those inlined pages too, but I think
 that would be overkill.
diff --git a/doc/bugs/bestlink_change_update_issue.mdwn b/doc/bugs/bestlink_change_update_issue.mdwn
index 5ce4a93d2..8a526e821 100644
--- a/doc/bugs/bestlink_change_update_issue.mdwn
+++ b/doc/bugs/bestlink_change_update_issue.mdwn
@@ -1,13 +1,29 @@
 * Has bugs updating things if the bestlink of a page changes due to
   adding/removing a page. For example, if Foo/Bar links to "Baz", which is
   Foo/Baz, and Foo/Bar/Baz gets added, it will update the links in Foo/Bar
-  to point to it, but will forget to update the linkbacks in Foo/Baz.
+  to point to it, but will forget to update the backlinks in Foo/Baz.
 
-* And if Foo/Bar/Baz is then removed, it forgets to update Foo/Bar to link
-  back to Foo/Baz.
+  The buggy code is in `refresh()`, when it determines what
+  links, on what pages, have changed. It only looks at
+  changed/added/deleted pages when doing this. But when Foo/Bar/Baz
+  is added, Foo/Bar is not changed -- so the change it its
+  backlinks is not noticed.
 
-As of 1.33, this is still true. The buggy code is the %linkchanged
-calculation in refresh(), which doesn't detect that the link has changed in
-this case.
+  To fix this, it needs to consider, when rebuilding Foo/Bar for the changed
+  links, what oldlinks Foo/Bar had. If one of the oldlinks linked to
+  Foo/Baz, and not links to Foo/Bar/Baz, it could then rebuild Foo/Baz.
 
-Still true in 1.43 although the code is much different now..
+  Problem is that in order to do that, it needs to be able to tell that
+  the oldlinks linked to Foo/Baz. Which would mean either calculating
+  all links before the scan phase, or keeping a copy of the backlinks
+  from the last build, and using that. The first option would be a lot
+  of work for this minor issue.. it might be less expensive to just rebuild
+  *all* pages that Foo/Bar links to.
+
+  Keeping a copy of the backlinks has some merit. It could also be
+  incrementally updated.
+
+* And if Foo/Bar/Baz is then removed, Foo/Bar gets a broken link,
+  instead of changing back to linking to Foo/Baz.
+
+This old bug still exists as of 031d1bf5046ab77c796477a19967e7c0c512c417.
diff --git a/doc/bugs/transitive_dependencies.mdwn b/doc/bugs/transitive_dependencies.mdwn
index 70b5fb4d4..c44fe7962 100644
--- a/doc/bugs/transitive_dependencies.mdwn
+++ b/doc/bugs/transitive_dependencies.mdwn
@@ -65,7 +65,7 @@ Downsides here:
   modification to plugins/brokenlinks causes an unnecessary update of
   plugins, and could be solved by adding more dependency types.)
 
---[[Joey]] 
+[[done]] --[[Joey]] 
 
 > Some questions/comments...  I've thought about this a lot for [[todo/tracking_bugs_with_dependencies]].
 > 
diff --git a/doc/examples/blog/index.mdwn b/doc/examples/blog/index.mdwn
index aef46eb68..01b714fcd 100644
--- a/doc/examples/blog/index.mdwn
+++ b/doc/examples/blog/index.mdwn
@@ -1,4 +1,4 @@
-[[!pagestats pages="./tags/*"]]
+[[!pagestats pages="./tags/*" among="./posts/*"]]
 
 Welcome to my blog.
 
diff --git a/doc/examples/blog/tags.mdwn b/doc/examples/blog/tags.mdwn
index 53cc8d368..b5eca5b71 100644
--- a/doc/examples/blog/tags.mdwn
+++ b/doc/examples/blog/tags.mdwn
@@ -1,3 +1,3 @@
-[[!pagestats pages="./tags/*"]]
+[[!pagestats pages="./tags/*" among="./posts/*"]]
 
 On the right you can see the tag cloud for this blog.
diff --git a/doc/ikiwiki-calendar.mdwn b/doc/ikiwiki-calendar.mdwn
index e2cc612f3..982892fca 100644
--- a/doc/ikiwiki-calendar.mdwn
+++ b/doc/ikiwiki-calendar.mdwn
@@ -4,7 +4,7 @@ ikiwiki-calendar - create calendar archive pages
 
 # SYNOPSIS
 
-ikiwiki-calendar [-f] your.setup [pagespec] [year]
+ikiwiki-calendar [-f] your.setup [pagespec] [startyear [endyear]]
 
 # DESCRIPTION
 
@@ -22,13 +22,13 @@ default is all pages. To limit it to only posts in a blog,
 use something like "posts/* and !*/Discussion".
 
 It defaults to creating calendar pages for the current
-year, as well as the previous year, and the next year.
-If you specify a year, it will create pages for that year.
+year. If you specify a year, it will create pages for that year.
+Specify a second year to create pages for a span of years.
 
 Existing pages will not be overwritten by this command by default.
 Use the `-f` switch to force it to overwrite any existing pages.
 
-## CRONTAB
+# CRONTAB
 
 While this command only needs to be run once a year to update
 the archive pages for each new year, you are recommended to set up
diff --git a/doc/ikiwiki/directive/inline.mdwn b/doc/ikiwiki/directive/inline.mdwn
index 99f795972..c6a23ce3c 100644
--- a/doc/ikiwiki/directive/inline.mdwn
+++ b/doc/ikiwiki/directive/inline.mdwn
@@ -86,19 +86,15 @@ Here are some less often needed parameters:
   if raw is set to "yes", the page will be included raw, without additional
   markup around it, as if it were a literal part of the source of the 
   inlining page.
-* `sort` - Controls how inlined pages are sorted. The default, "age" is to
-  sort newest created pages first. Setting it to "title" will sort pages by
-  title, and "mtime" sorts most recently modified pages first. If
-  [[!cpan Sort::Naturally]] is installed, `sort` can be set to "title_natural"
-  to sort by title with numbers treated as such ("1 2 9 10 20" instead of
-  "1 10 2 20 9").
+* `sort` - Controls how inlined pages are [[sorted|pagespec/sorting]].
+  The default is to sort the newest created pages first.
 * `reverse` - If set to "yes", causes the sort order to be reversed.
 * `feedshow` - Specify the maximum number of matching pages to include in
   the rss/atom feeds. The default is the same as the `show` value above.
 * `feedonly` - Only generate the feed, do not display the pages inline on
   the page.
 * `quick` - Build archives in quick mode, without reading page contents for
-  metadata. By default, this also turns off generation of any feeds.
+  metadata. This also turns off generation of any feeds.
 * `timeformat` - Use this to specify how to display the time or date for pages
   in the blog. The format string is passed to the strftime(3) function.
 * `feedpages` - A [[PageSpec]] of inlined pages to include in the rss/atom
diff --git a/doc/ikiwiki/directive/linkmap.mdwn b/doc/ikiwiki/directive/linkmap.mdwn
index db79a1491..38cf0fd11 100644
--- a/doc/ikiwiki/directive/linkmap.mdwn
+++ b/doc/ikiwiki/directive/linkmap.mdwn
@@ -9,9 +9,7 @@ Only links between mapped pages will be shown; links pointing to or from
 unmapped pages will be omitted. If the pages to include are not specified,
 the links between all pages (and other files) in the wiki are mapped. For
 best results, only a small set of pages should be mapped, since otherwise
-the map can become very large, unwieldy, and complicated. Also, the map is
-rebuilt whenever one of the mapped pages is changed, which can make the
-wiki a bit slow.
+the map can become very large, unwieldy, and complicated.
 
 Here are descriptions of all the supported parameters to the `linkmap`
 directive:
diff --git a/doc/ikiwiki/directive/pagestats.mdwn b/doc/ikiwiki/directive/pagestats.mdwn
index 66f851dbd..f14c80b07 100644
--- a/doc/ikiwiki/directive/pagestats.mdwn
+++ b/doc/ikiwiki/directive/pagestats.mdwn
@@ -12,13 +12,13 @@ And here's how to create a table of all the pages on the wiki:
 
 	\[[!pagestats style="table"]]
 
-The optional `among` parameter limits display to pages that match a
-[[ikiwiki/PageSpec]]. For instance, to display a cloud of tags used on blog
-entries, you could use:
+The optional `among` parameter limits the pages whose outgoing links are
+considered. For instance, to display a cloud of tags used on blog
+entries, while ignoring other pages that use those tags, you could use:
 
 	\[[!pagestats pages="tags/*" among="blog/posts/*"]]
 
-or to display a cloud of tags related to Linux, you could use:
+Or to display a cloud of tags related to Linux, you could use:
 
 	\[[!pagestats pages="tags/* and not tags/linux" among="tagged(linux)"]]
 
diff --git a/doc/ikiwiki/pagespec/sorting.mdwn b/doc/ikiwiki/pagespec/sorting.mdwn
new file mode 100644
index 000000000..41aa58151
--- /dev/null
+++ b/doc/ikiwiki/pagespec/sorting.mdwn
@@ -0,0 +1,11 @@
+Some [[directives|ikiwiki/directive]] that use
+[[PageSpecs|ikiwiki/pagespec]] allow
+specifying the order that matching pages are shown in. The following sort
+orders can be specified.
+
+* `age` - List pages from the most recently created to the oldest.
+* `mtime` - List pages with the most recently modified first.
+* `title` - Order by title.
+* `title_natural` - Only available if [[!cpan Sort::Naturally]] is
+  installed. Orders by title, but numbers in the title are treated
+  as such, ("1 2 9 10 20" instead of "1 10 2 20 9")
diff --git a/doc/plugins.mdwn b/doc/plugins.mdwn
index 527568208..697b4a219 100644
--- a/doc/plugins.mdwn
+++ b/doc/plugins.mdwn
@@ -1,7 +1,7 @@
 Most of ikiwiki's [[features]] are implemented as plugins. Many of these 
 plugins are included with ikiwiki.
 
-[[!pagestats pages="plugins/type/* and !plugins/type/slow"]]
+[[!pagestats pages="plugins/type/* and !plugins/type/slow" among="plugins/*"]]
 
 There's documentation if you want to [[write]] your own plugins, or you can
 [[install]] plugins [[contributed|contrib]] by others.
@@ -13,7 +13,5 @@ will fit most uses of ikiwiki.
 
 ## Plugin directory
 
-[[!inline pages="plugins/* and !plugins/type/* and !plugins/write and 
-!plugins/write/* and !plugins/contrib and !plugins/install and !*/Discussion"
-feedpages="created_after(plugins/graphviz)" archive="yes" sort=title
-rootpage="plugins/contrib" postformtext="Add a new plugin named:" show=0]]
+[[!map pages="plugins/* and !plugins/type/* and !plugins/write and 
+!plugins/write/* and !plugins/contrib and !plugins/install and !*/Discussion"]]
diff --git a/doc/plugins/contrib.mdwn b/doc/plugins/contrib.mdwn
index a03e6a95d..ac6c1b751 100644
--- a/doc/plugins/contrib.mdwn
+++ b/doc/plugins/contrib.mdwn
@@ -1,6 +1,4 @@
 These plugins are provided by third parties and are not currently
 included in ikiwiki. See [[install]] for installation help.
 
-[[!inline pages="plugins/contrib/* and !*/Discussion" 
-feedpages="created_after(plugins/contrib/navbar)" archive="yes"
-rootpage="plugins/contrib" postformtext="Add a new plugin named:" show=0]]
+[[!map pages="plugins/contrib/* and !*/Discussion"]]
diff --git a/doc/plugins/orphans.mdwn b/doc/plugins/orphans.mdwn
index ea7c4df13..e403c2d18 100644
--- a/doc/plugins/orphans.mdwn
+++ b/doc/plugins/orphans.mdwn
@@ -10,5 +10,6 @@ Here's a list of orphaned pages on this wiki:
 
 [[!orphans pages="* and !news/* and !todo/* and !bugs/* and !users/* and
 !recentchanges and !examples/* and !tips/* and !sandbox/* and !templates/* and
+!forum/* and !*.js and
 !wikiicons/* and !plugins/*"]]
 """]]
diff --git a/doc/plugins/sidebar.mdwn b/doc/plugins/sidebar.mdwn
index 36982eff3..4e356d65a 100644
--- a/doc/plugins/sidebar.mdwn
+++ b/doc/plugins/sidebar.mdwn
@@ -16,6 +16,10 @@ will turn off the sidebar altogether.
 
 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 [[inline]] or [[map]]
-directives, since any changes to pages inlined or mapped onto the sidebar
+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
+included in the map will cause a full rebuild. Modifying pages will not.
diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 8e8c3311e..c72418c3c 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -609,21 +609,60 @@ 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.
 
-#### `add_depends($$;@)`
+### `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.
+
+#### `pagespec_match_list($$;@)`
+
+Passed a page name, and [[ikiwiki/PageSpec]], returns a list of pages
+in the wiki that match the [[ikiwiki/PageSpec]]. 
+
+The page will automatically be made to depend on the specified
+[[ikiwiki/PageSpec]], so `add_depends` does not need to be called. This
+is often significantly more efficient than calling `add_depends` and
+`pagespec_match` in a loop. You should use this anytime a plugin
+needs to match a set of pages and do something based on that list.
+
+Unlike pagespec_match, this may throw an error if there is an error in
+the pagespec.
+
+Additional named parameters can be specified:
+
+* `deptype` optionally specifies the type of dependency to add. Use the
+  `deptype` function to generate a dependency type.
+* `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.
+* `reverse` if true, sorts in reverse.
+* `num` if nonzero, specifies the maximum number of matching pages that
+  will be returned.
+* `list` makes it only match amoung the specified list of pages.
+  Default is to match amoung all pages in the wiki.
+
+Any other named parameters are passed on to `pagespec_match`, to further
+limit the match.
+
+#### `add_depends($$;$)`
 
 Makes the specified page depend on the specified [[ikiwiki/PageSpec]].
 
 By default, dependencies are full content dependencies, meaning that the
 page will be updated whenever anything matching the PageSpec is modified.
-This default can be overridden by additional named parameters, which can be
-used to indicate weaker types of dependencies:
-
-* `presence` if set to true, only the presence of a matching page triggers
-  the dependency.
-* `links` if set to true, any change to links on a matching page
-  triggers the dependency. 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.
+This can be overridden by passing a `deptype` value as the third parameter.
 
 #### `pagespec_match($$;@)`
 
@@ -639,19 +678,6 @@ 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.
 
-#### `pagespec_match_list($$;@)`
-
-Passed a reference to a list of page names, and [[ikiwiki/PageSpec]],
-returns the set of pages that match the [[ikiwiki/PageSpec]].
-
-Additional named parameters can be passed, to further limit the match.
-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.
-
-Unlike pagespec_match, this may throw an error if there is an error in
-the pagespec.
-
 #### `bestlink($$)`
 
 Given a page and the text of a link on the page, determine which
@@ -982,6 +1008,15 @@ an IkiWiki::FailReason object if the match fails. If the match cannot be
 attempted at all, for any page, it can instead return an
 IkiWiki::ErrorReason object explaining why.
 
+When constructing these objects, you should also include information about
+of any pages whose contents or other metadata influenced the result of the
+match. Do this by passing a list of pages, followed by `deptype` values.
+
+For example, "backlink(foo)" is influenced by the contents of page foo;
+"link(foo)" and "title(bar)" are influenced by the contents of any page
+they match; "created_before(foo)" is influenced by the metadata of foo;
+while "glob(*)" is not influenced by the contents of any page.
+
 ### Setup plugins
 
 The ikiwiki setup file is loaded using a pluggable mechanism. If you look
diff --git a/doc/style.css b/doc/style.css
index 4770fc942..be86a0818 100644
--- a/doc/style.css
+++ b/doc/style.css
@@ -403,7 +403,6 @@ span.color {
 }
 
 /* Used by the highlight plugin. */
-
 pre.hl { color:#000000; background-color:#ffffff; }
 .hl.num { color:#2928ff; }
 .hl.esc { color:#ff00ff; }
@@ -419,3 +418,7 @@ pre.hl { color:#000000; background-color:#ffffff; }
 .hl.kwb { color:#830000; }
 .hl.kwc { color:#000000; font-weight:bold; }
 .hl.kwd { color:#010181; }
+
+/* For the calendar plugin. */
+.month-calendar-day-this-day { background-color: #eee; }
+.year-calendar-this-month { background-color: #eee; }
diff --git a/doc/todo/dependency_types.mdwn b/doc/todo/dependency_types.mdwn
index 2bdf1d6a3..4db633ead 100644
--- a/doc/todo/dependency_types.mdwn
+++ b/doc/todo/dependency_types.mdwn
@@ -280,6 +280,7 @@ sigh.
   that the page links to, which is just what link dependencies are
   triggered on.
 
+[[done]]
 ----
 
 ### the removal problem
diff --git a/doc/translation.mdwn b/doc/translation.mdwn
index d869a6821..9d874d98e 100644
--- a/doc/translation.mdwn
+++ b/doc/translation.mdwn
@@ -23,7 +23,7 @@ essentially three pieces needed for a complete translation:
      file, and in preprocessor directives.
 
 1. The [[basewiki]] needs to be translated. The
-   [[plugins/contrib/po]] ikiwiki plugin will allow translating
+   [[plugins/po]] ikiwiki plugin will allow translating
    wikis using po files and can be used for this.
 
    There is now a website, [l10n.ikiwiki.info](http://l10n.ikiwiki.info)