User:Zakgreant/pairdoc/2010-11-24
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 :) |