# HG changeset patch
# User Rik <rik@octave.org>
# Date 1371930232 25200
# Node ID 62fa28af28428a09d1f60ca70836574c2f1c8de3
# Parent  84505f200e05c56e1cc16dd51656a1d4d643db64
doc: add citation() to documentation.

* doc/interpreter/octave.texi: Add new menu entry in Preface chapter.
* doc/interpreter/preface.txi: Add new node "Citing Octave in Publications".
* scripts/miscellaneous/citation.m: Improve docstring.

diff --git a/doc/interpreter/octave.texi b/doc/interpreter/octave.texi
--- a/doc/interpreter/octave.texi
+++ b/doc/interpreter/octave.texi
@@ -200,6 +200,7 @@
 Preface
 
 * Acknowledgements::            
+* Citing Octave in Publications::
 * How You Can Contribute to Octave::  
 * Distribution::                
 
diff --git a/doc/interpreter/preface.txi b/doc/interpreter/preface.txi
--- a/doc/interpreter/preface.txi
+++ b/doc/interpreter/preface.txi
@@ -64,6 +64,7 @@
 
 @menu
 * Acknowledgements::            
+* Citing Octave in Publications::
 * How You Can Contribute to Octave::  
 * Distribution::                
 @end menu
@@ -146,6 +147,20 @@
 This project would not have been possible without the GNU software used
 in and to produce Octave.
 
+@node Citing Octave in Publications
+@unnumberedsec Citing Octave in Publications
+@cindex Citing Octave
+@cindex Citations
+
+In view of the many contributions made by numerous developers over many years
+it is common courtesy to cite Octave in publications when it has been used 
+during the course of research or the preparation of figures.  The
+@code{citation} function can automatically generate a recommended citation
+text for Octave or any of its packages.  See the help text below on how to
+use @code{citation}.
+
+@DOCSTRING(citation)
+
 @node How You Can Contribute to Octave
 @unnumberedsec How You Can Contribute to Octave
 @cindex contributing to Octave
diff --git a/scripts/miscellaneous/citation.m b/scripts/miscellaneous/citation.m
--- a/scripts/miscellaneous/citation.m
+++ b/scripts/miscellaneous/citation.m
@@ -19,12 +19,12 @@
 ## -*- texinfo -*-
 ## @deftypefn  {Command} {} citation
 ## @deftypefnx {Command} {} citation @var{package}
-## Display instructions to cite GNU Octave and packages in publications.
+## Display instructions for citing GNU Octave or its 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.
+## When called without an argument, display information on how to cite the core
+## GNU Octave system.  When given a package name @var{package}, display
+## information on citing the specific named package.  Note that some packages
+## may not yet 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.
@@ -46,6 +46,9 @@
 
 endfunction
 
+
+%% Test input validation
 %!error citation (1, 2)
 %!error <citation: PACKAGE must be a string> citation (1)
 %!error <citation: package .* is not installed> citation ("__NOT_A_VALID_PKG_NAME__")
+