svn merge ^/branches/released .

1 files changed, 244 insertions, 244 deletions

diff --git a/fontconfig/doc/fcstring.fncs b/fontconfig/doc/fcstring.fncs
index 5f1f93ac1..f30549308 100644
--- a/fontconfig/doc/fcstring.fncs
+++ b/fontconfig/doc/fcstring.fncs
@@ -1,244 +1,244 @@
-/*
- * fontconfig/doc/fcstring.fncs
- *
- * Copyright © 2003 Keith Packard
- *
- * 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.
- */
-    <variablelist>
-
-@RET@		int
-@FUNC@		FcUtf8ToUcs4 
-@TYPE1@		FcChar8 *			@ARG1@		src
-@TYPE2@		FcChar32 *			@ARG2@		dst
-@TYPE3@		int% 				@ARG3@		len
-@PURPOSE@	convert UTF-8 to UCS4
-@DESC@
-Converts the next Unicode char from <parameter>src</parameter> into
-<parameter>dst</parameter> and returns the number of bytes containing the
-char.  <parameter>src</parameter> must be at least
-<parameter>len</parameter> bytes long.
-@@
-
-@RET@		int 
-@FUNC@		FcUcs4ToUtf8
-@TYPE1@		FcChar32% 			@ARG1@		src	 
-@TYPE2@		FcChar8% 			@ARG2@		dst[FC_UTF8_MAX_LEN]
-@PURPOSE@	convert UCS4 to UTF-8
-@DESC@
-Converts the Unicode char from <parameter>src</parameter> into
-<parameter>dst</parameter> and returns the number of bytes needed to encode
-the char.
-@@
-
-@RET@		FcBool 
-@FUNC@		FcUtf8Len
-@TYPE1@		FcChar8 *			@ARG1@		src
-@TYPE2@		int% 				@ARG2@		len
-@TYPE3@		int *				@ARG3@		nchar
-@TYPE4@		int *				@ARG4@		wchar
-@PURPOSE@	count UTF-8 encoded chars
-@DESC@
-Counts the number of Unicode chars in <parameter>len</parameter> bytes of
-<parameter>src</parameter>.  Places that count in
-<parameter>nchar</parameter>.  <parameter>wchar</parameter> contains 1, 2 or
-4 depending on the number of bytes needed to hold the largest unicode char
-counted.  The return value indicates whether <parameter>src</parameter> is a
-well-formed UTF8 string.
-@@
-
-@RET@		int 
-@FUNC@		FcUtf16ToUcs4
-@TYPE1@		FcChar8 *			@ARG1@		src
-@TYPE2@		FcEndian% 			@ARG2@		endian
-@TYPE3@		FcChar32 *			@ARG3@		dst
-@TYPE4@		int% 				@ARG4@		len
-@PURPOSE@	convert UTF-16 to UCS4
-@DESC@
-Converts the next Unicode char from <parameter>src</parameter> into
-<parameter>dst</parameter> and returns the number of bytes containing the
-char. <parameter>src</parameter> must be at least <parameter>len</parameter>
-bytes long.  Bytes of <parameter>src</parameter> are combined into 16-bit
-units according to <parameter>endian</parameter>.
-@@
-
-@RET@		FcBool
-@FUNC@		FcUtf16Len
-@TYPE1@		FcChar8 *			@ARG1@		src
-@TYPE2@		FcEndian% 			@ARG2@		endian
-@TYPE3@		int% 				@ARG3@		len
-@TYPE4@		int *				@ARG4@		nchar
-@TYPE5@		int *				@ARG5@		wchar
-@PURPOSE@	count UTF-16 encoded chars
-@DESC@
-Counts the number of Unicode chars in <parameter>len</parameter> bytes of
-<parameter>src</parameter>.  Bytes of <parameter>src</parameter> are
-combined into 16-bit units according to <parameter>endian</parameter>.
-Places that count in <parameter>nchar</parameter>.
-<parameter>wchar</parameter> contains 1, 2 or 4 depending on the number of
-bytes needed to hold the largest unicode char counted.  The return value
-indicates whether <parameter>string</parameter> is a well-formed UTF16
-string.
-@@
-
-@RET@		FcBool
-@FUNC@		FcIsLower
-@TYPE1@		FcChar8				@ARG1@		c
-@PURPOSE@	check for lower case ASCII character
-@DESC@
-This macro checks whether <parameter>c</parameter> is an lower case ASCII
-letter.
-@@
-
-@RET@		FcBool
-@FUNC@		FcIsUpper
-@TYPE1@		FcChar8				@ARG1@		c
-@PURPOSE@	check for upper case ASCII character
-@DESC@
-This macro checks whether <parameter>c</parameter> is a upper case ASCII
-letter.
-@@
-
-@RET@		FcChar8
-@FUNC@		FcToLower
-@TYPE1@		FcChar8				@ARG1@		c
-@PURPOSE@	convert upper case ASCII to lower case
-@DESC@
-This macro converts upper case ASCII <parameter>c</parameter> to the
-equivalent lower case letter.
-@@
-
-@RET@		FcChar8 *
-@FUNC@		FcStrCopy
-@TYPE1@		const FcChar8 *			@ARG1@		s
-@PURPOSE@	duplicate a string
-@DESC@
-Allocates memory, copies <parameter>s</parameter> and returns the resulting
-buffer.  Yes, this is <function>strdup</function>, but that function isn't
-available on every platform.
-@@
-
-@RET@		FcChar8 *
-@FUNC@		FcStrDowncase
-@TYPE1@		const FcChar8 *			@ARG1@		s
-@PURPOSE@	create a lower case translation of a string
-@DESC@
-Allocates memory, copies <parameter>s</parameter>, converting upper case
-letters to lower case and returns the allocated buffer.
-@@
-
-@RET@		FcChar8 *
-@FUNC@		FcStrCopyFilename
-@TYPE1@		const FcChar8 *			@ARG1@		s
-@PURPOSE@	create a complete path from a filename
-@DESC@
-<function>FcStrCopyFilename</function> constructs an absolute pathname from
-<parameter>s</parameter>. It converts any leading '~' characters in
-to the value of the HOME environment variable, and any relative paths are
-converted to absolute paths using the current working directory. Sequences
-of '/' characters are converted to a single '/', and names containing the
-current directory '.' or parent directory '..' are correctly reconstructed.
-Returns NULL if '~' is the leading character and HOME is unset or disabled
-(see <function>FcConfigEnableHome</function>).
-@@
-
-@RET@		int
-@FUNC@		FcStrCmp
-@TYPE1@		const FcChar8 *			@ARG1@		s1
-@TYPE2@		const FcChar8 *			@ARG2@		s2
-@PURPOSE@	compare UTF-8 strings
-@DESC@
-Returns the usual &lt;0, 0, &gt;0 result of comparing
-<parameter>s1</parameter> and <parameter>s2</parameter>. 
-@@
-
-@RET@		int
-@FUNC@		FcStrCmpIgnoreCase
-@TYPE1@		const FcChar8 *			@ARG1@		s1
-@TYPE2@		const FcChar8 *			@ARG2@		s2
-@PURPOSE@	compare UTF-8 strings ignoring case
-@DESC@
-Returns the usual &lt;0, 0, &gt;0 result of comparing
-<parameter>s1</parameter> and <parameter>s2</parameter>. This test is
-case-insensitive for all proper UTF-8 encoded strings.
-@@
-
-@RET@		FcChar8 *
-@FUNC@		FcStrStr
-@TYPE1@		const FcChar8 *			@ARG1@		s1
-@TYPE2@		const FcChar8 *			@ARG2@		s2
-@PURPOSE@	locate UTF-8 substring
-@DESC@
-Returns the location of <parameter>s2</parameter> in
-<parameter>s1</parameter>.  Returns NULL if <parameter>s2</parameter>
-is not present in <parameter>s1</parameter>. This test will operate properly
-with UTF8 encoded strings.
-@@
-
-@RET@		FcChar8 *
-@FUNC@		FcStrStrIgnoreCase
-@TYPE1@		const FcChar8 *			@ARG1@		s1
-@TYPE2@		const FcChar8 *			@ARG2@		s2
-@PURPOSE@	locate UTF-8 substring ignoring ASCII case
-@DESC@
-Returns the location of <parameter>s2</parameter> in 
-<parameter>s1</parameter>, ignoring case.  Returns NULL if
-<parameter>s2</parameter> is not present in <parameter>s1</parameter>.
-This test is case-insensitive for all proper UTF-8 encoded strings.
-@@
-
-@RET@		FcChar8 *
-@FUNC@		FcStrPlus
-@TYPE1@		const FcChar8 *			@ARG1@		s1
-@TYPE2@		const FcChar8 *			@ARG2@		s2
-@PURPOSE@	concatenate two strings
-@DESC@
-This function allocates new storage and places the concatenation of
-<parameter>s1</parameter> and <parameter>s2</parameter> there, returning the
-new string.
-@@
-
-@RET@		void
-@FUNC@		FcStrFree
-@TYPE1@		FcChar8 *			@ARG1@		s
-@PURPOSE@	free a string
-@DESC@
-This is just a wrapper around free(3) which helps track memory usage of
-strings within the fontconfig library.
-@@
-
-@RET@		FcChar8 *
-@FUNC@		FcStrDirname
-@TYPE1@		const FcChar8 *			@ARG1@		file
-@PURPOSE@	directory part of filename
-@DESC@
-Returns the directory containing <parameter>file</parameter>.  This
-is returned in newly allocated storage which should be freed when no longer
-needed.
-@@
-
-@RET@		FcChar8 *
-@FUNC@		FcStrBasename
-@TYPE1@		const FcChar8 *			@ARG1@		file
-@PURPOSE@	last component of filename
-@DESC@
-Returns the filename of <parameter>file</parameter> stripped of any leading
-directory names.  This is returned in newly allocated storage which should
-be freed when no longer needed.
-@@
+/*

+ * fontconfig/doc/fcstring.fncs

+ *

+ * Copyright © 2003 Keith Packard

+ *

+ * 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.

+ */

