help xml syntax

[Philip Olson]

Hello all,

The following:
- http://wiki.habariproject.org/en/Creating_A_Plugin

Links to this:
- http://schemas.habariproject.org/pluggable-sample.xml

Which contains:
-----
<!-- help can come from the info file -->
<help name="main">
<value><![CDATA[This is helpful stuff.]]></value>
<value xml:lang="es-es"><![CDATA[Esto es útil cosas.]]></value>
</help>
<help name="secondary">
<value><![CDATA[This is more helpful stuff.]]></value>
<value xml:lang="es-es"><![CDATA[Esto es más útil cosas.]]></value>
</help>
-----

I have two questions:
- How do the 'main' and 'secondary' name attributes apply in real life?
- Is this schema considered final and implementation ready for 0.7?

And for what I [think I] know is true:
- 0.7+ utilizes these XML files, whereas 0.6 does not
- The lang attributes are not implemented currently, unlike help() usage today
- Not many (4) plugins in habari-extras use <help> yet, whereas several do within system/plugins
- None use 'main' or 'secondary', but instead simply <help>

Regards,
Philip

[rick c]

On Nov 30, 1:12 am, Philip Olson <phi...@roshambo.org> wrote:
> Hello all,
>
> The following:
> -http://wiki.habariproject.org/en/Creating_A_Plugin
>
> Links to this:
> -http://schemas.habariproject.org/pluggable-sample.xml

>
> Which contains:
> -----
> <!-- help can come from the info file -->
> <help name="main">
>  <value><![CDATA[This is helpful stuff.]]></value>
>  <value xml:lang="es-es"><![CDATA[Esto es útil cosas.]]></value>
> </help>
> <help name="secondary">
>  <value><![CDATA[This is more helpful stuff.]]></value>
>  <value xml:lang="es-es"><![CDATA[Esto es más útil cosas.]]></value>
> </help>
> -----
>
> I have two questions:
> - How do the 'main' and 'secondary' name attributes apply in real life?

I'd be interested in the answer to this, too.

> - Is this schema considered final and implementation ready for 0.7?
>
> And for what I [think I] know is true:
> - 0.7+ utilizes these XML files, whereas 0.6 does not
> - The lang attributes are not implemented currently, unlike help() usage today

These two points are true. As yet, the code isn't implemented to
properly use translations in the xml.

> - Not many (4) plugins in habari-extras use <help> yet, whereas several do within system/plugins
> - None use 'main' or 'secondary', but instead simply <help>

The main reason for this is that the help() in the plugin code came
first. With support still remaining for it in the core code, and
considering that if translation files are distributed with the plugin
the help in this function can be properly translated, there has been
little incentive to update the plugins. The core plugins, on the other
hand, try to stay in step with current code as examples of best
practices in writing plugins. Once translation support is incorporated
in the core code, having help in the xml should save having to load
what could be an extensive amount of text every time the plugin is
loaded.
>
> Regards,
> Philip

Rick

[Owen Winkler]

rick c wrote:
>>
>> I have two questions:
>> - How do the 'main' and 'secondary' name attributes apply in real life?
>
> I'd be interested in the answer to this, too.

The intent is to allow a plugin to display different help when you click
on the ? button depending on what's being displayed in the plugin
configuration, and to allow a plugin the potential to provide links in
the initial help to other "pages" of help that provide more details for
complex operations.

This would be particularly helpful for plugins like the podcast plugin,
which has multiple options in its dropdown, and each displays a
different form. By supplying a different set of help to each page, you
wouldn't need to sift through a single over-long chunk of text to get at
the instructions you need.

The implementation of this is in the same place as the language-specific
xml -- not there yet.

>> - Is this schema considered final and implementation ready for 0.7?

There are probably some things that could be improved in the schema, but
for 0.7, I think it's ready.

Owen

[Philip Olson]

On Nov 30, 2009, at 5:47 AM, Owen Winkler wrote:

> rick c wrote:
>>>
>>> I have two questions:
>>> - How do the 'main' and 'secondary' name attributes apply in real life?
>>
>> I'd be interested in the answer to this, too.
>
> The intent is to allow a plugin to display different help when you click
> on the ? button depending on what's being displayed in the plugin
> configuration, and to allow a plugin the potential to provide links in
> the initial help to other "pages" of help that provide more details for
> complex operations.
>
> This would be particularly helpful for plugins like the podcast plugin,
> which has multiple options in its dropdown, and each displays a
> different form. By supplying a different set of help to each page, you
> wouldn't need to sift through a single over-long chunk of text to get at
> the instructions you need.
>
> The implementation of this is in the same place as the language-specific
> xml -- not there yet.

Sounds reasonable. And to help add a little clarification, the following appears true today (in 0.7):

1. <help> without a name attribute is the default, and will always show (alone or with another).

2. The name attribute directly coincides with the configure action name.

Example: podcast has 'managefeeds' and 'configure_player' configure actions, so:

- <help name="managefeeds"><value>Manage your podcast feeds by doing this</value></help>
- <help name="configure_player"><value>Configure the podcast player like so</value></help>

3. The named helps are inline, so do not slide in/out like the default helps (so no jquery magic).

>>> - Is this schema considered final and implementation ready for 0.7?
>
> There are probably some things that could be improved in the schema, but
> for 0.7, I think it's ready.

Cool, I'll begin investigating and testing these further.

Regards,
Philip