Replace built-in HTML help files with proper strings

Discussions and objections appeared in replies to http://moodle.org/mod/forum/discuss.php?d=118707#p629948

Koen just started to document the migration procedure. For every help file we have at the moment, we must

• find all places where the file is used. There are several ways how the help may be called. The mostly used one is $mform->setHelpButton()
• propose a component and stringid for the new string that the help file should be migrated to. If, for example, the help file courseavailability.html is displayed for the field 'visible' (in course edit form) and a string 'availability' is a label of this field (see course/edit_form.php, line ~316), then the new help string shoud be 'availability_help' so it appears next to the field label during the translation.

The file can be found bij following https://spreadsheets.google.com/ccc?key=0AgZLM9dn6EcDdHFpY0tvV0hWT0gtWTN4OFk1TVJYMHc&hl=nl

Anyone who likes to help - just drop a line

deleted:
help/resource/* - replaced by new module with different settings
help/wiki/* - to be replaced by new wiki
help/journal/* - in ocntrib
help/helphiddenassign.html - no hidden role assingments any more
help/uploadusers(2).html - obsoleted
help/install.html - removing outdated instructions

I have changed the api once more, the old help functions have "old_help_*" form, the new help function do not have the old word in them. The forms is using new $mform->addHelpButton().

===========

First example is conversion of course full name help icon in course edit page - internally it is using
get_string('fullnamecourse', 'moodle') to get title of the help page and new
get_string('fullnamecourse_hlp', 'moodle') to get the help content

see:
http://cvs.moodle.org/moodle/course/edit_form.php.diff?r1=1.76&r2=1.77
http://cvs.moodle.org/moodle/lang/en/moodle.php.diff?r1=1.480&r2=1.481

============

I have added support for module help - the original resource/mods.html, it is replaced by 'modulename_hlp' string in module lang pack.

see:
http://cvs.moodle.org/moodle/mod/page/lang/en/page.php.diff?r1=1.2&r2=1.3

=============

feedback help icon conversion:

http://cvs.moodle.org/moodle/mod/feedback/edit.php.diff?r1=1.33&r2=1.34
http://cvs.moodle.org/moodle/mod/feedback/lang/en/feedback.php.diff?r1=1.2&r2=1.3

Hi Petr,

I'm improving the help icon label for screen-reader. MDL-20425 suggested that help icon's ALT attribute should begin with "Help with" string . I'm not sure whether this issue should be fix within your update or separately. Could you take a look and let me know.

Thanks
Rosie

the same examples:
form example - http://github.com/skodak/moodle/commit/503d243a3ca0dbfbc9e6074a26d5f448baf7d264
new module help - http://github.com/skodak/moodle/commit/3fc066917db16abccf7668f69662f71fd94d8130
general help icon (hacky) - http://github.com/skodak/moodle/commit/9fffbfc0fa884fba8026668d3a427d35c65a1bcf
standard general help icon - http://github.com/skodak/moodle/commit/d2265f130c6fc223726edf294dd1e7ee72032447

hi Rossiani,
the accessibility and UI issues will be discussed here: MDL-22067

Some thoughts after talking with Helen about this:

String names:

I'm not a big fan of introducing cryptic names just to save one character These would be clearer:

• stringname
• stringname_help
• stringname_link (optional string naming a path in Moodle docs, calculated just like the link in the footer to go to the right language etc, and shown after the help text in the popup as a link to "More info...")

String format:

Limited wiki format sounds good, since these texts are going to be short and simple (150 words?, no headings, no links, no bold, no tables etc) then I think all we need is:

• paragraphs (new line)
• occasionally bullets
• occasionally lists (#)

Process:

1. I asked Helen to start converting texts into strings and putting them into one big file (or perhaps one per module if that is obvious) over the next week or two, documenting the help file name -> string name in the spreadsheet.

2. Then I hope someone like David can come along and quickly perform all the help button API updates in the code, reorganising strings as they go.

Assignment help strings fixed.

Chat help strings fixed. Note that I realized that the help tooltip does not display properly in the chatting screen, probably due to frames. To be fixed after tooltip reimplementation.

Choice help strings fixed.

Database module help strings fixed.

Just to say that the actual implementation is more HTML rendering than wiki although not the same in the mouse over than in the pop-up window
see
http://docs.moodle.org/en/Development_talk:Help_strings

Pierre - yes, help.php does not properly handle format yet. I tend to call the future "standard" help format as MINIWIKI format. The proposed behaviour is following:

• if the help string contains any <p> tag, then it is considered legacy string copied from the HTML and will be rendered as plain HTML (so all copied help files will work)
• if there is no <p> tag used, then the help string is expected to be in MINIWIKI format.

Where MINIWIKI can be defined as:

• no <p> tags are allowed
• linebreaks are put automatically, using newline characters. The behaviour of newlines is the most significant difference between HTML and MINIWIKI
• unordered and ordered lists are supported using * and # as the first character on the line. One level only, no support for nesting in help
• all other common HTML tags are rendered as expected - <strong>, <em>, <dl> etc. This will allow us to use HTML where needed, but we will keep English master copies as simple as possible.

Forum module help strings fixed

I like the future you are designing and thanks for all your work..

I put your comments in the docs.

Pierre, thanks for your comments. Glad you like it!

Just adding a couple of relevant links:

http://docs.moodle.org/en/Development:Help_strings
http://moodle.org/mod/forum/discuss.php?d=149220

Change on help format. Thanks to Martin D., I realized that the MARKDOWN format preserves HTML and already contains support for basic formatting like bullet lists etc. The parser of this syntax has been in Moodle since ages and is considered stable, which is much better, effective and safer than writing a new parser. So, from now on, we use MARKDOWN for help strings.

• This actually simplifies my proposal above as all HTML tags including <p> are supported
• bullet lists work, as well as other structure tags (beware - there have to be an empty line before and after the list)
• nested lists are supported

For more information, see http://docs.moodle.org/en/Formatting_text#Markdown_text_format

Helen - I was looking at a recent commit regarding some of the forum strings where we went from User to Student. Elsewhere we seem to be using you. In any case, I think we are becoming even more scattered in the language and want things to be consistent. For example, below we have "You" in the cannotupdatepost and cannotviewpostyet strings. We leave cleanreadtime without a explicit subject - just beginning with the verb 'Mark. Then we replace a couple of users with students as in completiondiscussions. Then back to the verb (no explicit subject). In 'configajaxrating' we have 'If enable, users can rate forum posts'. We could move to the passive voice and avoid an explicit subject. However, some of these actions are not really particular to the role so I think a generic term like user is more appropriate than student (which is a particular role). Students, teachers, administrators, etc. could in theory (depending on how the roles are defined) be asked to complete posts. I wonder if Olli or Tomaz might have some suggestions. I just want to ensure that we are consistent with our use of subjects (you, user, student, etc.) so that there is a method to the madness. I understand that the strings you did change will predominantly be seen by students. Peace - Anthony

$string['cannotupdatepost'] = 'You can not update this post';
$string['cannotviewpostyet'] = 'You cannot read other students questions in this discussion yet because you haven\'t posted';
$string['cleanreadtime'] = 'Mark old posts as read hour';

-$string['completiondiscussions'] = 'User must create discussions:';

+$string['completiondiscussions'] = 'Student must create discussions:';

$string['completiondiscussionsgroup'] = 'Require discussions';
$string['completiondiscussionshelp'] = 'requiring discussions to complete';

-$string['completionposts'] = 'User must post discussions or replies:';

+$string['completionposts'] = 'Student must post discussions or replies:';

$string['completionpostsgroup'] = 'Require posts';
$string['completionpostshelp'] = 'requiring discussions or replies to complete';

-$string['completionreplies'] = 'User must post replies:';

+$string['completionreplies'] = 'Student must post replies:';

$string['completionrepliesgroup'] = 'Require replies';
$string['completionreplieshelp'] = 'requiring replies to complete';
$string['configajaxrating'] = 'AJAX rating is a forum rating usability improvement. If enabled, users can rate forum posts almost instantly without needing to scroll to the bottom of the page and click the \'Send in my latest ratings\' button. This setting also requires AJAX to be enabled for the site and in user profiles.';

Anthony, thanks for your comments regarding consistency.

Regarding help strings, I am attempting to follow the guidelines for words for roles as listed in http://docs.moodle.org/en/Development:Help_strings. Unfortunately I am unable to review all strings at this time, though I did chat with Sam Marshall about certain completion strings and we agreed upon changing the word 'User' to 'Student'. Please note that these strings only appear in the activity settings i.e. they are never seen by students.

arrgh, Markdown('') returns nasty newline, going to add
if ($text === '' or $text === NULL)

because otherwise it breaks empy() tests with the resulting converted strings because \n is not empty

OK. I think we can consider this issue fixed now. I got rid of all the help files from the English lang pack and did my best to migrate majority of the files into help strings. Blame me if this introduces some regressions or new error messages. However, the credit should go to Koen and Helen. Praise Helen especially for her excellent job of insightful re-wording all Moodle help strings.

If you spot any help related bug or request, please record it as a new issue in this tracker (possibly linked with this one if they are related).