# HG changeset patch
# User Carnë Draug <carandraug+dev@gmail.com>
# Date 1320513388 0
# Node ID a03e96aa497757eaf88c3c2eee46c32dc78076c1
# Parent  b81e0b3fedabf8d1ef7627f31e34c0e11b186c16
NEWS file of packages now expected to be in the package root. Also support ONEWS file as per GNU the standards. Updated manual accordingly.

diff -r b81e0b3fedab -r a03e96aa4977 doc/interpreter/package.txi
--- a/doc/interpreter/package.txi	Thu Nov 03 12:11:31 2011 +0000
+++ b/doc/interpreter/package.txi	Sat Nov 05 17:16:28 2011 +0000
@@ -179,27 +179,39 @@
 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
+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/DESCRIPTION
+This is a required file containing information about the package.
+@xref{The DESCRIPTION File}, for details on this file.
+
+@item package/ChangeLog
+This is an optional file describing all the changes made to the
+package source files.
+
 @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.
+@code{Categories} keyword in the @file{DESCRIPTION} file.
 @xref{The INDEX File}, for details on this file.
 
+@item package/NEWS
+This is an optional file describing all user-visible changes worth
+mentioning. As this file increases on size, old entries can be moved
+into @file{package/ONEWS}.
+
+@item package/ONEWS
+This is an optional file describing old entries from the @file{NEWS} file.
+
 @anchor{doc-PKG_ADD}
 @item package/PKG_ADD
 An optional file that includes commands that are run when the package
@@ -246,7 +258,7 @@
 @end table
 
 Besides the above mentioned files, a package can also contain on or
-more of the following directories
+more of the following directories:
 
 @noindent
 @table @code
@@ -289,7 +301,7 @@
 @node The DESCRIPTION File
 @subsection The DESCRIPTION File
 
-The @code{DESCRIPTION} file contains various information about the
+The @file{DESCRIPTION} file contains various information about the
 package, such as its name, author, and version.  This file has a very
 simple format
 
@@ -307,7 +319,7 @@
 @end itemize
 
 @noindent
-The following is a simple example of a @code{DESCRIPTION} file
+The following is a simple example of a @file{DESCRIPTION} file
 
 @example
 @group
@@ -334,7 +346,8 @@
 Name of the package.
 
 @item Version
-Version of the package.
+Version of the package.  A package version must be 3 numbers separated
+by a dot.
 
 @item Date
 Date of last update.
@@ -352,7 +365,7 @@
 A one paragraph description of the package.
 
 @item Categories
-Optional keyword describing the package (if no @code{INDEX} file is
+Optional keyword describing the package (if no @file{INDEX} file is
 given this is mandatory).
 
 @item Problems
@@ -385,7 +398,7 @@
 
 @item License
 An optional short description of the used license (e.g., GPL version 3
-or newer).  This is optional since the file @code{COPYING} is mandatory.
+or newer).  This is optional since the file @file{COPYING} is mandatory.
 
 @item SystemRequirements
 These are the external install dependencies of the package and are not
@@ -407,7 +420,7 @@
 
 @noindent
 The developer is free to add additional arguments to the 
-@code{DESCRIPTION} file for their own purposes.  One further detail to
+@file{DESCRIPTION} file for their own purposes.  One further detail to
 aid the packager is that the @code{SystemRequirements} and
 @code{BuildRequires} keywords can have a distribution dependent section,
 and the automatic build process will use these.  An example of the
@@ -425,7 +438,7 @@
 @node The INDEX File
 @subsection The INDEX File
 
-The optional @code{INDEX} file provides a categorical view of the
+The optional @file{INDEX} file provides a categorical view of the
 functions in the package.  This file has a very simple format
 
 @noindent
diff -r b81e0b3fedab -r a03e96aa4977 scripts/miscellaneous/news.m
--- a/scripts/miscellaneous/news.m	Thu Nov 03 12:11:31 2011 +0000
+++ b/scripts/miscellaneous/news.m	Sat Nov 05 17:16:28 2011 +0000
@@ -39,7 +39,7 @@
     if (!any (pos))
       error ("Package '%s' is not installed.", package);
     endif
