Welcome to 2019
[ikiwiki.git] / doc / todo / edittemplate_should_support_uuid__44___date_variables.mdwn
1 [[!template id=gitbranch branch=anderbubble/edittemplate author="Jonathon Anderson"]]
2 [[!tag wishlist patch]]
3
4 I use a default template for all new pages:
5
6     \[[!meta title="<TMPL_VAR name>"]]
7     \[[!meta author=]]
8     \[[!meta date="<TMPL_VAR time>"]]
9     \[[!meta guid="urn:uuid:<TMPL_VAR uuid>"]]
10     \[[!tag ]]
11
12 This encourages me to include useful metadata on the page.  In particular, though, I've modified the `edittemplate` plugin to generate a uuid for use in the guid, for use in `inline`.  Importantly, this keeps `inline` from flooding aggregators when I rename these pages.
13
14 I've also noticed that IkiWiki seems to use the creation time for the generated page for the page date.  This means that when I do a rebuild, `inline`d pages get shuffled.  The inclusion of a `time` variable in `edittemplate` (and in a `meta` declaration for all such pages) prevents the date from changing unexpectedly.
15
16 I've already made these changes in my installation, and have made my patches available in the `edittemplate` branch of git://civilfritz.net/ikiwiki.git.
17
18 Changes to the structure of `$pagestate{$registering_page}{edittemplate}{$pagespec}` mean that a `cgi` rebuild is necessary (for reasons I don't entirely understand); but I think that's preferable to creating an entirely separate `$pagestate` namespace for storing parameters.  That said, I'm not really a perl programmer, so corrections are welcome.
19
20 > I like this patch. I hate seeing things I've already read get marked as unread in my rss feed. -- [[JoshBBall]]
21
22 >> (I don't have commit access so take this with a pinch of salt -
23 >> I'm just trying to help deal with the code-review backlog.)
24 >>
25 >> I mostly like the first and third patches in the branch (adding v4
26 >> (random) UUIDs, and adding the timestamps). I'd be tempted to rename
27 >> `time` and `formatted_time` to `iso_time` and `time`, but that's
28 >> a matter of taste, and perhaps people with commit access have
29 >> stronger opinions one way or another. I haven't researched
30 >> whether there's precendent for any particular naming style
31 >> elsewhere in ikiwiki.
32 >>
33 >> The UUID bit would require adding some reference to libuuid-tiny-perl
34 >> to the Debian packaging - I think a `Recommends` is too strong
35 >> but a `Suggests` seems OK.
36 >>
37 >> I don't like the second patch (adding URL-namespaced UUID support).
38 >> I'm having a hard time thinking of any situation in which a v4 UUID
39 >> would be unsuitable, which means it's unnecessary complexity.
40 >> FYI, the reason that it makes a rebuild is necessary is that
41 >> you've restructured `$pagestate`, which is carried over from one
42 >> refresh to the next (that's its purpose), and you haven't
43 >> built in any migration or backwards-compatibility code that will
44 >> cope with it being in the old format. My inclination would be to
45 >> drop that patch. If there's a really good reason to prefer
46 >> v3/v5 UUIDs, please describe it and I'll try to suggest some
47 >> better way based on that, maybe global configuration in `$config`.
48 >> --[[smcv]]
49
50 >>> [[!template id=gitbranch branch=smcv/ready/edittemplate2
51   browse=http://git.pseudorandom.co.uk/smcv/ikiwiki.git/shortlog/refs/heads/ready/edittemplate2
52   author="Jonathon Anderson, [[smcv]]"]]
53 >>> Here is a version of that branch that I [[would merge|users/smcv/ready]] if I could.
54 >>> Changes since Jonathon's version:
55 >>>
56 >>> * only generate a UUID if needed
57 >>> * read `/proc/sys/kernel/random/uuid` instead of using [[!cpan UUID::Tiny]]
58 >>>   if available, to avoid the dependency on at least Linux
59 >>> * remove v3/v5 UUID support since I don't really see the point,
60 >>>   and if included, it would need a migration path for `$pagestate`
61 >>> * use RFC 3339 time format for `time` to make the timezone unambiguous
62 >>> * add `html_time` which is the output of `IkiWiki::displaytime`, e.g.
63 >>>   a `<time>` element on HTML5 wikis
64 >>>
65 >>> I'm not entirely sure what the use-case is for `formatted_time`,
66 >>> so perhaps either `html_time` or `formatted_time` should be
67 >>> removed; but it's not as if they really cost anything.
68 >>>
69 >>> There doesn't seem to be any strong convention for how we name
70 >>> timestamp variables/objects, so I left the naming as it was.
71 >>>
72 >>> --[[smcv]]
73
74 >>>> the ready/edittemplate branch looks good to me too. `formatted_time` and
75 >>>> `html_time` probably don't hurt, but personally i'd not add either and
76 >>>> instead expose displaytime as a directive, for otherwise migrating to
77 >>>> html5 would leave old evaluations of displaytime around in the repository.
78 >>>> (example template: `\[[!meta date="<TMPL_VAR time>"]]I wrote this post at
79 >>>> \[[!displaytime "<TMPL_VAR time>"]]`). --[[chrysn]]
80
81 >>>>> That's a very good point; and Joey added `\[[!date "<TMPL_VAR time">]]`,
82 >>>>> which does the same thing as your hypothetical `\[[!displaytime]]`,
83 >>>>> almost 5 years ago. Branch replaced by `smcv/ready/edittemplate2`
84 >>>>> which drops `formatted_time` and `html_time`, and adds a suggestion
85 >>>>> to use `\[[!date]]`. --[[smcv]]
86
87 >>>>>> [[merged|done]] --[[smcv]]