Bug 24897

Maemo 5 also puts various UI-specifics in profiles, including:

* for each available presence, the corresponding gettext()able string and icon

* for each available "action" (call, chat etc.), the corresponding icon, gettext()able string, vCard field, and properties to put in the EnsureChannel request (handle type CONTACT seems to be assumed?)

*** Bug 17836 has been marked as a duplicate of this bug. ***

This depends on Protocol objects, which are bug 20774.

Also, see the thread starting at http://lists.freedesktop.org/archives/telepathy/2010-June/004570.html for discussion.

Created attachment 37573 [details]
IRC log

Here is a summary of what was agreed on IRC regarding profiles:

- Profiles files will be searched in $XDG_DATA_HOME, defaulting to ($HOME/.local/share if unset), followed by colon-separated paths from $XDG_DATA_DIRS (defaulting to /usr/local/share:/usr/share if unset) for the files named telepathy/profiles/$service-name.profile

  If while traversing search dirs we find a profile for a given service, all subsequent profiles found for the same service should be ignored.
 
  The filename must be the same info return by Account.ServiceName, meaning that
for "main" CMs (each platform is responsible for defining what are the "main" CMs) this should be the service name as is, for example gabble should  just google-talk, while for non "main" CMs the filename must be named service-name-$something, where $something should be an unique identifier (CM name probably), to avoid name collisions).
 
  The file format defines the service with an xml element <service> with a atrribute "id" (e.g. <service id="google-talk"> where id MUST match the filename or it will be considered syntax error. This redundant info is useful for example when users download profiles whose filenames cannot be guaranteed, meaning that in this case if the filename is not the same as what is defined in the element service attr id, the file MUST be renamed before installation.

  The file is a XML file that follows an specific format. Vivek is working on updating the file format with the changes we agreed on IRC.

  See IRC log for more details.

Draft of the file format, as agreed at the end of the last meeting [see URL]

Mikhail Zabaluev suggested the following, which I think is a good idea for the most parts:

> Quoting the example:
> 
> <service id="google-talk"
>          xmlns="http://telepathy.freedesktop.org/wiki/service-profile-v1">
> 
>   <type>IM</type>
>   <provider>google</provider>
>   <name>GoogleTalk™</name>
>   <icon>base-name-of-icon</icon>
> 
>   <manager>gabble</manager>
>   <protocol>jabber</protocol>
> 
> Now the same reworked with an XML schema nazi attitude:
> 
> <service xmlns="http://telepathy.freedesktop.org/wiki/service-profile-according-to-mikhailz"
>          id="google-talk"
>          type="IM"
>          provider="google"
>          manager="gabble"
>          protocol="jabber">
> 
>   <name>GoogleTalk™</name>

++ for these

>   <icon base-name="base-name-of-icon" />  <!--
>      a simpler option could be file="pathname",
>      some could use stock-id="foo_bar"
>      or even uri="http://tranquility.moon/cheese.svg" -->

I think we want the same semantics, that is, the im-foo style name, for this one as the Icon property for Accounts and in the spec 0.19.10 .manager file additions, Protocol objects follows these semantics too. I'd think this would ~always be used with an icon loader which you can just pass the base name to, instead of having to specify the complete path? The base name, without the file extension, is beneficial in that we get icons from the current icon theme, in the desired size, if there are suitable ones, be they svg or png.

> 
> Rules of thumb applied:
> 
> * A unique attribute with a simple value is, naturally, best represented by an XML attribute.
> * A value that has a strict syntax (e.g. a pathname, an URI, or a member of an established registry) is safer as an XML attribute value, where less XML fanciness is permitted to disrupt the text content.
> For instance, less potential for stupid difficulties like <type> IM <!-- is this right? --></type> interpreted differently from <type>IM</type>. This does not mean only your code, but any tools that might be applied to these files for fun and profit.
> * When value's semantics are not the most natural to serve as the unqualified content to an entity (e.g. the fact that an icon is referred by a base name with some implied transformation), make it an attribute with a name referring to the semantics.
> * Text content is generally meant for text readable by the user. So <name/> is using it rightfully.
> 
> Misha,
>   amazed at how most people make their XML unnecessarily hard to use and fragile.
> 

Fully agree :)

Had a private exchange with Alberto on this, continuing it here:

>> Are libaccounts clients actually interested in the manager and protocol,
>> or not? And no, we don't want them to be stored as settings and have to
>> be special-cased from other, actual settings (or rather parameters, see
>> below).
> 
> I'd say that generally they are not interested. The only client being
> very interested in them is MC, though. :-)

MC uses tp-glib, which will expose these fields, so I think that's sorted out - or does MC definitely have to use libaccounts to parse the profile files? It could just get the profile name from libaccounts and use tp-glib to parse it.

