1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
I've found myself wanting to know which [[plugins]] are switched on so I know which pre-processor commands I can use. The attached [[patch]] adds a new plugin that generates the list of available plugins. -- [[Will]]
> Good idea, I do see a few problems:
>
> - preprocessor directives do not necessarily have the same name as the
> plugin that contains them (for example, the graphviz plugin adds a graph
> directive). Won't keys `%{IkiWiki::hooks{preprocess}}` work?
>>> Er, yeah - that's a much better solution. :) -- and done
> - "listplugins" is a bit misnamed since it only does preprocessor directives.
>>> Yes. Initially this was going to list all enabled plugins. Then when searching
>>> for enabled plugins I changed my mind and decided that a list of pre-processor
>>> directives was more useful. I'll fix that too. -- changed to `listpreprocessors`
> - comment was copied from version plugin and still mentions version :-)
>>> :-) -- fixed
> - Seems like [[ikiwiki/formatting]] could benefit from including the
> list.. however, just a list of preprocessor directive names is not
> the most user-friendly thing that could be put on that page. It would
> be nice if there were also a short description and maybe an example of
> use. Seems like the place to include that info would be in the call
> to `hook()`.
> (Maybe adding that is more involved than you want to go though..)
>
> --[[Joey]]
>> Adding a whole new hook for a usage example is more effort than I
>> wanted to go to. I was thinking of either:
>>> Just to clarify, I meant adding new parameters to the same hook call
>>> that registers the plugin. --[[Joey]]
>> - Adding a configuration for a wiki directory. If a matching page is in the
>> specified wiki directory then the plugin name gets turned into a link to that
>> page
>> - Adding configuration for an external URL. Each plugin name is added as
>> a link to the plugin name appended to the URL.
>>The first option is easier to navigate and wouldn't produce broken links,
>>but requires all the plugin documentation to be local. The second option
>>can link back to the main IkiWiki site, but if you have any non-standard
>>plugins then you'll get broken links.
>>
>>Hrm. After listing all of that, maybe your idea with the hooks is the better
>>solution. I'll think about it some more. -- [[Will]]
>>> I've also run into this problem with the websetup plugin, and
>>> considered those ideas too. I don't like the external url, because
>>> ikiwiki.info may be out of sync with the version of ikiwiki being used.
>>> (Or maybe it's gone! :-) The first idea is fine, except for the bloat
>>> issue. If turning on listpreprocessors and/or websetup means adding
>>> hundreds of pages (and of kilobytes) to your wiki, that could be an
>>> incentive to not turn them on..
>>>
>>> Hmm.. maybe the thing to do is to use _internal pages for the plugins;
>>> then the individual pages would not be rendered, and your inlines would
>>> still work. Although I don't know how websetup would use it then, and
>>> also they would have to be non-internal for ikiwiki's own docwiki. Hmm.
>>> Maybe these are two different things; one is a set of pages describing
>>> preprocessor directives, and the second a set of pages describing
>>> plugins. They're so closely related though it seems a shame to keep
>>> them separate..
>>> --[[Joey]]
>>> I started implementing the hook based solution, and decided I didn't like
>>> it because there was no nice way to rebuild pages when the preprocessor
>>> descriptions changed. So instead I assumed that the the [[plugins]] pages
>>> would be moved into the underlay directory. This plugin then uses an
>>> `inline` directive to include those pages. You can use the `inline`
>>> parameter to decide if you want to include all the descriptions or
>>> just the titles. There is also an option to auto-create default/blank
>>> description pages if they are missing (from a template). As preprocessor
>>> commands don't list unless they have a description page, auto-creation
>>> is enabled by default.
>>>
>>> There are three new templates that are needed. These are for:
>>>
>>> - The auto-created description pages are generated from `preprocessor-description.tmpl`.
>>> - When only pre-processor names are listed, the `listpreprocessors-listonly.tmpl` template is used.
>>> - When pre-processor descriptions are included inline, the `listpreprocessors-inline.tmpl` template is used.
>>>
>>> -- [[Will]]
>>>> Just a quick note: pages are only created for pre-processor commands
>>>> that exist when the `refresh` hook is called. This is before the [[shortcuts]] are
>>>> processed. However, the list of available pre-processor commands will include
>>>> shortcuts if they have description pages (the list is generated later, after the
>>>> shortcuts have been added). While this was unplanned, it seems a reasonable
>>>> tradeoff between including all the large number of shortcuts and including none. -- [[Will]]
>>>>>> I think that using an inline is elegant! However, I don't understand
>>>>>> why it has to create stub description pages? I doubt that, if a
>>>>>> directive is missing a page, the stub will be filled out in many
>>>>>> wikis. And it adds a lot of complexity, particularly committing a
>>>>>> bunch of generated pages to revision control when the user just
>>>>>> wants a plugin list seems undesirable.
>>>>>>
>>>>>> Seems to me it could use the inline for pages that exist, and append
>>>>>> to the bottom a generated text for anything that is currently missing.
>>>>>> The generated text could even have a page creation link in it if
>>>>>> you wanted.
>>>>>> --[[Joey]]
>>>>>>> I kinda agree about the page generation. I don't like mixing an
>>>>>>> inlined and a list though. Besides which, that ends
>>>>>>> up keeping much of complexity of the page generation because
>>>>>>> the code still has to detect which pages are missing. I've added
>>>>>>> a patch that uses a list of wikilinks instead. This way available
>>>>>>> pages get linked correctly, and missing pages get normal creation
>>>>>>> links. The old patch is still here if you decide you prefer that. -- [[Will]]
>>>>>>>> Can you explain the full/early list (why track both?) and generated parameter?
>>>>>>>>> If you add in all the shortcuts you get quite a long list. My original idea
>>>>>>>>> was to just track the plugin commands. This is the early list. But then
>>>>>>>>> I thought that it might be nice for someone looking at wiki source and
>>>>>>>>> seeing a shortcut to know where it came from. So I decided to make
>>>>>>>>> displaying the full list an option, with the original concept as the default.
>>>>>>>>> Another option here might be to generate the full list every time, but give
>>>>>>>>> generated pre-processor commands (e.g. shortcuts) a different css class.
>>>>>>>>> I'm not sure that is better than what I have though.
>>>>>>>>> I keep track of both in the page state because if a command moves from
>>>>>>>>> a shortcut to the early list (or vice versa) it changes what should be
>>>>>>>>> displayed in the default use of the plugin. I thought about tracking just what
>>>>>>>>> was actually used on the page, but I don't know in the needsbuild hook whether the `generated`
>>>>>>>>> parameter has been supplied (or maybe the plugin is used twice on the page -
>>>>>>>>> once in each form). It was just easier to track both.
>>>>>>>> Only code change I'd suggest is using `htmllink` rather than
>>>>>>>> generating a wikilink.
>>>>>>>>> Yeah - that would make sense. done. -- [[Will]]
Patch is applied (along with some changes..). [[done]] (But, see
[[directive_docs]].
|