+    <variablelist>

+

+@RET@		int

+@FUNC@		FcUtf8ToUcs4 

+@TYPE1@		FcChar8 *			@ARG1@		src

+@TYPE2@		FcChar32 *			@ARG2@		dst

+@TYPE3@		int% 				@ARG3@		len

+@PURPOSE@	convert UTF-8 to UCS4

+@DESC@

+Converts the next Unicode char from <parameter>src</parameter> into

+<parameter>dst</parameter> and returns the number of bytes containing the

+char.  <parameter>src</parameter> must be at least

+<parameter>len</parameter> bytes long.

+@@

+

+@RET@		int 

+@FUNC@		FcUcs4ToUtf8

+@TYPE1@		FcChar32% 			@ARG1@		src	 

+@TYPE2@		FcChar8% 			@ARG2@		dst[FC_UTF8_MAX_LEN]

+@PURPOSE@	convert UCS4 to UTF-8

+@DESC@

+Converts the Unicode char from <parameter>src</parameter> into

+<parameter>dst</parameter> and returns the number of bytes needed to encode

+the char.

+@@

+

+@RET@		FcBool 

+@FUNC@		FcUtf8Len

+@TYPE1@		FcChar8 *			@ARG1@		src

+@TYPE2@		int% 				@ARG2@		len