> 
>> I'm sorry, I'm not terribly familiar with whatever we use libaccounts
>> for, so please enlighten me.
> 
> libaccounts is being used by the accounts-ui to configure the account.
> So, all settings which a user is allowed to change should be accessible
> via the libaccounts API.
> It is also used by MC, to get the list of IM accounts, and their settings.
> 

Ok, so possibly we could add API to libaccounts to support the extra semantics/API specific to IM accounts wherever needed?

>> Why did you ask us to draft a standard file format in the first place if
>> you aren't willing to make libaccounts support it?
> 
> Depends what you mean by "support". There could be different levels of
> support, the least one being "compatible": libaccounts successfully
> loads the service file you define, and ignores all elements it doesn't
> recognize.
> 

Surely the parser can map tp <parameter> elements to whatever libaccounts <setting> elements are represented as in the API, be they inside a <group> with a magic name or inside a <parameters> container? That is, there won't be <parameter>s anywhere else anyway in the tp format so you can just get <parameter> / <setting> nodes from any subtree starting from the root and use them. (Or if you're using SAX just don't require them to be in any specific container element when you encounter one).

>> The service-profile-v1 format is intended to be specific to representing
>> IM service profiles, we'd much rather not have any generic <group>
>> element type in there, as we just want a parameters container, and no
>> other "groups" of the sort.
> 
> But I wouldn't like to modify libaccounts every time an element is added
> to any service file (you are defining the format for IM services, but
> there are many more -- sharing, e-mail, calendar, social networking...),
> so I'd rather libaccounts provide clients with a way to retrieve any
> information they want.
> 
> The tree structure is rather powerful, although it might not be the most
> efficient, to cover most of the data description cases.

You shouldn't need to add any elements beyond the parameters and the name, most likely.

> 
>> Also, having the per-parameter element be <parameter> is consistent of
>> how the rest of Telepathy calls account/connection *parameters*. Calling
>> them settings in profile files and parameters in manager files would be
>> confusing.
> 
> Well, but when talking about accounts we usually refer to them as
> "settings"; anyway, I'm not totally against changing this name, as long
> as we have only *one* element name for all single value elements in the
> XML file.
> 
> To clarify: there are a few basic properties that are more or less used
> in all services, whatever type they belong to. For instance, the "name",
> "icon", "enabled" properties are common to all services, whether they
> are IM, e-mail, sharing or what not. These deserve their own element
> name in the XML file, and must be available through libaccounts APIs.
> Other things, such as the server address, are not common to all service
> types, but they might be used in all services of a specific service
> type, for instance IM. Since these things are different among different
> service types, we don't want to hardcode their names and semantics into
> libaccounts -- we just want to give the clients some way to retrieve
> them. The <group> and <setting> elements should do the trick well
> enough. If they don't, let's see why.

Fine, just treat <parameters> like you would treat <group name="parameters"> in the parser then? Ditto for <parameter> vs <setting>? This way, clients using actual Telepathy libraries (tp-glib, tp-qt4) will get them with the usual semantics/naming they expect, and libaccounts clients will see them as "settings" in a single group.

Frankly, this is what XML namespaces are for - and why we defined our namespace to be service-profile-v1, not libaccounts-misc-whatever. You can easily support both current libaccounts format and the standard TP profile format in your parser if you take the namespace into account.

> So, my initial call was to invite the Rtcom/Telepathy people to define a
> set of settings for the IM service type, not to redesign how libaccounts
> works (although if there are good reasons to do so, that can be done
> too) :-)
> 
>> The mandatory attribute doesn't mean the same thing in the profile draft
>> as it does in the .manager files.
>>
>> In .manager files, a parameter being mandatory means that SOME value
>> must be provided for the parameter always when creating an account /
>> requesting a connection.
>>
>> However, in profile files, a parameter being mandatory means that the
>> parameter must be set to *the specific value* specified by the element.
>> This is thus that eg. GTalk accounts will always connect to the actual
>> GTalk server (talk.google.com) instead of allowing the user to change
>> the parameter to some random jabber server. Note that in current gabble
>> .manager the server isn't even mandatory anymore, because we can do SRV
>> lookups based on the account parameter, but in a GTalk profile for
>> gabble it would be.
>>
>> I agree this is a bit confusing though. Maybe we should call mandatory
>> something different here - fixed-for-service? Just fixed?
> 
> It could be a 'readonly="true"' attribute on the setting, meaning that
> this setting cannot be overriden by setting the same key on the accounts
> DB: the XML file will always have precedence over the account DB for
> this key. But on the other hand, do we need it? The users are not
> editing the accounts DB by hand, they only do via a UI which should know
> what settings to show.
> 

