b462948ebc3d0f65ad2ccd21be08f7e03e8cb622
[ikiwiki.git] / doc / bugs / listdirectives_doesn__39__t_register_a_link.mdwn
1 The [[ikiwiki/directive/listdirectives]]` directive doesn't register a link between the page and the subpages. This is a problem because then the [[ikiwiki/directive/orphans]] directive then marks the directives as orphans... Maybe it is a but with the orphans directive however... A simple workaround is to exclude those files from the orphans call... --[[anarcat]]
2
3 > There's a distinction between wikilinks (matched by `link()`,
4 > `backlink()` etc.) and other constructs that produce a
5 > hyperlink. Some directives count as a wikilink (like `tag`)
6 > but many don't (notably `inline`, `map`, `listdirectives`,
7 > and `orphans` itself). As documented in
8 > [[ikiwiki/directive/orphans]], orphans will tend to list
9 > pages that are only matched by inlines/maps, too.
10 >
11 > The rule of thumb seems to be that a link to a particular
12 > page counts as a wikilink, but a directive that lists
13 > pages matching some pattern does not; so I think
14 > `listdirectives` is working as intended here.
15 > `orphans` itself obviously shouldn't count as a wikilink,
16 > because that would defeat the point of it :-)
17 >
18 > Anything that uses a [[ikiwiki/pagespec]] to generate links,
19 > like `inline` and `map`, can't generate wikilinks, because
20 > wikilinks are gathered during the scan phase, and pagespecs
21 > can't be matched until after the scan phase has finished
22 > (otherwise, it'd be non-deterministic whether all wikilinks
23 > had been seen yet, and `link()` in pagespecs wouldn't work
24 > predictably).
25 >
26 > I suggest just using something like:
27 >
28 >     \[[!orphans pages="* and !blog/* and !ikiwiki/directive/*"]]
29 >
30 > This wiki's example of listing [[plugins/orphans]] has a
31 > more elaborate pagespec, which avoids bugs, todo items etc.
32 > as well.
33 >
34 > --[[smcv]]
35
36 > No follow-up or objection for a while, so considering this to
37 > be working as designed. --[[smcv]]
38
39 > > Seems I'm a bit late to butt in, but would it be possible to have two
40 > > further phases after the scan phase, the first running map and inline 
41 > > and the second orphan? Then map and inline could log or register their 
42 > > links (obviously somewhere were it won't change the result of the link function)
43 > > and orphan could take them into account. This logging could be
44 > > turned on by parameter to not waste time for users not needing this and 
45 > > make it tunable (i.e. so that the user can decide which map directives count and which don't)
46 > > 
47 > > For someone using map and especially autoindex the output of the orphans directive
48 > > is simply wrong/useless (at least it is for me). And there is no easy workaround like for listdirectives
49 > > -- [[holger]]
50
51 >>> Hmm. I think this can be done without introducing any "phases",
52 >>> even, but it would require each plugin that generates links according
53 >>> to a pagespec to have either a conditional call into the orphans plugin,
54 >>> or a call to a new core function in ikiwiki that exists solely to
55 >>> support the orphans plugin. Something like this, maybe:
56 >>>
57 >>>     # in map.pm, inline.pm, pagestats.pm etc., at scan time
58 >>>     if (IkiWiki::Plugin::orphans->can("add_reachable")) {
59 >>>         IkiWiki::Plugin::orphans::add_reachable($page, $pagespec);
60 >>>     }
61 >>>
62 >>>     # in orphans.pm (pseudocode; note that this does not *evaluate*
63 >>>     # $pagespec, only stores it, so it's OK to do this at scan time)
64 >>>     sub needsbuild ($pages)
65 >>>         for each page in $pages
66 >>>             clear $pagestate{location}{orphans}{reachable}
67 >>>     sub reachable ($location, $pagespec)
68 >>>         add $pagespec to @{$pagestate{location}{orphans}{reachable}}
69 >>>
70 >>>     # in preprocess function in orphans.pm (pseudocode)
71 >>>     # executed at build time, not at scan time, so pagespecs work
72 >>>
73 >>>     for each maybe_orphan with no links to it
74 >>>         for each location with a list of reachable pagespecs
75 >>>             make the page with the orphans directive depend on \
76 >>>                 the page that is the location
77 >>>             for each of those pagespecs
78 >>>                 if pagespec matches orphan
79 >>>                     take orphan off the list
80 >>>                     go to next orphan
81 >>>     output list of orphans
82 >>>
83 >>> (Maybe parentlinks should also annotate the parent/ancestors of
84 >>> each page as reachable from that page.)
85 >>>
86 >>> Do other people (mainly Joey) think that'd be acceptable, or
87 >>> too intrusive?
88 >>>
89 >>> Taking this off the list of resolved bugs again while we think about it.
90 >>>
91 >>> I suspect that in the presence of autoindex, what you really want might
92 >>> be less "there's a link to it" and more "there's a path to it from
93 >>> the root of the wiki", which is why I called the proposed function
94 >>> "add_reachable". On the other hand, maybe that's too computationally
95 >>> intensive to actually do; I haven't tried it.
96 >>> --[[smcv]]