svn merge ^/branches/released .

1 files changed, 301 insertions, 301 deletions

diff --git a/fontconfig/doc/fcformat.fncs b/fontconfig/doc/fcformat.fncs
index b092449cf..fb110f2b2 100644
--- a/fontconfig/doc/fcformat.fncs
+++ b/fontconfig/doc/fcformat.fncs
@@ -1,301 +1,301 @@
-/*
- * fontconfig/doc/fcformat.fncs
- *
- * Copyright © 2008 Behdad Esfahbod
- *
- * Permission to use, copy, modify, distribute, and sell this software and its
- * documentation for any purpose is hereby granted without fee, provided that
- * the above copyright notice appear in all copies and that both that
- * copyright notice and this permission notice appear in supporting
- * documentation, and that the name of Keith Packard not be used in
- * advertising or publicity pertaining to distribution of the software without
- * specific, written prior permission.  Keith Packard makes no
- * representations about the suitability of this software for any purpose.  It
- * is provided "as is" without express or implied warranty.
- *
- * THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
- * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
- * EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
- * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
- * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
- * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- * PERFORMANCE OF THIS SOFTWARE.
- */
-
-@RET@		FcChar8 *
-@FUNC@		FcPatternFormat
-@TYPE1@		FcPattern *			@ARG1@		pat
-@TYPE2@		const FcChar8 *			@ARG2@		format
-@PURPOSE@	Format a pattern into a string according to a format specifier
-@DESC@
-
-Converts given pattern <parameter>pat</parameter> into text described by
-the format specifier <parameter>format</parameter>.
-The return value refers to newly allocated memory which should be freed by the
-caller using free(), or NULL if <parameter>format</parameter> is invalid.
-
-</para><para>
-
-The format is loosely modelled after printf-style format string.
-The format string is composed of zero or more  directives: ordinary
-characters (not "%"), which are copied unchanged to the output stream;
-and tags which are interpreted to construct text from the pattern in a
-variety of ways (explained below).
-Special characters can be escaped
-using backslash.  C-string style special characters like \n and \r are
-also supported (this is useful when the format string is not a C string
-literal).
-It is advisable to always escape curly braces that
-are meant to be copied to the output as ordinary characters.
-
-</para><para>
-
-Each tags is introduced by the character "%",
-followed by an optional minimum field width,
-followed by tag contents in curly braces ({}).
-If the minimum field width value is provided the tag
-will be expanded and the result padded to achieve the minimum width.
-If the minimum field width is positive, the padding will right-align
-the text.  Negative field width will left-align.
-The rest of this section describes various supported tag contents
-and their expansion.
-
-</para><para>
-
-A <firstterm>simple</firstterm> tag
-is one where the content is an identifier.  When simple
-tags are expanded, the named identifier will be looked up in
-<parameter>pattern</parameter> and the resulting list of values returned,
-joined together using comma.  For example, to print the family name and style the
-pattern, use the format "%{family} %{style}\n".  To extend the family column
-to forty characters use "%-40{family}%{style}\n".
-
-</para><para>
-
-Simple tags expand to list of all values for an element.  To only choose
-one of the values, one can index using the syntax "%{elt[idx]}".  For example,
-to get the first family name only, use "%{family[0]}".
-
-</para><para>
-
-If a simple tag ends with "=" and the element is found in the pattern, the
-name of the element followed by "=" will be output before the list of values.
-For example, "%{weight=}" may expand to the string "weight=80".  Or to the empty
-string if <parameter>pattern</parameter> does not have weight set.
-
-</para><para>
-
-If a simple tag starts with ":" and the element is found in the pattern, ":"
-will be printed first.  For example, combining this with the =, the format
-"%{:weight=}" may expand to ":weight=80" or to the empty string
-if <parameter>pattern</parameter> does not have weight set.
-
-</para><para>
-
-If a simple tag contains the string ":-", the rest of the the tag contents
-will be used as a default string.  The default string is output if the element
-is not found in the pattern.  For example, the format
-"%{:weight=:-123}" may expand to ":weight=80" or to the string
-":weight=123" if <parameter>pattern</parameter> does not have weight set.
-
-</para><para>
-
-A <firstterm>count</firstterm> tag
-is one that starts with the character "#" followed by an element
-name, and expands to the number of values for the element in the pattern.
-For example, "%{#family}" expands to the number of family names
-<parameter>pattern</parameter> has set, which may be zero.
-
-</para><para>
-
-A <firstterm>sub-expression</firstterm> tag
-is one that expands a sub-expression.  The tag contents
-are the sub-expression to expand placed inside another set of curly braces.
-Sub-expression tags are useful for aligning an entire sub-expression, or to
-apply converters (explained later) on an entire sub-expression.
-For example, the format "%40{{%{family} %{style}}}" expands the sub-expression
-to construct the family name followed by the style, then takes the entire
-string and pads it on the left to be at least forty characters.
-
-</para><para>
-
-A <firstterm>filter-out</firstterm> tag
-is one starting with the character "-" followed by a
-comma-separated list of element names, followed by a sub-expression enclosed
-in curly braces.  The sub-expression will be expanded but with a pattern that
-has the listed elements removed from it.
-For example, the format "%{-size,pixelsize{sub-expr}}" will expand "sub-expr"
-with <parameter>pattern</parameter> sans the size and pixelsize elements.
-
-</para><para>
-
-A <firstterm>filter-in</firstterm> tag
-is one starting with the character "+" followed by a
-comma-separated list of element names, followed by a sub-expression enclosed
-in curly braces.  The sub-expression will be expanded but with a pattern that
-only has the listed elements from the surrounding pattern.
-For example, the format "%{+family,familylang{sub-expr}}" will expand "sub-expr"
-with a sub-pattern consisting only the family and family lang elements of
-<parameter>pattern</parameter>.
-
-</para><para>
-
-A <firstterm>conditional</firstterm> tag
-is one starting with the character "?" followed by a
-comma-separated list of element conditions, followed by two sub-expression
-enclosed in curly braces.  An element condition can be an element name,
-in which case it tests whether the element is defined in pattern, or
-the character "!" followed by an element name, in which case the test
-is negated.  The conditional passes if all the element conditions pass.
-The tag expands the first sub-expression if the conditional passes, and
-expands the second sub-expression otherwise.
-For example, the format "%{?size,dpi,!pixelsize{pass}{fail}}" will expand
-to "pass" if <parameter>pattern</parameter> has size and dpi elements but
-no pixelsize element, and to "fail" otherwise.
-
-</para><para>
-
-An <firstterm>enumerate</firstterm> tag
-is one starting with the string "[]" followed by a
-comma-separated list of element names, followed by a sub-expression enclosed
-in curly braces.  The list of values for the named elements are walked in
-parallel and the sub-expression expanded each time with a pattern just having
-a single value for those elements, starting from the first value and
-continuing as long as any of those elements has a value.
-For example, the format "%{[]family,familylang{%{family} (%{familylang})\n}}"
-will expand the pattern "%{family} (%{familylang})\n" with a pattern
-having only the first value of the family and familylang elemtns, then expands
-it with the second values, then the third, etc.
-
-</para><para>
-
-As a special case, if an enumerate tag has only one element, and that element
-has only one value in the pattern, and that value is of type FcLangSet, the
-individual languages in the language set are enumerated.
-
-</para><para>
-
-A <firstterm>builtin</firstterm> tag
-is one starting with the character "=" followed by a builtin
-name.  The following builtins are defined:
-
-<variablelist>
-
-<varlistentry><term>
-unparse
-</term><listitem><para>
-Expands to the result of calling FcNameUnparse() on the pattern.
-</para></listitem></varlistentry>
-
-<varlistentry><term>
-fcmatch
-</term><listitem><para>
-Expands to the output of the default output format of the fc-match
-command on the pattern, without the final newline.
-</para></listitem></varlistentry>
-
-<varlistentry><term>
-fclist
-</term><listitem><para>
-Expands to the output of the default output format of the fc-list
-command on the pattern, without the final newline.
-</para></listitem></varlistentry>
-
-<varlistentry><term>
-pkgkit
-</term><listitem><para>
-Expands to the list of PackageKit font() tags for the pattern.
-Currently this includes tags for each family name, and each language
-from the pattern, enumerated and sanitized into a set of tags terminated
-by newline.  Package management systems can use these tags to tag their
-packages accordingly.
-</para></listitem></varlistentry>
-
-</variablelist>
-
-For example, the format "%{+family,style{%{=unparse}}}\n" will expand
-to an unparsed name containing only the family and style element values
-from <parameter>pattern</parameter>.
-
-</para><para>
-
-The contents of any tag can be followed by a set of zero or more
-<firstterm>converter</firstterm>s.  A converter is specified by the
-character "|" followed by the converter name and arguments.  The
-following converters are defined:
-
-<variablelist>
-
-<varlistentry><term>
-basename
-</term><listitem><para>
-Replaces text with the results of calling FcStrBasename() on it.
-</para></listitem></varlistentry>
-
-<varlistentry><term>
-dirname
-</term><listitem><para>
-Replaces text with the results of calling FcStrDirname() on it.
-</para></listitem></varlistentry>
-
-<varlistentry><term>
-downcase
-</term><listitem><para>
-Replaces text with the results of calling FcStrDowncase() on it.
-</para></listitem></varlistentry>
-
-<varlistentry><term>
-shescape
-</term><listitem><para>
-Escapes text for one level of shell expansion.
-(Escapes single-quotes, also encloses text in single-quotes.)
-</para></listitem></varlistentry>
-
-<varlistentry><term>
-cescape
-</term><listitem><para>
-Escapes text such that it can be used as part of a C string literal.
-(Escapes backslash and double-quotes.)
-</para></listitem></varlistentry>
-
-<varlistentry><term>
-xmlescape
-</term><listitem><para>
-Escapes text such that it can be used in XML and HTML.
-(Escapes less-than, greater-than, and ampersand.)
-</para></listitem></varlistentry>
-
-<varlistentry><term>
-delete(<parameter>chars</parameter>)
-</term><listitem><para>
-Deletes all occurrences of each of the characters in <parameter>chars</parameter>
-from the text.
-FIXME: This converter is not UTF-8 aware yet.
-</para></listitem></varlistentry>
-
-<varlistentry><term>
-escape(<parameter>chars</parameter>)
-</term><listitem><para>
-Escapes all occurrences of each of the characters in <parameter>chars</parameter>
-by prepending it by the first character in <parameter>chars</parameter>.
-FIXME: This converter is not UTF-8 aware yet.
-</para></listitem></varlistentry>
-
-<varlistentry><term>
-translate(<parameter>from</parameter>,<parameter>to</parameter>)
-</term><listitem><para>
-Translates all occurrences of each of the characters in <parameter>from</parameter>
-by replacing them with their corresponding character in <parameter>to</parameter>.
-If <parameter>to</parameter> has fewer characters than
-<parameter>from</parameter>, it will be extended by repeating its last
-character.
-FIXME: This converter is not UTF-8 aware yet.
-</para></listitem></varlistentry>
-
-</variablelist>
-
-For example, the format "%{family|downcase|delete( )}\n" will expand
-to the values of the family element in <parameter>pattern</parameter>,
-lower-cased and with spaces removed.
-
-@@
+/*

+ * fontconfig/doc/fcformat.fncs

+ *

+ * Copyright © 2008 Behdad Esfahbod

+ *

+ * Permission to use, copy, modify, distribute, and sell this software and its

+ * documentation for any purpose is hereby granted without fee, provided that

+ * the above copyright notice appear in all copies and that both that

+ * copyright notice and this permission notice appear in supporting

+ * documentation, and that the name of the author(s) not be used in

+ * advertising or publicity pertaining to distribution of the software without

+ * specific, written prior permission.  The authors make no

+ * representations about the suitability of this software for any purpose.  It

+ * is provided "as is" without express or implied warranty.

+ *

+ * THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,

+ * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO

+ * EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR

+ * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,

+ * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER

+ * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR

+ * PERFORMANCE OF THIS SOFTWARE.

+ */