readonly sounds fine to me (read-only would be better naming though, or do we need this to be compatible with libaccounts <setting> nodes?). The point of having the attribute in the first place is to *NOT* have to hard-code all profile-specific knowledge in the UIs. If we can represent this information in a standard way in data/script files, there needs to be much less profile/protocol-specific code in the UIs. These include desktop UIs like the Empathy one and the aspiring KDE Telepathy ones too, mind you!. This is especially important so that we can support installing new profiles without code changes for them / compiled plugins, which is one design goal we had in mind while designing the profile format.

(In reply to comment #8)
> Had a private exchange with Alberto on this, continuing it here:
> 
> >> Are libaccounts clients actually interested in the manager and protocol,
> >> or not? And no, we don't want them to be stored as settings and have to
> >> be special-cased from other, actual settings (or rather parameters, see
> >> below).
> > 
> > I'd say that generally they are not interested. The only client being
> > very interested in them is MC, though. :-)
> 
> MC uses tp-glib, which will expose these fields, so I think that's sorted out -
> or does MC definitely have to use libaccounts to parse the profile files? It
> could just get the profile name from libaccounts and use tp-glib to parse it.

Since libaccounts is parsing these files anyways, I'd rather have their content exposed somehow in the libaccounts API. Currently libaccounts has an API to retrieve the file contents (not the filename, though that could be added too), but of course it would be better if we find a direct solution.

> > libaccounts is being used by the accounts-ui to configure the account.
> > So, all settings which a user is allowed to change should be accessible
> > via the libaccounts API.
> > It is also used by MC, to get the list of IM accounts, and their settings.
> 
> Ok, so possibly we could add API to libaccounts to support the extra
> semantics/API specific to IM accounts wherever needed?

Indeed.

> >> Why did you ask us to draft a standard file format in the first place if
> >> you aren't willing to make libaccounts support it?
> > 
> > Depends what you mean by "support". There could be different levels of
> > support, the least one being "compatible": libaccounts successfully
> > loads the service file you define, and ignores all elements it doesn't
> > recognize.
> > 
> 
> Surely the parser can map tp <parameter> elements to whatever libaccounts
> <setting> elements are represented as in the API, be they inside a <group> with
> a magic name or inside a <parameters> container? That is, there won't be
> <parameter>s anywhere else anyway in the tp format so you can just get
> <parameter> / <setting> nodes from any subtree starting from the root and use
> them. (Or if you're using SAX just don't require them to be in any specific
> container element when you encounter one).

This is indeed technically possible, but read below...

[...]
> > type, for instance IM. Since these things are different among different
> > service types, we don't want to hardcode their names and semantics into
> > libaccounts -- we just want to give the clients some way to retrieve
> > them. The <group> and <setting> elements should do the trick well
> > enough. If they don't, let's see why.
> 
> Fine, just treat <parameters> like you would treat <group name="parameters"> in
> the parser then?

This was actually working but Mikhail didn't like it -- and I agreed; see internal nokia bug 173355. Summing up, his remark was:

"This still uses the XML syntax so it could be parsed by an XML parser, but is
not a good practice for anything other that XML can help with, like document
validation or XSLT transformations."

> Ditto for <parameter> vs <setting>?

This is a slightly different thing. In libaccounts there is

<setting name="server" type="s">talk.google.com</setting>

and AFAIU you are not proposing to have

<server type="s">talk.google.com</server>

but just a renaming of the element:

<parameter name="server" type="s">talk.google.com</parameter>

Which would be perfectly fine, and we can even support "parameter" as alias for "setting", it's just that I see it as just a cosmetic issue not worth a change. You prefer talking about "account parameters", I prefer "account settings". Or did I miss your point?

> readonly sounds fine to me (read-only would be better naming though, or do we
> need this to be compatible with libaccounts <setting> nodes?). The point of
> having the attribute in the first place is to *NOT* have to hard-code all
> profile-specific knowledge in the UIs. If we can represent this information in
> a standard way in data/script files, there needs to be much less
> profile/protocol-specific code in the UIs. These include desktop UIs like the
> Empathy one and the aspiring KDE Telepathy ones too, mind you!. This is
> especially important so that we can support installing new profiles without
> code changes for them / compiled plugins, which is one design goal we had in
> mind while designing the profile format.

Mmm... first of all, we don't have yet a concept of read-only setting in libaccounts; it would be a new thing, so we can come up with anything we like.

But, as it comes to dynamically generated UIs for service settings, I'll run the risk to violate some secret and describe how this is being done in the Maemo Harmattan account-ui: although the UI is dynamically generated from the .service files, its description is under a different XML element, mainly because not all telepathy parameters should be exposed in the UI as account settings, and not all account settings are telepathy parameters. Also, one UI widget might cover two telepathy parameters (for instance server + port could be one common widget). Cutting it short, in general there is no 1-1 correspondence, unless you want a really trivial (and ugly :-) ) UI.

