Mercurial > octave-nkf

changeset 9081:c79cf77061b7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
author Rik <rdrider0-list@yahoo.com>
date Thu, 02 Apr 2009 15:25:41 -0700
parents ec41eabf4499
children 2d85197dbae4
files doc/interpreter/bugs.txi doc/interpreter/contrib.txi doc/interpreter/emacs.txi doc/interpreter/install.txi
diffstat 4 files changed, 102 insertions(+), 74 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/bugs.txi	Thu Apr 02 14:45:33 2009 -0700
+++ b/doc/interpreter/bugs.txi	Thu Apr 02 15:25:41 2009 -0700
@@ -204,11 +204,13 @@
 As a last resort, send bug reports on paper to:
 
 @example
+@group
 Octave Bugs c/o John W. Eaton
 University of Wisconsin-Madison
 Department of Chemical Engineering
 1415 Engineering Drive
 Madison, Wisconsin 53706  USA
+@end group
 @end example
 
 @node Bug Reporting
@@ -232,7 +234,7 @@
 despite the bug.  Play it safe and give a specific, complete example.
 
 Keep in mind that the purpose of a bug report is to enable someone to
-fix the bug if it is not known. Always write your bug reports on
+fix the bug if it is not known.  Always write your bug reports on
 the assumption that the bug is not known.
 
 Sometimes people give a few sketchy facts and ask, ``Does this ring a
@@ -335,7 +337,7 @@
 us to fix bugs in Octave, but if you can find a simpler example to
 report @emph{instead} of the original one, that is a convenience.
 Errors in the output will be easier to spot, running under the debugger
-will take less time, etc. Most Octave bugs involve just one function, so
+will take less time, etc.  Most Octave bugs involve just one function, so
 the most straightforward way to simplify an example is to delete all the
 function definitions except the one in which the bug occurs.
 
@@ -408,7 +410,7 @@
 often helpful to indicate where within the function the change was made.
 
 On the other hand, once you have shown people where to find the change,
-you need not explain its purpose. Thus, if you add a new function, all
+you need not explain its purpose.  Thus, if you add a new function, all
 you need to say about it is that it is new.  If you feel that the
 purpose needs explaining, it probably does---but the explanation will be
 much more useful if you put it in comments in the code.
--- a/doc/interpreter/contrib.txi	Thu Apr 02 14:45:33 2009 -0700
+++ b/doc/interpreter/contrib.txi	Thu Apr 02 15:25:41 2009 -0700
@@ -34,28 +34,29 @@
 @node How to Contribute
 @section How to Contribute
 The mailing list for Octave development discussion and sending contributions is
-@email{maintainers@@octave.org}. This concerns the development of Octave core,
-i.e. code that goes to Octave directly. You may consider developing and
+@email{maintainers@@octave.org}.  This concerns the development of Octave core,
+i.e., code that goes to Octave directly.  You may consider developing and
 publishing a package instead; a great place for this is the allied Octave-Forge
