# HG changeset patch # User Carnë Draug # Date 1362278084 0 # Node ID 3a93af21d2062d18d953c6ffc7f3f413b25d4461 # Parent a7669b4d27f6bae27af2545c46e32b15b82f0e11 New function citation() to display citation information (patch #7960) * display_info_file.m: the new function is pretty much the same as news() so this new private function is their common code * citation.m: the new function * help.m: changed to use the private function with common code with citation() * CITATION: new file with citation instructions for Octave core * Makefile.am: add CITATION file into the build system and install into octetc * bootstrap.conf: make sure that the CITATION is present when installing * copy_files.m: make pkg() check and install CITATION files from packages * doc/interpreter/package.txi: document optional CITATION files for packages diff --git a/CITATION b/CITATION new file mode 100644 --- /dev/null +++ b/CITATION @@ -0,0 +1,20 @@ +To cite GNU Octave in publications use: + + John W. Eaton, David Bateman, and Søren Hauberg (2009). GNU Octave version + 3.0.1 manual: a high-level interactive language for numerical computations. + CreateSpace Independent Publishing Platform. ISBN 1441413006, + URL http://www.gnu.org/software/octave/doc/interpreter/ + +A BibTeX entry for LaTeX users is: + + @book{, + author = {John W. Eaton and David Bateman and S\oren Hauberg}, + title = {{GNU Octave} version 3.0.1 manual: a high-level interactive language for numerical computations}, + publisher = {CreateSpace Independent Publishing Platform}, + year = {2009}, + note = {{ISBN} 1441413006}, + url = {http://www.gnu.org/software/octave/doc/interpreter}, + } + +We have invested a lot of time and effort in creating GNU Octave, please cite it +when using it. See also `citation pkgname' for citing Octave packages. diff --git a/Makefile.am b/Makefile.am --- a/Makefile.am +++ b/Makefile.am @@ -37,6 +37,7 @@ INSTALL.OCTAVE \ NEWS \ README \ + CITATION \ bootstrap \ bootstrap.conf \ build-aux/find-files-with-tests.sh \ @@ -132,7 +133,9 @@ mv $@.t $@ .PHONY: ChangeLog -octetc_DATA = NEWS +octetc_DATA = \ + NEWS \ + CITATION DIRS_TO_MAKE = \ $(localfcnfiledir) \ diff --git a/NEWS b/NEWS --- a/NEWS +++ b/NEWS @@ -177,6 +177,9 @@ CC_VERSION (now GCC_VERSION) CXX_VERSION (now GXX_VERSION) + ** A citation command has been added to display information on how to + cite Octave and packages in publications. The package system will + look for and install CITATION files from packages. Summary of important user-visible changes for version 3.6: --------------------------------------------------------- diff --git a/bootstrap.conf b/bootstrap.conf --- a/bootstrap.conf +++ b/bootstrap.conf @@ -156,7 +156,7 @@ ## with building the rest of Octave, and INSTALL, which is linked from ## gnulib/doc/INSTALL by the bootstrap script. - for f in NEWS README COPYING; do + for f in NEWS README COPYING CITATION; do if ! test -f $f; then echo "required file $f is missing" 2>&1 exit 1 diff --git a/doc/interpreter/package.txi b/doc/interpreter/package.txi --- a/doc/interpreter/package.txi +++ b/doc/interpreter/package.txi @@ -182,6 +182,11 @@ following files: @table @code +@item package/CITATION +This is am optional file describing instructions on how to cite +the package for publication. It will be displayed verbatim by the +function @code{citation}. + @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 diff --git a/scripts/miscellaneous/citation.m b/scripts/miscellaneous/citation.m new file mode 100644 --- /dev/null +++ b/scripts/miscellaneous/citation.m @@ -0,0 +1,51 @@ +## Copyright (C) 2013 Carnë Draug +## +## This file is part of Octave. +## +## Octave is free software; you can redistribute it and/or modify it +## under the terms of the GNU General Public License as published by +## the Free Software Foundation; either version 3 of the License, or (at +## your option) any later version. +## +## Octave is distributed in the hope that it will be useful, but +## WITHOUT ANY WARRANTY; without even the implied warranty of +## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +## General Public License for more details. +## +## You should have received a copy of the GNU General Public License +## along with Octave; see the file COPYING. If not, see +## . + +## -*- texinfo -*- +## @deftypefn {Command} {} citation +## @deftypefnx {Command} {} citation @var{package} +## Display instructions to cite GNU Octave and packages in publications. +## +## When called without an argument, displays information on how to cite the core +## GNU Octave system in publications. When given a package name @var{package}, +## display information on to cite it. However, note that some packages may not +## have instructions on how to cite them. +## +## The GNU Octave developers and its active community of package authors have +## invested a lot of time and effort in creating GNU Octave as it is today. +## Please give credit where credit is due and cite GNU Octave and its packages +## when you use them. +## +## @end deftypefn + +## Author: Carnë Draug +## Idea and documentation from R's citation() (also under GPL) + +function citation (package = "octave") + + if (nargin > 1) + print_usage (); + else + display_info_file ("citation", package, "CITATION"); + endif + +endfunction + +%!error citation (1, 2) +%!error citation (1) +%!error citation ("__NOT_A_VALID_PKG_NAME__") diff --git a/scripts/miscellaneous/module.mk b/scripts/miscellaneous/module.mk --- a/scripts/miscellaneous/module.mk +++ b/scripts/miscellaneous/module.mk @@ -1,6 +1,7 @@ FCN_FILE_DIRS += miscellaneous miscellaneous_PRIVATE_FCN_FILES = \ + miscellaneous/private/display_info_file.m \ miscellaneous/private/__xzip__.m miscellaneous_FCN_FILES = \ @@ -10,6 +11,7 @@ miscellaneous/bunzip2.m \ miscellaneous/bzip2.m \ miscellaneous/cast.m \ + miscellaneous/citation.m \ miscellaneous/comma.m \ miscellaneous/compare_versions.m \ miscellaneous/computer.m \ diff --git a/scripts/miscellaneous/news.m b/scripts/miscellaneous/news.m --- a/scripts/miscellaneous/news.m +++ b/scripts/miscellaneous/news.m @@ -17,8 +17,8 @@ ## . ## -*- texinfo -*- -## @deftypefn {Function File} {} news -## @deftypefnx {Function File} {} news (@var{package}) +## @deftypefn {Command} {} news +## @deftypefnx {Command} {} news @var{package} ## Display the current NEWS file for Octave or an installed package. ## ## When called without an argument, display the NEWS file for Octave. @@ -30,42 +30,13 @@ if (nargin > 1) print_usage (); - elseif (! ischar (package)) - error ("news: PACKAGE must be a string"); + else + display_info_file ("news", package, "NEWS"); endif - if (strcmpi (package, "octave")) - octetcdir = octave_config_info ("octetcdir"); - newsfile = fullfile (octetcdir, "NEWS"); - else - installed = pkg ("list"); - names = cellfun (@(x) x.name, installed, "UniformOutput", false); - ## we are nice and let the user use any case on the package name - pos = strcmpi (names, package); - if (!any (pos)) - error ("Package '%s' is not installed.", package); - endif - newsfile = fullfile (installed{pos}.dir, "packinfo", "NEWS"); - endif - - if (! exist (newsfile, "file")) - if (strcmpi (package, "octave")) - error ("news: unable to locate NEWS file"); - else - error ("news: unable to locate NEWS file for package %s", package); - endif - endif - - fid = fopen (newsfile, "r"); - while (ischar (line = fgets (fid))) - puts (line); - endwhile - fclose (fid); - endfunction %!error news (1, 2) -%!error news (1) -%!error news ("__NOT_A_VALID_PKG_NAME__") - +%!error news (1) +%!error news ("__NOT_A_VALID_PKG_NAME__") diff --git a/scripts/miscellaneous/private/display_info_file.m b/scripts/miscellaneous/private/display_info_file.m new file mode 100644 --- /dev/null +++ b/scripts/miscellaneous/private/display_info_file.m @@ -0,0 +1,59 @@ +## Copyright (C) 2013 Carnë Draug +## +## This file is part of Octave. +## +## Octave is free software; you can redistribute it and/or modify it +## under the terms of the GNU General Public License as published by +## the Free Software Foundation; either version 3 of the License, or (at +## your option) any later version. +## +## Octave is distributed in the hope that it will be useful, but +## WITHOUT ANY WARRANTY; without even the implied warranty of +## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +## General Public License for more details. +## +## You should have received a copy of the GNU General Public License +## along with Octave; see the file COPYING. If not, see +## . + +## news() and citation() are very much alike. They both do the same thing, just +## for different files. This function does all the work. + +function display_info_file (func, package, file) + + if (nargin != 3) + print_usage (); + endif + + if (! ischar (package)) + error ("%s: PACKAGE must be a string", func); + endif + + if (strcmpi (package, "octave")) + octetcdir = octave_config_info ("octetcdir"); + filepath = fullfile (octetcdir, file); + else + installed = pkg ("list"); + names = cellfun (@(x) x.name, installed, "UniformOutput", false); + pos = strcmpi (names, package); + if (! any (pos)) + error ("%s: package '%s' is not installed.", func, package); + endif + filepath = fullfile (installed{pos}.dir, "packinfo", file); + endif + + if (! exist (filepath, "file")) + if (strcmpi (package, "octave")) + error ("%s: broken installation -- unable to locate %s file", func, file); + else + error ("%s: unable to locate %s file for package %s", func, file, package); + endif + endif + + fid = fopen (filepath, "r"); + while (ischar (line = fgets (fid))) + puts (line); + endwhile + fclose (fid); + +endfunction diff --git a/scripts/pkg/private/copy_files.m b/scripts/pkg/private/copy_files.m --- a/scripts/pkg/private/copy_files.m +++ b/scripts/pkg/private/copy_files.m @@ -105,6 +105,7 @@ packinfo_copy_file ("DESCRIPTION", "required", packdir, packinfo, desc, octfiledir); packinfo_copy_file ("COPYING", "required", packdir, packinfo, desc, octfiledir); + packinfo_copy_file ("CITATION", "optional", packdir, packinfo, desc, octfiledir); 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);