Sample library.info file: Difference between revisions

From OLPC
Jump to navigation Jump to search
No edit summary
 
(50 intermediate revisions by 6 users not shown)
Line 1: Line 1:
Here is an example <tt>library.info</tt> configuration file for a collection called <tt>Dictionary</tt>:
To [[Creating a collection|create a collection]] you need a <tt>library.info</tt> file specifying information for it. Here is an example <tt>library.info</tt> configuration file for a collection called <code>Dictionary</code>, whose starting page is <tt>bundle_index.html</tt> in its root directory.


[Library]
[Library]
name = "Dictionary"
name = Dictionary
global_name = org.logos.dictionary
library_version = 1
long_name = children's dictionary
license = CC-BY-SA
library_version = 2
host_version = 1
host_version = 1
class = "dictionary"
l10n = false
l10n = false
locale = "en_US"
locale = en
category = "books"
category = books
subcategory = reference
category_icon = "library-dictionary.jpg"
icon = library-dictionary.jpg
subcategory = "reference"
activity = Browse
activity_start = bundle_index.html

To create a configuration file for your own collection, use the web-based [http://bantha.org/~kraken/olpc/bundler/makeLibraryInfo.html library.info file generator] or follow the instructions below.
== General Notes ==

; Entries : Entries are key/value pairs in the format: <code>Key = Value</code>. Space before and after the equals sign is ignored; the <code>=</code> sign is the actual delimiter.

; Multiple Values : Some keys can have multiple values. In such a case, the key is specified as a plural: for example, <code>locales</code>. The multiple values should each be separated by a semicolon. Keys that have multiple values must have a semicolon as the trailing character. Semicolons ''in'' these values need to be escaped using \;.


== Keys/Values==
== Keys/Values==
Line 16: Line 27:
; <tt>[Library]</tt> ''(required)'': The <tt>library.info</tt> file must begin with <tt>[Library]</tt>, and only that, on the first line of the file.
; <tt>[Library]</tt> ''(required)'': The <tt>library.info</tt> file must begin with <tt>[Library]</tt>, and only that, on the first line of the file.
<span id="basic_info"><!-- anchor for library.info generator. pls do not remove! --></span>
; <tt>name</tt> ''(required)'': This entry is the name is displayed in the library navigation sidebar that refers to the collection. Visit the online version of the [http://dev.laptop.org/pub/content/library/ OLPC Library] to view the current navigation sidebar and categories.
; <tt>name</tt> ''(required)'':


; <tt>global_name</tt> ''(required)'':
; <tt>library_version</tt> ''(required)'': The version is a single positive integer that refers to the version of the collection. Larger numbers are considered "newer". For now, the version is 1.


; <tt>host_version</tt> ''(required)'': The host version is a single positive integer that refers to the version of Sugar which the collection is compatible with. For now, the version is 1.
; <tt>long_name</tt> ''(required)'': This entry is the name is displayed in the library navigation sidebar that refers to the collection.


; <tt>license</tt> ''(required)'': This field names the license used for the content bundle. The contents of this field should conform to the same guidelines as the [http://fedoraproject.org/wiki/Packaging/LicensingGuidelines#License:_field <code>License:</code> field] of an RPM package; consult the [http://fedoraproject.org/wiki/Packaging/LicensingGuidelines Fedora Licensing Guidelines] for more information. A 'license' field naming an entry or entries in the "Good Licenses" table for Content Licenses at [http://fedoraproject.org/wiki/Licensing Fedora's Licensing list] is required for any content distributed by OLPC.
; <tt>l10n</tt> ''(required)'': This entry indicates whether the bundle is "officially" localized. The value is either <tt>true</tt> or <tt>false</tt>.


; <tt>library_version</tt> ''(required)'': The version is a single positive integer that refers to the version of the collection. Larger numbers are considered "newer". In this example, the version is 2.
:''Note: What it means to be "officially" localized hasn't been entirely worked out yet, so the value of this entry is <tt>false</tt> for now.

; <tt>host_version</tt> ''(required)'': The host version is a single positive integer that refers to the version of Sugar which the collection is compatible with. For now, the version is 1. Do not use a different value.

<span id="l10n"><!-- anchor for library.info generator. pls do not remove! --></span>
; <tt>l10n</tt> ''(required)'': This entry indicates whether the bundle is localized or not. The value is either <tt>true</tt> or <tt>false</tt>.

:''Note: What it means to be "officially" localized hasn't been entirely worked out yet, so the value of this entry is always <tt>false</tt> (for now).
; <tt>locale</tt> : This is the ISO code for the primary language of the collection, in lowercase, followed by an underscore, and then its localization information (also represented in ISO code). In this case, US-localized English is represented as en_US. UK-localized English, for example, would be represented as en_UK.
; <tt>locale</tt> ''(required)'': This is the ISO code for the language of the collection, in lowercase, followed by an underscore, and then its localization information (also represented in ISO code). For example, US-localized English is represented as en_US. UK-localized English, for example, would be represented as en_UK.

:It is possible to indicate language but not localization information. An example would be:
:<code>locale = es </code>

:It is also possible to indicate multiple languages and/or locales. An example would be:
:<code>locales = en_US;en_UK;es_PE;es_AR;</code>

:Note that <tt>locales</tt> is pluralized in order to indicate multiple values. Note also that values are separated by semi-colons, and that the final value must end with a semi-colon as well.


: For a list of [[ISO 639]] language codes, see http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
: For a list of [[ISO 639]] language codes, see http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
Line 32: Line 59:
: For a list of ISO country codes, see http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
: For a list of ISO country codes, see http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements


<span id="categories"><!-- anchor for library.info generator. pls do not remove! --></span>
: ''Note: At some point, the <tt>locale</tt> line should be expanded to match the [[Activity_bundle#Activity_Name_Localization.2FTranslation|localization scheme for activity bundles]]. For now, this spec only supports single-language bundles.''
; <tt>category</tt> ''(required)'': This refers to the category classification in the OLPC Library (visible on navigation sidebar). See the category chart below for current options.


:Note: It's OK to place your content in a new category, but if your category isn't on the list of global categories, it will be placed into "other" for the time being.
; <tt>class</tt> ''(optional)'': This entry is required if the collection is using a customized <tt>library.css</tt> file. The <tt>class</tt> value should be the same name as the collection's <tt>.xol file</tt>, except in lower case (and without the ".xol"). No whitespace or special characters are allowed.


; <tt>category</tt> : This refers to the subject classification in the OLPC Library (visible on navigation sidebar). The "category" value also corresponds to that category's class in the default CSS settings. See category chart below for current options. As always, if you don't like what you see, you can add your own.
; <tt>subcategory</tt> ''(currently unused)'': This refers to the subcategory classification within a category (visible on the navigation sidebar).


<span id="optional"><!-- anchor for library.info generator. pls do not remove! --></span>
; <tt>category_icon</tt> ''(optional)'': This is the filename of the icon that represents the collection in the library navigation sidebar. The actual image file is stored in the <tt>library</tt> directory (see [[Creating_a_content_bundle#Configuration_Files|configuration files]]. This line is only required if you decide to place your collection in its own top-level category in the navigation sidebar.
; <tt>activity</tt> ''(currently unused)'': This refers to the [[Activity]] used to read the content bundle, but Browse is the only supported activity at this time.


; <tt>subcategory</tt> ''(optional)'' : This refers to the subcategory classification within a category (visible on the navigation sidebar). If no subcategory is provided, the collection will be placed in its own subcategory. See category chart for current options. Again, as always, if you don't like what you see, you can add your own.
; <tt>activity_start</tt> ''(optional)'': This refers to the start page of your content bundle. The default is <tt>index.html</tt>. You might change the start page of the bundle, for instance, if you were converting a collection of OCW courses to be content bundles. (They name their homepage differently.)

:''Note:Subcategory placement is not yet automated. Syntax/whitespace/case sensitivity/etc will depend on how pattern matching is implemented.


==Category Chart==
==Category Chart==
The current category and subcategory options are:


The current category and subcategory options are:
{| border="1px;solid" cellpadding="3px"
{| border="1px;solid" cellpadding="3px"
|-
|-
|'''Description''' || '''Category''' || '''Current Subcategories'''
|'''Icon''' || '''Category''' || '''Icon''' || '''Subcategories'''
|-
|-
|style="background:gray" | [[Image:activities.png|40px]] || activities || activities.png || games
|Books and reference || <tt>books</tt> || <tt>picture books</tt>, <tt>reference</tt>, <tt>stories</tt>
|-
|-
|style="background:gray" | [[Image:books.png|40px]] || books || books.png|| children's books, encyclopedia, reference, stories
|Math and science || <tt>science</tt> || <tt>biology</tt>
|-
|-
|style="background:gray" | [[Image:uniwiki.png|40px]] || health || uniwiki.png || water & sanitation
|Images and maps || <tt>images</tt> || <tt>nature</tt>, <tt>atlas</tt>, <tt>historical</tt>
|-
|-
|style="background:gray" | [[Image:images.png|40px]] || images || images.png || nature, atlas, history
|Music and video || <tt>music</tt> || <tt>media</tt>
|-
|-
|style="background:gray" | [[Image:music.png|40px]] || media || music.png || media, music
|Activities || <tt>activities</tt> || <tt>games</tt>
|-
|-
|style="background:gray" | [[Image:science.png|40px]] || science || science.png || biology
|Web links || <tt>links</tt> || <tt>search the web</tt>
|-
|-
|style="background:gray" | [[Image:links.png|40px]] || search || links.png || search the web
|Uniwiki || <tt>uniwiki</tt> || <tt>water & environment</tt>
|}
|}


Visit the [http://dev.laptop.org/pub/content/library/ OLPC Library] to see these categories in action.
Browse the OLPC Library on your XO to see these categories in action.

== General Notes ==

.info files follow a key/value pair format, similar to the [http://standards.freedesktop.org/desktop-entry-spec/latest/ fd.o desktop entry spec]

'''Entries'''

Entries in the file are {key,value} pairs in the format:

<tt>Key = Value</tt>

Space before and after the equals sign should be ignored; the = sign is the actual delimiter.

Key names must contain only the characters A-Za-z0-9-.

As the case is significant, the keys Name and NAME are not equivalent.

Multiple keys in the same group may not have the same name. Keys in different groups may have the same name.

'''Possible Value Types'''

The value types recognized are string, boolean, and numeric.

* Values of type string may contain all ASCII characters except for control characters (space, newline, tab, carriage return, etc.). To include any of these characters, use the appropriate escape sequence. Strings should be delimited by double quotation marks, e.g. <tt>"This is a string"</tt>.
* Values of type boolean must either be <tt>true</tt> or <tt>false</tt>.
* Values of type numeric must be a valid floating point number, e.g. <tt>13</tt> or <tt>-2.5</tt>.


[[Category:File formats]]
Some keys can have multiple values. In such a case, the value of the key is specified as a plural: for example, <tt>locales</tt>. The multiple values should be separated by a semicolon. Those keys which have several values should have a semicolon as the trailing character. Semicolons in these values need to be escaped using \;.
[[Category:HowTo]]
[[Category:Bundles]]

Latest revision as of 13:24, 21 April 2010

To create a collection you need a library.info file specifying information for it. Here is an example library.info configuration file for a collection called Dictionary, whose starting page is bundle_index.html in its root directory.

[Library]
name = Dictionary
global_name = org.logos.dictionary
long_name = children's dictionary
license = CC-BY-SA
library_version = 2
host_version = 1
l10n = false
locale = en
category =  books
subcategory = reference
icon = library-dictionary.jpg
activity = Browse
activity_start = bundle_index.html

To create a configuration file for your own collection, use the web-based library.info file generator or follow the instructions below.

General Notes

Entries
Entries are key/value pairs in the format: Key = Value. Space before and after the equals sign is ignored; the = sign is the actual delimiter.
Multiple Values
Some keys can have multiple values. In such a case, the key is specified as a plural: for example, locales. The multiple values should each be separated by a semicolon. Keys that have multiple values must have a semicolon as the trailing character. Semicolons in these values need to be escaped using \;.

Keys/Values

[Library] (required)
The library.info file must begin with [Library], and only that, on the first line of the file.

name (required)
global_name (required)
long_name (required)
This entry is the name is displayed in the library navigation sidebar that refers to the collection.
license (required)
This field names the license used for the content bundle. The contents of this field should conform to the same guidelines as the License: field of an RPM package; consult the Fedora Licensing Guidelines for more information. A 'license' field naming an entry or entries in the "Good Licenses" table for Content Licenses at Fedora's Licensing list is required for any content distributed by OLPC.
library_version (required)
The version is a single positive integer that refers to the version of the collection. Larger numbers are considered "newer". In this example, the version is 2.
host_version (required)
The host version is a single positive integer that refers to the version of Sugar which the collection is compatible with. For now, the version is 1. Do not use a different value.

l10n (required)
This entry indicates whether the bundle is localized or not. The value is either true or false.
Note: What it means to be "officially" localized hasn't been entirely worked out yet, so the value of this entry is always false (for now).
locale (required)
This is the ISO code for the language of the collection, in lowercase, followed by an underscore, and then its localization information (also represented in ISO code). For example, US-localized English is represented as en_US. UK-localized English, for example, would be represented as en_UK.
It is possible to indicate language but not localization information. An example would be:
locale = es
It is also possible to indicate multiple languages and/or locales. An example would be:
locales = en_US;en_UK;es_PE;es_AR;
Note that locales is pluralized in order to indicate multiple values. Note also that values are separated by semi-colons, and that the final value must end with a semi-colon as well.
For a list of ISO 639 language codes, see http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
For a list of ISO country codes, see http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements

category (required)
This refers to the category classification in the OLPC Library (visible on navigation sidebar). See the category chart below for current options.
Note: It's OK to place your content in a new category, but if your category isn't on the list of global categories, it will be placed into "other" for the time being.
subcategory (currently unused)
This refers to the subcategory classification within a category (visible on the navigation sidebar).

activity (currently unused)
This refers to the Activity used to read the content bundle, but Browse is the only supported activity at this time.
activity_start (optional)
This refers to the start page of your content bundle. The default is index.html. You might change the start page of the bundle, for instance, if you were converting a collection of OCW courses to be content bundles. (They name their homepage differently.)

Category Chart

The current category and subcategory options are:

Icon Category Icon Subcategories
Activities.png activities activities.png games
Books.png books books.png children's books, encyclopedia, reference, stories
Uniwiki.png health uniwiki.png water & sanitation
Images.png images images.png nature, atlas, history
Music.png media music.png media, music
Science.png science science.png biology
Links.png search links.png search the web

Browse the OLPC Library on your XO to see these categories in action.