--- a/doc/ChangeLog	Wed Apr 18 16:26:49 2007 +0000
+++ b/doc/ChangeLog	Wed Apr 18 16:40:25 2007 +0000
@@ -1,3 +1,8 @@
+2007-04-18  Søren Hauberg  <hauberg@gmail.com>
+
+	* interpreter/package.texi: New file.
+	* octave/texi: @include it, add it to the menus.
+
 2007-04-18  John W. Eaton  <jwe@octave.org>
 
 	* interpreter/contributors.in: New file.

--- a/doc/interpreter/Makefile.in	Wed Apr 18 16:26:49 2007 +0000
+++ b/doc/interpreter/Makefile.in	Wed Apr 18 16:40:25 2007 +0000
@@ -42,7 +42,7 @@
 	expr.txi finance.txi fn-idx.txi func.txi gpl.txi \
 	grammar.txi image.txi install.txi intro.txi io.txi \
 	linalg.txi matrix.txi nonlin.txi numbers.txi \
-	op-idx.txi optim.txi plot.txi poly.txi preface.txi \
+	op-idx.txi optim.txi package.txi plot.txi poly.txi preface.txi \
 	quad.txi quaternion.txi set.txi signal.txi sparse.txi stats.txi \
 	stmt.txi strings.txi struct.txi system.txi \
 	testfun.txi tips.txi var.txi vr-idx.txi

--- a/doc/interpreter/contributors.in	Wed Apr 18 16:26:49 2007 +0000
+++ b/doc/interpreter/contributors.in	Wed Apr 18 16:40:25 2007 +0000
@@ -125,7 +125,6 @@
 Thorsten Ohl
 Arno Onken
 Luis F. Ortiz
-Luis Ortiz
 Scott Pakin
 Gabriele Pannocchia
 Sylvain Pelissier

--- a/doc/interpreter/octave.texi	Wed Apr 18 16:26:49 2007 +0000
+++ b/doc/interpreter/octave.texi	Wed Apr 18 16:40:25 2007 +0000
@@ -156,6 +156,7 @@
 * Audio Processing::            
 * Quaternions::                 
 * System Utilities::            
+* Packages::            
 * Test and Demo Functions::
 * Tips::                        
 * Trouble::                     If you have trouble installing Octave.
@@ -468,6 +469,16 @@
 * Group Database Functions::    
 * System Information::          
 
+Packages
+
+* Installing and Removing Packages::
+* Using Packages::
+* Administrating Packages::
+* Creating Packages::
+* The DESCRIPTION File::        
+* The INDEX file::              
+* PKG_ADD and PKG_DEL directives::  
+
 Test and Demo Functions
 
 * Test Functions::
@@ -553,6 +564,7 @@
 @include audio.texi
 @include quaternion.texi
 @include system.texi
+@include package.texi
 
 @c maybe add again later, if anyone every writes any really interesting
 @c fun stuff for Octave.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/interpreter/package.txi	Wed Apr 18 16:40:25 2007 +0000
