[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[GNUnet-SVN] r23705 - Extractor/doc
From: |
gnunet |
Subject: |
[GNUnet-SVN] r23705 - Extractor/doc |
Date: |
Sat, 8 Sep 2012 10:41:03 +0200 |
Author: grothoff
Date: 2012-09-08 10:41:03 +0200 (Sat, 08 Sep 2012)
New Revision: 23705
Modified:
Extractor/doc/libextractor.texi
Log:
removing macros
Modified: Extractor/doc/libextractor.texi
===================================================================
--- Extractor/doc/libextractor.texi 2012-09-08 08:37:58 UTC (rev 23704)
+++ Extractor/doc/libextractor.texi 2012-09-08 08:41:03 UTC (rev 23705)
@@ -51,36 +51,10 @@
@insertcopying
@end titlepage
-
@summarycontents
@contents
address@hidden gnu{}
address@hidden
address@hidden macro
-
address@hidden gpl{}
address@hidden
address@hidden macro
-
address@hidden api{}
address@hidden
address@hidden macro
-
address@hidden cfunction{arg}
address@hidden()}
address@hidden macro
-
address@hidden mynull{}
address@hidden
address@hidden macro
-
address@hidden gnule{}
address@hidden libextractor}
address@hidden macro
-
-
@ifnottex
@node Top
@top The GNU libextractor Reference Manual
@@ -88,15 +62,15 @@
@end ifnottex
@menu
-* Introduction:: What is @gnule{}.
+* Introduction:: What is GNU libextractor.
* Preparation:: What you should do before using the library.
* Generalities:: General library functions and data types.
-* Extracting meta data:: How to use @gnule{} to obtain meta data.
-* Language bindings:: How to use @gnule{} from languages other than
C.
-* Utility functions:: Utility functions of @gnule{}.
+* Extracting meta data:: How to use GNU libextractor to obtain meta
data.
+* Language bindings:: How to use GNU libextractor from languages
other than C.
+* Utility functions:: Utility functions of GNU libextractor.
* Existing Plugins:: What plugins are available.
-* Writing new Plugins:: How to write new plugins for @gnule{}.
-* Internal utility functions:: Utility functions of @gnule{} for writing
plugins.
+* Writing new Plugins:: How to write new plugins for GNU libextractor.
+* Internal utility functions:: Utility functions of GNU libextractor for
writing plugins.
* Reporting bugs:: How to report bugs or request new features.
Appendices
@@ -120,7 +94,7 @@
@chapter Introduction
@cindex error handling
address@hidden is GNU's library for extracting meta data from
+GNU libextractor is GNU's library for extracting meta data from
files. Meta data includes format information (such as mime type,
image dimensions, color depth, recording frequency), content
descriptions (such as document title or document description) and
@@ -128,38 +102,38 @@
Meta data extraction is an inherently uncertain business --- a parse
error can be a corrupt file, an incompatibility in the file format
version, an entirely different file format or a bug in the parser. As
-a result of this uncertainty, @gnule{} deliberately
+a result of this uncertainty, GNU libextractor deliberately
avoids to ever report any errors. Unexpected file contents simply
result in less or possibly no meta data being extracted.
@cindex plugin
address@hidden uses plugins to handle various file formats.
+GNU libextractor uses plugins to handle various file formats.
Technically a plugin can support multiple file formats; however, most
plugins only support one particular format. By default,
address@hidden will use all plugins that are available and found
+GNU libextractor will use all plugins that are available and found
in the plugin installation directory. Applications can
request the use of only specific plugins or the exclusion of
certain plugins.
address@hidden is distributed with the @command{extract}
+GNU libextractor is distributed with the @command{extract}
address@hidden distributions ship @command{extract} in a
seperate package.} which is a command-line tool for extracting
meta data. @command{extract} is given a list of filenames and
prints the resulting meta data to the console. The @command{extract}
source code also serves as an advanced example for how to use
address@hidden
+GNU libextractor.
This manual focuses on providing documentation for writing software
-with @gnule{}. The only relevant parts for end-users
-are the chapter on compiling and installing @gnule{}
+with GNU libextractor. The only relevant parts for end-users
+are the chapter on compiling and installing GNU libextractor
(@xref{Preparation}.). Also, the chapter on existing plugins maybe of
interest (@xref{Existing Plugins}.). Additional documentation for
end-users can be find in the man page on @command{extract} (using
@verb{|man extract|}).
@cindex license
address@hidden is licensed under the GNU General Public License,
-specifically, since version 0.7, @gnule{} is licensed under GPLv3
+GNU libextractor is licensed under the GNU General Public License,
+specifically, since version 0.7, GNU libextractor is licensed under GPLv3
@emph{or any later version}.
@node Preparation
@@ -170,12 +144,12 @@
for particular platforms are then described in individual sections
afterwards.
-Compiling @gnule{} follows the standard GNU autotools build process
+Compiling GNU libextractor follows the standard GNU autotools build process
using @command{configure} and @command{make}. For details on the GNU
autotools build process, read the @file{INSTALL} file and query
@verb{|./configure --help|} for additional options.
address@hidden has various dependencies, most of which are optional.
+GNU libextractor has various dependencies, most of which are optional.
Instead of specifying the names of the software packages, we
will give the list in terms of the names of the respective
Debian (unstable) packages that should be installed.
@@ -241,29 +215,29 @@
supposed to only list direct dependencies, not transitive
dependencies).
-Once you have compiled and installed @gnule{}, you should have a file
+Once you have compiled and installed GNU libextractor, you should have a file
@file{extractor.h} installed in your @file{include/} directory. This
file should be the starting point for your C and C++ development with
address@hidden The build process also installs the @file{extract} binary and
-man pages for @file{extract} and @gnule{}. The @file{extract} man page
-documents the @file{extract} tool. The @gnule{} man page gives a brief
-summary of the C API for @gnule{}.
+GNU libextractor. The build process also installs the @file{extract} binary
and
+man pages for @file{extract} and GNU libextractor. The @file{extract} man page
+documents the @file{extract} tool. The GNU libextractor man page gives a brief
+summary of the C API for GNU libextractor.
@cindex packageing
@cindex directory structure
@cindex plugin
@cindex environment variables
@vindex LIBEXTRACTOR_PREFIX
-When you install @gnule{}, various plugins will be
+When you install GNU libextractor, various plugins will be
installed in the @file{lib/libextractor/} directory. The main library
will be installed as @file{lib/libextractor.so}. Note that
address@hidden will attempt to find the plugins relative to the
+GNU libextractor will attempt to find the plugins relative to the
path of the main library. Consequently, a package manager can move
the library and its plugins to a different location later --- as long
as the relative path between the main library and the plugins is
preserved. As a method of last resort, the user can specify an
environment variable @verb{|LIBEXTRACTOR_PREFIX|}. If
address@hidden cannot locate a plugin, it will look in
+GNU libextractor cannot locate a plugin, it will look in
@verb{|LIBEXTRACTOR_PREFIX/lib/libextractor/|}.
@@ -280,7 +254,7 @@
@section Installation on OpenBSD
OpenBSD 3.8 also doesn't have CODESET in @file{langinfo.h}. CODESET
-is used in @gnule{} in about three places. This causes problems
+is used in GNU libextractor in about three places. This causes problems
during compilation.
@@ -477,9 +451,9 @@
@section Introduction to the libextractor library
-Each public symbol exported by @gnule{} has the prefix
+Each public symbol exported by GNU libextractor has the prefix
@verb{|EXTRACTOR_|}. All-caps names are used for constants. For the
-impatient, the minimal C code for using @gnule{} (on the
+impatient, the minimal C code for using GNU libextractor (on the
executing binary itself) looks like this:
@verbatim
@@ -499,7 +473,7 @@
@end verbatim
The minimal API illustrated by this example is actually sufficient for
-many applications. The full external C API of @gnule{} is described
+many applications. The full external C API of GNU libextractor is described
in chapter @xref{Extracting meta data}. Bindings for other languages
are described in chapter @xref{Language bindings}. The API for
writing new plugins is described in chapter @xref{Writing new Plugins}.
@@ -507,7 +481,7 @@
@node Extracting meta data
@chapter Extracting meta data
-In order to extract meta data with @gnule{} you first need to
+In order to extract meta data with GNU libextractor you first need to
load the respective plugins and then call the extraction API
with the plugins and the data to process. This section
documents how to load and unload plugins, the various types
@@ -531,8 +505,8 @@
@cindex thread-safety
@tindex enum EXTRACTOR_Options
-Using @gnule{} from a multi-threaded parent process requires some
-care. The problem is that on most platforms @gnule{} starts
+Using GNU libextractor from a multi-threaded parent process requires some
+care. The problem is that on most platforms GNU libextractor starts
sub-processes for the actual extraction work. This is useful to
isolate the parent process from potential bugs; however, it can cause
problems if the parent process is multi-threaded. The issue is that
@@ -545,7 +519,7 @@
the plugin startup code when it interacts with libltdl.
The problem can be solved by loading the plugins using the
address@hidden option, which will run @gnule{}
address@hidden option, which will run GNU libextractor
in-process and thus avoid the locking issue. In this case, all of the
functions for loading and unloading plugins, including
@verb{|EXTRACTOR_plugin_add_defaults|} and
@@ -583,19 +557,19 @@
@deftypefun {struct EXTRACTOR_PluginList *} EXTRACTOR_plugin_add (struct
EXTRACTOR_PluginList *plugins, const char* name,const char* options, enum
EXTRACTOR_Options flags)
@findex EXTRACTOR_plugin_add
-Loads a particular plugin. The plugin is added to the existing list, which
can be NULL. The second argument specifies the name of the plugin (i.e.
``ogg''). The third argument can be NULL and specifies plugin-specific
options. Finally, the last argument specifies if the plugin should be executed
out-of-process (@code{EXTRACTOR_OPTION_DEFAULT_POLICY}) or not.
+Loads a particular plugin. The plugin is added to the existing list, which
can be @code{NULL}. The second argument specifies the name of the plugin (i.e.
``ogg''). The third argument can be @code{NULL} and specifies plugin-specific
options. Finally, the last argument specifies if the plugin should be executed
out-of-process (@code{EXTRACTOR_OPTION_DEFAULT_POLICY}) or not.
@end deftypefun
@deftypefun {struct EXTRACTOR_PluginList *} EXTRACTOR_plugin_add_config
(struct EXTRACTOR_PluginList *plugins, const char* config, enum
EXTRACTOR_Options flags)
@findex EXTRACTOR_plugin_add_config
-Loads and unloads plugins based on a configuration string, modifying the
existing list, which can be NULL. The string has the format
``[-]NAME(OPTIONS)@{:[-]NAME(OPTIONS)@}*''. Prefixing the plugin name with a
``-'' means that the plugin should be unloaded.
+Loads and unloads plugins based on a configuration string, modifying the
existing list, which can be @code{NULL}. The string has the format
``[-]NAME(OPTIONS)@{:[-]NAME(OPTIONS)@}*''. Prefixing the plugin name with a
``-'' means that the plugin should be unloaded.
@end deftypefun
@deftypefun {struct EXTRACTOR_PluginList *} EXTRACTOR_plugin_add_defaults
(enum EXTRACTOR_Options flags)
@findex EXTRACTOR_plugin_add_defaults
-Loads all of the plugins in the plugin directory. This function is what most
@gnule{} applications should use to setup the plugins.
+Loads all of the plugins in the plugin directory. This function is what most
GNU libextractor applications should use to setup the plugins.
@end deftypefun
@@ -607,14 +581,14 @@
@tindex enum EXTRACTOR_MetaType
@findex EXTRACTOR_metatype_get_max
address@hidden|enum EXTRACTOR_MetaType|} is a C enum which defines a list of
over 100 different types of meta data. The total number can differ between
different @gnule{} releases; the maximum value for the current release can be
obtained using the @verb{|EXTRACTOR_metatype_get_max|} function. All values in
this enumeration are of the form @verb{|EXTRACTOR_METATYPE_XXX|}.
address@hidden|enum EXTRACTOR_MetaType|} is a C enum which defines a list of
over 100 different types of meta data. The total number can differ between
different GNU libextractor releases; the maximum value for the current release
can be obtained using the @verb{|EXTRACTOR_metatype_get_max|} function. All
values in this enumeration are of the form @verb{|EXTRACTOR_METATYPE_XXX|}.
@deftypefun {const char *} EXTRACTOR_metatype_to_string (enum
EXTRACTOR_MetaType type)
@findex EXTRACTOR_metatype_to_string
@cindex gettext
@cindex internationalization
-The function @verb{|EXTRACTOR_metatype_to_string|} can be used to obtain a
short English string @samp{s} describing the meta data type. The string can be
translated into other languages using GNU gettext with the domain set to
@gnule{} (@verb{|dgettext("libextractor", s)|}).
+The function @verb{|EXTRACTOR_metatype_to_string|} can be used to obtain a
short English string @samp{s} describing the meta data type. The string can be
translated into other languages using GNU gettext with the domain set to GNU
libextractor (@verb{|dgettext("libextractor", s)|}).
@end deftypefun
@deftypefun {const char *} EXTRACTOR_metatype_to_description (enum
EXTRACTOR_MetaType type)
@@ -622,7 +596,7 @@
@cindex gettext
@cindex internationalization
-The function @verb{|EXTRACTOR_metatype_to_description|} can be used to obtain
a longer English string @samp{s} describing the meta data type. The
description may be empty if the short description returned by
@code{EXTRACTOR_metatype_to_string} is already comprehensive. The string can
be translated into other languages using GNU gettext with the domain set to
@gnule{} (@verb{|dgettext("libextractor", s)|}).
+The function @verb{|EXTRACTOR_metatype_to_description|} can be used to obtain
a longer English string @samp{s} describing the meta data type. The
description may be empty if the short description returned by
@code{EXTRACTOR_metatype_to_string} is already comprehensive. The string can
be translated into other languages using GNU gettext with the domain set to GNU
libextractor (@verb{|dgettext("libextractor", s)|}).
@end deftypefun
@@ -661,7 +635,7 @@
format information about data
@item data_mime_type
-mime-type of data (not of the original file); can be NULL (if mime-type is not
known);
+mime-type of data (not of the original file); can be @code{NULL} (if mime-type
is not known);
@item data
actual meta-data found
@@ -683,11 +657,11 @@
@cindex threads
@cindex thread-safety
-This is the main function for extracting keywords with @gnule{}. The first
argument is a plugin list which specifies the set of plugins that should be
used for extracting meta data. The @samp{filename} argument is optional and
can be used to specify the name of a file to process. If @samp{filename} is
NULL, then the @samp{data} argument must point to the in-memory data to extract
meta data from. If @samp{filename} is non-NULL, @samp{data} can be NULL. If
@samp{data} is non-null, then @samp{size} is the size of @samp{data} in bytes.
Otherwise @samp{size} should be zero. For each meta data item found, GNU
libextractor will call the @samp{proc} function, passing @samp{proc_cls} as the
first argument to @samp{proc}. The other arguments to @samp{proc} depend on
the specific meta data found.
+This is the main function for extracting keywords with GNU libextractor. The
first argument is a plugin list which specifies the set of plugins that should
be used for extracting meta data. The @samp{filename} argument is optional and
can be used to specify the name of a file to process. If @samp{filename} is
@code{NULL}, then the @samp{data} argument must point to the in-memory data to
extract meta data from. If @samp{filename} is address@hidden, @samp{data} can
be @code{NULL}. If @samp{data} is non-null, then @samp{size} is the size of
@samp{data} in bytes. Otherwise @samp{size} should be zero. For each meta
data item found, GNU libextractor will call the @samp{proc} function, passing
@samp{proc_cls} as the first argument to @samp{proc}. The other arguments to
@samp{proc} depend on the specific meta data found.
@cindex SIGBUS
@cindex bus error
-Meta data extraction should never really fail --- at worst, @gnule{} should
not call @samp{proc} with any meta data. By design, @gnule{} should never crash
or leak memory, even given corrupt files as input. Note however, that running
@gnule{} on a corrupt file system (or incorrectly @verb{|mmap|}ed files) can
result in the operating system sending a SIGBUS (bus error) to the process.
While @gnule{} runs plugins out-of-process, it first maps the file into memory
and then attempts to decompress it. During decompression it is possible to
encounter a SIGBUS. @gnule{} will @emph{not} attempt to catch this signal and
your application is likely to crash. Note again that this should only happen
if the file @emph{system} is corrupt (not if individual files are corrupt). If
this is not acceptable, you might want to consider running @gnule{} itself also
out-of-process (as done, for example, by
@url{http://grothoff.org/christian/doodle/,doodle}).
+Meta data extraction should never really fail --- at worst, GNU libextractor
should not call @samp{proc} with any meta data. By design, GNU libextractor
should never crash or leak memory, even given corrupt files as input. Note
however, that running GNU libextractor on a corrupt file system (or incorrectly
@verb{|mmap|}ed files) can result in the operating system sending a SIGBUS (bus
error) to the process. While GNU libextractor runs plugins out-of-process, it
first maps the file into memory and then attempts to decompress it. During
decompression it is possible to encounter a SIGBUS. GNU libextractor will
@emph{not} attempt to catch this signal and your application is likely to
crash. Note again that this should only happen if the file @emph{system} is
corrupt (not if individual files are corrupt). If this is not acceptable, you
might want to consider running GNU libextractor itself also out-of-process (as
done, for example, by @url{http://grothoff.org/christian/doo
dle/,doo
dle}).
@end deftypefun
@@ -701,7 +675,7 @@
@cindex PHP
@cindex Ruby
address@hidden works immediately with C and C++ code. Bindings for Java, Mono,
Ruby, Perl, PHP and Python are available for download from the main @gnule{}
website. Documentation for these bindings (if available) is part of the
downloads for the respective binding. In all cases, a full installation of the
C library is required before the binding can be installed.
+GNU libextractor works immediately with C and C++ code. Bindings for Java,
Mono, Ruby, Perl, PHP and Python are available for download from the main GNU
libextractor website. Documentation for these bindings (if available) is part
of the downloads for the respective binding. In all cases, a full installation
of the C library is required before the binding can be installed.
@section Java
@@ -763,7 +737,7 @@
@cindex concurrency
@cindex threads
@cindex thread-safety
-This chapter describes various utility functions for @gnule{} usage. All of
the functions are reentrant.
+This chapter describes various utility functions for GNU libextractor usage.
All of the functions are reentrant.
@menu
* Utility Constants::
@@ -961,12 +935,12 @@
@cindex UTF-8
@cindex character set
@findex EXTRACTOR_common_convert_to_utf8
-Various @gnule{} plugins make use of the internal
+Various GNU libextractor plugins make use of the internal
@file{convert.h} header which defines a function
@verb{|EXTRACTOR_common_convert_to_utf8|} which can be used to easily convert
text from
any character set to UTF-8. This conversion is important since the
-linked list of keywords that is returned by @gnule{} is
+linked list of keywords that is returned by GNU libextractor is
expected to contain only UTF-8 strings. Naturally, proper conversion
may not always be possible since some file formats fail to specify the
character set. In that case, it is often better to not convert at
@@ -990,9 +964,9 @@
@chapter Reporting bugs
@cindex bug
address@hidden uses the @url{https://gnunet.org/bugs/,Mantis bugtracking
+GNU libextractor uses the @url{https://gnunet.org/bugs/,Mantis bugtracking
system}. If possible, please report bugs there. You can also e-mail
-the @gnule{} mailinglist at @url{libextractor@@gnu.org}.
+the GNU libextractor mailinglist at @url{libextractor@@gnu.org}.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [GNUnet-SVN] r23705 - Extractor/doc,
gnunet <=