+

+@RET@		FcChar8 *

+@FUNC@		FcPatternFormat

+@TYPE1@		FcPattern *			@ARG1@		pat

+@TYPE2@		const FcChar8 *			@ARG2@		format

+@PURPOSE@	Format a pattern into a string according to a format specifier

+@DESC@

+

+Converts given pattern <parameter>pat</parameter> into text described by

+the format specifier <parameter>format</parameter>.

+The return value refers to newly allocated memory which should be freed by the

+caller using free(), or NULL if <parameter>format</parameter> is invalid.

+

+</para><para>

+

+The format is loosely modeled after printf-style format string.

+The format string is composed of zero or more  directives: ordinary

+characters (not "%"), which are copied unchanged to the output stream;

+and tags which are interpreted to construct text from the pattern in a

+variety of ways (explained below).

+Special characters can be escaped

+using backslash.  C-string style special characters like \n and \r are

+also supported (this is useful when the format string is not a C string

+literal).

+It is advisable to always escape curly braces that

+are meant to be copied to the output as ordinary characters.

+

+</para><para>

+

+Each tag is introduced by the character "%",

+followed by an optional minimum field width,

+followed by tag contents in curly braces ({}).

+If the minimum field width value is provided the tag

+will be expanded and the result padded to achieve the minimum width.

