design-taste opinions?
[ikiwiki.git] / doc / todo / pick_a_new_canonical_name_for_equivalent_of_SQL_limit.mdwn
1 In [[todo/Option_linktext_for_pagestats_directive]] I wrote:
2
3 > It's unfortunate that map and pagestats have different meanings for
4 > the show parameter. I'm tempted to propose a patch that adds something
5 > like limit (by analogy with SQL) or max as the canonical name for the
6 > "number of things to match" parameter, at which point a non-numeric show
7 > could mean [what [[spalax]] proposed].
8
9 It isn't immediately obvious whether `show` should be used like
10 `\[[!map show=title]]` or like `\[[!inline show=10]]`. I can't think of
11 any better names for the "which property to display" parameter that don't
12 have the problem of being a synonym for show so you can't easily tell which
13 is which, and I think that suggests that it might be better to rename the
14 "number of items to display" parameter instead.
15
16 This would allow recycling the name `show` so that a non-numeric
17 value is interpreted analogous to `\[[!map show=title]]`,
18 for instance to solve [[todo/Option_linktext_for_pagestats_directive]].
19
20 If a committer (I think that just means Joey?) would review it, I'd be happy
21 to put together a patch that adds the chosen name to all the directives
22 that currently interpret `show` to mean "number of items", preferring the
23 new name but retaining compatibility for a numeric `show`.
24
25 Some possibilities (using inline as my example directive here):
26
27 * `\[[!inline limit=10]]` like SQL `select * from foo limit 10`
28 * `\[[!inline max-count=10]]` like `git log --max-count=10`
29 * `\[[!inline max=10]]`
30 * `\[[!inline n=10]]`, `\[[!inline num=10]]`, `\[[!inline number=10]]`
31
32 Which of those do Joey/other contributors prefer?
33
34 Or if keeping `show=10` is preferred, what should be the conventional name
35 for functionality like `\[[!map show=title]]`?
36
37 I personally like the idea of `\[[!inline limit=10]]`. --[[smcv]]