Merge remote branch 'smcv/trivia'
[ikiwiki] / doc / bugs / pagetitle_function_does_not_respect_meta_titles.mdwn
1 [[!tag patch plugins/inline patch/core]]
2
3 The `IkiWiki::pagetitle` function does not respect title changes via `meta.title`. It really should, so that links rendered with `htmllink` get the proper title in the link text.
4
5 --[[madduck]]
6
7 ----
8
9 It is possible to set a Page-Title in the meta-plugin, but that one isn't
10 reused in parentlinks. This patch may fix it.
11
12 <ul>
13 <li> I give pagetitle the full path to a page.
14 <li> I redefine the 'pagetitle'-sub to deal with it.
15 <li> to maintain compatibility for IkiWikis without the meta-plugin, i added a 'basename' to the Original-pagetitle.
16 </ul>
17
18 <pre>
19 diff -c /usr/share/perl5/IkiWiki/Render.pm.distrib /usr/share/perl5/IkiWiki/Render.pm
20 *** /usr/share/perl5/IkiWiki/Render.pm.distrib  Wed Aug  6 07:34:55 2008
21 --- /usr/share/perl5/IkiWiki/Render.pm  Tue Aug 26 23:29:32 2008
22 ***************
23 *** 102,108 ****
24         $template->param(
25                 title => $page eq 'index' 
26                         ? $config{wikiname} 
27 !                       : pagetitle(basename($page)),
28                 wikiname => $config{wikiname},
29                 content => $content,
30                 backlinks => $backlinks,
31 --- 102,108 ----
32         $template->param(
33                 title => $page eq 'index' 
34                         ? $config{wikiname} 
35 !                       : pagetitle($page),
36                 wikiname => $config{wikiname},
37                 content => $content,
38                 backlinks => $backlinks,
39
40 diff -c /usr/share/perl5/IkiWiki/Plugin/parentlinks.pm.distrib /usr/share/perl5/IkiWiki/Plugin/parentlinks.pm
41 *** /usr/share/perl5/IkiWiki/Plugin/parentlinks.pm.distrib      Wed Aug  6 07:34:55 2008
42 --- /usr/share/perl5/IkiWiki/Plugin/parentlinks.pm      Tue Aug 26 23:19:43 2008
43 ***************
44 *** 44,50 ****
45                         "height_$height" => 1,
46                 };
47                 $path.="/".$dir;
48 !               $title=IkiWiki::pagetitle($dir);
49                 $i++;
50         }
51         return @ret;
52 --- 44,50 ----
53                         "height_$height" => 1,
54                 };
55                 $path.="/".$dir;
56 !               $title=IkiWiki::pagetitle($path);
57                 $i++;
58         }
59         return @ret;
60
61 diff -c /usr/share/perl5/IkiWiki.pm.distrib /usr/share/perl5/IkiWiki.pm
62 *** /usr/share/perl5/IkiWiki.pm.distrib Wed Aug  6 07:48:34 2008
63 --- /usr/share/perl5/IkiWiki.pm Tue Aug 26 23:47:30 2008
64 ***************
65 *** 792,797 ****
66 --- 792,799 ----
67         my $page=shift;
68         my $unescaped=shift;
69   
70 +       $page=basename($page);
71
72         if ($unescaped) {
73                 $page=~s/(__(\d+)__|_)/$1 eq '_' ? ' ' : chr($2)/eg;
74         }
75
76 diff -c /usr/share/perl5/IkiWiki/Plugin/meta.pm.distrib /usr/share/perl5/IkiWiki/Plugin/meta.pm
77 *** /usr/share/perl5/IkiWiki/Plugin/meta.pm.distrib     Wed Aug  6 07:34:55 2008
78 --- /usr/share/perl5/IkiWiki/Plugin/meta.pm     Tue Aug 26 23:30:58 2008
79 ***************
80 *** 3,8 ****
81 --- 3,9 ----
82   package IkiWiki::Plugin::meta;
83   
84   use warnings;
85 + no warnings 'redefine';
86   use strict;
87   use IkiWiki 2.00;
88   
89 ***************
90 *** 289,294 ****
91 --- 290,319 ----
92         }
93   }
94   
95 + sub IkiWiki::pagetitle ($;$) {
96 +       my $page=shift;
97 +       my $unescaped=shift;
98
99 +       if ($page =~ m#/#) {
100 +               $page =~ s#^/##;
101 +               $page =~ s#/index$##;
102 +               if ($pagestate{"$page/index"}{meta}{title}) {
103 +                       $page = $pagestate{"$page/index"}{meta}{title};
104 +               } else {
105 +                       $page = IkiWiki::basename($page);
106 +               }
107 +       }
108
109 +       if ($unescaped) {
110 +               $page=~s/(__(\d+)__|_)/$1 eq '_' ? ' ' : chr($2)/eg;
111 +       }
112 +       else {
113 +               $page=~s/(__(\d+)__|_)/$1 eq '_' ? ' ' : "&#$2;"/eg;
114 +       }
115
116 +       return $page;
117 + }
118
119   package IkiWiki::PageSpec;
120   
121   sub match_title ($$;@) {
122
123 </pre>
124
125 ----
126
127 > A few quick notes about it:
128
129 > - Using <code>inline</code> would avoid the redefinition + code duplication.
130 > - A few plugins would need to be upgraded.
131 > - It may be necessary to adapt the testsuite in `t/pagetitle.t`, as well.
132 >
133 > --[[intrigeri]]
134 >
135 >> It was actually more complicated than expected. A working prototype is
136 >> now in my `meta` branch, see my userpage for the up-to-date url.
137 >> Thus tagging patch. --[[intrigeri]]
138 >>
139 >>> Joey, please consider merging my `meta` branch. --[[intrigeri]]
140
141 So, looking at your meta branch: --[[Joey]] 
142
143 * Inter-page dependencies. If page A links to page B, and page B currently
144   has no title, then A will display the link as "B". Now page B is modified
145   and a title is added. Nothing updates "A".
146   The added overhead of rebuilding every page that links to B when B is
147   changed (as the `postscan` hook of the po plugin does) is IMHO a killer.
148   That could be hundreds or thousands of pages, making interactive editing
149   way slow. This is probably the main reason I had not attempted this whole
150   thing myself. IMHO this calls for some kind of intellegent dependency
151   handler that can detect when B's title has changed and only rebuild pages
152   that link to B in that case.
153 * Looks like some plugins that use `pagetitle` to format it for display
154   were not changed to use `nicepagetitle` (for example, rename).
155   But most of those callers intend to display the page name
156   as a title, but including the parent directories in the path. (Ie,
157   "renaming foo/page title to bar/page title" -- 
158   you want to know it's moved from foo to bar.) `nicepagetitle` does not
159   allow doing that since it always takes the `basename`.
160 * I don't like the name `nicepagetitle`. It's not very descriptive, is it?
161   And it seems very confusing to choose whether to use the "nice" or original
162   version. My hope is that adding a second function is unnecessary.
163   As I understand it, you added a new function for two reasons: 
164   1) It needs the full page name, not basename.
165   2) `titlepage(pagetitle($page))` reversability.
166   
167   1) If you look at all the callers
168   Of `pagetitle` most of them pass a complete page name, not just the
169   basename. In most cases `pagetitle` is used to display the full name
170   of the page, including any subdirectory it's in. So why not just make
171   it consitently be given the full name of the page, with another argument
172   specifying if we want to get back just the base name.
173
174   2) I can't find any code that actually uses the reversability like that.
175   The value passed to `titlepage` always comes from some external
176   source. Unless I missed one.
177 * The use of `File::Spec->rel2abs` is a bit scary.
178 * Does it really make sense to call `pagetitle` on the meta title
179   in meta's `nicepagetitle`? What if the meta title is something like
180   "foo_bar" -- that would be changed to "foo bar".
181 * parentlinks is changed to use `nicepagetitle(bestlink($page, $path))`.
182   Won't `bestlink` return "" if the parent page in question does not exist?
183 * `backlinks()` is changed to add an additional `title` field
184   to the hash returned, but AFAICS this is not used in the template.
185 * Shouldn't `Render.pm` use nicepagetitle when getting the title for the
186   page template? Then meta would not need to override the title in the
187   `pagetemplate` hook. (Although this would eliminate handling of
188   `title_overridden` -- but that is little used and would not catch
189   all the other ways titles can be overridden with this patch anyway.)
190
191 > I'm not a reviewer or anything, but can I chime in on changes to pagetitle?
192 > I don't think having meta-titles in wikilinks and the parentlinks path by
193 > default is necessarily a good thing. I don't consider the meta-title of a page
194 > as used in `<title>` to be the same thing as the short title you
195 > want in those contexts - IMO, the meta-title is the "formal" title of the page,
196 > enough to identify it with no other context, and frequently too long to be used
197 > as a link title or a parentlink, whereas the parentlinks title in particular
198 > should be some abbreviated form that's enough to identify it in context.
199 > [tbm](http://www.cyrius.com/) expressed a similar opinion when I was discussing
200 > ikiwiki with him at the weekend.
201 >
202 > It's a matter of taste whether wikilinks are "like a parentlink" or "like a
203 > `<title>`"; I could be persuaded either way on that one.
204 >
205 > An example from my site: [this page](http://www.pseudorandom.co.uk/2004/debian/ipsec/)
206 > is the parent of [this page](http://www.pseudorandom.co.uk/2004/debian/ipsec/wifi/)
207 > with a title too long to use in the latter's parentlinks; I think the titles of
208 > both those pages are too long to use as wikilink text too. Similarly, tbm's page
209 > about [Debian on Orion devices from Buffalo](http://www.cyrius.com/debian/orion/buffalo/)
210 > can simply be called "Buffalo" in context.
211 >
212 > Having a `\[[!meta abbrev="..."]]` that took precedence over title
213 > in parentlinks and possibly wikilinks might be a good way to fix this? Or if your
214 > preference goes the other way, perhaps a `\[[!meta longtitle=""]]` could take
215 > precedence when generating the `<title>` and the title that comes after the
216 > parentlinks. --[[smcv]]
217
218 >> I think you've convinced me. (I had always had some doubt in my mind as
219 >> to whether using titles in all these other places would make sense.)
220 >> 
221 >> Instead of meta abbrev, you could have a meta pagename that
222 >> overrides the page name displayed everywhere (in turn overridden by
223 >> meta title iff the page's title is being displayed). But is this complexity
224 >> needed? We have meta redir, so if you want to change the name of a page,
225 >> you can just rename it, and put in a stub redirection page so links
226 >> still work.
227 >> 
228 >> This leaves the [[plugins/contrib/po]] plugin, which really does need
229 >> a way to change the displayed page name everywhere, and at least a
230 >> subset of the changes in the meta branch are needed to support that.
231 >> 
232 >> (This would also get around my concern about inter-page dependency
233 >> handling, since po contains a workaround for that, and it's probably
234 >> acceptable to use potentially slow methods to handle this case.)
235 >> --[[Joey]] 
236
237 >>> I'm glad to implement whatever decision we'll make, but I don't
238 >>> clearly understand what this discussion's conclusion is. It seems
239 >>> like we agree at least on one point: meta page titles shall not be
240 >>> displayed all over the place by default; I have therefore disabled
241 >>> `meta_overrides_page_title` by default in my `meta` branch.
242 >>> 
243 >>> My next question is then: do we only want to satisfy the `po`
244 >>> plugin needs? Or do we want to allow people who want this, such as
245 >>> [[madduck]], to turn on a config switch so that meta page titles
246 >>> are displayed as wikilinks titles? In the latter case, what level
247 >>> of configurability do we want? I can think of a quite inelegant
248 >>> way to implement full configurability, and provide a configuration
249 >>> switch for every place where links are displayed, such as
250 >>> wikilinks, parentlinks, etc., but I don't think the added bonus is
251 >>> worth the complexity of it.
252 >>> 
253 >>> I think we can roughly split the needs into three categories:
254 >>> 
255 >>> 1. never display any modified page title in links; this is the
256 >>>    current behaviour, and we should keep it as the default one
257 >>> 2. display modified page titles only at well chosen places; that
258 >>>    could be "manual" wikilinks, I mean those generated by the
259 >>>    `link`, `camelcase` & al. plugins, the recentchanges page, and
260 >>>    maybe a few other places; keep the usual pagename-based title
261 >>>    for every other link, such as the parentlinks ones.
262 >>>    The inter-page dependency problem remains, though. As a first
263 >>>    step, I'm in favour of the "slow, but correct" implementation,
264 >>>    with a big warning stating that enabling this option can make
265 >>>    a wiki really sluggish; if someone really wants this to work
266 >>>    fast, he/she'll implement a clever dependency handler :)
267 >>> 3. display modified page titles all over the place; IMHO, we
268 >>>    should implement only the bits needed so that the `po` plugin
269 >>>    can set this up, rather than provide this as
270 >>>    a user-configurable option.
271 >>> 
272 >>> So my question is: do we want to implement the #2 case, or not?
273 >>> I propose myself to only implement #1 and #3 to start with, but do
274 >>> it in a way that leaves room for #2.
275 >>> 
276 >>> --[[intrigeri]]
277 >>>
278 >>>> I agree, we should concentrate on getting just enough functionality
279 >>>> for the po plugin, because I want to merge the po plugin soon.
280 >>>> If #2 gets tackled later, we will certianly have all kinds of fun.
281 >>>> no matter what is done for the po plugin. --[[Joey]]