+If the minimum field width is positive, the padding will right-align

+the text.  Negative field width will left-align.

+The rest of this section describes various supported tag contents

+and their expansion.

+

+</para><para>

+

+A <firstterm>simple</firstterm> tag

+is one where the content is an identifier.  When simple

+tags are expanded, the named identifier will be looked up in

+<parameter>pattern</parameter> and the resulting list of values returned,

+joined together using comma.  For example, to print the family name and style of the

+pattern, use the format "%{family} %{style}\n".  To extend the family column

+to forty characters use "%-40{family}%{style}\n".

+

+</para><para>

+

+Simple tags expand to list of all values for an element.  To only choose

+one of the values, one can index using the syntax "%{elt[idx]}".  For example,

+to get the first family name only, use "%{family[0]}".

+

+</para><para>

+

+If a simple tag ends with "=" and the element is found in the pattern, the

+name of the element followed by "=" will be output before the list of values.

+For example, "%{weight=}" may expand to the string "weight=80".  Or to the empty

+string if <parameter>pattern</parameter> does not have weight set.

+

+</para><para>

+

+If a simple tag starts with ":" and the element is found in the pattern, ":"

+will be printed first.  For example, combining this with the =, the format

+"%{:weight=}" may expand to ":weight=80" or to the empty string

