Jump to content

User:Zakgreant/pairdoc/2010-11-24

From mediawiki.org

A discussion between User:Raymond and User:Zakgreant about embedding system message documentation in MediaWiki.

Chat log

[edit]
[12:00] <zakg> Ahoy Raimond - ready to chat?
[12:00] <Raymond_> hi
[12:00] <Raymond_> sure :)
[12:00] <zakg> Excellent!
[12:01] <zakg> I've put up an etherpad doc at etherpad:pair-doc-2010-11-24, if we need it
[12:01] <Raymond_> great. I have opened it :)
[12:01] <zakg> So. You wanted to talk about message documentation.
[12:02] <zakg> It seems odd that messages are documented on translatewiki, but not on MediaWiki.org
[12:02] <zakg> Can you give me some background?
[12:02] <Raymond_> yes. I don't know if you know that I am server admin volunteer on translatewiki.net
[12:03] <Raymond_> I sync all MediaWiki changes to translatewiki and export every day all new translations to MediaWiki SVN
[12:03] <Raymond_> these new translations go live every night on all WMF projects
[12:03] <zakg> That's a lot of work
[12:04] <Raymond_> with the help of LocalisationUpdate extension
[12:04] <Raymond_> yes :)
[12:04] <Raymond_> We have decided to put some translations hints in the 'qqq' pseudo language message
[12:05] <zakg> Ok
[12:05] <Raymond_> these hints are visible on translatewiki and maintained there by our translators
[12:05] <Raymond_> but they are invisible for all admins on enwiki, dewiki, etc and third party MediaWiki installations
[12:06] <zakg> Ah...
[12:06] <Raymond_> but they could be useful if an admin want to customize the interface
[12:07] <Raymond_> the qqq pseudo language is available in SVN too: http://svn.wikimedia.org/viewvc/mediawiki/trunk/phase3/languages/messages/MessagesQqq.php?revision=77180&view=markup
[12:08] <zakg> Ok
[12:08] <Raymond_> especially for messages with a lot of variables like $1, $2 etc these hints are useful
[12:09] <zakg> So, how do we easily get these hints into the MediaWiki docs?
[12:09] <Raymond_> and we have some messages which are empty by default but are useful sometimes. but no one knows them, and their variables
[12:10] <Raymond_> thats the question I am working on :-)
[12:10] <zakg> heh
[12:11] <Raymond_> but nothing ready until now because the hints use Translatewiki specific templates and screenshots
[12:12] <Raymond_> I do not know if it would make sense to create pages with these hints on mediawiki.org
[12:13] <Raymond_> because they change from time to time
[12:13] <zakg> Ah. Also, it seems that this information should go into the source – but I'm not sure if doxygen could sensibly retrieve it
[12:13] <Raymond_> don't know. I haven't worked with doxygon much.
[12:14] <Raymond_> but I am open for suggestions to improve the qqq message file for retrieve by doxygen
[12:15] <zakg> it is good at pulling out documentation for specific classes, methods and variables – i'm not sure if it would do a good job with method invocations.  We are dealing with calls to wfMessage, right?
[12:15] <Raymond_> yes
[12:16] <Raymond_> the idea I am working on is to show these hints on top of w:en:MediaWiki:Revision-info?action=edit
[12:16] <Raymond_> this message as example only :)
[12:17] <zakg> right
[12:18] <Raymond_> wfMessage is rarely used until now
[12:19] <zakg> aha
[12:19] <Raymond_> most calls are wfMsg(), wfMsgExt(), wfMsgHtml()
[12:19] <Raymond_> wfMsgForContent()
[12:19] <Raymond_> wfMsgNoTrans()
[12:21] <Raymond_> ok
[12:23] <zakg> So. Let me see if I understand (or show that I don't :)
[12:24] <zakg> An admin would go to the appropriate MessagesXxx.php file to customize messages for their install
[12:24] <Raymond_> no
[12:24] <zakg> Ok.  I'm not familiar with this part of MW
[12:24] <zakg> So... where would the admin go?
[12:24] <Raymond_> that is a no-go because all customizations would be overridden by the next upgrade
[12:25] <zakg> d'oh - of course
[12:25] <Raymond_> on-wiki in the MediaWIki namespace like w:en:MediaWiki:Revision-info?action=edit
[12:25] <zakg> aha
[12:26] <zakg> ... and what we need on these pages (or in some easy to reach place) is documentation on what $1, $2, ... are
[12:26] <Raymond_> yes
[12:27] <zakg> ... and, ideally, we want these embedded in each release so that the docs are appropriate for the version.
[12:27] <Raymond_> right
[12:27] <zakg> ok - i think that i now understand
[12:27] <Raymond_> this is not hard because they are updated daily too
[12:27] <zakg> right
[12:30] <zakg> So... for something like MediaWiki:Revision-info, we really just want to grab the docs for Revision-info in MessagesQqq and show it on the page.
[12:30] <Raymond_> yes
[12:31] <zakg> Hrm.  I'm betting that Trevor Parscal will be interested in doing this – it shouldn't be hard (unless I'm missing something really important.)
[12:31] <Raymond_> it shouldn't be hard but....
[12:31] <zakg> :)
[12:32] <Raymond_> let me search for an example...
[12:33] <Raymond_> please search in http://svn.wikimedia.org/viewvc/mediawiki/trunk/phase3/languages/messages/MessagesQqq.php?revision=77180&view=markup for 'article'
[12:33] <Raymond_> in the third text line you see Template:Identical
[12:33] <zakg> ok
[12:33] <Raymond_> this is a template which exists on translatewiki only
[12:33] <Raymond_> link:
[12:33] <zakg> so we ...
[12:33] <zakg> oh
[12:34] <Raymond_> hmmmm do you have an account on translatewiki?
[12:35] <zakg> I think that I do – Nikerabbit and Siebrand gave me a whirlwind tour.  moment
[12:35] <Raymond_> I want to show you something but you need an account and translator right - which I can grant you in a second
[12:35] <zakg> Account name is Zakgreant
[12:36] <Raymond_> second pls
[12:36] <Raymond_> oh you have the right already :)
[12:36] <zakg> logging in now
[12:37] <Raymond_> have a look at http://translatewiki.net/w/i.php?title=MediaWiki:Article/de&action=edit
[12:37] <Raymond_> or change /de to another language you speak/like :)
[12:37] <zakg> meine Deutsch ist sehr schlect :(
[12:38] <zakg> on the page in english
[12:38] <Raymond_> great :)
[12:38] <zakg> Ok. So we have some content in the source and some content on translatewiki and we need to get the two together.
[12:39] <Raymond_> yes
[12:39] <Raymond_> that could by tricky
[12:39] <zakg> Can't we just programatically grab the content from TW?
[12:40] <Raymond_> yes why not
[12:41] <zakg> It makes things a bit messier, but not much. :)  At least the hard part (all the content, in this case) seems written. :)
[12:42] <zakg> So, it seems that the help I can offer here is to help you work up a spec of what needs to be done. Is that right?
[12:43] <Raymond_> sounds good :)
[12:43] <zakg> Perfect.
[12:43] <zakg> If you have a draft proposal, I can work on that. If you don't have a draft proposal, I can use these notes to work something up.
[12:44] <Raymond_> I do not have a draft proposal now. just some unfinished code on my local testwiki
[12:44] <Raymond_> I can clean this up in the next days
[12:45] <zakg> Great. I will turn our discussion into some kind of brief proposal while you do that.
[12:46] <Raymond_> yes. I will send you my code and some screenshots in next days
[12:46] <zakg> Excellent!
[12:47] <zakg> Thank you for your time. Have a good evening.
[12:47] <Raymond_> thanks you too :)
[12:48] <zakg> My pleasure :)