So, we have something like that:

<ui>
  <layout type="flow">
    <widget type="text" label="Server:" mandatory="true" key="parameters/server"/>
    <widget ... />
  </layout>
</ui>

And this allows us to have different layouts, and create more fancy widget in the future. Recalling the example above, we might have a smarter UI parser which could build widgets like this

<widget type="server" label="Proxy">
  <setting type="address" key="parameters/server"/>
  <setting type="port" key="parameters/port"/>
</widget>

That's actually why libaccounts allows the client to get the contents of the file: not for parsing the settings, but for any other application specific things that it doesn't recognize. Of course it would be better if it could expose everything through its APIs, but that would also mean limiting the XML structure.
I also thought that libaccounts-glib could expose the xmlTextReaderPtr it is using internally, but in that way we wouldn't be free to move to some other XML parser, and it might be a PITA to write bindings to other languages.

On the other hand, for things like UI descriptions, which are probably specific to an application only (the accounts-ui), it might be better to keep those things out of the .service file, and ship a different XML file, with a format defined by the application, in another filesystem location which can be derived from the service name. For instance, there could be

/usr/share/maemo-accounts-ui/<service name>.xml
/usr/share/empathy/services/<service name>.empathy
...

each file with the format defined by the application which is using them.
The bad side of this is that the service provider needs to ship several files instead of one only, but it's not a big deal.
The good sides:
1) most applications would be parsing less XML code (for instance, MC wouldn't parse the empathy or maemo-accounts-ui files, since it doesn't need any information contained in them)
2) ease of installation and upgrade: when someone comes up with the rocking KDE accounts-ui, providers willing to support it will just have to have one small package which ships this UI's specific file, without touching the existing ones.

BTW, in my mail you quoted above I missed this latter part, of application/framework specific informations: so, summing up, there are at least three kinds of data related to services:

1) Read-only data which all services should have, no matter whether they are IM, e-mail, or anything. Example: name, icon, provider, service type.

2) Template values for account settings: this settings might be specific for the service type or even for the service (example: CM parameters); they are specified as default values in the XML file, but the account storage should be able to override them.

3) Application/framework specific information. Examples: the name of the CM to be used, the protocol, the definition of the presence types, the supported channels, the smileys, etc.

Of these things, libaccounts-glib supports (in the sense that it provides applications with easy access to read these data) only the first two.
I wouldn't dislike to have the application/framework specific parts out of the libaccounts .service files, as I was writing in the end of my previous comment; in alternative, what we currently offer is the raw access to the .service file contents, which seems to be a poor solution (because it means that every client would re-parse the document to extract the information it's interested in).

Any suggestion on how libaccount-glib could improve this situation is more than welcome. :-)
(you can use the meego-dev mailing list, if you feel like)

(In reply to comment #7)
> >   <name>GoogleTalk™</name>

Do we need to translate any texts in the manifests?
If yes, we can write in a refinement:

<name translation-id="bork_bork_acct_name_gtalk">GoogleTalk™</name>

Not everybody (ahem) knows to use gettext and intltool. For those who do, it can be more standard:

<name>GoogleTalk™</name>
<name xml:lang="ru">GoogleTalk™</name>

(In reply to comment #11)
> (In reply to comment #7)
> > >   <name>GoogleTalk™</name>
> 
> Do we need to translate any texts in the manifests?

Most likely yes.

> If yes, we can write in a refinement:
> 
> <name translation-id="bork_bork_acct_name_gtalk">GoogleTalk™</name>

While I like this, unfortunately it's a bit hard to use in Qt. AFAIK Qt doesn't allow you to specify the domain which should be used for translating a string; instead, you have to preload the domain(s), and then just translate the string hoping that the same string is not present in more than one domain.

That's why in harmattan we are using one global <translations> tag; but it's just a trick to make life easier for Qt developers, your suggestion is better.

> Not everybody (ahem) knows to use gettext and intltool. For those who do, it
> can be more standard:
> 
> <name>GoogleTalk™</name>
> <name xml:lang="ru">GoogleTalk™</name>

This is also OK.

fwiw I think keeping the UI/layout stuff elsewhere is the right decision,
for the same reason we decided translations belonged elsewhere: The service
profile defines the "mechanical" bits of the service, the things needed to 
make it work - updating a ui or adding a localisation shouldn't affect the 
service profile file, as that would make it pretty hairy to maintain.

Is there any decision on this yet? FWIW we tentatively implemented and released support for the latest format spec augmented with Mikhail's suggestions in tp-qt4-0.3.11 already.

-- GitLab Migration Automatic Message --

This bug has been migrated to freedesktop.org's GitLab instance and has been closed from further activity.

You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.freedesktop.org/telepathy/telepathy-spec/issues/45.