Adding upstream version 1.0.2.upstream/1.0.2upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 411 insertions, 0 deletions

diff --git a/doc/extension_system.txt b/doc/extension_system.txt
new file mode 100644
index 0000000..72ac282
--- /dev/null
+++ b/doc/extension_system.txt
@@ -0,0 +1,411 @@
+== Inkscape Extensions ==
+
+=== Introduction ===
+
+The extensions system in Inkscape is a way for adding functionality to
+Inkscape, without affecting the core of the program itself.  We want
+Inkscape to follow a core-plus-modules approach similar to that adopted
+by many successful open source projects such as the Linux kernel, Perl,
+Apache, Gimp, and so on.  There are many different types of extension
+mechanisms, including file format conversion tools, filter scripts that
+process SVG, user interface elements that can be added at runtime, and
+so forth.
+
+This proposal defines a design for handling this wide variety of
+extensions in a flexible manner.  This document provides a way to
+understand the extensions system, and how extensions fit into this
+overall system.
+
+Much of the documentation that will be useful for users of the extension
+system is not included in this document, it is autogenerated from the
+source code and placed on the Inkscape webpage.  While this is less
+convenient, it is more correct, and maintained as the source code is
+modified.  Please look aton the Inkscape webpage also.
+
+
+=== Terminology ===
+
+*Extension* - An extension is something that extends the functionality
+ of Inkscape without being directly part of the core.   This implies
+ that it should be easy to remove or add, and nothing in the core should
+ depend on it directly.
+
+*Extension Type* - Establishes the functional interface that the
+ Extension provides, including the types of messages it handles and what
+ is contained in its data structures.
+
+*Extension Implementation* - Defines how the extension is accessed;
+ i.e. through message passing, pipe/exec calls with commandline
+ arguments, direct function calls, etc.
+
+*Plug-in* - An extension that is implemented through a loadable library.
+ This is a .so file on Unix-like systems or a .dll on Win32.  The
+ libraries should not be loaded until they are used.
+
+*Script* - A script is a type of extension that is implemented through
+ an external program that receives and sets SVG data through files and
+ pipes.  This allows Inkscape to use programs that handle SVG but are
+ targeted differently, seamlessly inside of Inkscape.
+
+*Language Binding* - A special type of plug-in that wraps a scripting
+ language interpreter such as Perl, Python, Lisp, etc.  A user
+ interested in programmatic access to Inkscape's internals via one of
+ these languages can install (or create) the relevant Language Binding
+ Plug-in to achieve this.
+
+*INX* - *'INkscape eXtension'* - The filename extension used for XML
+ metadata files that describe each Inkscape Extension.
+
+*Internal Extension* - A part of the Inkscape codebase which uses the
+ extension system in order to make it more modular.  This code is
+ compiled into Inkscape, but appears as an extension to all other code
+ in the codebase.
+
+
+=== Requirements ===
+
+   * Uses a general language binding system so it's easy to add new
+     language binding support.
+   * Allows direct interaction with the document object model including
+     changing.
+   * Allows some limited interaction with the Inkscape UI such as
+     manipulating grids, overlays, etc.
+   * Allows direct interaction with file load/save/export/print
+     subsystem.
+   * Guaranteed to work properly with the undo system, even if the
+     extension is not written carefully.
+   * Well documented so is easy for people to learn how to make new
+     extensions.
+   * Each extension can be implemented, distributed, and managed
+     independently of the core project.
+   * Icons, buttons, and other UI elements for extensions fit seamlessly
+     into main application GUI.
+   * User can easily select which extensions to automatically load into
+     application at startup.
+   * Loading of extensions shall not seriously slow startup time or make
+     a major impact on memory footprint.
+   * Failure of a extension shall not leave the drawing in an
+     inconsistent state.
+   * Main application must gracefully recover from extension crashes or
+     other serious problems with extension execution.
+   * Dependencies for particular extensions must be clearly identified for user if missing.
+
+
+=== Overview ===
+
+Different kinds of extensions can be categorized in two ways.  First,
+but what the extension does: File format converters, printing, SVG
+manipulation, symbol libraries, etc.  Second, by how the extension is
+implemented: command-line scripts, dynamically loaded libraries,
+internal compiled-in code, etc.
+
+The first kind of categorization is called the *Extension Type*.  This
+essentially establishes a calling interface and the set of messages the
+extension must be able to receive and handle.  For example, extensions
+of type Print must have a way to handle 'print' message.
+
+The second is the *Extension Implementation*.  This defines the
+mechanism Inkscape must use for passing messages to the extension.  For
+example, commandline scripts would have messages passed as commandline
+arguments, whereas loadable plug-ins would have the messages passed to
+the plug-in's message handler routine.
+
+The categories of both Extension Types and Extension Implementations are
+left open ended.  This way, if someone comes up with new ideas for ways
+to extend Inkscape that doesn't fit within the existing models, they can
+add these mechanisms in a straightforward fashion.
+
+For the purposes of this document, however, we focus on just the
+following Types and Implementations:
+
+Extension
+  "Input"      - loading various file formats
+  "Output"     - saving as various file formats
+  "Effect"     - apply some sort of change to SVG elements in the doc
+  "Print"      - prints using different drivers or modes
+  "Collection" - a group of objects that have thumbnails and images that
+                 can be used inside a document.  Libraries can be
+                 searchable and may be presented in a hierarchical
+                 structure  
+
+"Extension Implementations"
+  "Internal"   - code that is internal to Inkscape which uses the
+                 extension system for some functionality
+  "Script"     - a cmdline program that takes an SVG document to its
+                 STDIN and emits a modified SVG document to its STDOUT,
+                 with control messages given as commandline parameters. 
+
+  "Plug-in"    - a loadable module with a message handler routine that
+                 receives messages and that operates on the Inkscape API
+                 functions directly. 
+
+=== Extension System Basics ===
+
+Leaving the topic of Types and Implementations aside, we can make some
+generalizations about how all Extensions work, and behaviors or
+attributes that all Extensions share.  This includes how they are
+registered, how they handle preferences, how dependency resolution is
+achieved, and versioning.  These common behaviors are all established
+via a base class that all Extension Types derive from.
+
+=== Extension Base Class ===
+
+The Extension base class holds the attribute data that all extensions
+must have and establishes the base functionality that all extensions
+share.  All extensions have the following properties:
+
+"ID" - A unique identifier for this extension that is used for referring
+to the extension and naming its parameters in the configuration files.
+
+"Name" - The textual name of the extension, it is used for user
+interaction with the extension.  It is used for users to identify the
+extension.
+
+"Parameters" - Each extension keeps a record of all of the parameters
+that it has.  The can be changed internally, through a GUI, or by other
+extensions.  Parameters can be found and adjusted using functions that
+are within the base class.
+
+=== Extension Registry ===
+
+Inkscape maintains a data structure of all the registered extensions.
+This registry can be queried against to retrieve lists of extensions
+meeting various conditions (such as all Input extensions).
+
+The Extension Registry contains all extensions whether or not they
+failed their dependency checking on startup.  This allows for additional
+information to be displayed on the reasoning behind marking the
+extension as disabled.
+
+The registry can be reloaded from the Inkscape GUI while Inkscape is
+running.  This can be used to add new extensions into the system, or
+help debug new extensions.  When the registry is reloaded all extensions
+are first unloaded, then they're specification files are re-read.
+
+=== Handling Preferences ===
+
+Individual extensions can have their own preferences which are used by
+the extension.  These are typically attributes of the operation that can
+be modified by the user through a dialog.  It is also possible to have
+other extensions modify these values when they are using an extension.
+For most extensions, these will be edited by a dialog that relates to
+the preferences of the user.
+
+The preferences themselves are defined in the inx file that describes
+the extension.  In this definition there is the name, the type, and the
+default value.  The types are: boolean, integer, float and string.
+Other types can be developed using these as a basis.  If there is no
+custom value set the default value is used.
+
+When a value is written to a preference for an extension, that value is
+saved in the global preferences for Inkscape using the ID of the module
+as the basis for the naming.  At next use (including after restarting
+the application) this value is used instead of the default.  This allows
+user preferences on a extension to remain persistent throughout uses of
+Inkscape.
+
+=== INX Files ===
+
+The INX file is the description of the Inkscape Extension.  It provides
+all of the information that is used to identify the extension, and
+determine what type of extension it is.  This file is loaded on startup
+of Inkscape, and the objects relating to the extension are created.  All
+extensions have an inx file, but many internal extensions compile this
+file into the codebase (to reduce dependencies).
+
+The INX file also contains information on the dependencies that are
+required for the extension to operate.  These dependencies can be
+everything from required files, required libraries or other extensions
+that help this one.  The dependencies are checked as the file is loaded,
+and an extension is marked as dead if they are not met.  Also
+dependencies can check different versions of particular objects to see
+if they are met.
+
+
+=== Extension Types ===
+
+Each Extension is identified by it's 'Type'.  This determines the type
+of programmatic interface that it adheres to, enabling Inkscape to know
+what functionality it can expect from the extension.
+
+=== Input ===
+
+An input extension provides a way to get data into Inkscape.  This type
+of extension creates a document given a filename.  This is done by using
+the 'open' method within the class.  Also, there is a 'prefs' function
+which will generate a GtkDialog.  This dialog is then used to get any
+settings that the incoming file and extension may use.  This function is
+executed, and the dialog returns, before the open method is called.
+
+There are also several other settings stored in an Input extension.
+This includes information on the type of file the input module can take
+in including its filename extension and mime type.  Also, there is a
+space to store a tooltip for additional information on the file type in
+the file dialog.  Lastly, there is the key of which Output extension is
+recommended for saving this filetype.  This is useful, as there is no
+other direct links between the Input and Output functions, and a user
+expects to be able to open and save without using the 'Save As...'
+dialog.
+
+=== Output ===
+
+An output extension controls how SVG documents are exported from
+Inkscape.  This type of extension creates a file given a document
+object.  This is done using the 'save' method within the class.
+
+The method for how files are exported depends on what type of
+Implementation is used.  For Scripts, the file is first saved as a
+temporary SVG file, and then processed by calling the commandline
+programs to convert it.  For Plug-ins, the document object is passed to
+the extension with a 'save' message and a filename, and the extension
+program performs the file save operation itself.
+
+=== Effect ===
+
+Effect extensions cause a modification of a loaded document.  For
+example, it might add a new shape to the drawing, or change all selected
+objects to be purple with green dotted borders.
+
+=== Print ===
+
+The Print Extension Type is for extensions that interface with printing
+subsystems.  Examples would be Win32, postscript, and GNOME Print.
+
+=== Collection ===
+
+
+=== Creating Extensions ===
+
+In this chapter, we discuss how to create an extension from scratch,
+incorporate into Inkscape, and release it for the general Inkscape
+community to use.  This chapter can be read independently of the rest of
+the document, using the rest as reference material.
+
+=== Selecting an Extension Strategy ===
+
+First of all, you will need to select the method you'll use for creating your extension.
+
+Scripts are the simplest extensions to create, because they work through
+STDIN/STDOUT, so you need to know very little about Inkscape internals
+to make them work.  However, their ability to interact with the Inkscape
+internals is limited compared with other approaches.  For file format
+converters, this is usually fine.  You can also create filters programs
+that take the entire document to its STDIN, process it, and return a
+modified copy to STDOUT.  Some control of the extension is possible via
+its commandline arguments.
+
+One of the nice things about Scripts is that they can be written in any
+language.  It need not even be a scripting language - as long as it
+handles STDIN and STDOUT and uses commandline arguments, you can write
+it however you wish.
+
+Plug-ins are more powerful than Scripts, but require more knowledge of
+Inkscape internals, and must be written according to specific criteria.
+Generally, since these are loaded as dynamic objects, they'll need to be
+written in a language that can generate them, such as C or C++.
+
+The best of both worlds can be available through Language Bindings,
+which are Plug-ins that wrapper a script interpreter.  This enables you
+to call various Inkscape internal routines through your scripting
+language's functions.  If someone has created a Language Binding for
+your language of choice, you're all set, otherwise you'll have to create
+a Plug-in for it.  Language Binding Plug-ins have a few more
+requirements than ordinary Plug-ins, and require a greater amount of
+knowledge of the Inkscape internals, so it can take quite some time to
+do properly.
+
+Internal Extensions are in a way the reverse of a normal Extension, in
+that instead of providing a way to hook into Inkscape from the outside,
+they provide hooks from inside Inkscape.  These are used directly by
+Inkscape, such as in the case of compiled-in printing modules.  Most
+users will never need to write this type of extension, they are pretty
+much for Inkscape core developers only.
+
+=== Writing Your Extension ===
+
+This section provides some guidance and examples for implementing
+different kinds of Extensions.
+
+=== Writing Script Extensions ===
+
+=== Writing Plug-in Extensions ===
+
+=== Writing Language Binding Plug-in Extensions ===
+
+=== Creating an INX File ===
+
+Every extension must have a corresponding *.inx file.  This is an XML
+file that provides Inkscape with information about the module and allows
+it to load the info without needing to access the module itself.  The
+*.inx file contains enough info for Inkscape to set up menu items and
+know what kinds of functionality to expect from the extension.
+
+=== Packaging Your Extension ===
+
+=== Contributing Your Extension to the Inkscape Community ===
+
+Once your extension is complete, you may wish to share it with the
+community.  There are of course no hard and fast rules for how to share
+your work, but this section illustrates some approaches.
+
+=== Listing Your Extension ===
+
+First, you will need to put your extension someplace that others can
+find and download it.  If you have adequate webspace, you could simply
+upload it to your web server.  More typically, you will want to upload
+it to a mirroring system like SourceForge (http://www.sourceforge.net),
+CPAN (http://www.cpan.org), and the like.  The Inkscape project may also
+be willing to host your extension; contact the admins for more info.
+
+It can also be helpful to list your extension with one of the various
+software registries, such as Freshmeat (http://www.freshmeat.net).  You
+should also list it on the Inkscape Wiki site.
+
+=== Announcing Your Extension ===
+
+After posting your extension someplace from which it can be downloaded,
+you should also announce its availability, by sending an email to
+inkscape-announce@lists.sourceforge.net.  You may also want to announce
+it on other related sites; for instance, if you've written a plug-in to
+allow operation of Imagemagick from within Inkscape, it could be a good
+idea to announce it to the Imagemagick list.
+
+
+=== Incorporating Your Extension in to Inkscape ===
+
+Because the intent with the extension system is to break things *out*
+from the core, most extensions should be packaged and distributed
+independently of the main Inkscape distribution.  However, for ease of
+user installation, an extension-pack can be shipped along with the core
+Inkscape package.  Also, certain extensions may be so critical to
+Inkscape operation (such as for printing) that they should be included
+in the core.
+
+If your extension seems like it should be incorporated into the Inkscape
+core, contact the Inkscape developers about this, and discuss how best
+to include it in the distribution with them.
+
+=== Conclusion ===
+
+It is anticipated that the incorporation of this extensions capability
+will bring Inkscape added power and flexibility while avoiding bloating
+the core with cool-but-rarely-used functionality.  Further, it empowers
+users and non-core Inkscape developers to extend the application with
+their own new capabilities, without needing to gain special access and
+acceptance by the project.  Dynamic loading of functionality will also
+allow Inkscape to remain 'lean and mean', loading up functionality on an
+as-needed basis, and conserving memory by unloading functionality when
+it is not needed.
+
+The key point of this design specification is the architectural concept
+of separately identifying an extension's interface type, or 'Extension
+Type', from its implementation method, or 'Extension Implementation'.
+This feature enables Inkscape to be extended in a variety of mechanisms,
+including ways not yet foreseen.
+
+
+=== History and references ===
+
+Base design taken from Ted Gould's Extension System work.
+
+This document originally authored by Bryce Harrington, July 2004