+if <parameter>pattern</parameter> does not have weight set.

+

+</para><para>

+

+If a simple tag contains the string ":-", the rest of the the tag contents

+will be used as a default string.  The default string is output if the element

+is not found in the pattern.  For example, the format

+"%{:weight=:-123}" may expand to ":weight=80" or to the string

+":weight=123" if <parameter>pattern</parameter> does not have weight set.

+

+</para><para>

+

+A <firstterm>count</firstterm> tag

+is one that starts with the character "#" followed by an element

+name, and expands to the number of values for the element in the pattern.

+For example, "%{#family}" expands to the number of family names

+<parameter>pattern</parameter> has set, which may be zero.

+

+</para><para>

+

+A <firstterm>sub-expression</firstterm> tag

+is one that expands a sub-expression.  The tag contents

+are the sub-expression to expand placed inside another set of curly braces.

+Sub-expression tags are useful for aligning an entire sub-expression, or to

+apply converters (explained later) to the entire sub-expression output.

+For example, the format "%40{{%{family} %{style}}}" expands the sub-expression

+to construct the family name followed by the style, then takes the entire

+string and pads it on the left to be at least forty characters.

+

+</para><para>

+

+A <firstterm>filter-out</firstterm> tag

+is one starting with the character "-" followed by a

+comma-separated list of element names, followed by a sub-expression enclosed

+in curly braces.  The sub-expression will be expanded but with a pattern that

+has the listed elements removed from it.

+For example, the format "%{-size,pixelsize{sub-expr}}" will expand "sub-expr"

+with <parameter>pattern</parameter> sans the size and pixelsize elements.

+

+</para><para>

+

+A <firstterm>filter-in</firstterm> tag

+is one starting with the character "+" followed by a

+comma-separated list of element names, followed by a sub-expression enclosed

+in curly braces.  The sub-expression will be expanded but with a pattern that

+only has the listed elements from the surrounding pattern.

+For example, the format "%{+family,familylang{sub-expr}}" will expand "sub-expr"

+with a sub-pattern consisting only the family and family lang elements of

+<parameter>pattern</parameter>.

+

+</para><para>

+

+A <firstterm>conditional</firstterm> tag

+is one starting with the character "?" followed by a

+comma-separated list of element conditions, followed by two sub-expression

+enclosed in curly braces.  An element condition can be an element name,

+in which case it tests whether the element is defined in pattern, or

+the character "!" followed by an element name, in which case the test

+is negated.  The conditional passes if all the element conditions pass.

+The tag expands the first sub-expression if the conditional passes, and

+expands the second sub-expression otherwise.

+For example, the format "%{?size,dpi,!pixelsize{pass}{fail}}" will expand

+to "pass" if <parameter>pattern</parameter> has size and dpi elements but

+no pixelsize element, and to "fail" otherwise.

+

+</para><para>

+

+An <firstterm>enumerate</firstterm> tag

+is one starting with the string "[]" followed by a

+comma-separated list of element names, followed by a sub-expression enclosed

+in curly braces.  The list of values for the named elements are walked in

+parallel and the sub-expression expanded each time with a pattern just having

+a single value for those elements, starting from the first value and

+continuing as long as any of those elements has a value.

