diff options
Diffstat (limited to 'fontconfig/doc')
28 files changed, 5065 insertions, 0 deletions
diff --git a/fontconfig/doc/Makefile.am b/fontconfig/doc/Makefile.am new file mode 100644 index 000000000..49e00e155 --- /dev/null +++ b/fontconfig/doc/Makefile.am @@ -0,0 +1,200 @@ +# +# fontconfig/doc/Makefile.am +# +# 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. + +CC = @CC_FOR_BUILD@ +EXEEXT = @EXEEXT_FOR_BUILD@ +LINK = $(CCLD) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -o $@ + +DOC_SRC = $(srcdir) +DOC_MODULE = fontconfig +DOC2HTML = docbook2html +DOC2TXT = docbook2txt +DOC2MAN = docbook2man +DOC2PDF = docbook2pdf + +TXT = fontconfig-user.txt fontconfig-devel.txt +PDF = fontconfig-user.pdf fontconfig-devel.pdf +HTML_FILES = fontconfig-user.html +HTML_DIR = fontconfig-devel +SGML = fontconfig-user.sgml fontconfig-devel.sgml +FNCS_TMPL = ${DOC_SRC}/func.sgml + +DOC_FUNCS_FNCS=\ + fcatomic.fncs \ + fcblanks.fncs \ + fccache.fncs \ + fccharset.fncs \ + fcconfig.fncs \ + fcconstant.fncs \ + fcdircache.fncs \ + fcfile.fncs \ + fcfontset.fncs \ + fcformat.fncs \ + fcfreetype.fncs \ + fcinit.fncs \ + fclangset.fncs \ + fcmatrix.fncs \ + fcobjectset.fncs \ + fcobjecttype.fncs \ + fcpattern.fncs \ + fcstring.fncs \ + fcstrset.fncs \ + fcvalue.fncs + +DOC_FUNCS_SGML=\ + fcatomic.sgml \ + fcblanks.sgml \ + fccache.sgml \ + fccharset.sgml \ + fcconfig.sgml \ + fcconstant.sgml \ + fcdircache.sgml \ + fcfile.sgml \ + fcfontset.sgml \ + fcformat.sgml \ + fcfreetype.sgml \ + fcinit.sgml \ + fclangset.sgml \ + fcmatrix.sgml \ + fcobjectset.sgml \ + fcobjecttype.sgml \ + fcpattern.sgml \ + fcstring.sgml \ + fcstrset.sgml \ + fcvalue.sgml + +man5_MANS=fonts-conf.5 +man3_MANS=$(DOCMAN3) + +noinst_PROGRAMS=edit-sgml +edit_sgml_SOURCES=edit-sgml.c + +DOC_FILES=$(TXT) $(PDF) $(HTML_FILES) +LOCAL_DOCS=$(man3_MANS) $(man5_MANS) $(DOC_FILES) $(HTML_DIR)/* + +check_SCRIPTS=check-missing-doc +TESTS_ENVIRONMENT=top_srcdir=${top_srcdir} sh +TESTS=check-missing-doc + +EXTRA_DIST=$(LOCAL_DOCS) $(SGML) $(DOC_FUNCS_FNCS) $(check_SCRIPTS) func.sgml confdir.sgml.in + +SUFFIXES=.fncs .sgml .txt .html + +if USEDOCBOOK + +.fncs.sgml: + $(RM) $@ + ./edit-sgml$(EXEEXT) $(FNCS_TMPL) < '$<' > $*.sgml + +.sgml.txt: + $(RM) $@ + $(DOC2TXT) $< + +.sgml.pdf: + $(RM) $@ + $(DOC2PDF) $< + +$(man3_MANS): func.refs + +func.refs: local-fontconfig-devel.sgml $(DOC_FUNCS_SGML) version.sgml confdir.sgml + $(RM) func.refs + $(DOC2MAN) -o devel-man local-fontconfig-devel.sgml && \ + mv devel-man/manpage.refs func.refs && \ + mv devel-man/*.3 . && \ + $(RM) devel-man/manpage.* && \ + rmdir devel-man + +local-fontconfig-devel.sgml: fontconfig-devel.sgml + $(LN_S) $< $@ + +$(DOC_FUNCS_SGML): edit-sgml$(EXEEXT) $(FNCS_TMPL) + +fonts-conf.5: local-fontconfig-user.sgml version.sgml confdir.sgml + $(RM) $@ + $(DOC2MAN) local-fontconfig-user.sgml && \ + $(RM) manpage.* + +local-fontconfig-user.sgml: fontconfig-user.sgml + $(LN_S) $< $@ + +all-local: $(LOCAL_DOCS) + +clean-local: + $(RM) $(man3_MANS) $(man5_MANS) $(DOC_FILES) $(DOC_FUNCS_SGML) func.refs + $(RM) -r $(HTML_DIR) + +$(HTML_DIR): local-fontconfig-devel.sgml $(DOC_FUNCS_SGML) version.sgml confdir.sgml + $(RM) -r $(HTML_DIR) + $(DOC2HTML) -V '%use-id-as-filename%' -o $(HTML_DIR) local-fontconfig-devel.sgml + +fontconfig-devel.txt: local-fontconfig-devel.sgml $(DOC_FUNCS_SGML) version.sgml confdir.sgml + $(RM) $@ + $(DOC2TXT) local-fontconfig-devel.sgml + mv local-fontconfig-devel.txt $@ + +fontconfig-devel.pdf: local-fontconfig-devel.sgml $(DOC_FUNCS_SGML) version.sgml confdir.sgml + $(RM) $@ + $(top_srcdir)/missing --run $(DOC2PDF) $< && mv local-$@ $@ \ + || echo Failed to generate $@ >&2; \ + (test -f $@ || echo $(DOC2PDF) is required to generate this file >> $@) + +fontconfig-user.html: local-fontconfig-user.sgml version.sgml confdir.sgml + $(RM) $@ local-$@ $@.tmp + $(DOC2HTML) -u local-fontconfig-user.sgml > $@.tmp + -test -f local-$@ && mv local-$@ $@ + -test -f $@ || mv $@.tmp $@ + -test -f $@.tmp && $(RM) $@.tmp + +fontconfig-user.txt: local-fontconfig-user.sgml version.sgml confdir.sgml + $(RM) $@ + $(DOC2TXT) local-fontconfig-user.sgml + mv local-fontconfig-user.txt $@ + +fontconfig-user.pdf: local-fontconfig-user.sgml version.sgml confdir.sgml + $(RM) $@ + $(top_srcdir)/missing --run $(DOC2PDF) $< && mv local-$@ $@ \ + || echo Failed to generate $@ >&2; \ + (test -f $@ || echo $(DOC2PDF) is required to generate this file >> $@) + +STRIPNL=awk '{ if (NR > 1) printf ("\n"); printf ("%s", $$0); }' +confdir.sgml: ${DOC_SRC}/confdir.sgml.in + sed "s,@CONFDIR\@,${CONFDIR}," < ${DOC_SRC}/confdir.sgml.in | $(STRIPNL) > confdir.sgml + +CLEANFILES=confdir.sgml local-fontconfig-user.sgml local-fontconfig-devel.sgml + +htmldoc_DATA = $(HTML_DIR)/* + +$(HTML_DIR)/*: $(HTML_DIR) + +else + +htmldoc_DATA = $(srcdir)/$(HTML_DIR)/* + +all-local: +clean-local: +endif + +htmldocdir=$(docdir)/$(HTML_DIR) + +doc_DATA = $(DOC_FILES) + diff --git a/fontconfig/doc/check-missing-doc b/fontconfig/doc/check-missing-doc new file mode 100644 index 000000000..195ec003b --- /dev/null +++ b/fontconfig/doc/check-missing-doc @@ -0,0 +1,24 @@ +#!/bin/sh +header=fontconfig-header +doc=fontconfig-doc +trap "rm $header $doc" 0 1 15 +top_srcdir=${top_srcdir-".."} +( +cat $top_srcdir/fontconfig/*.h | grep '^Fc' | + grep -v FcPublic | sed 's/[^a-zA-Z0-9].*//'; + cat $top_srcdir/fontconfig/*.h | + sed -n 's/#define \(Fc[a-zA-Z]*\)(.*$/\1/p') | + sort -u > $header + +grep '@FUNC[+]*@' $top_srcdir/doc/*.fncs | +awk '{print $2}' | +sort -u > $doc + +if cmp $doc $header > /dev/null; then + exit 0 +fi + +echo \ +'Library Export Documentation' +diff -y $header $doc | grep '[<>]' +exit 1 diff --git a/fontconfig/doc/confdir.sgml.in b/fontconfig/doc/confdir.sgml.in new file mode 100644 index 000000000..291b26bb3 --- /dev/null +++ b/fontconfig/doc/confdir.sgml.in @@ -0,0 +1,26 @@ +<!-- + fontconfig/doc/confdir.sgml.in + + 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. +--> +<!-- this is filled in at make time --> +<!--@CONFDIR@--> +/etc/fonts diff --git a/fontconfig/doc/edit-sgml.c b/fontconfig/doc/edit-sgml.c new file mode 100644 index 000000000..b69c93ed7 --- /dev/null +++ b/fontconfig/doc/edit-sgml.c @@ -0,0 +1,546 @@ +/* + * fontconfig/doc/edit-sgml.c + * + * 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. + */ + +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <ctype.h> + +static void * +New (int size); + +static void * +Reallocate (void *p, int size); + +static void +Dispose (void *p); + +typedef enum { False, True } Bool; + +typedef struct { + char *buf; + int size; + int len; +} String; + +static String * +StringNew (void); + +static void +StringAdd (String *s, char c); + +static void +StringAddString (String *s, char *buf); + +static String * +StringMake (char *buf); + +static void +StringDel (String *s); + +static void +StringPut (FILE *f, String *s); + +static void +StringDispose (String *s); + +typedef struct { + String *tag; + String *text; +} Replace; + +static Replace * +ReplaceNew (void); + +static void +ReplaceDispose (Replace *r); + +static void +Bail (const char *format, int line, const char *arg); + +static Replace * +ReplaceRead (FILE *f, int *linep); + +typedef struct _replaceList { + struct _replaceList *next; + Replace *r; +} ReplaceList; + +static ReplaceList * +ReplaceListNew (Replace *r, ReplaceList *next); + +static void +ReplaceListDispose (ReplaceList *l); + +typedef struct { + ReplaceList *head; +} ReplaceSet; + +static ReplaceSet * +ReplaceSetNew (void); + +static void +ReplaceSetDispose (ReplaceSet *s); + +static void +ReplaceSetAdd (ReplaceSet *s, Replace *r); + +static Replace * +ReplaceSetFind (ReplaceSet *s, char *tag); + +static ReplaceSet * +ReplaceSetRead (FILE *f, int *linep); + +typedef struct _skipStack { + struct _skipStack *prev; + int skipping; +} SkipStack; + +static SkipStack * +SkipStackPush (SkipStack *prev, int skipping); + +static SkipStack * +SkipStackPop (SkipStack *prev); + +typedef struct _loopStack { + struct _loopStack *prev; + String *tag; + String *extra; + long pos; +} LoopStack; + +static LoopStack * +LoopStackPush (LoopStack *prev, FILE *f, char *tag); + +static LoopStack * +LoopStackLoop (ReplaceSet *rs, LoopStack *ls, FILE *f); + +static void +LineSkip (FILE *f, int *linep); + +static void +DoReplace (FILE *f, int *linep, ReplaceSet *s); + +#define STRING_INIT 128 + +static void * +New (int size) +{ + void *m = malloc (size); + if (!m) + abort (); + return m; +} + +static void * +Reallocate (void *p, int size) +{ + void *r = realloc (p, size); + + if (!r) + abort (); + return r; +} + +static void +Dispose (void *p) +{ + free (p); +} + +static String * +StringNew (void) +{ + String *s; + + s = New (sizeof (String)); + s->buf = New (STRING_INIT); + s->size = STRING_INIT - 1; + s->buf[0] = '\0'; + s->len = 0; + return s; +} + +static void +StringAdd (String *s, char c) +{ + if (s->len == s->size) + s->buf = Reallocate (s->buf, (s->size *= 2) + 1); + s->buf[s->len++] = c; + s->buf[s->len] = '\0'; +} + +static void +StringAddString (String *s, char *buf) +{ + while (*buf) + StringAdd (s, *buf++); +} + +static String * +StringMake (char *buf) +{ + String *s = StringNew (); + StringAddString (s, buf); + return s; +} + +static void +StringDel (String *s) +{ + if (s->len) + s->buf[--s->len] = '\0'; +} + +static void +StringPut (FILE *f, String *s) +{ + char *b = s->buf; + + while (*b) + putc (*b++, f); +} + +#define StringLast(s) ((s)->len ? (s)->buf[(s)->len - 1] : '\0') + +static void +StringDispose (String *s) +{ + Dispose (s->buf); + Dispose (s); +} + +static Replace * +ReplaceNew (void) +{ + Replace *r = New (sizeof (Replace)); + r->tag = StringNew (); + r->text = StringNew (); + return r; +} + +static void +ReplaceDispose (Replace *r) +{ + StringDispose (r->tag); + StringDispose (r->text); + Dispose (r); +} + +static void +Bail (const char *format, int line, const char *arg) +{ + fprintf (stderr, "fatal: "); + fprintf (stderr, format, line, arg); + fprintf (stderr, "\n"); + exit (1); +} + +static int +Getc (FILE *f, int *linep) +{ + int c = getc (f); + if (c == '\n') + ++(*linep); + return c; +} + +static void +Ungetc (int c, FILE *f, int *linep) +{ + if (c == '\n') + --(*linep); + ungetc (c, f); +} + +static Replace * +ReplaceRead (FILE *f, int *linep) +{ + int c; + Replace *r; + + while ((c = Getc (f, linep)) != '@') + { + if (c == EOF) + return 0; + } + r = ReplaceNew(); + while ((c = Getc (f, linep)) != '@') + { + if (c == EOF) + { + ReplaceDispose (r); + return 0; + } + if (isspace (c)) + Bail ("%d: invalid character after tag %s", *linep, r->tag->buf); + StringAdd (r->tag, c); + } + if (r->tag->buf[0] == '\0') + { + ReplaceDispose (r); + return 0; + } + while (isspace ((c = Getc (f, linep)))) + ; + Ungetc (c, f, linep); + while ((c = Getc (f, linep)) != '@' && c != EOF) + StringAdd (r->text, c); + if (c == '@') + Ungetc (c, f, linep); + while (isspace (StringLast (r->text))) + StringDel (r->text); + if (StringLast(r->text) == '%') + { + StringDel (r->text); + StringAdd (r->text, ' '); + } + return r; +} + +static ReplaceList * +ReplaceListNew (Replace *r, ReplaceList *next) +{ + ReplaceList *l = New (sizeof (ReplaceList)); + l->r = r; + l->next = next; + return l; +} + +static void +ReplaceListDispose (ReplaceList *l) +{ + if (l) + { + ReplaceListDispose (l->next); + ReplaceDispose (l->r); + Dispose (l); + } +} + +static ReplaceSet * +ReplaceSetNew (void) +{ + ReplaceSet *s = New (sizeof (ReplaceSet)); + s->head = 0; + return s; +} + +static void +ReplaceSetDispose (ReplaceSet *s) +{ + ReplaceListDispose (s->head); + Dispose (s); +} + +static void +ReplaceSetAdd (ReplaceSet *s, Replace *r) +{ + s->head = ReplaceListNew (r, s->head); +} + +static Replace * +ReplaceSetFind (ReplaceSet *s, char *tag) +{ + ReplaceList *l; + + for (l = s->head; l; l = l->next) + if (!strcmp (tag, l->r->tag->buf)) + return l->r; + return 0; +} + +static ReplaceSet * +ReplaceSetRead (FILE *f, int *linep) +{ + ReplaceSet *s = ReplaceSetNew (); + Replace *r; + + while ((r = ReplaceRead (f, linep))) + { + while (ReplaceSetFind (s, r->tag->buf)) + StringAdd (r->tag, '+'); + ReplaceSetAdd (s, r); + } + if (!s->head) + { + ReplaceSetDispose (s); + s = 0; + } + return s; +} + +static SkipStack * +SkipStackPush (SkipStack *prev, int skipping) +{ + SkipStack *ss = New (sizeof (SkipStack)); + ss->prev = prev; + ss->skipping = skipping; + return ss; +} + +static SkipStack * +SkipStackPop (SkipStack *prev) +{ + SkipStack *ss = prev->prev; + Dispose (prev); + return ss; +} + +static LoopStack * +LoopStackPush (LoopStack *prev, FILE *f, char *tag) +{ + LoopStack *ls = New (sizeof (LoopStack)); + ls->prev = prev; + ls->tag = StringMake (tag); + ls->extra = StringNew (); + ls->pos = ftell (f); + return ls; +} + +static LoopStack * +LoopStackLoop (ReplaceSet *rs, LoopStack *ls, FILE *f) +{ + String *s = StringMake (ls->tag->buf); + LoopStack *ret = ls; + Bool loop; + + StringAdd (ls->extra, '+'); + StringAddString (s, ls->extra->buf); + loop = ReplaceSetFind (rs, s->buf) != 0; + StringDispose (s); + if (loop) + fseek (f, ls->pos, SEEK_SET); + else + { + ret = ls->prev; + StringDispose (ls->tag); + StringDispose (ls->extra); + Dispose (ls); + } + return ret; +} + +static void +LineSkip (FILE *f, int *linep) +{ + int c; + + while ((c = Getc (f, linep)) == '\n') + ; + Ungetc (c, f, linep); +} + +static void +DoReplace (FILE *f, int *linep, ReplaceSet *s) +{ + int c; + String *tag; + Replace *r; + SkipStack *ss = 0; + LoopStack *ls = 0; + int skipping = 0; + + while ((c = Getc (f, linep)) != EOF) + { + if (c == '@') + { + tag = StringNew (); + while ((c = Getc (f, linep)) != '@') + { + if (c == EOF) + abort (); + StringAdd (tag, c); + } + if (ls) + StringAddString (tag, ls->extra->buf); + switch (tag->buf[0]) { + case '?': + ss = SkipStackPush (ss, skipping); + if (!ReplaceSetFind (s, tag->buf + 1)) + skipping++; + LineSkip (f, linep); + break; + case ':': + if (!ss) + abort (); + if (ss->skipping == skipping) + ++skipping; + else + --skipping; + LineSkip (f, linep); + break; + case ';': + skipping = ss->skipping; + ss = SkipStackPop (ss); + LineSkip (f, linep); + break; + case '{': + ls = LoopStackPush (ls, f, tag->buf + 1); + LineSkip (f, linep); + break; + case '}': + ls = LoopStackLoop (s, ls, f); + LineSkip (f, linep); + break; + default: + r = ReplaceSetFind (s, tag->buf); + if (r && !skipping) + StringPut (stdout, r->text); + break; + } + StringDispose (tag); + } + else if (!skipping) + putchar (c); + } +} + +int +main (int argc, char **argv) +{ + FILE *f; + ReplaceSet *s; + int iline, oline; + + if (!argv[1]) + Bail ("usage: %*s <template.sgml>", 0, argv[0]); + f = fopen (argv[1], "r"); + if (!f) + { + Bail ("can't open file %s", 0, argv[1]); + exit (1); + } + iline = 1; + while ((s = ReplaceSetRead (stdin, &iline))) + { + oline = 1; + DoReplace (f, &oline, s); + ReplaceSetDispose (s); + rewind (f); + } + if (ferror (stdout)) + Bail ("%s", 0, "error writing output"); + exit (0); +} diff --git a/fontconfig/doc/fcatomic.fncs b/fontconfig/doc/fcatomic.fncs new file mode 100644 index 000000000..c6b924d84 --- /dev/null +++ b/fontconfig/doc/fcatomic.fncs @@ -0,0 +1,95 @@ +/* + * fontconfig/doc/fcatomic.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. + */ + +@RET@ FcAtomic * +@FUNC@ FcAtomicCreate +@TYPE1@ const FcChar8 * @ARG1@ file +@PURPOSE@ create an FcAtomic object +@DESC@ +Creates a data structure containing data needed to control access to <parameter>file</parameter>. +Writing is done to a separate file. Once that file is complete, the original +configuration file is atomically replaced so that reading process always see +a consistent and complete file without the need to lock for reading. +@@ + +@RET@ FcBool +@FUNC@ FcAtomicLock +@TYPE1@ FcAtomic * @ARG1@ atomic +@PURPOSE@ lock a file +@DESC@ +Attempts to lock the file referenced by <parameter>atomic</parameter>. +Returns FcFalse if the file is already locked, else returns FcTrue and +leaves the file locked. +@@ + +@RET@ FcChar8 * +@FUNC@ FcAtomicNewFile +@TYPE1@ FcAtomic * @ARG1@ atomic +@PURPOSE@ return new temporary file name +@DESC@ +Returns the filename for writing a new version of the file referenced +by <parameter>atomic</parameter>. +@@ + +@RET@ FcChar8 * +@FUNC@ FcAtomicOrigFile +@TYPE1@ FcAtomic * @ARG1@ atomic +@PURPOSE@ return original file name +@DESC@ +Returns the file refernced by <parameter>atomic</parameter>. +@@ + +@RET@ FcBool +@FUNC@ FcAtomicReplaceOrig +@TYPE1@ FcAtomic * @ARG1@ atomic +@PURPOSE@ replace original with new +@DESC@ +Replaces the original file referenced by <parameter>atomic</parameter> with +the new file. Returns FcFalse if the file cannot be replaced due to +permission issues in the filesystem. Otherwise returns FcTrue. +@@ + +@RET@ void +@FUNC@ FcAtomicDeleteNew +@TYPE1@ FcAtomic * @ARG1@ atomic +@PURPOSE@ delete new file +@DESC@ +Deletes the new file. Used in error recovery to back out changes. +@@ + +@RET@ void +@FUNC@ FcAtomicUnlock +@TYPE1@ FcAtomic * @ARG1@ atomic +@PURPOSE@ unlock a file +@DESC@ +Unlocks the file. +@@ + +@RET@ void +@FUNC@ FcAtomicDestroy +@TYPE1@ FcAtomic * @ARG1@ atomic +@PURPOSE@ destroy an FcAtomic object +@DESC@ +Destroys <parameter>atomic</parameter>. +@@ diff --git a/fontconfig/doc/fcblanks.fncs b/fontconfig/doc/fcblanks.fncs new file mode 100644 index 000000000..b8ce47d24 --- /dev/null +++ b/fontconfig/doc/fcblanks.fncs @@ -0,0 +1,58 @@ +/* + * fontconfig/doc/fcblanks.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. + */ +@RET@ FcBlanks * +@FUNC@ FcBlanksCreate +@TYPE1@ void +@PURPOSE@ Create an FcBlanks +@DESC@ +Creates an empty FcBlanks object. +@@ + +@RET@ void +@FUNC@ FcBlanksDestroy +@TYPE1@ FcBlanks * @ARG1@ b +@PURPOSE@ Destroy and FcBlanks +@DESC@ +Destroys an FcBlanks object, freeing any associated memory. +@@ + +@RET@ FcBool +@FUNC@ FcBlanksAdd +@TYPE1@ FcBlanks * @ARG1@ b +@TYPE2@ FcChar32% @ARG2@ ucs4 +@PURPOSE@ Add a character to an FcBlanks +@DESC@ +Adds a single character to an FcBlanks object, returning FcFalse +if this process ran out of memory. +@@ + +@RET@ FcBool +@FUNC@ FcBlanksIsMember +@TYPE1@ FcBlanks * @ARG1@ b +@TYPE2@ FcChar32% @ARG2@ ucs4 +@PURPOSE@ Query membership in an FcBlanks +@DESC@ +Returns whether the specified FcBlanks object contains the indicated Unicode +value. +@@ diff --git a/fontconfig/doc/fccache.fncs b/fontconfig/doc/fccache.fncs new file mode 100644 index 000000000..f0c984d79 --- /dev/null +++ b/fontconfig/doc/fccache.fncs @@ -0,0 +1,68 @@ +/* + * Copyright © 2007 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. + */ + +@RET@ const FcChar8 * +@FUNC@ FcCacheDir +@TYPE1@ const FcCache * @ARG1@ cache +@PURPOSE@ Return directory of <parameter>cache</parameter> +@DESC@ +This function returns the directory from which the cache was constructed. +@@ + +@RET@ FcFontSet * +@FUNC@ FcCacheCopySet +@TYPE1@ const FcCache * @ARG1@ cache +@PURPOSE@ Returns a copy of the fontset from <parameter>cache</parameter> +@DESC@ +The returned fontset contains each of the font patterns from +<parameter>cache</parameter>. This fontset may be modified, but the patterns +from the cache are read-only. +@@ + +@RET@ const FcChar8 * +@FUNC@ FcCacheSubdir +@TYPE1@ const FcCache * @ARG1@ cache +@TYPE2@ int @ARG2@ i +@PURPOSE@ Return the <parameter>i</parameter>'th subdirectory. +@DESC@ +The set of subdirectories stored in a cache file are indexed by this +function, <parameter>i</parameter> should range from 0 to +<parameter>n</parameter>-1, where <parameter>n</parameter> is the return +value from FcCacheNumSubdir. +@@ + +@RET@ int +@FUNC@ FcCacheNumSubdir +@TYPE1@ const FcCache * @ARG1@ cache +@PURPOSE@ Return the number of subdirectories in <parameter>cache</parameter>. +@DESC@ +This returns the total number of subdirectories in the cache. +@@ + +@RET@ int +@FUNC@ FcCacheNumFont +@TYPE1@ const FcCache * @ARG1@ cache +@PURPOSE@ Returns the number of fonts in <parameter>cache</parameter>. +@DESC@ +This returns the number of fonts which would be included in the return from +FcCacheCopySet. +@@ diff --git a/fontconfig/doc/fccharset.fncs b/fontconfig/doc/fccharset.fncs new file mode 100644 index 000000000..b12064a55 --- /dev/null +++ b/fontconfig/doc/fccharset.fncs @@ -0,0 +1,206 @@ +/* + * fontconfig/doc/fccharset.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. + */ +@RET@ FcCharSet * +@FUNC@ FcCharSetCreate +@TYPE1@ void +@PURPOSE@ Create an empty character set +@DESC@ +<function>FcCharSetCreate</function> allocates and initializes a new empty +character set object. +@@ + +@RET@ void +@FUNC@ FcCharSetDestroy +@TYPE1@ FcCharSet * @ARG1@ fcs +@PURPOSE@ Destroy a character set +@DESC@ +<function>FcCharSetDestroy</function> decrements the reference count +<parameter>fcs</parameter>. If the reference count becomes zero, all +memory referenced is freed. +@@ + +@RET@ FcBool +@FUNC@ FcCharSetAddChar +@TYPE1@ FcCharSet * @ARG1@ fcs +@TYPE2@ FcChar32% @ARG2@ ucs4 +@PURPOSE@ Add a character to a charset +@DESC@ +<function>FcCharSetAddChar</function> adds a single unicode char to the set, +returning FcFalse on failure, either as a result of a constant set or from +running out of memory. +@@ + +@RET@ FcCharSet * +@FUNC@ FcCharSetCopy +@TYPE1@ FcCharSet * @ARG1@ src +@PURPOSE@ Copy a charset +@DESC@ +Makes a copy of <parameter>src</parameter>; note that this may not actually do anything more +than increment the reference count on <parameter>src</parameter>. +@@ + +@RET@ FcBool +@FUNC@ FcCharSetEqual +@TYPE1@ const FcCharSet * @ARG1@ a +@TYPE2@ const FcCharSet * @ARG2@ b +@PURPOSE@ Compare two charsets +@DESC@ +Returns whether <parameter>a</parameter> and <parameter>b</parameter> +contain the same set of unicode chars. +@@ + +@RET@ FcCharSet * +@FUNC@ FcCharSetIntersect +@TYPE1@ const FcCharSet * @ARG1@ a +@TYPE2@ const FcCharSet * @ARG2@ b +@PURPOSE@ Intersect charsets +@DESC@ +Returns a set including only those chars found in both +<parameter>a</parameter> and <parameter>b</parameter>. +@@ + +@RET@ FcCharSet * +@FUNC@ FcCharSetUnion +@TYPE1@ const FcCharSet * @ARG1@ a +@TYPE2@ const FcCharSet * @ARG2@ b +@PURPOSE@ Add charsets +@DESC@ +Returns a set including only those chars found in either <parameter>a</parameter> or <parameter>b</parameter>. +@@ + +@RET@ FcCharSet * +@FUNC@ FcCharSetSubtract +@TYPE1@ const FcCharSet * @ARG1@ a +@TYPE2@ const FcCharSet * @ARG2@ b +@PURPOSE@ Subtract charsets +@DESC@ +Returns a set including only those chars found in <parameter>a</parameter> but not <parameter>b</parameter>. +@@ + +@RET@ FcBool +@FUNC@ FcCharSetMerge +@TYPE1@ FcCharSet * @ARG1@ a +@TYPE2@ const FcCharSet * @ARG2@ b +@TYPE3@ FcBool * @ARG3@ changed +@PURPOSE@ Merge charsets +@DESC@ +Adds all chars in <parameter>b</parameter> to <parameter>a</parameter>. +In other words, this is an in-place version of FcCharSetUnion. +If <parameter>changed</parameter> is not NULL, then it returns whether any new +chars from <parameter>b</parameter> were added to <parameter>a</parameter>. +Returns FcFalse on failure, either when <parameter>a</parameter> is a constant +set or from running out of memory. +@@ + +@RET@ FcBool +@FUNC@ FcCharSetHasChar +@TYPE1@ const FcCharSet * @ARG1@ fcs +@TYPE2@ FcChar32% @ARG2@ ucs4 +@PURPOSE@ Check a charset for a char +@DESC@ +Returns whether <parameter>fcs</parameter> contains the char <parameter>ucs4</parameter>. +@@ + +@RET@ FcChar32 +@FUNC@ FcCharSetCount +@TYPE1@ const FcCharSet * @ARG1@ a +@PURPOSE@ Count entries in a charset +@DESC@ +Returns the total number of unicode chars in <parameter>a</parameter>. +@@ + +@RET@ FcChar32 +@FUNC@ FcCharSetIntersectCount +@TYPE1@ const FcCharSet * @ARG1@ a +@TYPE2@ const FcCharSet * @ARG2@ b +@PURPOSE@ Intersect and count charsets +@DESC@ +Returns the number of chars that are in both <parameter>a</parameter> and <parameter>b</parameter>. +@@ + +@RET@ FcChar32 +@FUNC@ FcCharSetSubtractCount +@TYPE1@ const FcCharSet * @ARG1@ a +@TYPE2@ const FcCharSet * @ARG2@ b +@PURPOSE@ Subtract and count charsets +@DESC@ +Returns the number of chars that are in <parameter>a</parameter> but not in <parameter>b</parameter>. +@@ + +@RET@ FcBool +@FUNC@ FcCharSetIsSubset +@TYPE1@ const FcCharSet * @ARG1@ a +@TYPE2@ const FcCharSet * @ARG2@ b +@PURPOSE@ Test for charset inclusion +@DESC@ +Returns whether <parameter>a</parameter> is a subset of <parameter>b</parameter>. +@@ + +@RET@ FcChar32 +@FUNC@ FcCharSetFirstPage +@TYPE1@ const FcCharSet * @ARG1@ a +@TYPE2@ FcChar32[FC_CHARSET_MAP_SIZE]% @ARG2@ map +@TYPE3@ FcChar32 * @ARG3@ next +@PURPOSE@ Start enumerating charset contents +@DESC@ +Builds an array of bits marking the first page of Unicode coverage of +<parameter>a</parameter>. Returns the base of the array. <parameter>next</parameter> contains the next page in the +font. +@@ + +@RET@ FcChar32 +@FUNC@ FcCharSetNextPage +@TYPE1@ const FcCharSet * @ARG1@ a +@TYPE2@ FcChar32[FC_CHARSET_MAP_SIZE]% @ARG2@ map +@TYPE3@ FcChar32 * @ARG3@ next +@PURPOSE@ Continue enumerating charset contents +@DESC@ +Builds an array of bits marking the Unicode coverage of <parameter>a</parameter> for page +<parameter>*next</parameter>. Returns the base of the array. <parameter>next</parameter> contains the next page in +the font. +@@ + +@RET@ FcChar32 +@FUNC@ FcCharSetCoverage +@TYPE1@ const FcCharSet * @ARG1@ a +@TYPE2@ FcChar32 @ARG2@ page +@TYPE3@ FcChar32[8] @ARG3@ result +@PURPOSE@ DEPRECATED return coverage for a Unicode page +@DESC@ +DEPRECATED +This function returns a bitmask in <parameter>result</parameter> which +indicates which code points in +<parameter>page</parameter> are included in <parameter>a</parameter>. +<function>FcCharSetCoverage</function> returns the next page in the charset which has any +coverage. +@@ + +@RET@ FcCharSet * +@FUNC@ FcCharSetNew +@TYPE1@ void +@PURPOSE@ DEPRECATED alias for FcCharSetCreate +@DESC@ +<function>FcCharSetNew</function> is a DEPRECATED alias for FcCharSetCreate. +@@ + diff --git a/fontconfig/doc/fcconfig.fncs b/fontconfig/doc/fcconfig.fncs new file mode 100644 index 000000000..8bb953b34 --- /dev/null +++ b/fontconfig/doc/fcconfig.fncs @@ -0,0 +1,373 @@ +/* + * fontconfig/doc/fcconfig.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. + */ +@RET@ FcConfig * +@FUNC@ FcConfigCreate +@TYPE1@ void +@PURPOSE@ Create a configuration +@DESC@ +Creates an empty configuration. +@@ + +@RET@ FcConfig * +@FUNC@ FcConfigReference +@TYPE1@ FcConfig * @ARG1@ config +@PURPOSE@ Increment config reference count +@DESC@ +Add another reference to <parameter>config</parameter>. Configs are freed only +when the reference count reaches zero. +If <parameter>config</parameter> is NULL, the current configuration is used. +In that case this function will be similar to FcConfigGetCurrent() except that +it increments the reference count before returning and the user is responsible +for destroying the configuration when not needed anymore. +@@ + +@RET@ void +@FUNC@ FcConfigDestroy +@TYPE1@ FcConfig * @ARG1@ config +@PURPOSE@ Destroy a configuration +@DESC@ +Decrements the config reference count. If all references are gone, destroys +the configuration and any data associated with it. +Note that calling this function with the return from FcConfigGetCurrent will +cause a new configuration to be created for use as current configuration. +@@ + +@RET@ FcBool +@FUNC@ FcConfigSetCurrent +@TYPE1@ FcConfig * @ARG1@ config +@PURPOSE@ Set configuration as default +@DESC@ +Sets the current default configuration to <parameter>config</parameter>. Implicitly calls +FcConfigBuildFonts if necessary, returning FcFalse if that call fails. +@@ + +@RET@ FcConfig * +@FUNC@ FcConfigGetCurrent +@TYPE1@ void +@PURPOSE@ Return current configuration +@DESC@ +Returns the current default configuration. +@@ + +@RET@ FcBool +@FUNC@ FcConfigUptoDate +@TYPE1@ FcConfig * @ARG1@ config +@PURPOSE@ Check timestamps on config files +@DESC@ +Checks all of the files related to <parameter>config</parameter> and returns +whether any of them has been modified since the configuration was created. +If <parameter>config</parameter> is NULL, the current configuration is used. +@@ + +@RET@ FcChar8 * +@FUNC@ FcConfigHome +@TYPE1@ void +@PURPOSE@ return the current home directory. +@DESC@ +Return the current user's home directory, if it is available, and if using it +is enabled, and NULL otherwise. +See also <function>FcConfigEnableHome</function>). +@@ + +@RET@ FcBol +@FUNC@ FcConfigEnableHome +@TYPE1@ FcBool% @ARG1@ enable +@PURPOSE@ controls use of the home directory. +@DESC@ +If <parameter>enable</parameter> is FcTrue, then Fontconfig will use various +files which are specified relative to the user's home directory (using the ~ +notation in the configuration). When <parameter>enable</parameter> is +FcFalse, then all use of the home directory in these contexts will be +disabled. The previous setting of the value is returned. +@@ + +@RET@ FcBool +@FUNC@ FcConfigBuildFonts +@TYPE1@ FcConfig * @ARG1@ config +@PURPOSE@ Build font database +@DESC@ +Builds the set of available fonts for the given configuration. Note that +any changes to the configuration after this call have indeterminate effects. +Returns FcFalse if this operation runs out of memory. +If <parameter>config</parameter> is NULL, the current configuration is used. +@@ + +@RET@ FcStrList * +@FUNC@ FcConfigGetConfigDirs +@TYPE1@ FcConfig * @ARG1@ config +@PURPOSE@ Get config directories +@DESC@ +Returns the list of font directories specified in the configuration files +for <parameter>config</parameter>. Does not include any subdirectories. +If <parameter>config</parameter> is NULL, the current configuration is used. +@@ + +@RET@ FcStrList * +@FUNC@ FcConfigGetFontDirs +@TYPE1@ FcConfig * @ARG1@ config +@PURPOSE@ Get font directories +@DESC@ +Returns the list of font directories in <parameter>config</parameter>. This includes the +configured font directories along with any directories below those in the +filesystem. +If <parameter>config</parameter> is NULL, the current configuration is used. +@@ + +@RET@ FcStrList * +@FUNC@ FcConfigGetConfigFiles +@TYPE1@ FcConfig * @ARG1@ config +@PURPOSE@ Get config files +@DESC@ +Returns the list of known configuration files used to generate <parameter>config</parameter>. +If <parameter>config</parameter> is NULL, the current configuration is used. +@@ + +@RET@ FcChar8 * +@FUNC@ FcConfigGetCache +@TYPE1@ FcConfig * @ARG1@ config +@PURPOSE@ DEPRECATED used to return per-user cache filename +@DESC@ +With fontconfig no longer using per-user cache files, this function now +simply returns NULL to indicate that no per-user file exists. +@@ + +@RET@ FcStrList * +@FUNC@ FcConfigGetCacheDirs +@TYPE1@ FcConfig * @ARG1@ config +@PURPOSE@ return the list of directories searched for cache files +@DESC@ +<function>FcConfigGetCacheDirs</function> returns a string list containing +all of the directories that fontconfig will search when attempting to load a +cache file for a font directory. +If <parameter>config</parameter> is NULL, the current configuration is used. +@@ + +@RET@ FcFontSet * +@FUNC@ FcConfigGetFonts +@TYPE1@ FcConfig * @ARG1@ config +@TYPE2@ FcSetName% @ARG2@ set +@PURPOSE@ Get config font set +@DESC@ +Returns one of the two sets of fonts from the configuration as specified +by <parameter>set</parameter>. This font set is owned by the library and must +not be modified or freed. +If <parameter>config</parameter> is NULL, the current configuration is used. +@@ + +@RET@ FcBlanks * +@FUNC@ FcConfigGetBlanks +@TYPE1@ FcConfig * @ARG1@ config +@PURPOSE@ Get config blanks +@DESC@ +Returns the FcBlanks object associated with the given configuration, if no +blanks were present in the configuration, this function will return 0. +The returned FcBlanks object if not NULL, is valid as long as the owning +FcConfig is alive. +If <parameter>config</parameter> is NULL, the current configuration is used. +@@ + +@RET@ int +@FUNC@ FcConfigGetRescanInterval +@TYPE1@ FcConfig * @ARG1@ config +@PURPOSE@ Get config rescan interval +@DESC@ +Returns the interval between automatic checks of the configuration (in +seconds) specified in <parameter>config</parameter>. The configuration is checked during +a call to FcFontList when this interval has passed since the last check. +An interval setting of zero disables automatic checks. +If <parameter>config</parameter> is NULL, the current configuration is used. +@@ + +@RET@ FcBool +@FUNC@ FcConfigSetRescanInterval +@TYPE1@ FcConfig * @ARG1@ config +@TYPE2@ int% @ARG2@ rescanInterval +@PURPOSE@ Set config rescan interval +@DESC@ +Sets the rescan interval. Returns FcFalse if the interval cannot be set (due +to allocation failure). Otherwise returns FcTrue. +An interval setting of zero disables automatic checks. +If <parameter>config</parameter> is NULL, the current configuration is used. +@@ + +@RET@ FcBool +@FUNC@ FcConfigAppFontAddFile +@TYPE1@ FcConfig * @ARG1@ config +@TYPE2@ const FcChar8 * @ARG2@ file +@PURPOSE@ Add font file to font database +@DESC@ +Adds an application-specific font to the configuration. Returns FcFalse +if the fonts cannot be added (due to allocation failure). Otherwise returns FcTrue. +If <parameter>config</parameter> is NULL, the current configuration is used. +@@ + +@RET@ FcBool +@FUNC@ FcConfigAppFontAddDir +@TYPE1@ FcConfig * @ARG1@ config +@TYPE2@ const FcChar8 * @ARG2@ dir +@PURPOSE@ Add fonts from directory to font database +@DESC@ +Scans the specified directory for fonts, adding each one found to the +application-specific set of fonts. Returns FcFalse +if the fonts cannot be added (due to allocation failure). Otherwise returns FcTrue. +If <parameter>config</parameter> is NULL, the current configuration is used. +@@ + +@RET@ void +@FUNC@ FcConfigAppFontClear +@TYPE1@ FcConfig * @ARG1@ config +@PURPOSE@ Remove all app fonts from font database +@DESC@ +Clears the set of application-specific fonts. +If <parameter>config</parameter> is NULL, the current configuration is used. +@@ + +@RET@ FcBool +@FUNC@ FcConfigSubstituteWithPat +@TYPE1@ FcConfig * @ARG1@ config +@TYPE2@ FcPattern * @ARG2@ p +@TYPE3@ FcPattern * @ARG3@ p_pat +@TYPE4@ FcMatchKind% @ARG4@ kind +@PURPOSE@ Execute substitutions +@DESC@ +Performs the sequence of pattern modification operations, if <parameter>kind</parameter> is +FcMatchPattern, then those tagged as pattern operations are applied, else +if <parameter>kind</parameter> is FcMatchFont, those tagged as font operations are applied and +p_pat is used for <test> elements with target=pattern. Returns FcFalse +if the substitution cannot be performed (due to allocation failure). Otherwise returns FcTrue. +If <parameter>config</parameter> is NULL, the current configuration is used. +@@ + +@RET@ FcBool +@FUNC@ FcConfigSubstitute +@TYPE1@ FcConfig * @ARG1@ config +@TYPE2@ FcPattern * @ARG2@ p +@TYPE3@ FcMatchKind% @ARG3@ kind +@PURPOSE@ Execute substitutions +@DESC@ +Calls FcConfigSubstituteWithPat setting p_pat to NULL. Returns FcFalse +if the substitution cannot be performed (due to allocation failure). Otherwise returns FcTrue. +If <parameter>config</parameter> is NULL, the current configuration is used. +@@ + +@RET@ FcPattern * +@FUNC@ FcFontMatch +@TYPE1@ FcConfig * @ARG1@ config +@TYPE2@ FcPattern * @ARG2@ p +@TYPE3@ FcResult * @ARG3@ result +@PURPOSE@ Return best font +@DESC@ +Finds the font in <parameter>sets</parameter> most closely matching +<parameter>pattern</parameter> and returns the result of +<function>FcFontRenderPrepare</function> for that font and the provided +pattern. This function should be called only after +<function>FcConfigSubstitute</function> and +<function>FcDefaultSubstitute</function> have been called for +<parameter>p</parameter>; otherwise the results will not be correct. +If <parameter>config</parameter> is NULL, the current configuration is used. +@@ + +@RET@ FcFontSet * +@FUNC@ FcFontSort +@TYPE1@ FcConfig * @ARG1@ config +@TYPE2@ FcPattern * @ARG2@ p +@TYPE3@ FcBool% @ARG3@ trim +@TYPE4@ FcCharSet ** @ARG4@ csp +@TYPE5@ FcResult * @ARG5@ result +@PURPOSE@ Return list of matching fonts +@DESC@ +Returns the list of fonts sorted by closeness to <parameter>p</parameter>. If <parameter>trim</parameter> is FcTrue, +elements in the list which don't include Unicode coverage not provided by +earlier elements in the list are elided. The union of Unicode coverage of +all of the fonts is returned in <parameter>csp</parameter>, if <parameter>csp</parameter> is not NULL. This function +should be called only after FcConfigSubstitute and FcDefaultSubstitute have +been called for <parameter>p</parameter>; otherwise the results will not be correct. + </para><para> +The returned FcFontSet references FcPattern structures which may be shared +by the return value from multiple FcFontSort calls, applications must not +modify these patterns. Instead, they should be passed, along with <parameter>p</parameter> to +<function>FcFontRenderPrepare</function> which combines them into a complete pattern. + </para><para> +The FcFontSet returned by FcFontSort is destroyed by caling FcFontSetDestroy. +If <parameter>config</parameter> is NULL, the current configuration is used. +@@ + +@RET@ FcPattern * +@FUNC@ FcFontRenderPrepare +@TYPE1@ FcConfig * @ARG1@ config +@TYPE2@ FcPattern * @ARG2@ pat +@TYPE3@ FcPattern * @ARG3@ font +@PURPOSE@ Prepare pattern for loading font file +@DESC@ +Creates a new pattern consisting of elements of <parameter>font</parameter> not appearing +in <parameter>pat</parameter>, elements of <parameter>pat</parameter> not appearing in <parameter>font</parameter> and the best matching +value from <parameter>pat</parameter> for elements appearing in both. The result is passed to +FcConfigSubstituteWithPat with <parameter>kind</parameter> FcMatchFont and then returned. +@@ + +@RET@ FcFontSet * +@FUNC@ FcFontList +@TYPE1@ FcConfig * @ARG1@ config +@TYPE2@ FcPattern * @ARG2@ p +@TYPE3@ FcObjectSet * @ARG3@ os +@PURPOSE@ List fonts +@DESC@ +Selects fonts matching <parameter>p</parameter>, creates patterns from those fonts containing +only the objects in <parameter>os</parameter> and returns the set of unique such patterns. +If <parameter>config</parameter> is NULL, the default configuration is checked +to be up to date, and used. +@@ + +@RET@ FcChar8 * +@FUNC@ FcConfigFilename +@TYPE1@ const FcChar8 * @ARG1@ name +@PURPOSE@ Find a config file +@DESC@ +Given the specified external entity name, return the associated filename. +This provides applications a way to convert various configuration file +references into filename form. + </para><para> +A null or empty <parameter>name</parameter> indicates that the default configuration file should +be used; which file this references can be overridden with the +FC_CONFIG_FILE environment variable. Next, if the name starts with <parameter>~</parameter>, it +refers to a file in the current users home directory. Otherwise if the name +doesn't start with '/', it refers to a file in the default configuration +directory; the built-in default directory can be overridden with the +FC_CONFIG_DIR environment variable. +@@ + +@RET@ FcBool +@FUNC@ FcConfigParseAndLoad +@TYPE1@ FcConfig * @ARG1@ config +@TYPE2@ const FcChar8 * @ARG2@ file +@TYPE3@ FcBool% @ARG3@ complain +@PURPOSE@ load a configuration file +@DESC@ +Walks the configuration in 'file' and constructs the internal representation +in 'config'. Any include files referenced from within 'file' will be loaded +and parsed. If 'complain' is FcFalse, no warning will be displayed if +'file' does not exist. Error and warning messages will be output to stderr. +Returns FcFalse if some error occurred while loading the file, either a +parse error, semantic error or allocation failure. Otherwise returns FcTrue. +@@ diff --git a/fontconfig/doc/fcconstant.fncs b/fontconfig/doc/fcconstant.fncs new file mode 100644 index 000000000..86150f203 --- /dev/null +++ b/fontconfig/doc/fcconstant.fncs @@ -0,0 +1,62 @@ +/* + * fontconfig/doc/fcconstant.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. + */ +@RET@ FcBool +@FUNC@ FcNameRegisterConstants +@TYPE1@ const FcConstant * @ARG1@ consts +@TYPE2@ int% @ARG2@ nconsts +@PURPOSE@ Register symbolic constants +@DESC@ +Register <parameter>nconsts</parameter> new symbolic constants. Returns +FcFalse if the constants cannot be registered (due to allocation failure). +Otherwise returns FcTrue. +@@ + +@RET@ FcBool +@FUNC@ FcNameUnregisterConstants +@TYPE1@ const FcConstant * @ARG1@ consts +@TYPE2@ int% @ARG2@ nconsts +@PURPOSE@ Unregister symbolic constants +@DESC@ +Unregister <parameter>nconsts</parameter> symbolic constants. Returns +FcFalse if the specified constants were not registered. Otherwise returns +FcTrue. +@@ + +@RET@ const FcConstant * +@FUNC@ FcNameGetConstant +@TYPE1@ FcChar8 * @ARG1@ string +@PURPOSE@ Lookup symbolic constant +@DESC@ +Return the FcConstant structure related to symbolic constant <parameter>string</parameter>. +@@ + +@RET@ FcBool +@FUNC@ FcNameConstant +@TYPE1@ FcChar8 * @ARG1@ string +@TYPE2@ int * @ARG2@ result +@PURPOSE@ Get the value for a symbolic constant +@DESC@ +Returns whether a symbolic constant with name <parameter>string</parameter> is registered, +placing the value of the constant in <parameter>result</parameter> if present. +@@ diff --git a/fontconfig/doc/fcdircache.fncs b/fontconfig/doc/fcdircache.fncs new file mode 100644 index 000000000..24dea8bc5 --- /dev/null +++ b/fontconfig/doc/fcdircache.fncs @@ -0,0 +1,88 @@ +/* + * Copyright © 2007 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 copyright holders not be used in advertising or + * publicity pertaining to distribution of the software without specific, + * written prior permission. The copyright holders make no representations + * about the suitability of this software for any purpose. It is provided "as + * is" without express or implied warranty. + * + * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO + * EVENT SHALL THE COPYRIGHT HOLDERS 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@ FcBool +@FUNC@ FcDirCacheUnlink +@TYPE1@ const FcChar8 * @ARG1@ dir +@TYPE2@ FcConfig * @ARG2@ config +@PURPOSE@ Remove all caches related to <parameter>dir</parameter> +@DESC@ +Scans the cache directories in <parameter>config</parameter>, removing any +instances of the cache file for <parameter>dir</parameter>. Returns FcFalse +when some internal error occurs (out of memory, etc). Errors actually +unlinking any files are ignored. +@@ + +@RET@ FcBool +@FUNC@ FcDirCacheValid +@TYPE1@ const FcChar8 * @ARG1@ dir +@PURPOSE@ check directory cache +@DESC@ +Returns FcTrue if <parameter>dir</parameter> has an associated valid cache +file, else returns FcFalse +@@ + +@RET@ FcCache * +@FUNC@ FcDirCacheLoad +@TYPE1@ const FcChar8 * @ARG1@ dir +@TYPE2@ FcConfig * @ARG2@ config +@TYPE3@ FcChar8 ** @ARG3@ cache_file +@PURPOSE@ load a directory cache +@DESC@ +Loads the cache related to <parameter>dir</parameter>. If no cache file +exists, returns NULL. The name of the cache file is returned in +<parameter>cache_file</parameter>, unless that is NULL. See also +FcDirCacheRead. +@@ + +@RET@ FcCache * +@FUNC@ FcDirCacheRead +@TYPE1@ const FcChar8 * @ARG1@ dir +@TYPE2@ FcBool% @ARG2@ force +@TYPE3@ FcConfig * @ARG3@ config +@PURPOSE@ read or construct a directory cache +@DESC@ +This returns a cache for <parameter>dir</parameter>. If +<parameter>force</parameter> is FcFalse, then an existing, valid cache file +will be used. Otherwise, a new cache will be created by scanning the +directory and that returned. +@@ + +@RET@ FcCache * +@FUNC@ FcDirCacheLoadFile +@TYPE1@ const FcChar8 * @ARG1@ cache_file +@TYPE2@ struct stat * @ARG2@ file_stat +@PURPOSE@ load a cache file +@DESC@ +This function loads a directory cache from +<parameter>cache_file</parameter>. If <parameter>file_stat</parameter> is +non-NULL, it will be filled with the results of stat(2) on the cache file. +@@ + +@RET@ void +@FUNC@ FcDirCacheUnload +@TYPE1@ FcCache * @ARG1@ cache +@PURPOSE@ unload a cache file +@DESC@ +This function dereferences <parameter>cache</parameter>. When no other +references to it remain, all memory associated with the cache will be freed. +@@ diff --git a/fontconfig/doc/fcfile.fncs b/fontconfig/doc/fcfile.fncs new file mode 100644 index 000000000..d15ab27a3 --- /dev/null +++ b/fontconfig/doc/fcfile.fncs @@ -0,0 +1,88 @@ +/* + * fontconfig/doc/fcfile.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. + */ + +@RET@ FcBool +@FUNC@ FcFileScan +@TYPE1@ FcFontSet * @ARG1@ set +@TYPE2@ FcStrSet * @ARG2@ dirs +@TYPE3@ FcFileCache * @ARG3@ cache +@TYPE4@ FcBlanks * @ARG4@ blanks +@TYPE5@ const FcChar8 * @ARG5@ file +@TYPE6@ FcBool% @ARG6@ force +@PURPOSE@ scan a font file +@DESC@ +Scans a single file and adds all fonts found to <parameter>set</parameter>. +If <parameter>force</parameter> is FcTrue, then the file is scanned even if +associated information is found in <parameter>cache</parameter>. If +<parameter>file</parameter> is a directory, it is added to +<parameter>dirs</parameter>. Whether fonts are found depends on fontconfig +policy as well as the current configuration. Internally, fontconfig will +ignore BDF and PCF fonts which are not in Unicode (or the effectively +equivalent ISO Latin-1) encoding as those are not usable by Unicode-based +applications. The configuration can ignore fonts based on filename or +contents of the font file itself. Returns FcFalse if any of the fonts cannot be +added (due to allocation failure). Otherwise returns FcTrue. +@@ + +@RET@ FcBool +@FUNC@ FcFileIsDir +@TYPE1@ const FcChar8 * @ARG1@ file +@PURPOSE@ check whether a file is a directory +@DESC@ +Returns FcTrue if <parameter>file</parameter> is a directory, otherwise +returns FcFalse. +@@ + +@RET@ FcBool +@FUNC@ FcDirScan +@TYPE1@ FcFontSet * @ARG1@ set +@TYPE2@ FcStrSet * @ARG2@ dirs +@TYPE3@ FcFileCache * @ARG3@ cache +@TYPE4@ FcBlanks * @ARG4@ blanks +@TYPE5@ const FcChar8 * @ARG5@ dir +@TYPE6@ FcBool% @ARG6@ force +@PURPOSE@ scan a font directory without caching it +@DESC@ +If <parameter>cache</parameter> is not zero or if <parameter>force</parameter> +is FcFalse, this function currently returns FcFalse. Otherwise, it scans an +entire directory and adds all fonts found to <parameter>set</parameter>. +Any subdirectories found are added to <parameter>dirs</parameter>. Calling +this function does not create any cache files. Use FcDirCacheRead() if +caching is desired. +@@ + +@RET@ FcBool +@FUNC@ FcDirSave +@TYPE1@ FcFontSet * @ARG1@ set +@TYPE2@ FcStrSet * @ARG2@ dirs +@TYPE3@ const FcChar8 * @ARG3@ dir +@PURPOSE@ DEPRECATED: formerly used to save a directory cache +@DESC@ +This function now does nothing aside from returning FcFalse. It used to creates the +per-directory cache file for <parameter>dir</parameter> and populates it +with the fonts in <parameter>set</parameter> and subdirectories in +<parameter>dirs</parameter>. All of this functionality is now automatically +managed by FcDirCacheLoad and FcDirCacheRead. +@@ + diff --git a/fontconfig/doc/fcfontset.fncs b/fontconfig/doc/fcfontset.fncs new file mode 100644 index 000000000..57005fdd0 --- /dev/null +++ b/fontconfig/doc/fcfontset.fncs @@ -0,0 +1,140 @@ +/* + * fontconfig/doc/fcfontset.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. + */ +@RET@ FcFontSet * +@FUNC@ FcFontSetCreate +@TYPE1@ void +@PURPOSE@ Create a font set +@DESC@ +Creates an empty font set. +@@ + +@RET@ void +@FUNC@ FcFontSetDestroy +@TYPE1@ FcFontSet * @ARG1@ s +@PURPOSE@ Destroy a font set +@DESC@ +Destroys a font set. Note that this destroys any referenced patterns as +well. +@@ + +@RET@ FcBool +@FUNC@ FcFontSetAdd +@TYPE1@ FcFontSet * @ARG1@ s +@TYPE2@ FcPattern * @ARG2@ font +@PURPOSE@ Add to a font set +@DESC@ +Adds a pattern to a font set. Note that the pattern is not copied before +being inserted into the set. Returns FcFalse if the pattern cannot be +inserted into the set (due to allocation failure). Otherwise returns FcTrue. +@@ + +@RET@ FcFontSet * +@FUNC@ FcFontSetList +@TYPE1@ FcConfig * @ARG1@ config +@TYPE2@ FcFontSet ** @ARG2@ sets +@TYPE3@ int @ARG3@ nsets +@TYPE4@ FcPattern * @ARG4@ pattern +@TYPE5@ FcObjectSet * @ARG5@ object_set +@PURPOSE@ List fonts from a set of font sets +@DESC@ +Selects fonts matching <parameter>pattern</parameter> from +<parameter>sets</parameter>, creates patterns from those +fonts containing only the objects in <parameter>object_set</parameter> and returns +the set of unique such patterns. +If <parameter>config</parameter> is NULL, the default configuration is checked +to be up to date, and used. +@@ + +@RET@ FcPattern * +@FUNC@ FcFontSetMatch +@TYPE1@ FcConfig * @ARG1@ config +@TYPE2@ FcFontSet ** @ARG2@ sets +@TYPE3@ int @ARG3@ nsets +@TYPE4@ FcPattern * @ARG4@ pattern +@TYPE5@ FcResult * @ARG5@ result +@PURPOSE@ Return the best font from a set of font sets +@DESC@ +Finds the font in <parameter>sets</parameter> most closely matching +<parameter>pattern</parameter> and returns the result of +<function>FcFontRenderPrepare</function> for that font and the provided +pattern. This function should be called only after +<function>FcConfigSubstitute</function> and +<function>FcDefaultSubstitute</function> have been called for +<parameter>pattern</parameter>; otherwise the results will not be correct. +If <parameter>config</parameter> is NULL, the current configuration is used. +Returns NULL if an error occurs during this process. +@@ + +@RET@ void +@FUNC@ FcFontSetPrint +@TYPE1@ FcFontSet * @ARG1@ set +@PURPOSE@ Print a set of patterns to stdout +@DESC@ +This function is useful for diagnosing font related issues, printing the +complete contents of every pattern in <parameter>set</parameter>. The format +of the output is designed to be of help to users and developers, and may +change at any time. +@@ + +@RET@ +@FUNC@ FcFontSetSort +@TYPE1@ FcConfig * @ARG1@ config +@TYPE2@ FcFontSet ** @ARG2@ sets +@TYPE3@ int @ARG3@ nsets +@TYPE4@ FcPattern * @ARG4@ pattern +@TYPE5@ FcBool% @ARG5@ trim +@TYPE6@ FcCharSet ** @ARG6@ csp +@TYPE7@ FcResult * @ARG7@ result +@PURPOSE@ Add to a font set +@DESC@ +Returns the list of fonts from <parameter>sets</parameter> +sorted by closeness to <parameter>pattern</parameter>. +If <parameter>trim</parameter> is FcTrue, +elements in the list which don't include Unicode coverage not provided by +earlier elements in the list are elided. The union of Unicode coverage of +all of the fonts is returned in <parameter>csp</parameter>, +if <parameter>csp</parameter> is not NULL. This function +should be called only after FcConfigSubstitute and FcDefaultSubstitute have +been called for <parameter>p</parameter>; +otherwise the results will not be correct. + </para><para> +The returned FcFontSet references FcPattern structures which may be shared +by the return value from multiple FcFontSort calls, applications cannot +modify these patterns. Instead, they should be passed, along with +<parameter>pattern</parameter> to +<function>FcFontRenderPrepare</function> which combines them into a complete pattern. + </para><para> +The FcFontSet returned by FcFontSetSort is destroyed by caling FcFontSetDestroy. +@@ + +@RET@ +@FUNC@ FcFontSetSortDestroy +@TYPE1@ FcFontSet * @ARG1@ set +@PURPOSE@ DEPRECATED destroy a font set +@DESC@ +This function is DEPRECATED. <function>FcFontSetSortDestroy</function> +destroys <parameter>set</parameter> by calling +<function>FcFontSetDestroy</function>. Applications should use +<function>FcFontSetDestroy</function> directly instead. +@@ diff --git a/fontconfig/doc/fcformat.fncs b/fontconfig/doc/fcformat.fncs new file mode 100644 index 000000000..b092449cf --- /dev/null +++ b/fontconfig/doc/fcformat.fncs @@ -0,0 +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. + +@@ diff --git a/fontconfig/doc/fcfreetype.fncs b/fontconfig/doc/fcfreetype.fncs new file mode 100644 index 000000000..366cfaef8 --- /dev/null +++ b/fontconfig/doc/fcfreetype.fncs @@ -0,0 +1,106 @@ +/* + * fontconfig/doc/fcfreetype.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. + */ + +@SYNOPSIS@ +#include <fontconfig.h> +#include <fcfreetype.h> +@RET@ FT_UInt +@FUNC@ FcFreeTypeCharIndex +@TYPE1@ FT_Face% @ARG1@ face +@TYPE2@ FcChar32% @ARG2@ ucs4 +@PURPOSE@ map Unicode to glyph id +@DESC@ +Maps a Unicode char to a glyph index. This function uses information from +several possible underlying encoding tables to work around broken fonts. +As a result, this function isn't designed to be used in performance +sensitive areas; results from this function are intended to be cached by +higher level functions. +@@ + +@SYNOPSIS@ +#include <fontconfig.h> +#include <fcfreetype.h> +@RET@ FcCharSet * +@FUNC@ FcFreeTypeCharSet +@TYPE1@ FT_Face% @ARG1@ face +@TYPE2@ FcBlanks * @ARG2@ blanks +@PURPOSE@ compute unicode coverage +@DESC@ +Scans a FreeType face and returns the set of encoded Unicode chars. This scans +several encoding tables to build as complete a list as possible. +If 'blanks' is not 0, the glyphs in the font are examined and any blank glyphs +not in 'blanks' are not placed in the returned FcCharSet. +@@ + +@SYNOPSIS@ +#include <fontconfig.h> +#include <fcfreetype.h> +@RET@ FcCharSet * +@FUNC@ FcFreeTypeCharSetAndSpacing +@TYPE1@ FT_Face% @ARG1@ face +@TYPE2@ FcBlanks * @ARG2@ blanks +@TYPE3@ int * @ARG3@ spacing +@PURPOSE@ compute unicode coverage and spacing type +@DESC@ +Scans a FreeType face and returns the set of encoded Unicode chars. +This scans +several encoding tables to build as complete a list as possible. +If 'blanks' is not 0, the glyphs in the font are examined and any blank glyphs +not in 'blanks' are not placed in the returned FcCharSet. +<parameter>spacing</parameter> receives the computed spacing type of the +font, one of FC_MONO for a font where all glyphs have the same width, +FC_DUAL, where the font has glyphs in precisely two widths, one twice as +wide as the other, or FC_PROPORTIONAL where the font has glyphs of many +widths. +@@ + +@SYNOPSIS@ +#include <fontconfig.h> +#include <fcfreetype.h> +@RET@ FcPattern * +@FUNC@ FcFreeTypeQuery +@TYPE1@ const FcChar8 * @ARG1@ file +@TYPE2@ int% @ARG2@ id +@TYPE3@ FcBlanks * @ARG3@ blanks +@TYPE4@ int * @ARG4@ count +@PURPOSE@ compute pattern from font file (and index) +@DESC@ +Constructs a pattern representing the 'id'th font in 'file'. The number +of fonts in 'file' is returned in 'count'. +@@ + +@SYNOPSIS@ +#include <fontconfig.h> +#include <fcfreetype.h> +@RET@ FcPattern * +@FUNC@ FcFreeTypeQueryFace +@TYPE1@ const FT_Face% @ARG1@ face +@TYPE2@ const FcChar8 * @ARG2@ file +@TYPE3@ int% @ARG3@ id +@TYPE4@ FcBlanks * @ARG4@ blanks +@PURPOSE@ compute pattern from FT_Face +@DESC@ +Constructs a pattern representing 'face'. 'file' and 'id' are used solely as +data for pattern elements (FC_FILE, FC_INDEX and sometimes FC_FAMILY). +@@ diff --git a/fontconfig/doc/fcinit.fncs b/fontconfig/doc/fcinit.fncs new file mode 100644 index 000000000..e9b7947b8 --- /dev/null +++ b/fontconfig/doc/fcinit.fncs @@ -0,0 +1,92 @@ +/* + * fontconfig/doc/fcinit.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. + */ +@RET@ FcConfig * +@FUNC@ FcInitLoadConfig +@TYPE1@ void +@PURPOSE@ load configuration +@DESC@ +Loads the default configuration file and returns the resulting configuration. +Does not load any font information. +@@ + +@RET@ FcConfig * +@FUNC@ FcInitLoadConfigAndFonts +@TYPE1@ void +@PURPOSE@ load configuration and font data +@DESC@ +Loads the default configuration file and builds information about the +available fonts. Returns the resulting configuration. +@@ + +@RET@ FcBool +@FUNC@ FcInit +@TYPE1@ void +@PURPOSE@ initialize fontconfig library +@DESC@ +Loads the default configuration file and the fonts referenced therein and +sets the default configuration to that result. Returns whether this +process succeeded or not. If the default configuration has already +been loaded, this routine does nothing and returns FcTrue. +@@ + +@RET@ void +@FUNC@ FcFini +@TYPE1@ void +@PURPOSE@ finalize fonconfig library +@DESC@ +Frees all data structures allocated by previous calls to fontconfig +functions. Fontconfig returns to an uninitialized state, requiring a +new call to one of the FcInit functions before any other fontconfig +function may be called. +@@ + +@RET@ int +@FUNC@ FcGetVersion +@TYPE1@ void +@PURPOSE@ library version number +@DESC@ +Returns the version number of the library. +@@ + +@RET@ FcBool +@FUNC@ FcInitReinitialize +@TYPE1@ void +@PURPOSE@ re-initialize library +@DESC@ +Forces the default configuration file to be reloaded and resets the default +configuration. Returns FcFalse if the configuration cannot be reloaded (due +to config file errors, allocation failures or other issues) and leaves the +existing configuration unchanged. Otherwise returns FcTrue. +@@ + +@RET@ FcBool +@FUNC@ FcInitBringUptoDate +@TYPE1@ void +@PURPOSE@ reload configuration files if needed +@DESC@ +Checks the rescan interval in the default configuration, checking the +configuration if the interval has passed and reloading the configuration if +when any changes are detected. Returns FcFalse if the configuration cannot +be reloaded (see FcInitReinitialize). Otherwise returns FcTrue. +@@ diff --git a/fontconfig/doc/fclangset.fncs b/fontconfig/doc/fclangset.fncs new file mode 100644 index 000000000..f9d578e65 --- /dev/null +++ b/fontconfig/doc/fclangset.fncs @@ -0,0 +1,148 @@ +/* + * Copyright © 2007 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 copyright holders not be used in advertising or + * publicity pertaining to distribution of the software without specific, + * written prior permission. The copyright holders make no representations + * about the suitability of this software for any purpose. It is provided "as + * is" without express or implied warranty. + * + * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO + * EVENT SHALL THE COPYRIGHT HOLDERS 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@ FcLangSet * +@FUNC@ FcLangSetCreate +@TYPE1@ void +@PURPOSE@ create a langset object +@DESC@ +<function>FcLangSetCreate</function> creates a new FcLangSet object. +@@ + +@RET@ void +@FUNC@ FcLangSetDestroy +@TYPE1@ FcLangSet * @ARG1@ ls +@PURPOSE@ destroy a langset object +@DESC@ +<function>FcLangSetDestroy</function> destroys a FcLangSet object, freeing +all memory associated with it. +@@ + +@RET@ FcLangSet * +@FUNC@ FcLangSetCopy +@TYPE1@ const FcLangSet * @ARG1@ ls +@PURPOSE@ copy a langset object +@DESC@ +<function>FcLangSetCopy</function> creates a new FcLangSet object and +populates it with the contents of <parameter>ls</parameter>. +@@ + +@RET@ FcBool +@FUNC@ FcLangSetAdd +@TYPE1@ FcLangSet * @ARG1@ ls +@TYPE2@ const FcChar8 * @ARG2@ lang +@PURPOSE@ add a language to a langset +@DESC@ +<parameter>lang</parameter> is added to <parameter>ls</parameter>. +<parameter>lang</parameter> should be of the form Ll-Tt where Ll is a +two or three letter language from ISO 639 and Tt is a territory from ISO +3166. +@@ + +@RET@ FcLangResult +@FUNC@ FcLangSetCompare +@TYPE1@ const FcLangSet * @ARG1@ ls_a +@TYPE2@ const FcLangSet * @ARG2@ ls_b +@PURPOSE@ compare language sets +@DESC@ +<function>FcLangSetCompare</function> compares language coverage for +<parameter>ls_a</parameter> and <parameter>ls_b</parameter>. If they share +any language and territory pair, this function returns FcLangEqual. If they +share a language but differ in which territory that language is for, this +function returns FcLangDiffentTerritory. If they share no languages in +common, this function returns FcLangDifferentLang. +@@ + +@RET@ FcBool +@FUNC@ FcLangSetContains +@TYPE1@ const FcLangSet * @ARG1@ ls_a +@TYPE2@ const FcLangSet * @ARG2@ ls_b +@PURPOSE@ check langset subset relation +@DESC@ +<function>FcLangSetContains</function> returns FcTrue if +<parameter>ls_a</parameter> contains every language in +<parameter>ls_b</parameter>. <parameter>ls_a</parameter> will 'contain' a +language from <parameter>ls_b</parameter> if <parameter>ls_a</parameter> +has exactly the language, or either the language or +<parameter>ls_a</parameter> has no territory. +@@ + +@RET@ FcBool +@FUNC@ FcLangSetEqual +@TYPE1@ const FcLangSet * @ARG1@ ls_a +@TYPE2@ const FcLangSet * @ARG2@ ls_b +@PURPOSE@ test for matching langsets +@DESC@ +Returns FcTrue if and only if <parameter>ls_a</parameter> supports precisely +the same language and territory combinations as <parameter>ls_b</parameter>. +@@ + +@RET@ FcChar32 +@FUNC@ FcLangSetHash +@TYPE1@ const FcLangSet * @ARG1@ ls +@PURPOSE@ return a hash value for a langset +@DESC@ +This function returns a value which depends solely on the languages +supported by <parameter>ls</parameter>. Any language which equals +<parameter>ls</parameter> will have the same result from +<function>FcLangSetHash</function>. However, two langsets with the same hash +value may not be equal. +@@ + +@RET@ FcLangResult +@FUNC@ FcLangSetHasLang +@TYPE1@ const FcLangSet * @ARG1@ ls +@TYPE2@ const FcChar8 * @ARG2@ lang +@PURPOSE@ test langset for language support +@DESC@ +<function>FcLangSetHasLang</function> checks whether +<parameter>ls</parameter> supports <parameter>lang</parameter>. If +<parameter>ls</parameter> has a matching language and territory pair, +this function returns FcLangEqual. If <parameter>ls</parameter> has +a matching language but differs in which territory that language is for, this +function returns FcLangDiffentTerritory. If <parameter>ls</parameter> +has no matching language, this function returns FcLangDifferentLang. +@@ + +@RET@ FcStrSet * +@FUNC@ FcLangSetGetLangs +@TYPE1@ const FcLangSet * @ARG1@ ls +@PURPOSE@ get the list of languages in the langset +@DESC@ +Returns a string set of all languages in <parameter>langset</parameter>. +@@ + +@RET@ FcStrSet * +@FUNC@ FcGetLangs +@TYPE1@ void +@PURPOSE@ Get list of languages +@DESC@ +Returns a string set of all known languages. +@@ + +@RET@ const FcCharSet * +@FUNC@ FcLangGetCharSet +@TYPE1@ const FcChar8 * @ARG1@ lang +@PURPOSE@ Get character map for a language +@DESC@ +Returns the FcCharMap for a language. +@@ diff --git a/fontconfig/doc/fcmatrix.fncs b/fontconfig/doc/fcmatrix.fncs new file mode 100644 index 000000000..fd680e458 --- /dev/null +++ b/fontconfig/doc/fcmatrix.fncs @@ -0,0 +1,125 @@ +/* + * fontconfig/doc/fcmatrix.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. + */ + +@RET@ void +@FUNC@ FcMatrixInit +@PURPOSE@ initialize an FcMatrix structure +@TYPE1@ FcMatrix * +@ARG1@ matrix +@DESC@ +<function>FcMatrixInit</function> initializes <parameter>matrix</parameter> +to the identity matrix. +@@ + +@FUNC@ FcMatrixCopy +@PURPOSE@ Copy a matrix +@TYPE1@ const FcMatrix * +@ARG1@ matrix +@DESC@ +<function>FcMatrixCopy</function> allocates a new FcMatrix +and copies <parameter>mat</parameter> into it. +@@ + +@FUNC@ FcMatrixEqual +@PURPOSE@ Compare two matrices +@TYPE1@ const FcMatrix * +@ARG1@ matrix1 +@TYPE2@ const FcMatrix * +@ARG2@ matrix2 +@DESC@ +<function>FcMatrixEqual</function> compares <parameter>matrix1</parameter> +and <parameter>matrix2</parameter> returning FcTrue when they are equal and +FcFalse when they are not. +@@ + +@FUNC@ FcMatrixMultiply +@PURPOSE@ Multiply matrices +@TYPE1@ FcMatrix * +@ARG1@ result +@TYPE2@ const FcMatrix * +@ARG2@ matrix1 +@TYPE3@ const FcMatrix * +@ARG3@ matrix2 +@DESC@ +<function>FcMatrixMultiply</function> multiplies +<parameter>matrix1</parameter> and <parameter>matrix2</parameter> storing +the result in <parameter>result</parameter>. +@@ + +@FUNC@ FcMatrixRotate +@PURPOSE@ Rotate a matrix +@TYPE1@ FcMatrix * +@ARG1@ matrix +@TYPE2@ double% +@ARG2@ cos +@TYPE3@ double% +@ARG3@ sin +@DESC@ +<function>FcMatrixRotate</function> rotates <parameter>matrix</parameter> +by the angle who's sine is <parameter>sin</parameter> and cosine is +<parameter>cos</parameter>. This is done by multiplying by the +matrix: +<programlisting> + cos -sin + sin cos +</programlisting> +@@ + +@FUNC@ FcMatrixScale +@PURPOSE@ Scale a matrix +@TYPE1@ FcMatrix * +@ARG1@ matrix +@TYPE2@ double% +@ARG2@ sx +@TYPE3@ double% +@ARG3@ dy +@DESC@ +<function>FcMatrixScale</function> multiplies <parameter>matrix</parameter> +x values by <parameter>sx</parameter> and y values by +<parameter>sy</parameter>. This is done by multiplying by +the matrix: +<programlisting> + sx 0 + 0 sy +</programlisting> +@@ + +@FUNC@ FcMatrixShear +@PURPOSE@ Shear a matrix +@TYPE1@ FcMatrix * +@ARG1@ matrix +@TYPE2@ double% +@ARG2@ sh +@TYPE3@ double% +@ARG3@ sv +@DESC@ +<function>FcMatrixShare</function> shears <parameter>matrix</parameter> +horizontally by <parameter>sh</parameter> and vertically by +<parameter>sv</parameter>. This is done by multiplying by +the matrix: +<programlisting> + 1 sh + sv 1 +</programlisting> +@@ diff --git a/fontconfig/doc/fcobjectset.fncs b/fontconfig/doc/fcobjectset.fncs new file mode 100644 index 000000000..468a7bfc1 --- /dev/null +++ b/fontconfig/doc/fcobjectset.fncs @@ -0,0 +1,73 @@ +/* + * fontconfig/doc/fcobjectset.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. + */ +@RET@ FcObjectSet * +@FUNC@ FcObjectSetCreate +@TYPE1@ void +@PURPOSE@ Create an object set +@DESC@ +Creates an empty set. +@@ + +@RET@ FcBool +@FUNC@ FcObjectSetAdd +@TYPE1@ FcObjectSet * @ARG1@ os +@TYPE2@ const char * @ARG2@ object +@PURPOSE@ Add to an object set +@DESC@ +Adds a proprety name to the set. Returns FcFalse if the property name cannot be +inserted into the set (due to allocation failure). Otherwise returns FcTrue. +@@ + +@RET@ void +@FUNC@ FcObjectSetDestroy +@TYPE1@ FcObjectSet * @ARG1@ os +@PURPOSE@ Destroy an object set +@DESC@ +Destroys an object set. +@@ + +@RET@ FcObjectSet * +@FUNC@ FcObjectSetBuild +@TYPE1@ const char * @ARG1@ first +@TYPE2@ ... + +@PROTOTYPE+@ +@RET+@ FcObjectSet * +@FUNC+@ FcObjectSetVaBuild +@TYPE1+@ const char * @ARG1+@ first +@TYPE2+@ va_list% @ARG2+@ va + +@PROTOTYPE++@ +@RET++@ void +@FUNC++@ FcObjectSetVapBuild +@TYPE1++@ FcObjectSet * @ARG1++@ result +@TYPE2++@ const char * @ARG2++@ first +@TYPE3++@ va_list% @ARG3++@ va + +@PURPOSE@ Build object set from args +@DESC@ +These build an object set from a null-terminated list of property names. +FcObjectSetVapBuild is a macro version of FcObjectSetVaBuild which returns +the result in the <parameter>result</parameter> variable directly. +@@ diff --git a/fontconfig/doc/fcobjecttype.fncs b/fontconfig/doc/fcobjecttype.fncs new file mode 100644 index 000000000..bc254f3b9 --- /dev/null +++ b/fontconfig/doc/fcobjecttype.fncs @@ -0,0 +1,50 @@ +/* + * fontconfig/doc/fcobjecttype.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. + */ +@RET@ FcBool +@FUNC@ FcNameRegisterObjectTypes +@TYPE1@ const FcObjectType * @ARG1@ types +@TYPE2@ int% @ARG2@ ntype +@PURPOSE@ Register object types +@DESC@ +Register <parameter>ntype</parameter> new object types. Returns FcFalse if +some of the names cannot be +registered (due to allocation failure). Otherwise returns FcTrue. +@@ + +@RET@ FcBool +@FUNC@ FcNameUnregisterObjectTypes +@TYPE1@ const FcObjectType * @ARG1@ types +@TYPE2@ int% @ARG2@ ntype +@PURPOSE@ Unregister object types +@DESC@ +Unregister <parameter>ntype</parameter> object types. Returns FcTrue. +@@ + +@RET@ const FcObjectType * +@FUNC@ FcNameGetObjectType +@TYPE1@ const char * @ARG1@ object +@PURPOSE@ Lookup an object type +@DESC@ +Return the object type for the pattern element named <parameter>object</parameter>. +@@ diff --git a/fontconfig/doc/fcpattern.fncs b/fontconfig/doc/fcpattern.fncs new file mode 100644 index 000000000..e2c2953df --- /dev/null +++ b/fontconfig/doc/fcpattern.fncs @@ -0,0 +1,397 @@ +/* + * fontconfig/doc/fcpattern.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. + */ +@RET@ FcPattern * +@FUNC@ FcPatternCreate +@TYPE1@ void +@PURPOSE@ Create a pattern +@DESC@ +Creates a pattern with no properties; used to build patterns from scratch. +@@ + +@RET@ FcPattern * +@FUNC@ FcPatternDuplicate +@TYPE1@ const FcPattern * @ARG1@ p +@PURPOSE@ Copy a pattern +@DESC@ +Copy a pattern, returning a new pattern that matches +<parameter>p</parameter>. Each pattern may be modified without affecting the +other. +@@ + +@RET@ void +@FUNC@ FcPatternReference +@TYPE1@ FcPattern * @ARG1@ p +@PURPOSE@ Increment pattern reference count +@DESC@ +Add another reference to <parameter>p</parameter>. Patterns are freed only +when the reference count reaches zero. +@@ + +@RET@ void +@FUNC@ FcPatternDestroy +@TYPE1@ FcPattern * @ARG1@ p +@PURPOSE@ Destroy a pattern +@DESC@ +Decrement the pattern reference count. If all references are gone, destroys +the pattern, in the process destroying all related values. +@@ + +@RET@ FcBool +@FUNC@ FcPatternEqual +@TYPE1@ const FcPattern * @ARG1@ pa +@TYPE2@ const FcPattern * @ARG2@ pb +@PURPOSE@ Compare patterns +@DESC@ +Returns whether <parameter>pa</parameter> and <parameter>pb</parameter> are exactly alike. +@@ + +@RET@ FcBool +@FUNC@ FcPatternEqualSubset +@TYPE1@ const FcPattern * @ARG1@ pa +@TYPE2@ const FcPattern * @ARG2@ pb +@TYPE3@ const FcObjectSet * @ARG3@ os +@PURPOSE@ Compare portions of patterns +@DESC@ +Returns whether <parameter>pa</parameter> and <parameter>pb</parameter> have exactly the same values for all of the +objects in <parameter>os</parameter>. +@@ + +@RET@ FcPattern * +@FUNC@ FcPatternFilter +@TYPE1@ FcPattern * @ARG1@ p +@TYPE2@ const FcObjectSet * @ARG1@ os +@PURPOSE@ Filter the objects of pattern +@DESC@ +Returns a new pattern that only has those objects from +<parameter>p</parameter> that are in <parameter>os</parameter>. +If <parameter>os</parameter> is NULL, a duplicate of +<parameter>p</parameter> is returned. +@@ + +@RET@ FcChar32 +@FUNC@ FcPatternHash +@TYPE1@ const FcPattern * @ARG1@ p +@PURPOSE@ Compute a pattern hash value +@DESC@ +Returns a 32-bit number which is the same for any two patterns which are +equal. +@@ + +@RET@ FcBool +@FUNC@ FcPatternAdd +@TYPE1@ FcPattern * @ARG1@ p +@TYPE2@ const char * @ARG2@ object +@TYPE3@ FcValue% @ARG3@ value +@TYPE4@ FcBool% @ARG4@ append +@PURPOSE@ Add a value to a pattern +@DESC@ +Adds a single value to the list of values associated with the property named +`object<parameter>. If `append</parameter> is FcTrue, the value is added at the end of any +existing list, otherwise it is inserted at the begining. `value' is saved +(with FcValueSave) when inserted into the pattern so that the library +retains no reference to any application-supplied data structure. +@@ + +@RET@ FcBool +@FUNC@ FcPatternAddWeak +@TYPE1@ FcPattern * @ARG1@ p +@TYPE2@ const char * @ARG2@ object +@TYPE3@ FcValue% @ARG3@ value +@TYPE4@ FcBool% @ARG4@ append +@PURPOSE@ Add a value to a pattern with weak binding +@DESC@ +FcPatternAddWeak is essentially the same as FcPatternAdd except that any +values added to the list have binding <parameter>weak</parameter> instead of <parameter>strong</parameter>. +@@ + +@TITLE@ FcPatternAdd-Type +@RET@ FcBool +@FUNC@ FcPatternAddInteger +@TYPE1@ FcPattern * @ARG1@ p +@TYPE2@ const char * @ARG2@ object +@TYPE3@ int% @ARG3@ i + +@PROTOTYPE+@ +@RET+@ FcBool +@FUNC+@ FcPatternAddDouble +@TYPE1+@ FcPattern * @ARG1+@ p +@TYPE2+@ const char * @ARG2+@ object +@TYPE3+@ double% @ARG3+@ d + +@PROTOTYPE++@ +@RET++@ FcBool +@FUNC++@ FcPatternAddString +@TYPE1++@ FcPattern * @ARG1++@ p +@TYPE2++@ const char * @ARG2++@ object +@TYPE3++@ const FcChar8 * @ARG3++@ s + +@PROTOTYPE+++@ +@RET+++@ FcBool +@FUNC+++@ FcPatternAddMatrix +@TYPE1+++@ FcPattern * @ARG1+++@ p +@TYPE2+++@ const char * @ARG2+++@ object +@TYPE3+++@ const FcMatrix * @ARG3+++@ m + +@PROTOTYPE++++@ +@RET++++@ FcBool +@FUNC++++@ FcPatternAddCharSet +@TYPE1++++@ FcPattern * @ARG1++++@ p +@TYPE2++++@ const char * @ARG2++++@ object +@TYPE3++++@ const FcCharSet * @ARG3++++@ c + +@PROTOTYPE+++++@ +@RET+++++@ FcBool +@FUNC+++++@ FcPatternAddBool +@TYPE1+++++@ FcPattern * @ARG1+++++@ p +@TYPE2+++++@ const char * @ARG2+++++@ object +@TYPE3+++++@ FcBool% @ARG3+++++@ b + +@PROTOTYPE++++++@ +@RET++++++@ FcBool +@FUNC++++++@ FcPatternAddFTFace +@TYPE1++++++@ FcPattern * @ARG1++++++@ p +@TYPE2++++++@ const char * @ARG2++++++@ object +@TYPE3++++++@ const FT_Face @ARG3++++++@ f + +@PROTOTYPE+++++++@ +@RET+++++++@ FcBool +@FUNC+++++++@ FcPatternAddLangSet +@TYPE1+++++++@ FcPattern * @ARG1+++++++@ p +@TYPE2+++++++@ const char * @ARG2+++++++@ object +@TYPE3+++++++@ const FcLangSet * @ARG3+++++++@ l + +@PURPOSE@ Add a typed value to a pattern +@DESC@ +These are all convenience functions that insert objects of the specified +type into the pattern. Use these in preference to FcPatternAdd as they +will provide compile-time typechecking. These all append values to +any existing list of values. +@@ + +@RET@ FcResult +@FUNC@ FcPatternGet +@TYPE1@ FcPattern * @ARG1@ p +@TYPE2@ const char * @ARG2@ object +@TYPE3@ int% @ARG3@ id +@TYPE4@ FcValue * @ARG4@ v +@PURPOSE@ Return a value from a pattern +@DESC@ +Returns in <parameter>v</parameter> the <parameter>id</parameter>'th value +associated with the property <parameter>object</parameter>. +The value returned is not a copy, but rather refers to the data stored +within the pattern directly. Applications must not free this value. +@@ + +@TITLE@ FcPatternGet-Type +@PROTOTYPE@ +@RET@ FcResult +@FUNC@ FcPatternGetInteger +@TYPE1@ FcPattern * @ARG1@ p +@TYPE2@ const char * @ARG2@ object +@TYPE3@ int% @ARG3@ n +@TYPE4@ int * @ARG4@ i + +@PROTOTYPE+@ +@RET+@ FcResult +@FUNC+@ FcPatternGetDouble +@TYPE1+@ FcPattern * @ARG1+@ p +@TYPE2+@ const char * @ARG2+@ object +@TYPE3+@ int% @ARG3+@ n +@TYPE4+@ double * @ARG4+@ d + +@PROTOTYPE++@ +@RET++@ FcResult +@FUNC++@ FcPatternGetString +@TYPE1++@ FcPattern * @ARG1++@ p +@TYPE2++@ const char * @ARG2++@ object +@TYPE3++@ int% @ARG3++@ n +@TYPE4++@ FcChar8 ** @ARG4++@ s + +@PROTOTYPE+++@ +@RET+++@ FcResult +@FUNC+++@ FcPatternGetMatrix +@TYPE1+++@ FcPattern * @ARG1+++@ p +@TYPE2+++@ const char * @ARG2+++@ object +@TYPE3+++@ int% @ARG3+++@ n +@TYPE4+++@ FcMatrix ** @ARG4+++@ s + +@PROTOTYPE++++@ +@RET++++@ FcResult +@FUNC++++@ FcPatternGetCharSet +@TYPE1++++@ FcPattern * @ARG1++++@ p +@TYPE2++++@ const char * @ARG2++++@ object +@TYPE3++++@ int% @ARG3++++@ n +@TYPE4++++@ FcCharSet ** @ARG4++++@ c + +@PROTOTYPE+++++@ +@RET+++++@ FcResult +@FUNC+++++@ FcPatternGetBool +@TYPE1+++++@ FcPattern * @ARG1+++++@ p +@TYPE2+++++@ const char * @ARG2+++++@ object +@TYPE3+++++@ int% @ARG3+++++@ n +@TYPE4+++++@ FcBool * @ARG4+++++@ b + +@PROTOTYPE++++++@ +@RET++++++@ FcResult +@FUNC++++++@ FcPatternGetFTFace +@TYPE1++++++@ FcPattern * @ARG1++++++@ p +@TYPE2++++++@ const char * @ARG2++++++@ object +@TYPE3+++++@ int% @ARG3+++++@ n +@TYPE3++++++@ FT_Face * @ARG3++++++@ f + +@PROTOTYPE+++++++@ +@RET+++++++@ FcResult +@FUNC+++++++@ FcPatternGetLangSet +@TYPE1+++++++@ FcPattern * @ARG1+++++++@ p +@TYPE2+++++++@ const char * @ARG2+++++++@ object +@TYPE3+++++@ int% @ARG3+++++@ n +@TYPE3+++++++@ FcLangSet ** @ARG3+++++++@ l + +@PURPOSE@ Return a typed value from a pattern +@DESC@ +These are convenience functions that call FcPatternGet and verify that the +returned data is of the expected type. They return FcResultTypeMismatch if +this is not the case. Note that these (like FcPatternGet) do not make a +copy of any data structure referenced by the return value. Use these +in preference to FcPatternGet to provide compile-time typechecking. +@@ + +@RET@ FcPattern * +@FUNC@ FcPatternBuild +@TYPE1@ FcPattern * @ARG1@ pattern +@TYPE2@ ... + +@PROTOTYPE+@ +@RET+@ FcPattern * +@FUNC+@ FcPatternVaBuild +@TYPE1+@ FcPattern * @ARG1+@ pattern +@TYPE2+@ va_list% @ARG2+@ va + +@PROTOTYPE++@ +@RET++@ void +@FUNC++@ FcPatternVapBuild +@TYPE1++@ FcPattern * @ARG1++@ result +@TYPE2++@ FcPattern * @ARG2++@ pattern +@TYPE3++@ va_list% @ARG3++@ va + +@PURPOSE@ Create patterns from arguments +@DESC@ +Builds a pattern using a list of objects, types and values. Each +value to be entered in the pattern is specified with three arguments: +</para> +<orderedlist> +<listitem><para> +Object name, a string describing the property to be added. +</para></listitem><listitem><para> +Object type, one of the FcType enumerated values +</para></listitem><listitem><para> +Value, not an FcValue, but the raw type as passed to any of the +FcPatternAdd<type> functions. Must match the type of the second +argument. +</para></listitem> +</orderedlist> +<para> +The argument list is terminated by a null object name, no object type nor +value need be passed for this. The values are added to `pattern', if +`pattern' is null, a new pattern is created. In either case, the pattern is +returned. Example +</para> +<programlisting> +pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *) 0); +</programlisting> +<para> +FcPatternVaBuild is used when the arguments are already in the form of a +varargs value. FcPatternVapBuild is a macro version of FcPatternVaBuild +which returns its result directly in the <parameter>result</parameter> +variable. +@@ + +@RET@ FcBool +@FUNC@ FcPatternDel +@TYPE1@ FcPattern * @ARG1@ p +@TYPE2@ const char * @ARG2@ object +@PURPOSE@ Delete a property from a pattern +@DESC@ +Deletes all values associated with the property `object', returning +whether the property existed or not. +@@ + +@RET@ FcBool +@FUNC@ FcPatternRemove +@TYPE1@ FcPattern * @ARG1@ p +@TYPE2@ const char * @ARG2@ object +@TYPE3@ int% @ARG3@ id +@PURPOSE@ Remove one object of the specified type from the pattern +@DESC@ +Removes the value associated with the property `object' at position `id', returning +whether the property existed and had a value at that position or not. +@@ + +@RET@ void +@FUNC@ FcPatternPrint +@TYPE1@ const FcPattern * @ARG1@ p +@PURPOSE@ Print a pattern for debugging +@DESC@ +Prints an easily readable version of the pattern to stdout. There is +no provision for reparsing data in this format, it's just for diagnostics +and debugging. +@@ + +@RET@ void +@FUNC@ FcDefaultSubstitute +@TYPE1@ FcPattern * @ARG1@ pattern +@PURPOSE@ Perform default substitutions in a pattern +@DESC@ +Supplies default values for underspecified font patterns: +<itemizedlist> +<listitem><para> +Patterns without a specified style or weight are set to Medium +</para></listitem> +<listitem><para> +Patterns without a specified style or slant are set to Roman +</para></listitem> +<listitem><para> +Patterns without a specified pixel size are given one computed from any +specified point size (default 12), dpi (default 75) and scale (default 1). +</para></listitem> +</itemizedlist> +@@ + +@RET@ FcPattern * +@FUNC@ FcNameParse +@TYPE1@ const FcChar8 * @ARG1@ name +@PURPOSE@ Parse a pattern string +@DESC@ +Converts <parameter>name</parameter> from the standard text format described above into a pattern. +@@ + +@RET@ FcChar8 * +@FUNC@ FcNameUnparse +@TYPE1@ FcPattern * @ARG1@ pat +@PURPOSE@ Convert a pattern back into a string that can be parsed +@DESC@ +Converts the given pattern into the standard text format described above. +The return value is not static, but instead refers to newly allocated memory +which should be freed by the caller using free(). +@@ diff --git a/fontconfig/doc/fcstring.fncs b/fontconfig/doc/fcstring.fncs new file mode 100644 index 000000000..5f1f93ac1 --- /dev/null +++ b/fontconfig/doc/fcstring.fncs @@ -0,0 +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 <0, 0, >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 <0, 0, >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. +@@ diff --git a/fontconfig/doc/fcstrset.fncs b/fontconfig/doc/fcstrset.fncs new file mode 100644 index 000000000..61af37b63 --- /dev/null +++ b/fontconfig/doc/fcstrset.fncs @@ -0,0 +1,115 @@ +/* + * fontconfig/doc/fcstrset.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@ FcStrSet * +@FUNC@ FcStrSetCreate +@TYPE1@ void +@PURPOSE@ create a string set +@DESC@ +Create an empty set. +@@ + +@RET@ FcBool +@FUNC@ FcStrSetMember +@TYPE1@ FcStrSet * @ARG1@ set +@TYPE2@ const FcChar8 * @ARG2@ s +@PURPOSE@ check set for membership +@DESC@ +Returns whether <parameter>s</parameter> is a member of +<parameter>set</parameter>. +@@ + +@RET@ FcBool +@FUNC@ FcStrSetEqual +@TYPE1@ FcStrSet * @ARG1@ set_a +@TYPE2@ FcStrSet * @ARG2@ set_b +@PURPOSE@ check sets for equality +@DESC@ +Returns whether <parameter>set_a</parameter> contains precisely the same +strings as <parameter>set_b</parameter>. Ordering of strings within the two +sets is not considered. +@@ + +@RET@ FcBool +@FUNC@ FcStrSetAdd +@TYPE1@ FcStrSet * @ARG1@ set +@TYPE2@ const FcChar8 * @ARG2@ s +@PURPOSE@ add to a string set +@DESC@ +Adds a copy of <parameter>s</parameter> to <parameter>set</parameter>. +@@ + +@RET@ FcBool +@FUNC@ FcStrSetAddFilename +@TYPE1@ FcStrSet * @ARG1@ set +@TYPE2@ const FcChar8 * @ARG2@ s +@PURPOSE@ add a filename to a string set +@DESC@ +Adds a copy <parameter>s</parameter> to <parameter>set</parameter>, The copy +is created with FcStrCopyFilename so that leading '~' values are replaced +with the value of the HOME environment variable. +@@ + +@RET@ FcBool +@FUNC@ FcStrSetDel +@TYPE1@ FcStrSet * @ARG1@ set +@TYPE2@ const FcChar8 * @ARG2@ s +@PURPOSE@ delete from a string set +@DESC@ +Removes <parameter>s</parameter> from <parameter>set</parameter>, returning +FcTrue if <parameter>s</parameter> was a member else FcFalse. +@@ + +@RET@ void +@FUNC@ FcStrSetDestroy +@TYPE1@ FcStrSet * @ARG1@ set +@PURPOSE@ destroy a string set +@DESC@ +Destroys <parameter>set</parameter>. +@@ + +@RET@ FcStrList * +@FUNC@ FcStrListCreate +@TYPE1@ FcStrSet * @ARG1@ set +@PURPOSE@ create a string iterator +@DESC@ +Creates an iterator to list the strings in <parameter>set</parameter>. +@@ + +@RET@ FcChar8 * +@FUNC@ FcStrListNext +@TYPE1@ FcStrList * @ARG1@ list +@PURPOSE@ get next string in iteration +@DESC@ +Returns the next string in <parameter>set</parameter>. +@@ + +@RET@ void +@FUNC@ FcStrListDone +@TYPE1@ FcStrList * @ARG1@ list +@PURPOSE@ destroy a string iterator +@DESC@ +Destroys the enumerator <parameter>list</parameter>. +@@ diff --git a/fontconfig/doc/fcvalue.fncs b/fontconfig/doc/fcvalue.fncs new file mode 100644 index 000000000..d0c669b1f --- /dev/null +++ b/fontconfig/doc/fcvalue.fncs @@ -0,0 +1,61 @@ +/* + * fontconfig/doc/fcvalue.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. + */ +@RET@ void +@FUNC@ FcValueDestroy +@TYPE1@ FcValue% @ARG1@ v +@PURPOSE@ Free a value +@DESC@ +Frees any memory referenced by <parameter>v</parameter>. Values of type FcTypeString, +FcTypeMatrix and FcTypeCharSet reference memory, the other types do not. +@@ + +@RET@ FcValue +@FUNC@ FcValueSave +@TYPE1@ FcValue% @ARG1@ v +@PURPOSE@ Copy a value +@DESC@ +Returns a copy of <parameter>v</parameter> duplicating any object referenced by it so that <parameter>v</parameter> +may be safely destroyed without harming the new value. +@@ + +@RET@ void +@FUNC@ FcValuePrint +@TYPE1@ FcValue% @ARG1@ v +@PURPOSE@ Print a value to stdout +@DESC@ +Prints a human-readable representation of <parameter>v</parameter> to +stdout. The format should not be considered part of the library +specification as it may change in the future. +@@ + +@RET@ FcBool +@FUNC@ FcValueEqual +@TYPE1@ FcValue% @ARG1@ v_a +@TYPE2@ FcValue% @ARG2@ v_b +@PURPOSE@ Test two values for equality +@DESC@ +Compares two values. Integers and Doubles are compared as numbers; otherwise +the two values have to be the same type to be considered equal. Strings are +compared ignoring case. +@@ diff --git a/fontconfig/doc/fontconfig-devel.sgml b/fontconfig/doc/fontconfig-devel.sgml new file mode 100644 index 000000000..891251f30 --- /dev/null +++ b/fontconfig/doc/fontconfig-devel.sgml @@ -0,0 +1,573 @@ +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ +<!ENTITY fcatomic SYSTEM "fcatomic.sgml"> +<!ENTITY fcblanks SYSTEM "fcblanks.sgml"> +<!ENTITY fccache SYSTEM "fccache.sgml"> +<!ENTITY fccharset SYSTEM "fccharset.sgml"> +<!ENTITY fcconfig SYSTEM "fcconfig.sgml"> +<!ENTITY fcconstant SYSTEM "fcconstant.sgml"> +<!ENTITY fcdircache SYSTEM "fcdircache.sgml"> +<!ENTITY fcfile SYSTEM "fcfile.sgml"> +<!ENTITY fcfontset SYSTEM "fcfontset.sgml"> +<!ENTITY fcformat SYSTEM "fcformat.sgml"> +<!ENTITY fcfreetype SYSTEM "fcfreetype.sgml"> +<!ENTITY fcinit SYSTEM "fcinit.sgml"> +<!ENTITY fclangset SYSTEM "fclangset.sgml"> +<!ENTITY fcmatrix SYSTEM "fcmatrix.sgml"> +<!ENTITY fcobjectset SYSTEM "fcobjectset.sgml"> +<!ENTITY fcobjecttype SYSTEM "fcobjecttype.sgml"> +<!ENTITY fcpattern SYSTEM "fcpattern.sgml"> +<!ENTITY fcstring SYSTEM "fcstring.sgml"> +<!ENTITY fcstrset SYSTEM "fcstrset.sgml"> +<!ENTITY fcvalue SYSTEM "fcvalue.sgml"> +<!ENTITY version SYSTEM "version.sgml"> +]> +<!-- + fontconfig/doc/local-fontconfig-devel.sgml + + 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. +--> +<article> + <title>Fontconfig Developers Reference, Version &version; </title> + <artheader> + <author> + <firstname>Keith</firstname> + <surname>Packard</surname> + <affiliation><orgname> + HP Cambridge Research Lab + </orgname></affiliation> + </author> + <authorinitials>KRP</authorinitials> + <productname>Fontconfig</productname> + <productnumber>&version;</productnumber> + <LegalNotice> + <simpara> +Copyright © 2002 Keith Packard + </simpara><simpara> +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. + </simpara><simpara> +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. + </simpara> + </LegalNotice> + </artheader> +<sect1><title>DESCRIPTION</title> + <para> +Fontconfig is a library designed to provide system-wide font configuration, +customization and application access. + </para> +</sect1> +<sect1><title>FUNCTIONAL OVERVIEW</title> + <para> +Fontconfig contains two essential modules, the configuration module which +builds an internal configuration from XML files and the matching module +which accepts font patterns and returns the nearest matching font. + </para> + <sect2><title>FONT CONFIGURATION</title> + <para> +The configuration module consists of the FcConfig datatype, libexpat and +FcConfigParse which walks over an XML tree and ammends a configuration with +data found within. From an external perspective, configuration of the +library consists of generating a valid XML tree and feeding that to +FcConfigParse. The only other mechanism provided to applications for +changing the running configuration is to add fonts and directories to the +list of application-provided font files. + </para><para> +The intent is to make font configurations relatively static, and shared by +as many applications as possible. It is hoped that this will lead to more +stable font selection when passing names from one application to another. +XML was chosen as a configuration file format because it provides a format +which is easy for external agents to edit while retaining the correct +structure and syntax. + </para><para> +Font configuration is separate from font matching; applications needing to +do their own matching can access the available fonts from the library and +perform private matching. The intent is to permit applications to pick and +choose appropriate functionality from the library instead of forcing them to +choose between this library and a private configuration mechanism. The hope +is that this will ensure that configuration of fonts for all applications +can be centralized in one place. Centralizing font configuration will +simplify and regularize font installation and customization. + </para> + </sect2> + <sect2> + <title>FONT PROPERTIES</title> + <para> +While font patterns may contain essentially any properties, there are some +well known properties with associated types. Fontconfig uses some of these +properties for font matching and font completion. Others are provided as a +convenience for the applications rendering mechanism. + </para> + <programlisting> + Property Definitions + + Property CPP Symbol Type Description + ---------------------------------------------------- + family FC_FAMILY String Font family names + familylang FC_FAMILYLANG String Language cooresponding to + each family name + style FC_STYLE String Font style. Overrides weight + and slant + stylelang FC_STYLELANG String Language cooresponding to + each style name + fullname FC_FULLNAME String Font face full name where + different from family and + family + style + fullnamelang FC_FULLNAMELANG String Language cooresponding to + each fullname + slant FC_SLANT Int Italic, oblique or roman + weight FC_WEIGHT Int Light, medium, demibold, + bold or black + size FC_SIZE Double Point size + width FC_WIDTH Int Condensed, normal or expanded + aspect FC_ASPECT Double Stretches glyphs horizontally + before hinting + pixelsize FC_PIXEL_SIZE Double Pixel size + spacing FC_SPACING Int Proportional, dual-width, + monospace or charcell + foundry FC_FOUNDRY String Font foundry name + antialias FC_ANTIALIAS Bool Whether glyphs can be + antialiased + hinting FC_HINTING Bool Whether the rasterizer should + use hinting + hintstyle FC_HINT_STYLE Int Automatic hinting style + verticallayout FC_VERTICAL_LAYOUT Bool Use vertical layout + autohint FC_AUTOHINT Bool Use autohinter instead of + normal hinter + globaladvance FC_GLOBAL_ADVANCE Bool Use font global advance data + file FC_FILE String The filename holding the font + index FC_INDEX Int The index of the font within + the file + ftface FC_FT_FACE FT_Face Use the specified FreeType + face object + rasterizer FC_RASTERIZER String Which rasterizer is in use + outline FC_OUTLINE Bool Whether the glyphs are outlines + scalable FC_SCALABLE Bool Whether glyphs can be scaled + scale FC_SCALE Double Scale factor for point->pixel + conversions + dpi FC_DPI Double Target dots per inch + rgba FC_RGBA Int unknown, rgb, bgr, vrgb, + vbgr, none - subpixel geometry + lcdfilter FC_LCD_FILTER Int Type of LCD filter + minspace FC_MINSPACE Bool Eliminate leading from line + spacing + charset FC_CHARSET CharSet Unicode chars encoded by + the font + lang FC_LANG LangSet Set of RFC-3066-style + languages this font supports + fontversion FC_FONTVERSION Int Version number of the font + capability FC_CAPABILITY String List of layout capabilities in + the font + embolden FC_EMBOLDEN Bool Rasterizer should + synthetically embolden the font + </programlisting> + </sect2> +</sect1> +<sect1><title>Datatypes</title> + <para> +Fontconfig uses abstract datatypes to hide internal implementation details +for most data structures. A few structures are exposed where appropriate. + </para> + <sect2><title>FcChar8, FcChar16, FcChar32, FcBool</title> + <para> +These are primitive datatypes; the FcChar* types hold precisely the number +of bits stated (if supported by the C implementation). FcBool holds +one of two CPP symbols: FcFalse or FcTrue. + </para> + </sect2> + <sect2><title>FcMatrix</title> + <para> +An FcMatrix holds an affine transformation, usually used to reshape glyphs. +A small set of matrix operations are provided to manipulate these. + <programlisting> + typedef struct _FcMatrix { + double xx, xy, yx, yy; + } FcMatrix; + </programlisting> + </para> + </sect2> + <sect2><title>FcCharSet</title> + <para> +An FcCharSet is an abstract type that holds the set of encoded unicode chars +in a font. Operations to build and compare these sets are provided. + </para> + </sect2> + <sect2><title>FcLangSet</title> + <para> +An FcLangSet is an abstract type that holds the set of languages supported +by a font. Operations to build and compare these sets are provided. These +are computed for a font based on orthographic information built into the +fontconfig library. Fontconfig has orthographies for all of the ISO 639-1 +languages except for MS, NA, PA, PS, QU, RN, RW, SD, SG, SN, SU and ZA. If +you have orthographic information for any of these languages, please submit +them. + </para> + </sect2> + <sect2><title>FcLangResult</title> + <para> +An FcLangResult is an enumeration used to return the results of comparing +two language strings or FcLangSet objects. FcLangEqual means the +objects match language and territory. FcLangDifferentTerritory means +the objects match in language but differ in territory. +FcLangDifferentLang means the objects differ in language. + </para> + </sect2> + <sect2><title>FcType</title> + <para> +Tags the kind of data stored in an FcValue. + </para> + </sect2> + <sect2><title>FcValue</title> + <para> +An FcValue object holds a single value with one of a number of different +types. The 'type' tag indicates which member is valid. + <programlisting> + typedef struct _FcValue { + FcType type; + union { + const FcChar8 *s; + int i; + FcBool b; + double d; + const FcMatrix *m; + const FcCharSet *c; + void *f; + const FcLangSet *l; + } u; + } FcValue; + </programlisting> + <programlisting> + FcValue Members + + Type Union member Datatype + -------------------------------- + FcTypeVoid (none) (none) + FcTypeInteger i int + FcTypeDouble d double + FcTypeString s FcChar8 * + FcTypeBool b b + FcTypeMatrix m FcMatrix * + FcTypeCharSet c FcCharSet * + FcTypeFTFace f void * (FT_Face) + FcTypeLangSet l FcLangSet * + </programlisting> + </para> + </sect2> + <sect2><title>FcPattern</title> + <para> +holds a set of names with associated value lists; each name refers to a +property of a font. FcPatterns are used as inputs to the matching code as +well as holding information about specific fonts. Each property can hold +one or more values; conventionally all of the same type, although the +interface doesn't demand that. + </para> + </sect2> + <sect2><title>FcFontSet</title> + <para> + <programlisting> + typedef struct _FcFontSet { + int nfont; + int sfont; + FcPattern **fonts; + } FcFontSet; + </programlisting> +An FcFontSet contains a list of FcPatterns. Internally fontconfig uses this +data structure to hold sets of fonts. Externally, fontconfig returns the +results of listing fonts in this format. 'nfont' holds the number of +patterns in the 'fonts' array; 'sfont' is used to indicate the size of that +array. + </para> + </sect2> + <sect2><title>FcStrSet, FcStrList</title> + <para> +FcStrSet holds a list of strings that can be appended to and enumerated. +Its unique characteristic is that the enumeration works even while strings +are appended during enumeration. FcStrList is used during enumeration to +safely and correctly walk the list of strings even while that list is edited +in the middle of enumeration. + </para> + </sect2> + <sect2><title>FcObjectSet</title> + <para> + <programlisting> + typedef struct _FcObjectSet { + int nobject; + int sobject; + const char **objects; + } FcObjectSet; + </programlisting> +holds a set of names and is used to specify which fields from fonts are +placed in the the list of returned patterns when listing fonts. + </para> + </sect2> + <sect2><title>FcObjectType</title> + <para> + <programlisting> + typedef struct _FcObjectType { + const char *object; + FcType type; + } FcObjectType; + </programlisting> +marks the type of a pattern element generated when parsing font names. +Applications can add new object types so that font names may contain the new +elements. + </para> + </sect2> + <sect2><title>FcConstant</title> + <para> + <programlisting> + typedef struct _FcConstant { + const FcChar8 *name; + const char *object; + int value; + } FcConstant; + </programlisting> +Provides for symbolic constants for new pattern elements. When 'name' is +seen in a font name, an 'object' element is created with value 'value'. + </para> + </sect2> + <sect2><title>FcBlanks</title> + <para> +holds a list of Unicode chars which are expected to be blank; unexpectedly +blank chars are assumed to be invalid and are elided from the charset +associated with the font. + </para> + </sect2> + <sect2><title>FcFileCache</title> + <para> +holds the per-user cache information for use while loading the font +database. This is built automatically for the current configuration when +that is loaded. Applications must always pass '0' when one is requested. + </para> + </sect2> + <sect2><title>FcConfig</title> + <para> +holds a complete configuration of the library; there is one default +configuration, other can be constructed from XML data structures. All +public entry points that need global data can take an optional FcConfig* +argument; passing 0 uses the default configuration. FcConfig objects hold two +sets of fonts, the first contains those specified by the configuration, the +second set holds those added by the application at run-time. Interfaces +that need to reference a particulat set use one of the FcSetName enumerated +values. + </para> + </sect2> + <sect2><title>FcSetName</title> + <para> +Specifies one of the two sets of fonts available in a configuration; +FcSetSystem for those fonts specified in the configuration and +FcSetApplication which holds fonts provided by the application. + </para> + </sect2> + <sect2><title>FcResult</title> + <para> +Used as a return type for functions manipulating FcPattern objects. + <programlisting> + FcResult Values + Result Code Meaning + ----------------------------------------------------------- + FcResultMatch Object exists with the specified ID + FcResultNoMatch Object doesn't exist at all + FcResultTypeMismatch Object exists, but the type doesn't match + FcResultNoId Object exists, but has fewer values + than specified + FcResultOutOfMemory Malloc failed + </programlisting> + </para> + </sect2> + <sect2><title>FcAtomic</title> + <para> +Used for locking access to config files. Provides a safe way to update +configuration files. + </para> + </sect2> + <sect2><title>FcCache</title> + <para> +Holds information about the fonts contained in a single directory. Normal +applications need not worry about this as caches for font access are +automatically managed by the library. Applications dealing with cache +management may want to use some of these objects in their work, however the +included 'fc-cache' program generally suffices for all of that. + </para> + </sect2> +</sect1> +<sect1><title>FUNCTIONS</title> + <para> +These are grouped by functionality, often using the main datatype being +manipulated. + </para> + <sect2><title>Initialization</title> + <para> +These functions provide some control over how the library is initialized. + </para> + &fcinit; + </sect2> + <sect2><title>FcPattern</title> + <para> +An FcPattern is an opaque type that holds both patterns to match against the +available fonts, as well as the information about each font. + </para> + &fcpattern; + &fcformat; + </sect2> + <sect2><title>FcFontSet</title> + <para> +An FcFontSet simply holds a list of patterns; these are used to return the +results of listing available fonts. + </para> + &fcfontset; + </sect2> + <sect2><title>FcObjectSet</title> + <para> +An FcObjectSet holds a list of pattern property names; it is used to +indiciate which properties are to be returned in the patterns from +FcFontList. + </para> + &fcobjectset; + </sect2> + <sect2><title>FreeType specific functions</title> + <para> +While the fontconfig library doesn't insist that FreeType be used as the +rasterization mechanism for fonts, it does provide some convenience +functions. + </para> + &fcfreetype; + </sect2> + <sect2><title>FcValue</title> + <para> +FcValue is a structure containing a type tag and a union of all possible +datatypes. The tag is an enum of type +<emphasis>FcType</emphasis> +and is intended to provide a measure of run-time +typechecking, although that depends on careful programming. + </para> + &fcvalue; + </sect2> + <sect2><title>FcCharSet</title> + <para> +An FcCharSet is a boolean array indicating a set of unicode chars. Those +associated with a font are marked constant and cannot be edited. +FcCharSets may be reference counted internally to reduce memory consumption; +this may be visible to applications as the result of FcCharSetCopy may +return it's argument, and that CharSet may remain unmodifiable. + </para> + &fccharset; + </sect2> + <sect2><title>FcLangSet</title> + <para> +An FcLangSet is a set of language names (each of which include language and +an optional territory). They are used when selecting fonts to indicate which +languages the fonts need to support. Each font is marked, using language +orthography information built into fontconfig, with the set of supported +languages. + </para> + &fclangset; + </sect2> + <sect2><title>FcMatrix</title> + <para> +FcMatrix structures hold an affine transformation in matrix form. + </para> + &fcmatrix; + </sect2> + <sect2><title>FcConfig</title> + <para> +An FcConfig object holds the internal representation of a configuration. +There is a default configuration which applications may use by passing 0 to +any function using the data within an FcConfig. + </para> + &fcconfig; + </sect2> + <sect2><title>FcObjectType</title> + <para> +Provides for applcation-specified font name object types so that new +pattern elements can be generated from font names. + </para> + &fcobjecttype; + </sect2> + <sect2><title>FcConstant</title> + <para> +Provides for application-specified symbolic constants for font names. + </para> + &fcconstant; + </sect2> + <sect2><title>FcBlanks</title> + <para> +An FcBlanks object holds a list of Unicode chars which are expected to +be blank when drawn. When scanning new fonts, any glyphs which are +empty and not in this list will be assumed to be broken and not placed in +the FcCharSet associated with the font. This provides a significantly more +accurate CharSet for applications. + </para> + &fcblanks; + </sect2> + <sect2><title>FcAtomic</title> + <para> +These functions provide a safe way to update config files, allowing ongoing +reading of the old config file while locked for writing and ensuring that a +consistent and complete version of the config file is always available. + </para> + &fcatomic; + </sect2> + <sect2><title>File and Directory routines</title> + <para> +These routines work with font files and directories, including font +directory cache files. + </para> + &fcfile; + &fcdircache; + </sect2> + <sect2><title>FcCache routines</title> + <para> +These routines work with font directory caches, accessing their contents in +limited ways. It is not expected that normal applications will need to use +these functions. + </para> + &fccache; + </sect2> + <sect2><title>FcStrSet and FcStrList</title> + <para> +A data structure for enumerating strings, used to list directories while +scanning the configuration as directories are added while scanning. + </para> + &fcstrset; + </sect2> + <sect2><title>String utilities</title> + <para> +Fontconfig manipulates many UTF-8 strings represented with the FcChar8 type. +These functions are exposed to help applications deal with these UTF-8 +strings in a locale-insensitive manner. + </para> + &fcstring; + </sect2> +</sect1> +</article> diff --git a/fontconfig/doc/fontconfig-user.sgml b/fontconfig/doc/fontconfig-user.sgml new file mode 100644 index 000000000..298f8d5f5 --- /dev/null +++ b/fontconfig/doc/fontconfig-user.sgml @@ -0,0 +1,692 @@ +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ +<!ENTITY version SYSTEM "version.sgml"> +<!ENTITY confdir SYSTEM "confdir.sgml"> +]> +<!-- + 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. +--> +<refentry> +<refmeta> + <refentrytitle>fonts-conf</refentrytitle> + <manvolnum>5</manvolnum> +</refmeta> +<refnamediv> + <refname>fonts.conf</refname> + <refpurpose>Font configuration files</refpurpose> +</refnamediv> +<refsynopsisdiv> +<synopsis> + &confdir;/fonts.conf + &confdir;/fonts.dtd + &confdir;/conf.d + ~/.fonts.conf.d + ~/.fonts.conf +</synopsis> +</refsynopsisdiv> +<refsect1><title>Description</title> + <para> +Fontconfig is a library designed to provide system-wide font configuration, +customization and application access. + </para> +</refsect1> +<refsect1><title>Functional Overview</title> + <para> +Fontconfig contains two essential modules, the configuration module which +builds an internal configuration from XML files and the matching module +which accepts font patterns and returns the nearest matching font. + </para> + <refsect2><title>Font Configuration</title> + <para> +The configuration module consists of the FcConfig datatype, libexpat and +FcConfigParse which walks over an XML tree and amends a configuration with +data found within. From an external perspective, configuration of the +library consists of generating a valid XML tree and feeding that to +FcConfigParse. The only other mechanism provided to applications for +changing the running configuration is to add fonts and directories to the +list of application-provided font files. + </para><para> +The intent is to make font configurations relatively static, and shared by +as many applications as possible. It is hoped that this will lead to more +stable font selection when passing names from one application to another. +XML was chosen as a configuration file format because it provides a format +which is easy for external agents to edit while retaining the correct +structure and syntax. + </para><para> +Font configuration is separate from font matching; applications needing to +do their own matching can access the available fonts from the library and +perform private matching. The intent is to permit applications to pick and +choose appropriate functionality from the library instead of forcing them to +choose between this library and a private configuration mechanism. The hope +is that this will ensure that configuration of fonts for all applications +can be centralized in one place. Centralizing font configuration will +simplify and regularize font installation and customization. + </para> + </refsect2> + <refsect2> + <title>Font Properties</title> + <para> +While font patterns may contain essentially any properties, there are some +well known properties with associated types. Fontconfig uses some of these +properties for font matching and font completion. Others are provided as a +convenience for the applications' rendering mechanism. + </para> + <programlisting> + Property Type Description + -------------------------------------------------------------- + family String Font family names + familylang String Languages corresponding to each family + style String Font style. Overrides weight and slant + stylelang String Languages corresponding to each style + fullname String Font full names (often includes style) + fullnamelang String Languages corresponding to each fullname + slant Int Italic, oblique or roman + weight Int Light, medium, demibold, bold or black + size Double Point size + width Int Condensed, normal or expanded + aspect Double Stretches glyphs horizontally before hinting + pixelsize Double Pixel size + spacing Int Proportional, dual-width, monospace or charcell + foundry String Font foundry name + antialias Bool Whether glyphs can be antialiased + hinting Bool Whether the rasterizer should use hinting + hintstyle Int Automatic hinting style + verticallayout Bool Use vertical layout + autohint Bool Use autohinter instead of normal hinter + globaladvance Bool Use font global advance data + file String The filename holding the font + index Int The index of the font within the file + ftface FT_Face Use the specified FreeType face object + rasterizer String Which rasterizer is in use + outline Bool Whether the glyphs are outlines + scalable Bool Whether glyphs can be scaled + scale Double Scale factor for point->pixel conversions + dpi Double Target dots per inch + rgba Int unknown, rgb, bgr, vrgb, vbgr, + none - subpixel geometry + lcdfilter Int Type of LCD filter + minspace Bool Eliminate leading from line spacing + charset CharSet Unicode chars encoded by the font + lang String List of RFC-3066-style languages this + font supports + fontversion Int Version number of the font + capability String List of layout capabilities in the font + embolden Bool Rasterizer should synthetically embolden the font + </programlisting> + </refsect2> + <refsect2> + <title>Font Matching</title> + <para> +Fontconfig performs matching by measuring the distance from a provided +pattern to all of the available fonts in the system. The closest matching +font is selected. This ensures that a font will always be returned, but +doesn't ensure that it is anything like the requested pattern. + </para><para> +Font matching starts with an application constructed pattern. The desired +attributes of the resulting font are collected together in a pattern. Each +property of the pattern can contain one or more values; these are listed in +priority order; matches earlier in the list are considered "closer" than +matches later in the list. + </para><para> +The initial pattern is modified by applying the list of editing instructions +specific to patterns found in the configuration; each consists of a match +predicate and a set of editing operations. They are executed in the order +they appeared in the configuration. Each match causes the associated +sequence of editing operations to be applied. + </para><para> +After the pattern has been edited, a sequence of default substitutions are +performed to canonicalize the set of available properties; this avoids the +need for the lower layers to constantly provide default values for various +font properties during rendering. + </para><para> +The canonical font pattern is finally matched against all available fonts. +The distance from the pattern to the font is measured for each of several +properties: foundry, charset, family, lang, spacing, pixelsize, style, +slant, weight, antialias, rasterizer and outline. This list is in priority +order -- results of comparing earlier elements of this list weigh more +heavily than later elements. + </para><para> +There is one special case to this rule; family names are split into two +bindings; strong and weak. Strong family names are given greater precedence +in the match than lang elements while weak family names are given lower +precedence than lang elements. This permits the document language to drive +font selection when any document specified font is unavailable. + </para><para> +The pattern representing that font is augmented to include any properties +found in the pattern but not found in the font itself; this permits the +application to pass rendering instructions or any other data through the +matching system. Finally, the list of editing instructions specific to +fonts found in the configuration are applied to the pattern. This modified +pattern is returned to the application. + </para><para> +The return value contains sufficient information to locate and rasterize the +font, including the file name, pixel size and other rendering data. As +none of the information involved pertains to the FreeType library, +applications are free to use any rasterization engine or even to take +the identified font file and access it directly. + </para><para> +The match/edit sequences in the configuration are performed in two passes +because there are essentially two different operations necessary -- the +first is to modify how fonts are selected; aliasing families and adding +suitable defaults. The second is to modify how the selected fonts are +rasterized. Those must apply to the selected font, not the original pattern +as false matches will often occur. + </para> + </refsect2> + <refsect2><title>Font Names</title> + <para> +Fontconfig provides a textual representation for patterns that the library +can both accept and generate. The representation is in three parts, first a +list of family names, second a list of point sizes and finally a list of +additional properties: + </para> + <programlisting> + <families>-<point sizes>:<name1>=<values1>:<name2>=<values2>... + </programlisting> + <para> +Values in a list are separated with commas. The name needn't include either +families or point sizes; they can be elided. In addition, there are +symbolic constants that simultaneously indicate both a name and a value. +Here are some examples: + </para> + <programlisting> + Name Meaning + ---------------------------------------------------------- + Times-12 12 point Times Roman + Times-12:bold 12 point Times Bold + Courier:italic Courier Italic in the default size + Monospace:matrix=1 .1 0 1 The users preferred monospace font + with artificial obliquing + </programlisting> + <para> +The '\', '-', ':' and ',' characters in family names must be preceeded by a +'\' character to avoid having them misinterpreted. Similarly, values +containing '\', '=', '_', ':' and ',' must also have them preceeded by a +'\' character. The '\' characters are stripped out of the family name and +values as the font name is read. + </para> + </refsect2> +</refsect1> +<refsect1><title>Debugging Applications</title> + <para> +To help diagnose font and applications problems, fontconfig is built with a +large amount of internal debugging left enabled. It is controlled by means +of the FC_DEBUG environment variable. The value of this variable is +interpreted as a number, and each bit within that value controls different +debugging messages. + </para> + <programlisting> + Name Value Meaning + --------------------------------------------------------- + MATCH 1 Brief information about font matching + MATCHV 2 Extensive font matching information + EDIT 4 Monitor match/test/edit execution + FONTSET 8 Track loading of font information at startup + CACHE 16 Watch cache files being written + CACHEV 32 Extensive cache file writing information + PARSE 64 (no longer in use) + SCAN 128 Watch font files being scanned to build caches + SCANV 256 Verbose font file scanning information + MEMORY 512 Monitor fontconfig memory usage + CONFIG 1024 Monitor which config files are loaded + LANGSET 2048 Dump char sets used to construct lang values + OBJTYPES 4096 Display message when value typechecks fail + </programlisting> + <para> +Add the value of the desired debug levels together and assign that (in +base 10) to the FC_DEBUG environment variable before running the +application. Output from these statements is sent to stdout. + </para> +</refsect1> +<refsect1><title>Lang Tags</title> + <para> +Each font in the database contains a list of languages it supports. This is +computed by comparing the Unicode coverage of the font with the orthography +of each language. Languages are tagged using an RFC-3066 compatible naming +and occur in two parts -- the ISO 639 language tag followed a hyphen and then +by the ISO 3166 country code. The hyphen and country code may be elided. + </para><para> +Fontconfig has orthographies for several languages built into the library. +No provision has been made for adding new ones aside from rebuilding the +library. It currently supports 122 of the 139 languages named in ISO 639-1, +141 of the languages with two-letter codes from ISO 639-2 and another 30 +languages with only three-letter codes. Languages with both two and three +letter codes are provided with only the two letter code. + </para><para> +For languages used in multiple territories with radically different +character sets, fontconfig includes per-territory orthographies. This +includes Azerbaijani, Kurdish, Pashto, Tigrinya and Chinese. + </para> +</refsect1> +<refsect1><title>Configuration File Format</title> + <para> +Configuration files for fontconfig are stored in XML format; this +format makes external configuration tools easier to write and ensures that +they will generate syntactically correct configuration files. As XML +files are plain text, they can also be manipulated by the expert user using +a text editor. + </para><para> +The fontconfig document type definition resides in the external entity +"fonts.dtd"; this is normally stored in the default font configuration +directory (&confdir;). Each configuration file should contain the +following structure: + <programlisting> + <?xml version="1.0"?> + <!DOCTYPE fontconfig SYSTEM "fonts.dtd"> + <fontconfig> + ... + </fontconfig> + </programlisting> + </para> +<refsect2><title><literal><fontconfig></literal></title><para> +This is the top level element for a font configuration and can contain +<literal><dir></literal>, <literal><cache></literal>, <literal><include></literal>, <literal><match></literal> and <literal><alias></literal> elements in any order. + </para></refsect2> + <refsect2><title><literal><dir></literal></title><para> +This element contains a directory name which will be scanned for font files +to include in the set of available fonts. + </para></refsect2> + <refsect2><title><literal><cache></literal></title><para> +This element contains a file name for the per-user cache of font +information. If it starts with '~', it refers to a file in the users +home directory. This file is used to hold information about fonts that +isn't present in the per-directory cache files. It is automatically +maintained by the fontconfig library. The default for this file +is ``~/.fonts.cache-<literal><version></literal>'', where <literal><version></literal> is the font configuration +file version number (currently 2). + </para></refsect2> + <refsect2><title><literal><include ignore_missing="no"></literal></title><para> +This element contains the name of an additional configuration file or +directory. If a directory, every file within that directory starting with an +ASCII digit (U+0030 - U+0039) and ending with the string ``.conf'' will be processed in sorted order. When +the XML datatype is traversed by FcConfigParse, the contents of the file(s) +will also be incorporated into the configuration by passing the filename(s) to +FcConfigLoadAndParse. If 'ignore_missing' is set to "yes" instead of the +default "no", a missing file or directory will elicit no warning message from +the library. + </para></refsect2> + <refsect2><title><literal><config></literal></title><para> +This element provides a place to consolidate additional configuration +information. <literal><config></literal> can contain <literal><blank></literal> and <literal><rescan></literal> elements in any +order. + </para></refsect2> + <refsect2><title><literal><blank></literal></title><para> +Fonts often include "broken" glyphs which appear in the encoding but are +drawn as blanks on the screen. Within the <literal><blank></literal> element, place each +Unicode characters which is supposed to be blank in an <literal><int></literal> element. +Characters outside of this set which are drawn as blank will be elided from +the set of characters supported by the font. + </para></refsect2> + <refsect2><title><literal><rescan></literal></title><para> +The <literal><rescan></literal> element holds an <literal><int></literal> element which indicates the default +interval between automatic checks for font configuration changes. +Fontconfig will validate all of the configuration files and directories and +automatically rebuild the internal datastructures when this interval passes. + </para></refsect2> + <refsect2><title><literal><selectfont></literal></title><para> +This element is used to black/white list fonts from being listed or matched +against. It holds acceptfont and rejectfont elements. + </para></refsect2> + <refsect2><title><literal><acceptfont></literal></title><para> +Fonts matched by an acceptfont element are "whitelisted"; such fonts are +explicitly included in the set of fonts used to resolve list and match +requests; including them in this list protects them from being "blacklisted" +by a rejectfont element. Acceptfont elements include glob and pattern +elements which are used to match fonts. + </para></refsect2> + <refsect2><title><literal><rejectfont></literal></title><para> +Fonts matched by an rejectfont element are "blacklisted"; such fonts are +excluded from the set of fonts used to resolve list and match requests as if +they didn't exist in the system. Rejectfont elements include glob and +pattern elements which are used to match fonts. + </para></refsect2> + <refsect2><title><literal><glob></literal></title><para> +Glob elements hold shell-style filename matching patterns (including ? and +*) which match fonts based on their complete pathnames. This can be used to +exclude a set of directories (/usr/share/fonts/uglyfont*), or particular +font file types (*.pcf.gz), but the latter mechanism relies rather heavily +on filenaming conventions which can't be relied upon. Note that globs +only apply to directories, not to individual fonts. + </para></refsect2> + <refsect2><title><literal><pattern></literal></title><para> +Pattern elements perform list-style matching on incoming fonts; that is, +they hold a list of elements and associated values. If all of those +elements have a matching value, then the pattern matches the font. This can +be used to select fonts based on attributes of the font (scalable, bold, +etc), which is a more reliable mechanism than using file extensions. +Pattern elements include patelt elements. + </para></refsect2> + <refsect2><title><literal><patelt name="property"></literal></title><para> +Patelt elements hold a single pattern element and list of values. They must +have a 'name' attribute which indicates the pattern element name. Patelt +elements include int, double, string, matrix, bool, charset and const +elements. + </para></refsect2> + <refsect2><title><literal><match target="pattern"></literal></title><para> +This element holds first a (possibly empty) list of <literal><test></literal> elements and then +a (possibly empty) list of <literal><edit></literal> elements. Patterns which match all of the +tests are subjected to all the edits. If 'target' is set to "font" instead +of the default "pattern", then this element applies to the font name +resulting from a match rather than a font pattern to be matched. If 'target' +is set to "scan", then this element applies when the font is scanned to +build the fontconfig database. + </para></refsect2> + <refsect2><title><literal><test qual="any" name="property" target="default" compare="eq"></literal></title><para> +This element contains a single value which is compared with the target +('pattern', 'font', 'scan' or 'default') property "property" (substitute any of the property names seen +above). 'compare' can be one of "eq", "not_eq", "less", "less_eq", "more", or +"more_eq". 'qual' may either be the default, "any", in which case the match +succeeds if any value associated with the property matches the test value, or +"all", in which case all of the values associated with the property must +match the test value. When used in a <match target="font"> element, +the target= attribute in the <test> element selects between matching +the original pattern or the font. "default" selects whichever target the +outer <match> element has selected. + </para></refsect2> + <refsect2><title><literal><edit name="property" mode="assign" binding="weak"></literal></title><para> +This element contains a list of expression elements (any of the value or +operator elements). The expression elements are evaluated at run-time and +modify the property "property". The modification depends on whether +"property" was matched by one of the associated <literal><test></literal> elements, if so, the +modification may affect the first matched value. Any values inserted into +the property are given the indicated binding ("strong", "weak" or "same") +with "same" binding using the value from the matched pattern element. +'mode' is one of: + <programlisting> + Mode With Match Without Match + --------------------------------------------------------------------- + "assign" Replace matching value Replace all values + "assign_replace" Replace all values Replace all values + "prepend" Insert before matching Insert at head of list + "prepend_first" Insert at head of list Insert at head of list + "append" Append after matching Append at end of list + "append_last" Append at end of list Append at end of list + </programlisting> + </para></refsect2> + <refsect2><title><literal><int></literal>, <literal><double></literal>, <literal><string></literal>, <literal><bool></literal></title><para> +These elements hold a single value of the indicated type. <literal><bool></literal> +elements hold either true or false. An important limitation exists in +the parsing of floating point numbers -- fontconfig requires that +the mantissa start with a digit, not a decimal point, so insert a leading +zero for purely fractional values (e.g. use 0.5 instead of .5 and -0.5 +instead of -.5). + </para></refsect2> + <refsect2><title><literal><matrix></literal></title><para> +This element holds the four <literal><double></literal> elements of an affine +transformation. + </para></refsect2> + <refsect2><title><literal><name></literal></title><para> +Holds a property name. Evaluates to the first value from the property of +the font, not the pattern. + </para></refsect2> + <refsect2><title><literal><const></literal></title><para> +Holds the name of a constant; these are always integers and serve as +symbolic names for common font values: + <programlisting> + Constant Property Value + ------------------------------------- + thin weight 0 + extralight weight 40 + ultralight weight 40 + light weight 50 + book weight 75 + regular weight 80 + normal weight 80 + medium weight 100 + demibold weight 180 + semibold weight 180 + bold weight 200 + extrabold weight 205 + black weight 210 + heavy weight 210 + roman slant 0 + italic slant 100 + oblique slant 110 + ultracondensed width 50 + extracondensed width 63 + condensed width 75 + semicondensed width 87 + normal width 100 + semiexpanded width 113 + expanded width 125 + extraexpanded width 150 + ultraexpanded width 200 + proportional spacing 0 + dual spacing 90 + mono spacing 100 + charcell spacing 110 + unknown rgba 0 + rgb rgba 1 + bgr rgba 2 + vrgb rgba 3 + vbgr rgba 4 + none rgba 5 + lcdnone lcdfilter 0 + lcddefault lcdfilter 1 + lcdlight lcdfilter 2 + lcdlegacy lcdfilter 3 + hintnone hintstyle 0 + hintslight hintstyle 1 + hintmedium hintstyle 2 + hintfull hintstyle 3 + </programlisting> + </para> + </refsect2> + <refsect2> + <title><literal><or></literal>, <literal><and></literal>, <literal><plus></literal>, <literal><minus></literal>, <literal><times></literal>, <literal><divide></literal></title> + <para> +These elements perform the specified operation on a list of expression +elements. <literal><or></literal> and <literal><and></literal> are boolean, not bitwise. + </para> + </refsect2> + <refsect2> + <title><literal><eq></literal>, <literal><not_eq></literal>, <literal><less></literal>, <literal><less_eq></literal>, <literal><more></literal>, <literal><more_eq></literal></title> + <para> +These elements compare two values, producing a boolean result. + </para></refsect2> + <refsect2><title><literal><not></literal></title><para> +Inverts the boolean sense of its one expression element + </para></refsect2> + <refsect2><title><literal><if></literal></title><para> +This element takes three expression elements; if the value of the first is +true, it produces the value of the second, otherwise it produces the value +of the third. + </para></refsect2> + <refsect2><title><literal><alias></literal></title><para> +Alias elements provide a shorthand notation for the set of common match +operations needed to substitute one font family for another. They contain a +<literal><family></literal> element followed by optional <literal><prefer></literal>, <literal><accept></literal> and <literal><default></literal> +elements. Fonts matching the <literal><family></literal> element are edited to prepend the +list of <literal><prefer></literal>ed families before the matching <literal><family></literal>, append the +<literal><accept></literal>able families after the matching <literal><family></literal> and append the <literal><default></literal> +families to the end of the family list. + </para></refsect2> + <refsect2><title><literal><family></literal></title><para> +Holds a single font family name + </para></refsect2> + <refsect2><title><literal><prefer></literal>, <literal><accept></literal>, <literal><default></literal></title><para> +These hold a list of <literal><family></literal> elements to be used by the <literal><alias></literal> element. + </para></refsect2> +</refsect1> +<refsect1><title>EXAMPLE CONFIGURATION FILE</title> + <refsect2><title>System configuration file</title> + <para> +This is an example of a system-wide configuration file + </para> + <programlisting> +<?xml version="1.0"?> +<!DOCTYPE fontconfig SYSTEM "fonts.dtd"> +<!-- &confdir;/fonts.conf file to configure system font access --> +<fontconfig> +<!-- + Find fonts in these directories +--> +<dir>/usr/share/fonts</dir> +<dir>/usr/X11R6/lib/X11/fonts</dir> + +<!-- + Accept deprecated 'mono' alias, replacing it with 'monospace' +--> +<match target="pattern"> + <test qual="any" name="family"><string>mono</string></test> + <edit name="family" mode="assign"><string>monospace</string></edit> +</match> + +<!-- + Names not including any well known alias are given 'sans' +--> +<match target="pattern"> + <test qual="all" name="family" mode="not_eq">sans</test> + <test qual="all" name="family" mode="not_eq">serif</test> + <test qual="all" name="family" mode="not_eq">monospace</test> + <edit name="family" mode="append_last"><string>sans</string></edit> +</match> + +<!-- + Load per-user customization file, but don't complain + if it doesn't exist +--> +<include ignore_missing="yes">~/.fonts.conf</include> + +<!-- + Load local customization files, but don't complain + if there aren't any +--> +<include ignore_missing="yes">conf.d</include> +<include ignore_missing="yes">local.conf</include> + +<!-- + Alias well known font names to available TrueType fonts. + These substitute TrueType faces for similar Type1 + faces to improve screen appearance. +--> +<alias> + <family>Times</family> + <prefer><family>Times New Roman</family></prefer> + <default><family>serif</family></default> +</alias> +<alias> + <family>Helvetica</family> + <prefer><family>Arial</family></prefer> + <default><family>sans</family></default> +</alias> +<alias> + <family>Courier</family> + <prefer><family>Courier New</family></prefer> + <default><family>monospace</family></default> +</alias> + +<!-- + Provide required aliases for standard names + Do these after the users configuration file so that + any aliases there are used preferentially +--> +<alias> + <family>serif</family> + <prefer><family>Times New Roman</family></prefer> +</alias> +<alias> + <family>sans</family> + <prefer><family>Arial</family></prefer> +</alias> +<alias> + <family>monospace</family> + <prefer><family>Andale Mono</family></prefer> +</alias> +</fontconfig> + </programlisting> + </refsect2> + <refsect2><title>User configuration file</title> + <para> +This is an example of a per-user configuration file that lives in +~/.fonts.conf + </para> + <programlisting> +<?xml version="1.0"?> +<!DOCTYPE fontconfig SYSTEM "fonts.dtd"> +<!-- ~/.fonts.conf for per-user font configuration --> +<fontconfig> + +<!-- + Private font directory +--> +<dir>~/.fonts</dir> + +<!-- + use rgb sub-pixel ordering to improve glyph appearance on + LCD screens. Changes affecting rendering, but not matching + should always use target="font". +--> +<match target="font"> + <edit name="rgba" mode="assign"><const>rgb</const></edit> +</match> +</fontconfig> + </programlisting> + </refsect2> +</refsect1> +<refsect1><title>Files</title> + <para> +<emphasis>fonts.conf</emphasis> +contains configuration information for the fontconfig library +consisting of directories to look at for font information as well as +instructions on editing program specified font patterns before attempting to +match the available fonts. It is in xml format. + </para> + <para> +<emphasis>conf.d</emphasis> +is the conventional name for a directory of additional configuration files +managed by external applications or the local administrator. The +filenames starting with decimal digits are sorted in lexicographic order +and used as additional configuration files. All of these files are in xml +format. The master fonts.conf file references this directory in an +<include> directive. + </para> + <para> +<emphasis>fonts.dtd</emphasis> +is a DTD that describes the format of the configuration files. + </para> + <para> +<emphasis>~/.fonts.conf.d</emphasis> +is the conventional name for a per-user directory of (typically +auto-generated) configuration files, although the +actual location is specified in the global fonts.conf file. + </para> + <para> +<emphasis>~/.fonts.conf</emphasis> +is the conventional location for per-user font configuration, although the +actual location is specified in the global fonts.conf file. + </para> + <para> +<emphasis> ~/.fonts.cache-*</emphasis> +is the conventional repository of font information that isn't found in the +per-directory caches. This file is automatically maintained by fontconfig. + </para> +</refsect1> +<refsect1><title>See Also</title> + <para> +fc-cat(1), fc-cache(1), fc-list(1), fc-match(1), fc-query(1) + </para> +</refsect1> +<refsect1><title>Version</title> + <para> +Fontconfig version &version; + </para> +</refsect1> +</refentry> diff --git a/fontconfig/doc/func.sgml b/fontconfig/doc/func.sgml new file mode 100644 index 000000000..0da5ae4a6 --- /dev/null +++ b/fontconfig/doc/func.sgml @@ -0,0 +1,90 @@ +<!-- + fontconfig/doc/func.sgml + + 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. + --> +@?TITLE@ + <refentry id="@TITLE@"> +@:@ + <refentry id="@FUNC@"> +@;@ + <refmeta> +@?TITLE@ + <refentrytitle>@TITLE@</refentrytitle> +@:@ + <refentrytitle>@FUNC@</refentrytitle> +@;@ + <manvolnum>3</manvolnum> + </refmeta> + <refnamediv> +@{PROTOTYPE@ + <refname>@FUNC@</refname> +@}PROTOTYPE@ + <refpurpose>@PURPOSE@</refpurpose> + </refnamediv> + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo> +@?SYNOPSIS@ +@SYNOPSIS@ +@:@ +#include <fontconfig.h> +@;@ + </funcsynopsisinfo> +@{PROTOTYPE@ + <funcprototype> + <funcdef>@?RET@@RET@@:@void@;@ <function>@FUNC@</function></funcdef> +@?TYPE1@ + <paramdef>@TYPE1@<parameter>@ARG1@</parameter></paramdef> +@;@ +@?TYPE2@ + <paramdef>@TYPE2@<parameter>@ARG2@</parameter></paramdef> +@;@ +@?TYPE3@ + <paramdef>@TYPE3@<parameter>@ARG3@</parameter></paramdef> +@;@ +@?TYPE4@ + <paramdef>@TYPE4@<parameter>@ARG4@</parameter></paramdef> +@;@ +@?TYPE5@ + <paramdef>@TYPE5@<parameter>@ARG5@</parameter></paramdef> +@;@ +@?TYPE6@ + <paramdef>@TYPE6@<parameter>@ARG6@</parameter></paramdef> +@;@ +@?TYPE7@ + <paramdef>@TYPE7@<parameter>@ARG7@</parameter></paramdef> +@;@ + </funcprototype> +@}PROTOTYPE@ + </funcsynopsis> + </refsynopsisdiv> + <refsect1><title>Description</title> + <para> +@DESC@ + </para> + </refsect1> + <refsect1><title>Version</title> + <para> +Fontconfig version &version; + </para> + </refsect1> + </refentry> diff --git a/fontconfig/doc/version.sgml.in b/fontconfig/doc/version.sgml.in new file mode 100644 index 000000000..9981b1c74 --- /dev/null +++ b/fontconfig/doc/version.sgml.in @@ -0,0 +1,24 @@ +<!-- + fontconfig/doc/version.sgml.in + + 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. +--> +@VERSION@ |