diff doc/interpreter/tips.txi @ 12546:39ca02387a32

Improve docstrings for a number of functions.
author Rik <octave@nomad.inbox5.com>
date Mon, 28 Mar 2011 16:38:13 -0700
parents fd0a3ac60b0e
children d0b799dafede
line wrap: on
line diff
--- a/doc/interpreter/tips.txi
+++ b/doc/interpreter/tips.txi
@@ -463,16 +463,21 @@
 
 @item
 Avoid using the word ``cause'' (or its equivalents) unnecessarily.
-Instead of, ``Cause Octave to display text in boldface,'' write just
+Instead of, ``Cause Octave to display text in boldface,'' just write
 ``Display text in boldface.''
 
 @item
+Use two spaces between the period marking the end of a sentence and the
+word which opens the next sentence.  This convention has no effect for
+typeset formats like @TeX{}, but improves the readability of the documentation
+in fixed-width environments such as the Info reader.
+
+@item
 Do not start or end a documentation string with whitespace.
 
 @item
-Format the documentation string so that it fits in an Emacs window on an
-80-column screen.  It is a good idea for most lines to be no wider than
-60 characters.
+Format the documentation string so that it fits within an 80-column screen.
+It is a good idea for most lines to be no wider than 60 characters.
 
 However, rather than simply filling the entire documentation string, you
 can make it much more readable by choosing line breaks with care.
@@ -486,6 +491,26 @@
 starting double-quote is not part of the string!
 
 @item
+When choosing variable names try to adhere to the following guidelines.
+
+@table @asis
+@item 
+vectors : x,y,z,t,w
+
+@item
+matrices : A,B,M
+
+@item
+strings : str,s
+
+@item
+filenames : fname
+
+@item
+cells,cellstrs : c,cstr
+@end table
+
+@item
 The documentation string for a variable that is a yes-or-no flag should
 start with words such as ``Nonzero means@dots{}'', to make it clear that
 all nonzero values are equivalent and indicate explicitly what zero and
@@ -650,7 +675,7 @@
 @example
 @group
 -*- texinfo -*-
-@@deftypefn@{Function File@} @{@@var@{a@} =@} fn (@@var@{x@}, @dots{})
+@@deftypefn @{Function File@} @{@@var@{a@} =@} fn (@@var@{x@}, @dots{})
 @@deftypefnx@{Function File@} @{@@var@{a@} =@} fn (@@var@{y@}, @dots{})
 Help text in Texinfo format.
 @@end deftypefn