GNOME Bugzilla – Bug 741788
Document GSettings build system integration
Last modified: 2015-06-09 07:28:53 UTC
Currently this is only documented in migrating-gconf.xml, which makes it: a) hard to find, and b) tied up in a load of GConf documentation. These patches distil the relevant GSettings-only documentation to the main GSettings documentation block.
Created attachment 293105 [details] [review] gsettings: Expand documentation default value l10n Mention context, translation category, and the need for syntactic validity of the translated values.
Created attachment 293106 [details] [review] gsettings: Document GSettings build system integration Add a new section to the main GSettings documentation which documents the best practices for integrating GSettings into an autoconf/automake build system using the GLIB_GSETTINGS macro. Some of this material was adapted from the migrating-gconf.xml guide.
Created attachment 293107 [details] [review] gsettings: Add a documentation section on relocatable schemas
Created attachment 293108 [details] [review] gsettings: Fix a typo in the GSettings documentation
(In reply to comment #2) > Created an attachment (id=293106) [details] [review] > gsettings: Document GSettings build system integration > > Add a new section to the main GSettings documentation which documents > the best practices for integrating GSettings into an autoconf/automake > build system using the GLIB_GSETTINGS macro. > > Some of this material was adapted from the migrating-gconf.xml guide. One thought about this — perhaps it would be best to explicitly say that marking a .gschema.xml file for translation will also translate the <summary> and <description> elements? IIRC people have had concerns about that in the past. I’ll include that in the next revision of the patches if desired.
Review of attachment 293108 [details] [review]: Philip: Feel free to commit stuff like this without review.
Review of attachment 293106 [details] [review]: My first reaction was "I hate having this kind of information in the reference docs" but I think this is actually pretty reasonable. Some comments below, though. Please note that I may be wrong -- it's been a while since I had non-trivial interactions with this stuff. ::: gio/gsettings.c @@ +259,3 @@ + * + * If any of the schema files are generated from another source, that source + * should be included in `EXTRA_DIST` (or an equivalent distribution variable) I don't think that this is actually necessary? Also: why are you generating schema files? That would probably not work very nicely for intltool, which expects to be able to work on a pristine checkout. @@ +263,3 @@ + * + * No changes are needed to the build system to mark a schema XML file for + * translation. Assuming it sets the `gettext-domain` attribute, a schema may I'd specifically go out of my way to mention that the translations are handled by gettext at runtime, so you should not use a .xml.in file. This is a fairly common mistake. @@ +285,3 @@ + * automatically included in the schema compilation, install and uninstall + * rules. It should not be committed to version control or included in + * `EXTRA_DIST`. If you remove the note about EXTRA_DIST above, probably worth dropping the mention here as well.
Review of attachment 293107 [details] [review]: Ya... this is OK, but it seems a bit overly explicit in some places. I'm not sure it really needs to be stated that values that you store in a particular path will indeed still be there again later... ::: gio/gsettings.c @@ +246,3 @@ + * <schema> element. By using g_settings_new_with_path(), a #GSettings object + * can be instantiated for a relocatable schema, assigning a path to the + * instance. Paths passed to g_settings_new_with_path() will typically be Another intended use was for common types of objects like a schema for specifying the size/position of a window that could then be used by any apps at random places -- not just the 'common prefix' case.
Review of attachment 293105 [details] [review]: ::: gio/gsettings.c @@ +105,3 @@ + * translation category. A recommended but optional translation context can be + * set with the `context` attribute on the <default> element. This provides a + * message to translators giving context for the default value. I'm not sure context is recommended per se, nor is it in common use. Context is usually used for disambiguation more than anything else, and it is unlikely that there would be a conflict between the few defaults that people typically translate. A full translators comment is usually more helpful -- I'd recommend that more than trying to jam a few meaningful words into the context. gucharmap does both and the result ends up looking reasonable for translators: #. The unicode code point of the first letter of the alphabet #: ../gucharmap/org.gnome.Charmap.gschema.xml.h:12 msgctxt "First letter" msgid "0x41" msgstr "0x623" but I'd argue that it's just as readable without the context. Maybe something along the lines of 'make sure to add a comment -- and context can be useful if there is a chance that the same string gets translated in more than one spot".
Comment on attachment 293108 [details] [review] gsettings: Fix a typo in the GSettings documentation Attachment 293108 [details] pushed as 70e2630 - gsettings: Fix a typo in the GSettings documentation
Created attachment 294507 [details] [review] gsettings: Expand documentation default value l10n Mention context, translation category, and the need for syntactic validity of the translated values.
Created attachment 294509 [details] [review] gsettings: Document GSettings build system integration Add a new section to the main GSettings documentation which documents the best practices for integrating GSettings into an autoconf/automake build system using the GLIB_GSETTINGS macro. Some of this material was adapted from the migrating-gconf.xml guide.
Created attachment 294532 [details] [review] gsettings: Add a documentation section on relocatable schemas
Ping?
Review of attachment 294507 [details] [review]: ::: gio/gsettings.c @@ +103,3 @@ + * + * The `l10n` attribute must be set to `messages` or `time`, and sets the + * translation category. A translation comment can be added as an XML comment You should include some hints here about when 'messages' is appropriate (basically: always) and when one might want to use 'time' (when specifying a translatable date format). @@ +113,3 @@ + * |[ + * <!-- The Unicode code point of the first letter of the alphabet. --> + * <default l10n='messages' context='First letter'>0x41</default> I think it might be more interesting to show an example that includes gvariant serialization syntax, and also include a translator comment that points out the syntax.
Review of attachment 294509 [details] [review]: ::: gio/gsettings.c @@ +251,3 @@ + * ## Build system integration # {#gsettings-build-system} + * + * GSettings comes with autoconf and automake macros to simplify compiling and To be pedantic, it is an autoconf macro, and an automake variable and placeholder... @@ +270,3 @@ + * translation. Assuming it sets the `gettext-domain` attribute, a schema may + * be marked for translation by adding it to `POTFILES.in`, assuming intltool + * 0.50.1 is in use: I would slightly prefer if we documented gettext 0.19 use instead of intltool use, considering intltools incompatibility with current automake.
Review of attachment 294532 [details] [review]: Looks good to me
Comment on attachment 294532 [details] [review] gsettings: Add a documentation section on relocatable schemas Attachment 294532 [details] pushed as c94e4c6 - gsettings: Add a documentation section on relocatable schemas
Created attachment 304644 [details] [review] gsettings: Expand documentation default value l10n Mention context, translation category, and the need for syntactic validity of the translated values.
Created attachment 304645 [details] [review] gsettings: Document GSettings build system integration Add a new section to the main GSettings documentation which documents the best practices for integrating GSettings into an autoconf/automake build system using the GLIB_GSETTINGS macro. Some of this material was adapted from the migrating-gconf.xml guide.
Review of attachment 304644 [details] [review]: Thanks, looks good now
Review of attachment 304645 [details] [review]: ok
Thanks! Attachment 304644 [details] pushed as 723961b - gsettings: Expand documentation default value l10n Attachment 304645 [details] pushed as 6cd1f8b - gsettings: Document GSettings build system integration