doc/todo/feed_enhancements_for_inline_pages.mdwn

   1 [[!template id=gitbranch branch=GiuseppeBilotta/inlinestuff author="[[GiuseppeBilotta]]"]]
   2
   3 I rearranged my patchset once again, to clearly identify the origin and
   4 motivation of each patch, which is explained in the following.
   5
   6 In my ikiwiki-based website I have the following situation:
   7
   8 * `$config{usedirs}` is 1
   9 * there are a number of subdirectories (A/, B/, C/, etc)
  10   with pages under each of them (A/page1, A/page2, B/page3, etc)
  11 * 'index pages' for each subdirectory: A.mdwn, B.mdwn, C.mdwn;
  12   these are rather barebone, only contain an inline directive for their
  13   respective subpages and become A/index.html, etc
  14 * there is also the main index.mdwn, which inlines A.mdwn, B.mdwn, C.mdwn,
  15   etc (i.e. the top-level index files are also inlined on the homepage)
  16
  17 With the upstream `inline` plugin, the feeds for A, B, C etc are located
  18 in `A/index.atom`, `B/index.atom`, etc; their title is the wiki name and
  19 their main link goes to the wiki homepage rather than to their
  20 respective subdir (e.g. I would expect `A/index.atom` to have a link to
  21 `http://website/A` but it actually points to `http://website/`).
  22
  23 This is due to them being generated from the main index page, and is
  24 fixed by the first patch: ‘inline: base feed urls on included page
  25 name’. As explained in the commit message for the patch itself, this is
  26 a ‘forgotten part’ from a previous page vs destpage fix which has
  27 already been included upstream.
  28
  29 > Applied. --[[Joey]]
  30
  31 >> Thanks.
  32
  33 The second patch, ‘inline: improve feed title and description
  34 management’, aligns feed title and description management by introducing
  35 a `title` option to complement `description`, and by basing the
  36 description on the page description if the entry is missing. If no
  37 description is provided by either the directive parameter or the page
  38 metadata, we use a user-configurable default based on both the page
  39 title and wiki name rather than hard-coding the wiki name as description.
  40
  41 > Reviewing, this seems ok, but I don't like that
  42 > `feed_desc_fmt` is "safe => 0". And I question if that needs
  43 > to be configurable at all. I say, drop that configurable, and
  44 > only use the page meta description (or wikiname for index).
  45 >
  46 > Oh, and could you indent your `elsif` the same as I? --[[Joey]]
  47
  48 >> I hadn't even realized that I was nesting ifs inside else clauses,
  49 >> sorry. I think you're also right about the safety of the key, after
  50 >> all it only gets interpolated with known, safe strings.
  51
  52 >>> I did not mean to imply that I thought it safe. --[[Joey]]
  53
  54 >>>> Sorry for assuming you implied that. I do think it is safe, though
  55 >>>> (I defaulted to not safe just to err on the safe side).
  56
  57 >> The question is what to do for pages that do not have a description
  58 >> (and are not the index). With your proposal, the Atom feed subtitle
  59 >> would turn up empty. We could make it conditional in the default
  60 >> template, or we could have `$desc` default to `$title` if nothing
  61 >> else is provided, but at this point I see no reason to _not_ allow
  62 >> the user to choose a way to build a default description.
  63
  64 >>> RSS requires the `<description>` element be present, it can't
  65 >>> be conditionalized away. But I see no reason to add the complexity
  66 >>> of an option to configure a default value for a field that
  67 >>> few RSS consumers likely even use. That's about 3 levels below useful.
  68 >>> --[[Joey]]
  69
  70 >>>> The way I see it, there are three possibilities for non-index pages
  71 >>>> which have no description meta: (1) we leave the
  72 >>>> description/subtitle in feed blank, per your current proposal here
  73 >>>> (2) we hard-code some string to put there and (3) we make the
  74 >>>> string to put there configurable. Honestly, I think option #1 sucks
  75 >>>> aesthetically and option #2 is conceptually wrong (I'm against
  76 >>>> hard-coding stuff in general), which leaves option #3: however
  77 >>>> rarely used it would be, I still think it'd be better than #2 and
  78 >>>> less unaesthetical than #1.
  79
  80 >>>> I'm also not sure what's ‘complex’ about having such an option:
  81 >>>> it's definitely not going to get much use, but does it hurt to have
  82 >>>> it? I could understand not wasting time putting it in, but since
  83 >>>> the code is written already … (but then again I'm known for being a
  84 >>>> guy who loves options).
  85
  86 The third patch, ‘inline: allow assigning an id to postform/feedlink’,
  87 does just that. I don't currently use it, but it can be particularly
  88 useful in the postform case for example for scriptable management of
  89 multiple postforms in the same page.
  90
  91 > Applied. --[[Joey]]
  92
  93 >> Thanks.
  94
  95 In one of my wiki setups I had a terminating '/' in `$config{url}`. You
  96 mention that it should not be present, but I have not seen this
  97 requirement described anywhere. Rather than restricting the user input,
  98 I propose a patch that prevents double slashes from appearing in links
  99 created by `urlto()` by fixing the routine itself.
 100
 101 > If this is fixed I would rather not put the overhead of fixing it in
 102 > every call to `urlto`. And I'm not sure this is a comprehensive
 103 > fix to every problem a trailing slash in the url could cause. --[[Joey]]
 104
 105 >> Maybe something that sanitizes the config value would be better instead?
 106 >> What is the policy about automatic changing user config?
 107
 108 >>> It's impossible to do for perl-format setup files. --[[Joey]]
 109
 110 >>>> Ok. In that case I think that we should document that it must be
 111 >>>> slash-less. I'll cook up a patch in that sense.
 112
 113 The inline plugin is also updated (in a separate patch) to use `urlto()`
 114 rather than hand-coding the feed urls. You might want to keep this
 115 change even if you discard the urlto patch.
 116
 117 > IIRC, I was missing a proof that this always resulted in identical urls,
 118 > which is necessary to prevent flooding. I need such a proof before I can
 119 > apply that. --[[Joey]]
 120
 121 >> Well, the URL would obviously change if the `$config{url}` ended in
 122 >> slash and the `urlto` patch (or other equivalent) went into effect.
 123
 124 >> Aside from that, if I read the code correctly, the only other extra
 125 >> thing that `urlto` does is to `beautify_url_path` the `"/".$to` part,
 126 >> and the only way this would cause the url to be altered is if the
 127 >> feed name was "index" (which can easily happen) and
 128 >> `$config{htmlext}` was set to something like `.rss` or
 129 >> `.rss.1`.
 130
 131 >> So there is a remote possibility that a different URL would be
 132 >> produced.