.\" Copyright (C) 2001 Information-technology Promotion Agency (IPA) .\" Copyright (C) 2001-2003 .\" National Institute of Advanced Industrial Science and Technology (AIST) .\" This file si aprt of the m17n library documentation. .\" Permission is granted to copy, distribute and/or modify this document .\" under the terms of the GNU Free Documentation License, Version 1.2 or .\" any later version published by the Free Software Foundation; with no .\" Invariant Section, Front-Cover Texts "The m17n library documentation", .\" and no Back-Cover Texts. A copy of the license is included in the .\" appendix entitled "GNU Free Documentation License". .TH "Introduction" 3m17n "14 Jul 2007" "" "Version 1.4.0" "" "The m17n Library" \" -*- nroff -*- .ad l .nh .SH NAME Introduction \- Introduction to the m17n library. .PP .SS "Defines" .in +1c .ti -1c .RI "#define \fBM17NLIB_MAJOR_VERSION\fP" .br .ti -1c .RI "#define \fBM17NLIB_MINOR_VERSION\fP" .br .ti -1c .RI "#define \fBM17NLIB_PATCH_LEVEL\fP" .br .ti -1c .RI "#define \fBM17NLIB_VERSION_NAME\fP" .br .ti -1c .RI "#define \fBM17N_INIT\fP()" .br .RI "\fIInitialize the m17n library. \fP" .ti -1c .RI "#define \fBM17N_FINI\fP()" .br .RI "\fIFinalize the m17n library. \fP" .in -1c .SS "Enumerations" .in +1c .ti -1c .RI "enum \fBM17NStatus\fP { \fBM17N_NOT_INITIALIZED\fP, \fBM17N_CORE_INITIALIZED\fP, \fBM17N_SHELL_INITIALIZED\fP, \fBM17N_GUI_INITIALIZED\fP }" .br .RI "\fIEnumeration for the status of the m17n library. \fP" .in -1c .SS "Functions" .in +1c .ti -1c .RI "enum \fBM17NStatus\fP \fBm17n_status\fP (void)" .br .RI "\fIReport which part of the m17n library is initialized. \fP" .in -1c .SH "Detailed Description" .PP \fIAPI LEVELS\fP .PP The API of the m17n library is divided into these four. .PP .PD 0 .TP CORE API It provides basic modules to handle M-texts. They do not require the m17n database. To use this API, an application program must include and be linked by -lm17n-core. .PP .TP SHELL API It provides modules that utilize the m17n database (code conversion, character property, etc). They load various kinds of data from the database on demand. To use this API, an application program must include and be linked by -lm17n-core -lm17n. .PP When you use this API, CORE API is also available. .PP .TP GUI API It provides GUI modules such as drawing and inputting M-texts on a graphic device. The API itself is independent on a graphic device but most functions require an argument MFrame which is created for a specific type of graphic device. Currently, a null device, X Window System, and an image date (gdImagePtr) of GD library are supported as a graphic device. .PP On a frame of the null device, you can't draw text nor use an input method (but, for instance, the function \fBmdraw_glyph_list()\fP is available). .PP On a frame of the X Window System, you can use the whole GUI API. .PP On a frame of GD library, you can use all drawing API but can't use input method. .PP To use this device, an application program must include and be linked by -lm17n-core -lm17n -lm17n-gui. .PP When you use this API, CORE and SHELL API are also available. .PP .TP MISC API It provides miscellaneous functions to support error handling and debugging. This API cannot be used by itself, but with one or more APIs listed above. To use the API, an application program must include in addition to one of a header file described above. .PP .PP .PP See also the section \fBm17n-config(1)\fP. .PP \fIENVIRONMENT VARIABLE\fP .PP The m17n library pays attention to these environment variables. .PP .PD 0 .TP \fCM17NDIR\fP Name of a directory that contains data of the m17n database. See \fBDatabase\fP for more details. .PP .TP \fCMDEBUG_XXXX\fP Environment variables whose name start by 'MDEBUG_' controls printing of debug information. See \fBDebugging\fP for more details. .PP .PP .PP \fIAPI NAMING CONVENTION\fP .PP The library exports functions, variables, macros, and types. All of them start by the letter 'm' or 'M' followed by an object name (e.g. 'symbol' and 'plist', but 'mtext' object is given the name 'text' to avoid double 'm' at the head) or a module name (e.g. draw, input). .PP .PD 0 .TP functions -- mobject() or mobject_xxx() They start with 'm' followed by lower case object name. For example, \fBmsymbol()\fP, \fBmtext_ref_char()\fP, \fBmdraw_text()\fP. .PP .TP non-symbol variables -- mobject, or mobject_xxx The naming convention is the same as functions (e.g. mface_large). .PP .TP symbol variables -- Mname Variables of type MSymbol start with 'M' followed by their names (e.g. Mlanguage (name is 'language'), Miso_2022 (name is 'iso-2022'). .PP .TP macros -- MOBJECT_XXX They start by 'M' followed by upper case object names. .PP .TP types -- MObject or MObjectXxx They start by 'M' followed by capitalized object names (e.g. \fBMConverter\fP, \fBMInputDriver\fP). .PP .PP .SH "Define Documentation" .PP .SS "#define M17NLIB_MAJOR_VERSION" .PP The \fBM17NLIB_MAJOR_VERSION\fP macro gives the major version number of the m17n library. .SS "#define M17NLIB_MINOR_VERSION" .PP The \fBM17NLIB_MINOR_VERSION\fP macro gives the minor version number of the m17n library. .SS "#define M17NLIB_PATCH_LEVEL" .PP The \fBM17NLIB_PATCH_LEVEL\fP macro gives the patch level number of the m17n library. .SS "#define M17NLIB_VERSION_NAME" .PP The \fBM17NLIB_VERSION_NAME\fP macro gives the version name of the m17n library as a string. .SS "#define M17N_INIT()" .PP The macro \fBM17N_INIT()\fP initializes the m17n library. This macro must be called before any m17n functions are used. .PP It is safe to call this macro multiple times, but in that case, the macro \fBM17N_FINI()\fP must be called the same times to free the memory. .PP If the initialization was successful, the external variable \fBmerror_code\fP is set to 0. Otherwise it is set to -1. .PP \fBSee Also:\fP.RS 4 \fBM17N_FINI()\fP, \fBm17n_status()\fP .RE .PP .SS "#define M17N_FINI()" .PP The macro \fBM17N_FINI()\fP finalizes the m17n library. It frees all the memory area used by the m17n library. Once this macro is called, no m17n functions should be used until the macro \fBM17N_INIT()\fP is called again. .PP If the macro \fBM17N_INIT()\fP was called N times, the Nth call of this macro actually free the memory. .PP \fBSee Also:\fP.RS 4 \fBM17N_INIT()\fP, \fBm17n_status()\fP .RE .PP .SH "Enumeration Type Documentation" .PP .SS "enum \fBM17NStatus\fP" .PP The enum \fBM17NStatus\fP is used as a return value of the function \fBm17n_status()\fP. .PP \fBEnumerator: \fP .in +1c .TP \fB\fIM17N_NOT_INITIALIZED \fP\fP .TP \fB\fIM17N_CORE_INITIALIZED \fP\fP .TP \fB\fIM17N_SHELL_INITIALIZED \fP\fP .TP \fB\fIM17N_GUI_INITIALIZED \fP\fP