[Building Sakai] Renaming tools (bad habit)

[Matthew Jones]

Yea, it really seemed like if you were changing the name of a tool, you'd
be changing a lot more in the help files than just the title on top and the
item in the navigation menu. You'd essentially want to search and replace
for that word everywhere that it's appropriate.

Like in the evaluation->survey case you mentioned this is what the help
says in the overview.

"Evaluations Overview

The Evaluations tool allows users with appropriate permission to evaluate
work in a wizard page or matrix cell after it has been submitted for
evaluation by a site participant. If you are an evaluator, you use this
tool to access the appropriate part of a participant's wizard or matrix,
review the work shown there, and provide an evaluation of it."

You'd probably need to change this to

"Surveys Overview

The Surveys tool allows users with appropriate permission to survey work in
a wizard page or matrix cell after it has been submitted by a site
participate. If you are a surveyer, you use this tool to access the
appropriate part of a participant's wizard or matrix, review the work show
there, and survey it."

Seems like a lot more replacements, almost like every page in help would
need template variables.

Some people at conferences and on lists have been talking about the "Help
Files" customization project, but this seems like a "big deal".

https://confluence.sakaiproject.org/display/ESUP/Help+Files+and+Documentation+Process+Redesign


It might be easier to take all of the help files and just host them
externally, making changes as needed, you can do this as well, and the
readme talks about external registration. This is what we were doing at
Michigan.

https://source.sakaiproject.org/svn/help/trunk/README

Any of these are better than rebuilding/customizing source all the time
though. ;)
On Wed, Mar 28, 2012 at 11:29 AM, Matthew Buckett <
matthew.buckett at oucs.ox.ac.uk> wrote:

> > I was thinking it would be best if all of these help files are templates
> > with some simple variables like (tool title) (tool description) (skin
> repo),
> > then I could just have used some simple template processor like JTpl to
> > quickly replace. But alas that would have required modifying every help
> file
> > in the system (and contrib). I know skin hard coded repo is static in
> every
> > file, replacing the title would be harder because it wouldn't know what
> the
> > default title to replace is?
>
> This is along the lines I was thinking of. It could be done in a
> reasonably backwards compatible way by having the variable in the
> temple be something like:
>
> <span class="tool-title">Resources</span>
>
> This way if the help tool doesn't support replacing the tool title it
> gets pass through, but if it does then the updated tool title gets
> substituted.
>
> Otherwise you have the problem that contrib tools wouldn't use the
> substitution as they didn't want to drop support for older versions of
> the help tool.
>
> Filed as a Jira at: https://jira.sakaiproject.org/browse/SAK-21990
>
> --
>   Matthew Buckett
>   VLE Developer, LTG, Oxford University Computing Services
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai-dev/attachments/20120328/f8fa70c5/attachment.html