+For example, the format "%{[]family,familylang{%{family} (%{familylang})\n}}"

+will expand the pattern "%{family} (%{familylang})\n" with a pattern

+having only the first value of the family and familylang elements, then expands

+it with the second values, then the third, etc.

+

+</para><para>

+

+As a special case, if an enumerate tag has only one element, and that element

+has only one value in the pattern, and that value is of type FcLangSet, the

+individual languages in the language set are enumerated.

+

+</para><para>

+

+A <firstterm>builtin</firstterm> tag

+is one starting with the character "=" followed by a builtin

+name.  The following builtins are defined:

+

+<variablelist>

+

+<varlistentry><term>

+unparse

+</term><listitem><para>

+Expands to the result of calling FcNameUnparse() on the pattern.

+</para></listitem></varlistentry>

+

+<varlistentry><term>

+fcmatch

+</term><listitem><para>

+Expands to the output of the default output format of the fc-match

+command on the pattern, without the final newline.

+</para></listitem></varlistentry>

+

+<varlistentry><term>

+fclist

+</term><listitem><para>

+Expands to the output of the default output format of the fc-list

+command on the pattern, without the final newline.

+</para></listitem></varlistentry>

+

+<varlistentry><term>

+pkgkit

+</term><listitem><para>

+Expands to the list of PackageKit font() tags for the pattern.

+Currently this includes tags for each family name, and each language

+from the pattern, enumerated and sanitized into a set of tags terminated

+by newline.  Package management systems can use these tags to tag their

+packages accordingly.

+</para></listitem></varlistentry>

+

+</variablelist>

+

+For example, the format "%{+family,style{%{=unparse}}}\n" will expand

+to an unparsed name containing only the family and style element values

+from <parameter>pattern</parameter>.

+

+</para><para>

+

+The contents of any tag can be followed by a set of zero or more

+<firstterm>converter</firstterm>s.  A converter is specified by the

+character "|" followed by the converter name and arguments.  The

+following converters are defined:

+

+<variablelist>

+

+<varlistentry><term>

+basename

+</term><listitem><para>

+Replaces text with the results of calling FcStrBasename() on it.

+</para></listitem></varlistentry>

+

+<varlistentry><term>

+dirname

+</term><listitem><para>

+Replaces text with the results of calling FcStrDirname() on it.

+</para></listitem></varlistentry>

+

+<varlistentry><term>

+downcase

+</term><listitem><para>

+Replaces text with the results of calling FcStrDowncase() on it.

+</para></listitem></varlistentry>

+

+<varlistentry><term>

+shescape

+</term><listitem><para>

+Escapes text for one level of shell expansion.

+(Escapes single-quotes, also encloses text in single-quotes.)

+</para></listitem></varlistentry>

+

+<varlistentry><term>

+cescape

+</term><listitem><para>

+Escapes text such that it can be used as part of a C string literal.

+(Escapes backslash and double-quotes.)

+</para></listitem></varlistentry>

+

+<varlistentry><term>

+xmlescape

+</term><listitem><para>

+Escapes text such that it can be used in XML and HTML.

+(Escapes less-than, greater-than, and ampersand.)

+</para></listitem></varlistentry>

+

+<varlistentry><term>

+delete(<parameter>chars</parameter>)

+</term><listitem><para>

+Deletes all occurrences of each of the characters in <parameter>chars</parameter>

+from the text.

+FIXME: This converter is not UTF-8 aware yet.

+</para></listitem></varlistentry>

+

+<varlistentry><term>

+escape(<parameter>chars</parameter>)

+</term><listitem><para>

+Escapes all occurrences of each of the characters in <parameter>chars</parameter>

+by prepending it by the first character in <parameter>chars</parameter>.

+FIXME: This converter is not UTF-8 aware yet.

+</para></listitem></varlistentry>

+

+<varlistentry><term>

+translate(<parameter>from</parameter>,<parameter>to</parameter>)

+</term><listitem><para>

+Translates all occurrences of each of the characters in <parameter>from</parameter>

+by replacing them with their corresponding character in <parameter>to</parameter>.

+If <parameter>to</parameter> has fewer characters than

+<parameter>from</parameter>, it will be extended by repeating its last

+character.

+FIXME: This converter is not UTF-8 aware yet.

+</para></listitem></varlistentry>

+

+</variablelist>

+

+For example, the format "%{family|downcase|delete( )}\n" will expand

+to the values of the family element in <parameter>pattern</parameter>,

+lower-cased and with spaces removed.

+

+@@