Page MenuHomePhabricator

Do not hardcode the documentation location for modules
Closed, ResolvedPublic

Description

The following messages and their behavior imply that the documentation location *must* be as a subpage. That is not an approach taken by all wikis, so the location must not be hardcoded this way.

scribunto-doc-subpage-does-not-exist

''Documentation for this module may be created at [[$1]]''

Rename to scribunto-doc-page-does-not-exist
Change the behavior of $1 to be <scribunto-doc-page-name>

scribunto-doc-subpage-header

'''This is the documentation subpage for [[$1]]'''

Rename to scribunto-doc-page-header
Change to '''This is the documentation page for [[$1]]'''

scribunto-doc-subpage-name

doc

Rename to scribunto-doc-page-name
Change to {{FULLPAGENAME}}/doc (alt. $1/doc, if the former wouldn't work)

scribunto-doc-subpage-show

{{$1}} <hr />

Change to scribunto-doc-page-show


Version: unspecified
Severity: normal
Whiteboard: usability

Details

Reference
bz45845

Event Timeline

bzimport raised the priority of this task from to Medium.Nov 22 2014, 1:26 AM
bzimport set Reference to bz45845.

Reverting my changes after IRC chat. Sorry.

It *could* work as long as scribunto-doc-page-name remains unparsed (i.e. using Message::plain()). Which would mean you'd be able to put the documentation at something like "Project:Module documentation/$1", or generally add any prefix or suffix to $1, but you couldn't do anything fancier, i.e. no parser functions. Allowing parser functions would make it impossible for Scribunto to determine whether any particular page is supposed to be documentation so it can allow it to be rendered as wikitext.

$1 could be either {{FULLPAGENAME}} or {{PAGENAME}}, with the default being either "$1/doc" or "Module:$1/doc" to match.

If you actually need this to determine whether to syntaxhilight or parse the page in Module namespace, then better approach would be to have another message, let's say "scribunto-noscript-pages" as a blacklist of those not to be hilighted / whitelist of those to be parsed. Similar to title blacklist, bad image list and others. Or have a new magic word, let's say NOCODE or something like that to be added to pages which should be parsed.

Hardcoding some pattern is definitely not good approach because it is so very limmiting, besides it can cause issues in case the name which would match the patter would have to be actually used for the code.

(In reply to comment #2)

Which would mean you'd be able to put the documentation at
something like "Project:Module documentation/$1", or generally add any prefix
or suffix to $1
$1 could be either {{FULLPAGENAME}} or {{PAGENAME}}, with the default being
either "$1/doc" or "Module:$1/doc" to match.

That's exactly what I'm suggesting. To be able to add any prefix/suffix to the name itself. Which implies, that having {{PAGENAME}} for $1 is obviously better than {{FULLPAGENAME}}, since it's easy to add namespace as prefix, but quite impossible to remove it.

Looking forward this solution the sooner the better, preferably before the wider deployment of Scribunto on WMF wikis to save the further work with relocations.

(In reply to comment #3)

If you actually need this to determine whether to syntaxhilight or parse the
page in Module namespace, then better approach would be to have another
message, let's say "scribunto-noscript-pages" as a blacklist of those not to
be
hilighted / whitelist of those to be parsed. Similar to title blacklist, bad
image list and others. Or have a new magic word, let's say NOCODE or
something like that to be added to pages which should be parsed.

No. Let's keep things simple: if a module looks at a particular page for its documentation, then that page should be module documentation.

Looking forward this solution the sooner the better, preferably before the
wider deployment of Scribunto on WMF wikis to save the further work with
relocations.

You'll have to convince someone to update the extension in wmf11 then, because wmf12 will be too late.

Merged by Demon on the 13th. Is this bug fixed now?