-project (@url{http://octave.sf.net}). Note that the Octave project is
+project (@url{http://octave.sf.net}).  Note that the Octave project is
 inherently more conservative and follows narrower rules.
 
 The preferable form of contribution is creating a Mercurial changeset and
-sending it via e-mail to the octave-maintainers mailing list. Mercurial is the
-source code management system currently used to develop Octave. Other forms of 
-contributions (e.g. simple diff patches) are also acceptable, but they slow 
-down the review process. If you want to make more contributions, you should 
+sending it via e-mail to the octave-maintainers mailing list.  Mercurial is the
+source code management system currently used to develop Octave.  Other forms of 
+contributions (e.g., simple diff patches) are also acceptable, but they slow 
+down the review process.  If you want to make more contributions, you should 
 really get familiar with Mercurial.  A good place to start is 
-@url{http://www.selenic.com/mercurial/wiki/index.cgi/Tutorial}. There you will
+@url{http://www.selenic.com/mercurial/wiki/index.cgi/Tutorial}.  There you will
 also find help how to install Mercurial.
 
 A simple contribution sequence could look like this:
 @example
+@group
 hg clone http://www.octave.org/hg/octave
                              # make a local copy of the octave 
                              # source repository
 cd octave
-# change some sources...
+# change some sources@dots{}
 hg commit -m "make Octave the coolest software ever"
                              # commit the changeset into your
                              # local repository
@@ -63,6 +64,7 @@
                              # export the changeset to a diff
                              # file
 # send ../cool.diff via email
+@end group
 @end example
 
 You may want to get familiar with Mercurial queues to manage your changesets.
@@ -71,9 +73,9 @@
 discussion in the maintainers mailing list:
 @example
 hg qnew nasty_bug            # create a new patch 
-# change sources...
+# change sources@dots{}
 hg qref                      # save the changes into the patch
-# change even more...
+# change even more@dots{}
 hg qref -m "solution to nasty bug!"
                              # save again with commit message
 hg export -o ../nasty.diff tip
@@ -83,16 +85,16 @@
                              # and remove the changes from the
                              # source tree
 hg qnew doc_improvements     # create an unrelated patch 
-# change doc sources...
+# change doc sources@dots{}
 hg qref -m "could not find myfav.m in the doc"
                              # save the changes into the patch
 hg export -o ../doc.diff tip
                              # export the second patch
 # send ../doc.diff tip via email
 hg qpop
-# discussion in the maintainers mailing list ...
-hg gpush nasty_bug           # apply the patch again
-# change sources yet again ...
+# discussion in the maintainers mailing list @dots{}
+hg qpush nasty_bug           # apply the patch again
+# change sources yet again @dots{}
 hg qref
 hg export -o ../nasty2.diff tip
 # send ../nasty2.diff via email
@@ -129,19 +131,21 @@
 ## see <http://www.gnu.org/licenses/>.
 @end example
 
-Always include ChangeLog entries in changesets. After making your source
+Always include ChangeLog entries in changesets.  After making your source
 changes, record and briefly describe the changes in the nearest ChangeLog file
-upwards in the directory tree. Use the previous entries as a template. Your
+upwards in the directory tree.  Use the previous entries as a template.  Your
 entry should contain your name and email, and the path to the modified source
-file relative to the parent directory of the ChangeLog file. If there are more
+file relative to the parent directory of the ChangeLog file.  If there are more
 functions in the file, you should also include the name of the modified function
-(in parentheses after file path). Example:
+(in parentheses after file path).  Example:
 
 @example
+@group
 2008-04-02  David Bateman  <dbateman@@free.fr>
 
         * graphics.cc (void gnuplot_backend::close_figure (const
         octave_value&) const): Allow for an input and output stream.
+@end group
 @end example
 
 @noindent
@@ -155,7 +159,7 @@
 @node Octave Sources (m-files)
 @section Octave Sources (m-files)
 
-Don't use tabs. Tabs cause trouble. If you are used to them, set up your editor
+Don't use tabs.  Tabs cause trouble.  If you are used to them, set up your editor
 so that it converts tabs to spaces.  Indent the bodies of the statement blocks.
 Recommended indent is 2 spaces.  When calling functions, put spaces after commas
 and before the calling parentheses, like this:
@@ -174,8 +178,8 @@
 @noindent
 Here, putting spaces after @code{sin}, @code{cos} would result in a parse error.
 In indexing expression, do not put a space after the identifier (this
-differentiates indexing and function calls nicely). The space after comma is not
-necessary if index expressions are simple, i.e. you may write
+differentiates indexing and function calls nicely).  The space after comma is not
+necessary if index expressions are simple, i.e., you may write
 @example
   A(:,i,j)
 @end example
@@ -187,54 +191,61 @@
   A([1:i-1;i+1:n], XI(:,2:n-1))
 @end example
 
-Use lowercase names if possible. Uppercase is acceptable for variable names
-consisting of 1-2 letters. Do not use mixed case names. Function names must be
-lowercase. Function names are global, so choose them wisely.
+Use lowercase names if possible.  Uppercase is acceptable for variable names
+consisting of 1-2 letters.  Do not use mixed case names.  Function names must be
+lowercase.  Function names are global, so choose them wisely.
 
 Always use a specific end-of-block statement (like @code{endif},
-@code{endswitch}) rather than generic @code{end}. Enclose the @code{if},
+@code{endswitch}) rather than generic @code{end}.  Enclose the @code{if},
 @code{while}, @code{until} and @code{switch} conditions in parentheses, 
 like in C: 
 
 @example
+@group
 if (isvector (a))
   s = sum(a);
 endif
+@end group
 @end example
 
 @noindent
 Do not do this, however, with @code{for}:
 
 @example
+@group
 for i = 1:n
   b(i) = sum (a(:,i));
 endfor
+@end group
 @end example
 
 @node C++ Sources
 @section C++ Sources
 
-Don't use tabs. Tabs cause trouble. If you are used to them, set up your editor
-so that it converts tabs to spaces. Format function headers like this:
+Don't use tabs.  Tabs cause trouble.  If you are used to them, set up your editor
+so that it converts tabs to spaces.  Format function headers like this:
 
 @example
+@group
 static bool
 matches_patterns (const string_vector& patterns, int pat_idx,
 		  int num_pat, const std::string& name)
+@end group
 @end example
 
 @noindent
 The function name should start in column 1, and multi-line argument lists should
-be aligned on the first char after the open parenthesis. You should put a space
+be aligned on the first char after the open parenthesis.  You should put a space
 after the left open parenthesis and after commas, for both function definitions
 and function calls.
 
-Recommended indent is 2 spaces. When indenting, indent the statement after
-control structures (like @code{if}, @code{while} etc.). If there is a compound
+Recommended indent is 2 spaces.  When indenting, indent the statement after
+control structures (like @code{if}, @code{while}, etc.). If there is a compound
 statement, indent @i{both} the curly braces and the body of the statement (so
-that the body gets indented by @i{two} indents). Example:
+that the body gets indented by @i{two} indents).  Example:
 
 @example
+@group
 if (have_args)
   @{
     idx.push_back (first_args);
@@ -242,6 +253,7 @@
   @}
 else
   idx.push_back (make_value_list (*p_args, *p_arg_nm, &tmp));
+@end group
 @end example
 
 @noindent
@@ -249,14 +261,16 @@
 clarification. 
 
 Split long expressions in such a way that a continuation line starts with an
-operator rather than identifier. If the split occurs inside braces, continuation
+operator rather than identifier.  If the split occurs inside braces, continuation
 should be aligned with the first char after the innermost braces enclosing the
-split. Example:
+split.  Example:
 
 @example
+@group
 SVD::type type = ((nargout == 0 || nargout == 1)
                   ? SVD::sigma_only
                   : (nargin == 2) ? SVD::economy : SVD::std);
+@end group
 @end example
 
 @noindent
@@ -264,34 +278,36 @@
 readable, even if they are not necessary.  Also, do not hesitate to put extra
 braces anywhere if it improves clarity.
 
-Try declaring variables just before they're needed. Use local variables of
-blocks - it helps optimization. Don't write multi-line variable declaration
-with a single type specification and multiple variables. If the variables don't
-fit on single line, repeat the type specification. Example:
+Try declaring variables just before they're needed.  Use local variables of
+blocks - it helps optimization.  Don't write multi-line variable declaration
+with a single type specification and multiple variables.  If the variables don't
+fit on single line, repeat the type specification.  Example:
 
 @example
+@group
 octave_value retval;
 
 octave_idx_type nr = b.rows ();
 octave_idx_type nc = b.cols ();
 
 double d1, d2;
+@end group
 @end example
 
-Use lowercase names if possible. Uppercase is acceptable for variable names
-consisting of 1-2 letters. Do not use mixed case names.
+Use lowercase names if possible.  Uppercase is acceptable for variable names
+consisting of 1-2 letters.  Do not use mixed case names.
 
-Try to use Octave's types and classes if possible. Otherwise, try to use C++
-standard library. Use of STL containers and algorithms is encouraged.  Use
-templates wisely to reduce code duplication. Avoid comma expressions, labels
-and gotos, and explicit typecasts. If you need to typecast, use the modern C++
-casting operators. In functions, try to reduce the number of @code{return}
+Try to use Octave's types and classes if possible.  Otherwise, try to use C++
+standard library.  Use of STL containers and algorithms is encouraged.  Use
+templates wisely to reduce code duplication.  Avoid comma expressions, labels
+and gotos, and explicit typecasts.  If you need to typecast, use the modern C++
+casting operators.  In functions, try to reduce the number of @code{return}
 statements - use nested @code{if} statements if possible.
 
 @node Other Sources
 @section Other Sources
 Apart from C++ and Octave language (m-files), Octave's sources include files
-written in C, Fortran, M4, perl, unix shell, AWK, texinfo and TeX. There are
+written in C, Fortran, M4, perl, unix shell, AWK, texinfo and TeX.  There are
 not many rules to follow when using these other languages; some of them are
 summarized below.  In any case, the golden rule is: if you modify a source
 file, try to follow any conventions you can detect in the file or other similar
@@ -300,19 +316,19 @@
 For C you should obviously follow all C++ rules that can apply.
 
 If you happen to modify a Fortran file, you should stay within Fortran 77
-with common extensions like @code{END DO}. Currently, we want all sources
+with common extensions like @code{END DO}.  Currently, we want all sources
 to be compilable with the f2c and g77 compilers, without special flags if
-possible. This usually means that non-legacy compilers also accept the sources.
+possible.  This usually means that non-legacy compilers also accept the sources.
 
-The M4 macro language is mainly used for autoconf configuration files. You should
-follow normal M4 rules when contributing to these files. Some M4 files come
+The M4 macro language is mainly used for autoconf configuration files.  You should
+follow normal M4 rules when contributing to these files.  Some M4 files come
 from external source, namely the Autoconf archive
 @url{http://autoconf-archive.cryp.to}.
 
 If you give a code example in the documentation written in texinfo with the 
 @code{@@example} environment, you should be aware that the text within such an 
-environment will not be wrapped. It is recommended that you keep the lines
-short enough to fit on pages in the generated pdf or ps documents. Here is a 
+environment will not be wrapped.  It is recommended that you keep the lines
+short enough to fit on pages in the generated pdf or ps documents.  Here is a 
 ruler (in an @code{@@example} environment) for finding the appropriate line 
 width:
 
--- a/doc/interpreter/emacs.txi	Thu Apr 02 14:45:33 2009 -0700
+++ b/doc/interpreter/emacs.txi	Thu Apr 02 15:25:41 2009 -0700
@@ -196,7 +196,7 @@
 (@code{octave-beginning-of-line}).  If point is in an empty or comment
 line, simply go to its beginning;  otherwise, move backwards to the
 beginning of the first code line which is not inside a continuation
-statement,  i.e., which does not follow a code line ending in @samp{...}
+statement, i.e., which does not follow a code line ending in @samp{...}
 or @samp{\}, or is inside an open parenthesis list.
 
 @item C-c C-e
@@ -241,7 +241,7 @@
 
 @item C-c f
 Insert a function skeleton, prompting for the function's name, arguments
-and return values which have to be entered without parens
+and return values which have to be entered without parentheses
 (@code{octave-insert-defun}).
 
 @item C-c C-h
--- a/doc/interpreter/install.txi	Thu Apr 02 14:45:33 2009 -0700
+++ b/doc/interpreter/install.txi	Thu Apr 02 15:25:41 2009 -0700
@@ -78,7 +78,7 @@
 
 If you use @code{--enable-64}, you must ensure that your Fortran
 compiler generates code with 8 byte signed @code{INTEGER} values, and
-that your BLAS and LAPACK libraries are compiled to use 8 byte
+that your @sc{blas} and @sc{lapack} libraries are compiled to use 8 byte
 signed integers for array dimensions and indexing.
 
 @item --enable-shared
@@ -100,15 +100,15 @@
 your @file{.oct} files.
 
 @item --without-blas
-Compile and use the generic BLAS and LAPACK versions included with
-Octave.  By default, configure first looks for BLAS and LAPACK matrix
-libraries on your system, including optimized BLAS implementations such
+Compile and use the generic @sc{blas} and @sc{lapack} versions included with
+Octave.  By default, configure first looks for @sc{blas} and @sc{lapack} matrix
+libraries on your system, including optimized @sc{blas} implementations such
 as the free ATLAS 3.0, as well as vendor-tuned libraries.  (The use of
-an optimized BLAS will generally result in several-times faster matrix
-operations.)  Only use this option if your system has BLAS/LAPACK
+an optimized @sc{blas} will generally result in several-times faster matrix
+operations.)  Only use this option if your system has @sc{blas}/@sc{lapack}
 libraries that cause problems for some reason.  You can also use
-@code{--with-blas=lib} to specify a particular BLAS library
-@code{-llib} that configure doesn't check for automatically.
+@code{--with-blas=lib} to specify a particular @sc{blas} library
+ that configure doesn't check for automatically.
 
 @item --without-ccolamd
 Don't use CCOLAMD, disable some sparse matrix functionality.
@@ -127,7 +127,7 @@
 Don't use UMFPACK, disable some sparse matrix functionality.
 
 @item --without-fftw
-Use the included fftpack library instead of the FFTW library.
+Use the included @sc{fftpack} library instead of the @sc{fftw} library.
 
 @item --without-glpk
 Don't use the GLPK library for linear programming.
@@ -140,20 +140,20 @@
 for recent MAT file formats.
 
 @item --without-lapack
-Compile and use the generic BLAS and LAPACK versions included with
-Octave.  By default, configure first looks for BLAS and LAPACK matrix
-libraries on your system, including optimized BLAS implementations such
+Compile and use the generic @sc{blas} and @sc{lapack} versions included with
+Octave.  By default, configure first looks for @sc{blas} and @sc{lapack} matrix
+libraries on your system, including optimized @sc{blas} implementations such
 as the free ATLAS 3.0, as well as vendor-tuned libraries.  (The use of
-an optimized BLAS will generally result in several-times faster matrix
-operations.)  Only use this option if your system has BLAS/LAPACK
+an optimized @sc{blas} will generally result in several-times faster matrix
+operations.)  Only use this option if your system has @sc{blas}/@sc{lapack}
 libraries that cause problems for some reason.  You can also use
-@code{--with-blas=lib} to specify a particular BLAS library
-@code{-llib} that configure doesn't check for automatically.
+@code{--with-blas=lib} to specify a particular @sc{blas} library
+ that configure doesn't check for automatically.
 
 @item --without-framework-carbon
 Don't use framework Carbon headers, libraries and specific source code
 for compilation even if the configure test succeeds (the default value
-is @code{--with-framework-carbon}). This is a platform specific configure
+is @code{--with-framework-carbon}).  This is a platform specific configure
 option for Mac systems.
 
 @item --without-framework-opengl
@@ -346,8 +346,10 @@
 or
 
 @example
+@group
 warning: ANSI C++ prohibits conversion from `(int)' 
          to `(...)'
+@end group
 @end example
 
 @noindent
@@ -397,6 +399,7 @@
 of the Sun Fortran compiler.  If you get errors like
 
 @example
+@group
 zgemm.f:
 	zgemm:
 warning: unexpected parent of complex expression subtree
@@ -410,6 +413,7 @@
   expression subtree
 pcc_binval: missing IR_CONV in complex op
 make[2]: *** [zgemm.o] Error 1
+@end group
 @end example
 
 @noindent
@@ -421,10 +425,12 @@
 On NeXT systems, if you get errors like this:
 
 @example
+@group
 /usr/tmp/cc007458.s:unknown:Undefined local 
       symbol LBB7656
 /usr/tmp/cc007458.s:unknown:Undefined local
       symbol LBE7656
+@end group
 @end example
 
 @noindent
@@ -442,9 +448,11 @@
 following functions
 
 @example
+@group
 _tcgetattr
 _tcsetattr
 _tcflow
+@end group
 @end example
 
 @noindent
@@ -452,6 +460,7 @@
 @code{-posix} results in the following undefined symbols.
 
 @example
+@group
 .destructors_used
 .constructors_used
 _objc_msgSend
@@ -459,6 +468,7 @@
 _NXRegisterDefaults
 .objc_class_name_NXStringTable
 .objc_class_name_NXBundle
+@end group
 @end example
 
 One kluge around this problem is to extract @file{termios.o} from