Welcome to 2019
[ikiwiki.git] / doc / plugins / contrib / ymlfront / discussion.mdwn
1 **Update:** I've submitted a patch, [rubykat/ikiplugins pull request #5](https://github.com/rubykat/ikiplugins/issues/5).
2
3 I have just opened [rubykat/ikiplugins issue #4](https://github.com/rubykat/ikiplugins/issues/4)
4 regarding the fact that ymlfront doesn't seem to delete any old pagestate when fields have been
5 removed in an edit. The fields are stuck there with their old values until a full rebuild. Seems
6 to me ymlfront should just clear out all of the `{ymlfront}` pagestate before parsing the new
7 stuff - including in the case where the new page has no ymlfront section at all.
8
9 I discovered another slightly-different-but-related issue where simply _changing_ a field value
10 in the YAML section doesn't always cause the generated HTML to be updated. Oddly, ikiwiki will
11 _say_ it's building the page, but when you look at the HTML output, it's the old content.
12
13 Could this involve some clever optimization where ikiwiki looks at the content (that's left over
14 after ymlfront stripped out the YAML) and sees it hasn't changed? Does ymlfront need to do
15 something more to indicate there is a change? Does the _template_ need to somehow be declared
16 to depend on more stuff?
17
18 As I said, the log does have a line for 'building' the page, so whatever optimization is happening
19 must come later than the determination of what pages to 'build'.
20
21 I'm mentioning it here because I'm not sure whether this or the issue on github will be seen
22 first - there's a pretty old one open there. This seems to be quite
23 potentially useful stuff that never quite got finished - is [[KathrynAndersen]] still
24 interested? -- [[jcflack]]
25
26 ----
27 Previous discussion re: delimiters
28
29 Now that I have implemented a \[[!ymlfront ...]] directive, I would like to remove support for the old "---" delimited format, because
30
31 * it is fragile (easily breakable)
32 * it is non-standard
33
34 Any objections?
35
36 > Well, I don't have much standing since I have been too lame to integrate
37 > ymlfront into ikiwiki yet. Buy, my opinion is, I liked the old
38 > format of putting the YAML literally at the front of the file. It
39 > seemed to allow parsing the file as YAML, using any arbitrary YAML
40 > processer. And it was nice how it avoided boilerplate. --[[Joey]] 
41
42 >> The old delimited format also has the advantage of being remarkably similar to the
43 >> [MultiMarkDown](http://fletcherpenney.net/multimarkdown/users_guide/multimarkdown_syntax_guide/)
44 >> way of including metadata in documents. The only difference is that MMD doesn't expect the
45 >> triple-dash separators, but I'm thinking about submitting a patch to MMD to actually support
46 >> that syntax. --GB
47
48 >>> Yes, the idea was to allow the file to be parsed as YAML, you're right.  I just found that I tended to have problems when people used "---" for horizontal rules.  However, I have also found that trying to keep it solely as an IkiWiki directive doesn't work either, since sometimes the meta-data I need also contained "]]" which broke the parsing of the directive.
49 >>> So I have decided to go for a compromise, and make the delimiter configurable, rather than hardcoded as "---"; the triple-dash is the default, but it can be configured to be something else instead.  I haven't pushed the change yet, but I have written it, and it seems to work. -- [[KathrynAndersen]]
50
51 >>>> I'm not sure about what kind of problems you're meeting with "---" being used
52 >>>> for horizontal rules: isn't it sufficient to just check that (1) the triple-dash
53 >>>> is the first thing in the page and (2) there are only YAML-style assignments
54 >>>> (and no blank lines) between the two markers? Check #2 would also be enough to
55 >>>> support MMD-style metadata, which means (a) no start marker and (b) empty line
56 >>>> to mark the end of the metadata block. Would this be supported by the plugin?
57 >>>> --GB
58
59 >>>>> Since I allow all legal YAML, the only way to check if it is legal YAML is to use the YAML parser, by which time one is already parsing the YAML, so it seems a bit pointless to check before one does so. -- KA