+@TYPE3@		int *				@ARG3@		nchar

+@TYPE4@		int *				@ARG4@		wchar

+@PURPOSE@	count UTF-8 encoded chars

+@DESC@

+Counts the number of Unicode chars in <parameter>len</parameter> bytes of

+<parameter>src</parameter>.  Places that count in

+<parameter>nchar</parameter>.  <parameter>wchar</parameter> contains 1, 2 or

+4 depending on the number of bytes needed to hold the largest Unicode char

+counted.  The return value indicates whether <parameter>src</parameter> is a

+well-formed UTF8 string.

+@@

+

+@RET@		int 

+@FUNC@		FcUtf16ToUcs4

+@TYPE1@		FcChar8 *			@ARG1@		src

+@TYPE2@		FcEndian% 			@ARG2@		endian

+@TYPE3@		FcChar32 *			@ARG3@		dst

+@TYPE4@		int% 				@ARG4@		len

+@PURPOSE@	convert UTF-16 to UCS4

+@DESC@

+Converts the next Unicode char from <parameter>src</parameter> into

+<parameter>dst</parameter> and returns the number of bytes containing the

+char. <parameter>src</parameter> must be at least <parameter>len</parameter>

+bytes long.  Bytes of <parameter>src</parameter> are combined into 16-bit

