This is great. I think building HTML from source files is the way to go for
dry reference material like this.
You need links both ways so people know the other format is available. The
hooks.txt should say "The documentation at
https://doc.wikimedia.org/mw-hooks/hooks_mainpage.htmlis regularly
generated from the master branch of the gerrit repository."
If mediawiki.org's extension template linked "hooks in use" to this doc
instead of
mediawiki.org/Hooks:xyz pages then we could retire the latter
pages and have less stuff to maintain.
Except...
* It's sometimes useful that the Hooks pages are searchable along with the
rest of the documentation on
mediawiki.org.
* The
mw.org hooks pages have additional information. E.g. comparing
https://doc.wikimedia.org/mw-hooks/page_hooks_list.html#UserCreateForm and
http://www.mediawiki.org/wiki/Manual:Hooks/UserCreateForm , the
mw.org page
has
** version = 1.6.0
** source = SpecialUserlogin.php
** These categorize it as [Hooks added in MediaWiki 1.6.0]
and [MediaWiki hooks included in SpecialUserlogin.php]
If we add this information to hooks.txt maybe there's a way doxygen can
show the information and produce tables similar to the categories.
- The hooks are documented in a separate file (still docs/hooks.txt),
when we might want to have the doc near the
wfRunHooks() call.
Hmm. On the one hand if they're all in one place it's easier to do
cargo-cult pattern matching when adding new hook documentation. But if the
doc is in the PHP near the wfRunHooks call it's more likely people will
update it when making changes.
Now that we have mw.hook() in JavaScript we have a second universe of hooks
to think about :)
--
=S Page software engineer on Editor Engagement Experiments