X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/8bb94bb197714fcac1ac48f9b330bef4d17dd800..d8607f5e73990e7802e03eef2065ebac102fbd2f:/doc/todo/dependency_types.mdwn?ds=inline diff --git a/doc/todo/dependency_types.mdwn b/doc/todo/dependency_types.mdwn index db7d06914..7e940543c 100644 --- a/doc/todo/dependency_types.mdwn +++ b/doc/todo/dependency_types.mdwn @@ -1,5 +1,24 @@ -Moved this relevant discussion to here from -[[tracking_bugs_with_dependencies]]: --[[Joey]] +Ikiwiki currently only has one type of dependency between pages +(plus wikilinks special cased in on the side). This has resulted in various +problems, and it's seemed for a long time to me that ikiwiki needs to get +smarter about what types of dependencies are supported. + +### unnecessary work + +The current single dependency type causes the depending page to be rebuilt +whenever a matching dependency is added, removed, or *modified*. But a +great many things don't care about the modification case, and often cause +unnecessary page rebuilds: + +* map only cares if the pages are added or removed. Content change does + not matter (unless show=title is used). +* brokenlinks, orphans, pagecount, ditto (generally) +* inline in archive mode cares about page title, author changing, but + not content. (Ditto for meta with show=title.) +* Causes extra work when solving the [[bugs/transitive_dependencies]] + problem. + +### two types of dependencies needed for [[tracking_bugs_with_dependencies]] >> it seems that there are two types of dependency, and ikiwiki >> currently only handles one of them. The first type is "Rebuild this @@ -81,3 +100,107 @@ Moved this relevant discussion to here from >>>>> For old-style pagespecs without backlinks, the dependency set for a pagespec is the same as the set of pages the pagespec matches. >>>>> Unfortunately, with existential matching, the set of pages that each >>>>> pagespec depends upon can quickly become "*", which is not very useful. -- [[Will]] + +### proposal + +I propose the following. --[[Joey]] + +* Add a second type of dependency, call it an "presence dependency". +* `add_depends` defaults to adding a regular ("full") dependency, as + before. (So nothing breaks.) +* `add_depends($page, $spec, presence => 0)` adds an presence dependency. +* `refresh` only looks at added/removed pages when resolving presence + dependencies. + +This seems straightforwardly doable. I'd like [[Will]]'s feedback on it, if +possible. The type types of dependencies I am proposing are not identical +to the two types he talks about above, but I hope are close enough that +they can be used. + +This doesn't deal with the stuff that only depend on the metadata of a +page, as collected in the scan pass, changing. But it does leave a window +open for adding such a dependency type later. + +---- + +I implemented the above in a branch. +[[!template id=gitbranch branch=origin/dependency-types author="[[joey]]"]] + +Then I found some problems: + +* Something simple like pagecount, that seems like it could use a + presence dependency, can have a pagespec that uses metadata, like + `author()` or `copyright()`. +* pagestats, orphans and brokenlinks cannot use presence dependencies + because they need to update when links change. + +Now I'm thinking about having a special dependency look at page +metadata, and fire if the metadata changes. And it seems links should +either be included in that, or there should be a way to make a dependency +that fires when a page's links change. (And what about backlinks?) + +It's easy to see when a page's links change, since there is `%oldlinks`. +To see when metadata is changed is harder, since it's stored in the +pagestate by the meta plugin. Also, there are many different types of +metadata, that would need to be matched with the pagespecs somehow. + +Quick alternative: Make add_depends look at the pagespec. Ie, if it +is a simple page name, or a glob, we know a presence dependency +can be valid. If's more complex, convert the dependency from +presence to full. + +There is a lot to dislike about this method. Its parsing of the pagespec, +as currently implemented, does not let plugins add new types of pagespecs +that only care about presence. Its pagespec parsing is also subject to +false negatives (though these should be somewhat rare, and no false +positives). Still, it does work, and it makes things like simple maps and +pagecounts much more efficient. + +---- + +### Link dependencies + +* `add_depends($page, $spec, links => 1, presence => 1)` + adds a links + presence dependency. +* `refresh` only rebuilds a page with a links dependency if + pages matched by the pagespec gain or lose links. (What the link + actually points to may change independent of this, due to changes + elsewhere, without it firing.) +* So, brokenlinks can fire whenever any links in any of the + pages it's tracking change, or when pages are added or + removed. +* To determine if a pagespec is valid to be used with a links dependency, + use the same set that are valid for presence dependencies. But also + allow `backlinks()` to be used in it, since that matches pages + that the page links to, which is just what link dependencies are + triggered on. + +---- + +### the removal problem + +So far I have not addressed fixing the removal problem (which Will +discusses above). + +Summary of problem: A has a dependency on a pagespec such as +"bugs/* and !link(done)". B currently matches. Then B is updated, +in a way that makes A's dependency not match it (ie, it links to done). +Now A is not updated, because ikiwiki does not realize that it +depended on B before. + +This was worked around to fix [[bugs/inline_page_not_updated_on_removal]] +by inline and map adding explicit dependencies on each page that appears +on them. Then a change to B triggers the explicit dep. While this works, +it's 1) ugly 2) probably not implemented by all plugins that could +be affected by this problem (ie, linkmap) and 3) is most of the reason why +we grew the complication of `depends_simple`. + +One way to fix this is to include with each dependency, a list of pages +that currently match it. If the list changes, the dependency is triggered. + +Should be doable, but seems to involve a more work than +currently. Consider that a dependency on "bugs/*" currently +is triggered by just checking until *one* page is found to match it. +But to store the list, *every* page would have to be tried against it. +Unless the list can somehow be intelligently updated, looking at only the +changed pages.