Skip to content

Latest commit

 

History

History
137 lines (103 loc) · 5.41 KB

Languages.xml extensions.markdown

File metadata and controls

137 lines (103 loc) · 5.41 KB
Raw

Languages.xml extensions

I've defined some extensions to the standard Espresso Languages.xml that allow a Sugar developer to convey more information abut their Sugar. These extensions primarily allow your Sugar to be indexed by my Sugar Manager.sugar and alexgordon's Coffee House.

Usage

These elements should be placed in a <meta> section of your Languages.xml file, as follows:

<?xml version="1.0" encoding="UTF-8"?>
<settings>
  
  <language id="com.someone.something">
    <!-- You should already have this, if you're defining a language -->
  </language>
  
  <meta>
    <!-- Extension's elements go here -->
  </meta>
  
</settings>

Elements

<name> (required)

The <name> element should contain, quite simply, the name of the sugar. In the vast majority of cases, this is going to be identical to the name of the folder in which the sugar's Language.xml file resides, but minus the .sugar extension.

<name>Django</name>

<description>

This should be a short and succinct description of the sugar. No formatting is guaranteed to be interpreted. This shouldn't often be longer than a sentance or two.

<description>Fully describes the Django web framework for Python</description>

<author> (required)

The author's (your) name(s). May be multiple names seperated by ", ".

<author>elliottcable, Alex Gordon</author>

<identifier> (required)

Identifier string (for the whole sugar, not the same as the language string above). Should probably look like 'tld.domain.Sugar.Language-name' or 'tld.domain.Sugar.Language-name.framework'. For example, 'com.mydom.Sugar.Ruby' or 'com.mydom.Sugar.Ruby.Rails'.

<identifier>name.elliottcable.Sugar.Python.Django</identifier>

<version status=""> (required)

This should store the current 'version string' of the sugar. If you change this number, systems may prompt the user to update your sugar.

The status attribute must be one of the following

  • development: Not working at all, still under active development in preparation for a preview version or a release

  • preview: Working, but not fully functional. Intended as a 'feature preview' for beta testers or interested parties

  • release: A release version, this is prepared for general use.

    0.1b2

    2.1

<download format=""> (required)

This should provide a publicly-accessibe URL at which the sugar's uncompiled sources can be accessed.

The 'format' attribute should be one of the following:

  • raw: Only to be used internally by systems. Do not use.
  • tgz: URL references a tarred GZIP
  • zip: URL references a zipfile
  • svn: URL references the Sugar directory's path in a SVN repository
  • git: URL references a publicly-accessible git upstream

In all cases, the archive/repository should have the Sugar directory as it's root - that is, the Languages.xml file and Sugar folders (Syntaxes, Itemizers, etc...) should all be directly within the root of the archive/ repository, not within a subfolder.

This URL should point to the version of the sugar referenced by the <version> tag in this same file, that is, don't simply point at the latest version (if you're pointing at a downloadable file and not a repository).

<download format="git">git://github.com/elliottcable/django.sugar.git</download>
<!-- ...or... -->
<download format="zip">http://stuff.elliottcable.name/django.sugar.2.1.zip</download>

<url>

The 'home URL' of the Sugar. This could be a project website, your personal website, or any URL at which the user could get more information about your Sugar's features and purpose before installing it.

<url>http://github.com/elliottcable/django.sugar/</url>

<dependencies>

This is an array of dependency elements, each of which references the identifier of a Sugar upon which this Sugar depends. Dependencies will be automatically installed first if found, and this sugar will marked as unavailable if it's dependencies are not found / unavailable.

<dependencies>
  <dependency id="name.elliottcable.Sugar.Python">Python</dependency>
</dependencies>

<script interpreter="">

A shell script / shell command to be executed after the sugar is acquired, but before it is installed.

This will be executed with the downloaded and uncompressed directory as the working directory. No other environment is guaranteed, so be as explicit as possible. This is primarily intended for Cocoa sugars to compile themselves before installation.

This tag may also appear more than once, though that should be avoided. Order of execution is not guaranteed.

<script interpreter="/bin/sh">/usr/bin/xcodebuild</script>

<build-directory>

If it is not sufficient for your sugar to be copied verbatim into the Sugars directory as-is, such as if your sugar is compressed into a sub-directory or your sugar has to be compiled and then copied from a build folder, then you should define a relative path to your actual .sugar folder here.

<build-directory>build/Release/Sugar Manager.sugar</build-directory>