@@ -0,0 +1,468 @@
+@c Copyright (C) 2007 Søren Hauberg
+@c This is part of the Octave manual.
+@c For copying conditions, see the file gpl.texi.
+
+@node Packages
+@chapter Packages
+
+Since Octave is Free Software users are encouraged to share their
+programs amongst each other. To aid this sharing Octave supports the
+installation of extra packages. The `Octave-Forge' project is a
+community-maintained set of packages that can be downloaded and
+installed in Octave. At the time of writing the `Octave-Forge' project
+can be found on-line at @uref{http://octave.sourceforge.net}, but
+since the Internet is an ever-changing place this may not be true at
+the time of reading. Therefore it is recommended to see the Octave
+website for an updated reference.
+
+@menu
+* Installing and Removing Packages::  
+* Using Packages::              
+* Administrating Packages::     
+* Creating Packages::           
+@end menu
+
+@node Installing and Removing Packages
+@section Installing and Removing Packages
+
+Assuming a package is available in the file @code{image-1.0.0.tar.gz}
+it can be installed from the Octave prompt by writing
+
+@example
+pkg install image-1.0.0.tar.gz
+@end example
+
+@noindent
+If the package is installed successfully nothing will be printed on
+the prompt, but if an error occurred during installation it will be
+reported. It is possible to install several packages at once by
+writing several package files after the @code{pkg install} command.
+If a different version of the package is already installed it will
+be removed prior to installing the new package. This makes it easy to
+upgrade and downgrade the version of a package, but makes it
+impossible to have several versions of the same package installed at
+once.
+
+To see which packages are installed type
+
+@example
+@group
+pkg list
+     @print{} Package Name | Version | Installation directory
+     @print{} -------------+---------+-----------------------
+     @print{}        image |   1.0.0 | /home/jwe/octave/image-1.0.0
+@end group
+@end example
+
+@noindent
+In this case only version 1.0.0 of the @code{image} package is
+installed.
+
+It is possible to remove a package from the system using the
+@code{pkg uninstall} command like this
+
+@example
+pkg uninstall image
+@end example
+
+@noindent
+If the package is removed successfully nothing will be printed in the
+prompt, but if an error occurred it will be reported. It should be
+noted that the package file used for installation is not needed for
+removal, and that only the package name as reported by @code{pkg list}
+should be used when removing a package. It is possible to remove
+several packages at once by writing several package names after the
+@code{pkg uninstall} command.
+
+To minimize the amount of code duplication between packages it is
+possible that one package depends on another one. If a package
+depends on another, it will check if that package is installed
+during installation. If it is not, an error will be reported and
+the package will not be installed. This behaviour can be disabled
+by passing the @code{-nodeps} flag to the @code{pkg install}
+command
+
+@example
+pkg install -nodeps my_package_with_dependencies.tar.gz
+@end example
+
+@noindent
+Since the installed package expects its dependencies to be installed
+it may not function correctly. Because of this it is not recommended
+to disable dependency checking.
+
+@node Using Packages
+@section Using Packages
+
+By default installed packages are available from the Octave prompt,
+but it is possible to control this using the @code{pkg load} and 
+@code{pkg unload} commands. The functions from a package can be 
+removed from the Octave path by typing
+
+@example
+pkg unload package_name
+@end example
+
+@noindent
+where @code{package_name} is the name of the package to be removed
+from the path.
+
+In much the same way a package can be added to the Octave path by
+typing
+
+@example
+pkg load package_name
+@end example
+
+@node Administrating Packages
+@section Administrating Packages
+
+On UNIX-like systems it is possible to make both per-user and
+system-wide installations of a package. If the user performing the
+installation is @code{root} the packages will be installed in a
+system-wide directory that defaults to 
+@code{OCTAVE_HOME/share/octave/packages/}. If the user is not 
+@code{root} the default installation directory is
+@code{~/octave/}. Packages will be installed in a subdirectory of the
+installation directory that will be named after the package. It is
+possible to change the installation directory by using the
+@code{pkg prefix} command
+
+@example
+pkg prefix new_installation_directory
+@end example
+
+@noindent
+The current installation directory can be retrieved by typing
+
+@example
+current_installation_directory = pkg prefix
+@end example
+
+To function properly the package manager needs to keep some
+information about the installed packages. For per-user packages this
+information is by default stored in the file @code{~/.octave_packages}
+and for system-wide installations it is stored in
+@code{OCTAVE_HOME/share/octave/octave_packages}. The path to the
+per-user file can be changed with the @code{pkg local_list} command
+
+@example
+pkg local_list /path/to/new_file
+@end example
+
+@noindent
+For system-wide installations this can be changed in the same way
+using the @code{pkg global_list} command. If these commands are
+called without a new path, the current path will be returned.
+
+@node Creating Packages
+@section Creating Packages
+
+Internally a package is simply a gzipped tar file that contains a
+top level directory of any given name. This directory will in the
+following be referred to as @code{package} and may contain the
+following files
+
+@noindent
+@table @code
+@item package/DESCRIPTION
+This is a required file containing information about the package.
+@xref{The DESCRIPTION File}, for details on this file.
+
+@item package/COPYING
+This is a required file containing the license of the package. No
+restrictions is made on the license in general. If however the
+package contains dynamically linked functions the license must be
+compatible with the GNU General Public License.
+
+@item package/INDEX
+This is an optional file describing the functions provided by the
+package. If this file is not given then one with be created
+automatically from the functions in the package and the
+@code{Categories} keyword in the @code{DESCRIPTION} file.
+@xref{The INDEX file}, for details on this file.
+
+@item package/PKG_ADD
+An optional file that includes commands that are run when the package
+is added to the users path. Note that @code{PKG_ADD} directives in the
+source code of the package will also be added to this file by the
+Octave package manager. Note that symbolic links are to be avoided in
+packages, as symbolic links do not exist on some file systems, and so
+a typical use for this file is the replacement of the symbolic link
+
+@example
+ln -s foo.oct bar.oct
+@end example
+
+@noindent
+with an autoload directive like
+
+@example
+autoload ('bar', which ('foo'));
+@end example
+
+@noindent
+@xref{PKG_ADD and PKG_DEL directives}, for details on @code{PKG_ADD}
+directives.
+
+@item package/PKG_DEL
+An optional file that includes commands that are run when the package
+is removed from the users path. Note that @code{PKG_DEL} directives in
+the source code of the package will also be added to this file by the
+Octave package manager. 
+@xref{PKG_ADD and PKG_DEL directives}, for details on @code{PKG_DEL}
+directives.
+
+@item package/pre_install.m
+This is an optional script that is run prior to the installation of a
+package. 
+
+@item package/post_install.m
+This is an optional script that is run after the installation of a
+package. 
+
+@item package/on_uninstall.m
+This is an optional script that is run prior to the removal of a
+package. 
+@end table
+
+Besides the above mentioned files, a package can also contain on or
+more of the following directories
+
+@noindent
+@table @code
+@item package/inst
+An optional directory containing any files that are directly installed
+by the package. Typically this will include any @code{m}-files. 
+
+@item package/src
+An optional directory containing code that must be built prior to the
+packages installation. The Octave package manager will execute
+@code{./configure} in this directory if this script exists, and will
+then call @code{make} if a file @code{Makefile} exists in this
+directory. @code{make install} will however not be called. If a file
+called @code{FILES} exist all files listed there will be copied to the
+@code{inst} directory, so they also will be installed. If the
+@code{FILES} file doesn't exist, @code{src/*.m} and @code{src/*.oct}
+will be copied to the @code{inst} directory.
+
+@item package/doc
+An optional directory containing documentation for the package. The
+files in this directory will be directly installed in a sub-directory
+of the installed package for future reference.
+
+@item package/bin
+An optional directory containing files that will be added to the
+Octave @code{EXEC_PATH} when the package is loaded. This might contain
+external scripts, etc, called by functions within the package.
+@end table
+
+@menu
+* The DESCRIPTION File::        
+* The INDEX file::              
+* PKG_ADD and PKG_DEL directives::  
+@end menu
+
+@node The DESCRIPTION File
+@subsection The DESCRIPTION File
+
+The @code{DESCRIPTION} file contains various information about the
+package, such as it's name, author, and version. This file has a very
+simple format
+
+@noindent
+@itemize
+@item
+Lines starting with @code{#} are comments.
+
+@item
+Lines starting with a blank character are continuations from the 
+previous line.
+
+@item
+Everything else is of the form @code{NameOfOption: ValueOfOption}.
+@end itemize
+
+@noindent
+The following is a simple example of a @code{DESCRIPTION} file
+
+@example
+Name: The name of my package
+Version: 1.0.0
+Date: 2007-18-04
+Author: The name (and possibly email) of the package author.
+Maintainer: The name (and possibly email) of the current package maintainer.
+Title: The title of the package
+Description: A short description of the package. If this description
+ gets too long for one line it can continue on the next by adding a
+ space to the beginning of the following lines.
+License: GPL version 2 or later
+@end example
+
+The package manager currently recognizes the following keywords
+
+@noindent
+@table @code
+@item Name
+Name of the package.
+
+@item Version
+Version of the package.
+
+@item Date
+Date of last update.
+
+@item Author
+Original author of the package.
+
+@item Maintainer
+Maintainer of the package.
+
+@item Title
+A one line description of the package.
+
+@item Description
+A one paragraph description of the package.
+
+@item Categories
+Optional keyword describing the package (if no @code{INDEX} file is
+given this is mandatory).
+
+@item Problems
+Optional list of known problems.
+
+@item Url
+Optional list of homepages related to the package.
+
+@item Autoload
+Optional field that sets the default loading behavior for the package.
+If set to @code{yes}, @code{true} or @code{on}, then Octave will
+automatically load the package when starting. Otherwise the package
+must be manually loaded with the pkg load command. This default
+behavior can be overridden when the package is installed.
+
+@item Depends
+A list of other Octave packages that this package depends on. This can
+include dependencies on particular versions, with a format
+
+@example
+Depends: package (>= 1.0.0)
+@end example
+
+@noindent
+Possible operators are @code{<}, @code{<=}, @code{==}, @code{>=} or
+@code{>}. If the part of the dependency in @code{()} is missing, any
+version of the package is acceptable. Multiple dependencies can be
+defined either as a comma separated list or on separate @code{Depends}
+lines.
+
+@item License
+An optional short description of the used license (e.g. GPL version 2
+or newer). This is optional since the file @code{COPYING} is mandatory.
+
+@item SystemRequirements
+These are the external install dependencies of the package and are not
+checked by the package manager. This is here as a hint to the
+distribution packager. They follows the same conventions as the
+@code{Depends} keyword.
+
+@item BuildRequires
+These are the external build dependencies of the package and are not
+checked by the package manager. This is here as a hint to the
+distribution packager. They follows the same conventions as the 
+@code{Depends} keyword. Note that in general, packaging systems such
+as @code{rpm} or @code{deb} and autoprobe the install dependencies
+from the build dependencies, and therefore the often a
+@code{BuildRequires} dependency removes the need for a
+@code{SystemRequirements} dependency.
+
+@end table
+
+@noindent
+The developer is free to add additional arguments to the 
+@code{DESCRIPTION} file for their own purposes. One further detail to
+aid the packager is that the @code{SystemRequirments} and
+@code{BuildRequires} keywords can have distribution dependent section,
+and the automatic build process will use these. An example of the
+format of this is
+
+@example
+BuildRequires: libtermcap-devel [Mandriva] libtermcap2-devel
+@end example
+
+@noindent
+where the first package name will be used as a default and if the
+RPMs are built on a Mandriva distribution, then the second package
+name will be used instead. 
+
+@node The INDEX file
+@subsection The INDEX file
+
+The optional @code{INDEX} file provides an categorical view of the
+functions in the package. This file has a very simple format
+
+@noindent
+@itemize
+@item Lines beginning with @code{#} are comments.
+
+@item The first non-comment line should look like this
+
+@example
+toolbox >> Toolbox name
+@end example
+
+@item Lines beginning with an alphabetical character indicates a new
+category of functions.
+
+@item Lines starting with a white space character indicate that the
+function names on the line belong to last mentioned category.
+@end itemize
+
+@noindent
+The format can be summarized with the following example
+
+@example
+# A comment
+toolbox >> Toolbox name
+Category Name 1
+ function1 function2 function3
+ function4
+Category Name 2
+ functio2 function5
+@end example
+
+@node PKG_ADD and PKG_DEL directives
+@subsection PKG_ADD and PKG_DEL directives
+
+If the package contains files called @code{PKG_ADD} or @code{PKG_DEL}
+the commands in these files will be executed when the package is
+added or removed from the users path. In some situations such files
+are a bit cumbersome to maintain, so the package manager supports
+automatic creation of such files. If a source file in the package
+contains a @code{PKG_ADD} or @code{PKG_DEL} directive they will be
+added to either the @code{PKG_ADD} or @code{PKG_DEL} files.
+
+In @code{m}-files a @code{PKG_ADD} directive looks like this
+
+@example
+## PKG_ADD: some_octave_command
+@end example
+
+@noindent
+Such lines should be added before the @code{function} keyword.
+In C++ files a @code{PKG_ADD} directive looks like this
+
+@example
+// PKG_ADD: some_octave_command
+@end example
+
+@noindent
+In both cases @code{some_octave_command} should be replaced by the
+command that should be placed in the @code{PKG_ADD} file.
+@code{PKG_DEL} directives work in the same way, except the @code{PKG_ADD}
+keyword is replaced with @code{PKG_DEL} and the commands get added
+to the @code{PKG_DEL} file.
+
+@c Perhaps we should include this line when creating info files?
+@c That way the user can still type 'doc pkg'.
+@c DOCSTRING(pkg)