doc/bugs/pagetitle_function_does_not_respect_meta_titles.mdwn

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