-    newsfile = fullfile (installed{pos}.dir, "doc", "NEWS");
+    newsfile = fullfile (installed{pos}.dir, "packinfo", "NEWS");
 
   else
     print_usage;
diff -r b81e0b3fedab -r a03e96aa4977 scripts/pkg/pkg.m
--- a/scripts/pkg/pkg.m	Thu Nov 03 12:11:31 2011 +0000
+++ b/scripts/pkg/pkg.m	Sat Nov 05 17:16:28 2011 +0000
@@ -1626,42 +1626,17 @@
     error ("couldn't create packinfo directory: %s", msg);
   endif
 
-  ## Copy DESCRIPTION.
-  [status, output] = copyfile (fullfile (packdir, "DESCRIPTION"), packinfo);
-  if (status != 1)
-    rm_rf (desc.dir);
-    rm_rf (octfiledir);
-    error ("couldn't copy DESCRIPTION: %s", output);
-  endif
+  packinfo_copy_file ("DESCRIPTION", "required", packdir, packinfo, desc, octfiledir);
+  packinfo_copy_file ("COPYING", "required", packdir, packinfo, desc, octfiledir);
 
-  ## Copy COPYING.
-  [status, output] = copyfile (fullfile (packdir, "COPYING"), packinfo);
-  if (status != 1)
-    rm_rf (desc.dir);
-    rm_rf (octfiledir);
-    error ("couldn't copy COPYING: %s", output);
-  endif
-
-  ## If the file ChangeLog exists, copy it.
-  changelog_file = fullfile (packdir, "ChangeLog");
-  if (exist (changelog_file, "file"))
-    [status, output] = copyfile (changelog_file, packinfo);
-    if (status != 1)
-      rm_rf (desc.dir);
-      rm_rf (octfiledir);
-      error ("couldn't copy ChangeLog file: %s", output);
-    endif
-  endif
+  packinfo_copy_file ("NEWS", "optional", packdir, packinfo, desc, octfiledir);
+  packinfo_copy_file ("ONEWS", "optional", packdir, packinfo, desc, octfiledir);
+  packinfo_copy_file ("ChangeLog", "optional", packdir, packinfo, desc, octfiledir);
 
   ## Is there an INDEX file to copy or should we generate one?
   index_file = fullfile (packdir, "INDEX");
   if (exist(index_file, "file"))
-    [status, output] = copyfile (index_file, packinfo);
-    if (status != 1)
-      rm_rf (desc.dir);
-      rm_rf (octfiledir);
-      error ("couldn't copy INDEX file: %s", output);
-    endif
+    packinfo_copy_file ("INDEX", "required", packdir, packinfo, desc, octfiledir);
   else
     try
       write_index (desc, fullfile (packdir, "inst"),
@@ -1674,15 +1649,7 @@
   endif
 
   ## Is there an 'on_uninstall.m' to install?
-  fon_uninstall = fullfile (packdir, "on_uninstall.m");
-  if (exist (fon_uninstall, "file"))
-    [status, output] = copyfile (fon_uninstall, packinfo);
-    if (status != 1)
-      rm_rf (desc.dir);
-      rm_rf (octfiledir);
-      error ("couldn't copy on_uninstall.m: %s", output);
-    endif
-  endif
+  packinfo_copy_file ("on_uninstall.m", "optional", packdir, packinfo, desc, octfiledir);
 
   ## Is there a doc/ directory that needs to be installed?
   docdir = fullfile (packdir, "doc");
@@ -1698,6 +1665,20 @@
   endif
 endfunction
 
+function packinfo_copy_file (filename, requirement, packdir, packinfo, desc, octfiledir)
+  filepath = fullfile (packdir, filename);
+  if (!exist (filepath, "file") && strcmpi (requirement, "optional"))
+    ## do nothing, it's still OK
+  else
+    [status, output] = copyfile (filepath, packinfo);
+    if (status != 1)
+      rm_rf (desc.dir);
+      rm_rf (octfiledir);
+      error ("Couldn't copy %s file: %s", filename, output);
+    endif
+  endif
+endfunction
+
 function finish_installation (desc, packdir, global_install)
   ## Is there a post-install to call?
   if (exist (fullfile (packdir, "post_install.m"), "file"))
