doc/plugins/trail/discussion.mdwn

   1 I believe the `trail3-integrated` and `trail3-prebuild` branches address
   2 Joey's review comments from IRC:
   3
   4     06-12-2011 19:01:07 <joeyh>: ok, light review finished. so, if you want
   5     to make a branch with inline trail=yes, and perhaps also adding a hook
   6     so you don't need to inject, I think I can merge it right away
   7
   8 I haven't published instructions for using this version as a
   9 standalone plugin, because it needs core and inline changes.
  10
  11 Commits up to 63bb8b42 make the trail plugin better-integrated,
  12 including `\[[!inline trail=yes]]`. 63bb8b42 is the commit to
  13 merge if you don't like the design of my hooks.
  14
  15 Commit 24168b99 adds a `build_affected` hook, run at about the
  16 same time as `render_backlinks`, and uses it to render the
  17 extra pages. This removes the need for `trail` to inject
  18 anything. In principle, backlinks etc. could use this hook
  19 too, if they weren't core.
  20
  21 Commit d0dea308 on the `trail3-prebuild` branch adds a
  22 `prebuild` hook, which runs after everything has been scanned
  23 but before anything is rendered. This removes the need
  24 for `trail` to run its old `prerender` function in its
  25 render hooks (preprocess, pagetemplate etc.) to collate
  26 metadata before it renders anything. However, I'm not sure
  27 that this is really the right thing to do, which is why it's
  28 in its own branch: the `prebuild` hook is a lot like
  29 `needsbuild` (but later), so it's called even if no trail
  30 or trail member has actually been edited.
  31
  32 For it to be useful for `trail`, the `prebuild` hook has to run
  33 after both pagespecs and sorting work. The other use case
  34 I've seen for a similar hook was for Giuseppe Bilotta to
  35 sort an inline-of-inlines by mtime of newest post, but that
  36 can't be the same hook, because it has to run after pagespecs
  37 work, but before sorting.
  38
  39 --[[smcv]]
  40
  41 > I've merged trail3-integrated, but not prebuild. I don't exactly dislike
  42 > prebuild, but dunno that the hook prolieration is worth the minor cleanup
  43 > it allows in trail. --[[Joey]]
  44
  45 >> Hmm, t/trail.t is failing several tests here. To reproduce, I build the
  46 >> debian package from a clean state, or `rm -rf .t` between test runs. --[[Joey]]
  47
  48 <pre>
  49 t/trail.t .................... 1/?
  50 #   Failed test at t/trail.t line 211.
  51 #   Failed test at t/trail.t line 213.
  52 #   Failed test at t/trail.t line 215.
  53 #   Failed test at t/trail.t line 217.
  54 #   Failed test at t/trail.t line 219.
  55 #   Failed test at t/trail.t line 221.
  56 #   Failed test at t/trail.t line 223.
  57 #   Failed test at t/trail.t line 225.
  58 #   Failed test at t/trail.t line 227.
  59 #   Failed test at t/trail.t line 229.
  60 #   Failed test at t/trail.t line 231.
  61 </pre>
  62
  63 > Looking at the first of these, it expected "trail=sorting n=sorting/new p="
  64 > but gets: "trail=sorting n=sorting/ancient p=sorting/new"
  65 >
  66 > Looking at the second failure, it expected "trail=sorting n=sorting/middle p=sorting/old$"
  67 > but got: "trail=sorting n=sorting/old p=sorting/end"
  68 >
  69 > Perhaps a legitimate bug? --[[Joey]]
  70
  71 >> I saw this while developing, but couldn't reproduce it, and assumed
  72 >> I'd failed to update `blib` before `make test`, or some such.
  73 >> In fact it's a race condition, I think.
  74 >>
  75 >> The change and failure here is that `sorting.mdwn` is modified
  76 >> to sort its trail in reverse order of title. Previously, it
  77 >> was sorted by order of directives in the page, and secondarily
  78 >> by whatever sort order each directive specified (e.g.
  79 >> new, old and ancient were sorted by increasing age).
  80 >> `old` appearing between `new` and `ancient`, and `new` appearing
  81 >> between `end` and `old`, indicates that this re-sorting has not
  82 >> actually taken effect, and the old sort order is still used.
  83 >>
  84 >> I believe this is because the system time (as an integer) remained
  85 >> the same for the entire test, and mtimes as used in ikiwiki
  86 >> only have a 1-second resolution. We can either fix this with
  87 >> utime or sleep; I chose utime, since sleeping for 1 second would
  88 >> slow down the test significantly. Please merge or cherry-pick
  89 >> `smcv/trail-test` (there's only one commit). --[[smcv]]
  90
  91 ----
  92
  93 [[!template id=gitbranch branch=smcv/ready/trail author=smcv]]
  94
  95 Some later changes to trail:
  96
  97 * Display the trail links at beginning/end of default `page.tmpl`
  98   as suggested on IRC
  99 * Improve CSS, particularly in blueview and goldtype themes
 100   ([example](http://blueview.hosted.pseudorandom.co.uk/posts/second_post/))
 101 * Fix a possible bug regarding state deletion
 102
 103 --[[smcv]]
 104
 105 > Applied --[[Joey]]
 106
 107 ----
 108
 109 ### Trail plugin creates unexpected interdependencies?
 110 *(ikiwiki master branch 2014-06-06 also tested with 3.20140228 release)*
 111
 112 I noticed the problem when using the [[/plugins/contrib/album]] plugin but a bit of testing revealed that the [[trail]] plugin, which is used by [[/plugins/contrib/album]] may be the cause of the problem.
 113
 114 On a site with the following structure where all albumN.mdwn files have the `\[[!inline  pages="page(./album01/*)" trail="yes"]]` directive set. All albumN pages and imgN pages get rebuilt whenever any one of the albumN or imgN pages are changed and the command  `ikiwiki --setup wiki.setup --refresh --verbose`
 115  is issued.
 116
 117     /index.mdwn                        Contains no links maps or inlines
 118     |-album01.mdwn                 \[[!inline  pages="page(./album01/*)" trail="yes"]]
 119     |-album01/
 120     | |-imgA.mdwn
 121     | |-imgB.mdwn
 122     |
 123     |-album02.mdwn                 \[[!inline  pages="page(./album02/*)" trail="yes"]]
 124     |-album02/
 125     | |-imgC.mdwn
 126     | |-imgD.mdwn
 127     |
 128     |-album03.mdwn                 \[[!inline  pages="page(./album03/*)" trail="yes"]]
 129     |-album03/
 130     | |-imgE.mdwn
 131     | |-imgF.mdwn
 132
 133 Changing the index.mdwn page also triggers a full rebuild of all pages with [[trail]] directives. My sites tend to look like the above but with double digit numbers of files in at each level. Changing any file then means a full rebuild of a rather complex site which takes a long time.
 134
 135 My setup and test may very well have mistakes but perhaps someone using the trail plugin could check (using the --verbose flag) if all their trails get rebuild when changing only one. I also find it curious that changes to the parent index.mdwn page triggers the same behaviour.
 136
 137 I have removed a similar comment from the album discussion.
 138
 139  --[[kjs]]
 140
 141 > I would expect changing imgE.mdwn to rebuild album03.mdwn (because album03
 142 > inlines imgE) and vice versa (because imgE uses album03's \[[!meta title]]).
 143 >
 144 > I would not expect changing imgE.mdwn or album03.mdwn to affect album02
 145 > or imgC.
 146 >
 147 > I would also not expect changing index.mdwn to rebuild anything else
 148 > unless there is a valid dependency reason to do so.
 149 >
 150 > Can you reproduce this problem in a wiki that does not contain anything
 151 > private, and publish its git repo somewhere? (I realise photo galleries
 152 > tend to be more personal/private than typical wikis, so you don't
 153 > necessarily want to link the real thing - that's why my album demos
 154 > tend to use dummy data). --[[smcv]]
 155
 156 >> I was expecting the same depends pattern you describe.
 157 >> My photo wikis are mostly public so I've set up a publicly accessible repo
 158 >> (update-server-info type, git clone the first link below), a low-res copy of
 159 >> the underlay and a quick sanitized setup file.
 160
 161 >>* [[http://www.kalleswork.net/downloads/stockholm/.git]]
 162 >>* [[http://www.kalleswork.net/downloads/stockholm.underlay.tar.gz]]
 163 >>* [[http://www.kalleswork.net/downloads/stockholm.setup]]
 164
 165 >> It might be a bit unwieldly and the site itself at [[http://stockholm.kalleswork.net]]
 166 >> uses a few tweaks to the album templates and css, but I don't currently
 167 >> have access to the machine where I setup a cleaner debug wiki to test.
 168 >> (travelling atm). The images will likely be distorted due to the up scaling
 169 >> bug in the [[img]] plugin but other than that it should work.
 170
 171 >> Let me know if you need anything else. Would be great to hear it works
 172 >> as expected for everyone else ;) --[[kjs]]
 173
 174 >>> Hmm. Investigating the indexdb:
 175 >>>
 176 >>>     perl -le 'use Storable; my $index = Storable::retrieve("stockholm/.ikiwiki/indexdb"); use Data::Dumper; print Dumper $index' |less
 177 >>>
 178 >>> indicates that `20130504` depends on `internal(*)` and so does `20130505`.
 179 >>>
 180 >>> After adding some `Carp::cluck` calls to the bits of IkiWiki.pm that add
 181 >>> dependencies, this turns out to be two similar issues, in `album` and
 182 >>> `trail`: they each use `pagespec_match_list` with the pagespec
 183 >>> `internal(*)` in order to apply a trivial filter (accept everything)
 184 >>> to an existing list for its side-effect of sorting that list.
 185 >>> Bug filed as [[bugs/trails depend on everything]] --smcv