+units according to <parameter>endian</parameter>.

+@@

+

+@RET@		FcBool

+@FUNC@		FcUtf16Len

+@TYPE1@		FcChar8 *			@ARG1@		src

+@TYPE2@		FcEndian% 			@ARG2@		endian

+@TYPE3@		int% 				@ARG3@		len

+@TYPE4@		int *				@ARG4@		nchar

+@TYPE5@		int *				@ARG5@		wchar

+@PURPOSE@	count UTF-16 encoded chars

+@DESC@

+Counts the number of Unicode chars in <parameter>len</parameter> bytes of

+<parameter>src</parameter>.  Bytes of <parameter>src</parameter> are

+combined into 16-bit units according to <parameter>endian</parameter>.

+Places that count in <parameter>nchar</parameter>.

+<parameter>wchar</parameter> contains 1, 2 or 4 depending on the number of

+bytes needed to hold the largest Unicode char counted.  The return value

+indicates whether <parameter>string</parameter> is a well-formed UTF16

+string.

+@@

+

+@RET@		FcBool

+@FUNC@		FcIsLower

+@TYPE1@		FcChar8				@ARG1@		c

+@PURPOSE@	check for lower case ASCII character

+@DESC@

+This macro checks whether <parameter>c</parameter> is an lower case ASCII

+letter.

+@@

+

+@RET@		FcBool

+@FUNC@		FcIsUpper

+@TYPE1@		FcChar8				@ARG1@		c

+@PURPOSE@	check for upper case ASCII character

+@DESC@

+This macro checks whether <parameter>c</parameter> is a upper case ASCII

+letter.

+@@

+

+@RET@		FcChar8

+@FUNC@		FcToLower

+@TYPE1@		FcChar8				@ARG1@		c

+@PURPOSE@	convert upper case ASCII to lower case

+@DESC@

+This macro converts upper case ASCII <parameter>c</parameter> to the

+equivalent lower case letter.

+@@

+

+@RET@		FcChar8 *

+@FUNC@		FcStrCopy

+@TYPE1@		const FcChar8 *			@ARG1@		s

+@PURPOSE@	duplicate a string

+@DESC@

+Allocates memory, copies <parameter>s</parameter> and returns the resulting

+buffer.  Yes, this is <function>strdup</function>, but that function isn't

+available on every platform.

+@@

+

+@RET@		FcChar8 *

+@FUNC@		FcStrDowncase

+@TYPE1@		const FcChar8 *			@ARG1@		s

+@PURPOSE@	create a lower case translation of a string

+@DESC@

+Allocates memory, copies <parameter>s</parameter>, converting upper case

+letters to lower case and returns the allocated buffer.

+@@

+

+@RET@		FcChar8 *

+@FUNC@		FcStrCopyFilename

+@TYPE1@		const FcChar8 *			@ARG1@		s

+@PURPOSE@	create a complete path from a filename

+@DESC@

+<function>FcStrCopyFilename</function> constructs an absolute pathname from

+<parameter>s</parameter>. It converts any leading '~' characters in

+to the value of the HOME environment variable, and any relative paths are

+converted to absolute paths using the current working directory. Sequences

+of '/' characters are converted to a single '/', and names containing the

+current directory '.' or parent directory '..' are correctly reconstructed.

+Returns NULL if '~' is the leading character and HOME is unset or disabled

+(see <function>FcConfigEnableHome</function>).

+@@

+

+@RET@		int

+@FUNC@		FcStrCmp

+@TYPE1@		const FcChar8 *			@ARG1@		s1

+@TYPE2@		const FcChar8 *			@ARG2@		s2

+@PURPOSE@	compare UTF-8 strings

+@DESC@

+Returns the usual &lt;0, 0, &gt;0 result of comparing

+<parameter>s1</parameter> and <parameter>s2</parameter>. 

+@@

+

+@RET@		int

+@FUNC@		FcStrCmpIgnoreCase

+@TYPE1@		const FcChar8 *			@ARG1@		s1

+@TYPE2@		const FcChar8 *			@ARG2@		s2

+@PURPOSE@	compare UTF-8 strings ignoring case

+@DESC@

+Returns the usual &lt;0, 0, &gt;0 result of comparing

+<parameter>s1</parameter> and <parameter>s2</parameter>. This test is

+case-insensitive for all proper UTF-8 encoded strings.

+@@

+

+@RET@		FcChar8 *

+@FUNC@		FcStrStr

+@TYPE1@		const FcChar8 *			@ARG1@		s1

+@TYPE2@		const FcChar8 *			@ARG2@		s2

+@PURPOSE@	locate UTF-8 substring

+@DESC@

+Returns the location of <parameter>s2</parameter> in

+<parameter>s1</parameter>.  Returns NULL if <parameter>s2</parameter>

+is not present in <parameter>s1</parameter>. This test will operate properly

+with UTF8 encoded strings.

+@@

+

+@RET@		FcChar8 *

+@FUNC@		FcStrStrIgnoreCase

+@TYPE1@		const FcChar8 *			@ARG1@		s1

+@TYPE2@		const FcChar8 *			@ARG2@		s2

+@PURPOSE@	locate UTF-8 substring ignoring ASCII case

+@DESC@

+Returns the location of <parameter>s2</parameter> in 

+<parameter>s1</parameter>, ignoring case.  Returns NULL if

+<parameter>s2</parameter> is not present in <parameter>s1</parameter>.

+This test is case-insensitive for all proper UTF-8 encoded strings.

+@@

+

+@RET@		FcChar8 *

+@FUNC@		FcStrPlus

+@TYPE1@		const FcChar8 *			@ARG1@		s1

+@TYPE2@		const FcChar8 *			@ARG2@		s2

+@PURPOSE@	concatenate two strings

+@DESC@

+This function allocates new storage and places the concatenation of

+<parameter>s1</parameter> and <parameter>s2</parameter> there, returning the

+new string.

+@@

+

+@RET@		void

+@FUNC@		FcStrFree

+@TYPE1@		FcChar8 *			@ARG1@		s

+@PURPOSE@	free a string

+@DESC@

+This is just a wrapper around free(3) which helps track memory usage of

+strings within the fontconfig library.

+@@

+

+@RET@		FcChar8 *

+@FUNC@		FcStrDirname

+@TYPE1@		const FcChar8 *			@ARG1@		file

+@PURPOSE@	directory part of filename

+@DESC@

+Returns the directory containing <parameter>file</parameter>.  This

+is returned in newly allocated storage which should be freed when no longer

+needed.

+@@

+

+@RET@		FcChar8 *

+@FUNC@		FcStrBasename

+@TYPE1@		const FcChar8 *			@ARG1@		file

+@PURPOSE@	last component of filename

+@DESC@

+Returns the filename of <parameter>file</parameter> stripped of any leading

+directory names.  This is returned in newly allocated storage which should

+be freed when no longer needed.

+@@