changeset 12341:402456ba3f61

Overhaul usage strings and man pages for octave, octave-config, mkoctfile.
author Rik <octave@nomad.inbox5.com>
date Sat, 05 Feb 2011 11:51:18 -0800
parents d63007ac067a
children 83a37dc986f8
files ChangeLog doc/ChangeLog doc/interpreter/mkoctfile.1 doc/interpreter/octave-config.1 doc/interpreter/octave.1 mkoctfile.in octave-config.in
diffstat 7 files changed, 263 insertions(+), 207 deletions(-) [+]
line wrap: on
line diff
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2010-02-05  Rik  <octave@nomad.inbox5.com>
+
+	* mkoctfile.in, octave-config.in: Update usage strings.
+
 2010-02-04  Rik  <octave@nomad.inbox5.com>
 
 	* configure.ac: Add new doc/icons/Makefile to list of Makefiles to build
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2010-02-05  Rik  <octave@nomad.inbox5.com>
+
+	* interpreter/mkoctfile.1, interpreter/octave-config.1,
+	interpreter/octave.1: Overhaul man pages for release 3.4.
+
 2010-02-04  Rik  <octave@nomad.inbox5.com>
 
 	* icons/octave-logo.ico: Add logo format left out of last changeset.
--- a/doc/interpreter/mkoctfile.1
+++ b/doc/interpreter/mkoctfile.1
@@ -17,98 +17,130 @@
 .\" <http://www.gnu.org/licenses/>.
 .\"
 .\" This page was contributed by Dirk Eddelbuettel <edd@debian.org>
-.\"
-.TH MKOCTFILE 1 "1 November 2002" "GNU Octave"
+.\" This page was completely re-written by Rik <octave@nomad.inbox5.com>
+.\" --------------------------------------------------------------------
+.de Vb \" (V)erbatim (b)egin.  Use fixed width font and no justification
+.ft CW
+.nf
+..
+.de Ve \" (V)erbatim (e)nd.  Return to regular font and justification
+.ft R
+.fi
+..
+.\" --------------------------------------------------------------------
+.TH MKOCTFILE 1 "4 February 2011" "GNU Octave"
 .SH NAME
 mkoctfile \- Compile dynamic-load modules for GNU Octave
 .SH SYNOPSIS
-.BR mkoctfile\  [\-IDIR]\ [\-DDEF]\ [\-lLIB]\ [\-LDIR]\ [\-M|\-\-depend]
-\ [\-c]\ [\-o FILE|\-\-output FILE]\ [\-p VAR|\-\-print VAR]\ [\-s|\-\-strip]
-\ [\-v|\-\-verbose]\ [\-h|\-?|\-\-help]\ \fIfile\fP .\|.\|.
+\fBmkoctfile\fP [\fIOPTION\fP]... file...
 .SH DESCRIPTION
-.PP
-\fImkoctfile\fP is used to compile source C, C++ or Fortran source code in
-dynamically loadable
-.I .oct
-file for
+\fBmkoctfile\fP is used to compile C, C++, or Fortran source code in
+to a dynamically loadable \fI.oct\fP file for
 .BR octave (1).
 .SH OPTIONS
-\fImkoctfile\fP accepts the following options:
 .TP 8
-.B \-IDIR
-Add include directory DIR to compile commands.
-.TP 8
-.B \-DDEF
-Add definition DEF to compiler call.
-.TP 8
-.B \-lLIB
-Add library LIB to link command.
-.TP 8
-.B \-LDIR
-Add library directory DIR to link command.
-.TP 8
-.B \-M|\-\-depend
+\fB\-h\fP, \fB\-?\fP, \fB\-\-help\fP
+Print help message.
+.TP
+.B \-I\fIdir\fP
+Add include directory \fIdir\fP to compile commands.
+.TP
+.B \-idirafter\fIdir\fP
+Add include directory to second include search path after '\fB\-I\fP'.
+.TP
+.B \-D\fIdef\fP
+Add definition \fIdef\fP to compiler command.
+.TP
+.B \-l\fIlib\fP
+Add library \fIlib\fP to link command.
+.TP
+.B \-L\fIdir\fP
+Add library directory \fIdir\fP to link command.
+.TP
+.B \-R\fIdir\fP
+Pass \fB\-R\fP\fIdir\fP to link command.
+.TP
+.B \-g
+Enable debugging option for all compilers.
+.TP
+.B \-pthread
+Add \fB\-pthread\fP to link command.
+.TP
+.B \-W...
+Pass flags to the compiler such as \fB\-Wa,\fP\fIOPTION\fP.
+.TP
+.B \-Wl,...
+Pass flags to the linker such as \fB\-Wl,-rpath=...\fP
+.TP
+.B \-M\fR,\fB \-\-depend
 Generate dependency files (.d) for C and C++ source files.
-.TP 8
+.TP
 .B \-c
 Compile but do not link.
-.TP 8
-.B \-o FILE|\-\-output FILE
-Output file name; default extension is .oct (or .mex if \-\-mex is
+.TP
+.B \-\-link-stand-alone
+Link a stand-alone executable file.
+.TP
+.B \-s\fR,\fB --strip
+Strip the output file.
+.TP
+.B \-\-mex
+Create a MEX file.  Set the default output extension to \fB.mex\fP.
+.TP
+.B \-o \fIfile\fP\fR,\fB \-\-output \fIfile\fP
+Output file name.  Default extension is \fB.oct\fP (or \fB.mex\fP if \-\-mex is
 specified) unless linking a stand-alone executable.
 .TP
-.B \-p VAR|\-\-print VAR
-Print configuration variable VAR.  Recognized variables are:
+.B \-p \fIVAR\fP\fR,\fB \-\-print \fIVAR\fP
+Print configuration variable \fIVAR\fP.  Recognized variables are:
 .RS
-    ALL_CFLAGS                FFTW_LIBS
-    ALL_CXXFLAGS              FLIBS
-    ALL_FFLAGS                FPICFLAG
-    ALL_LDFLAGS               INCFLAGS
-    BLAS_LIBS                 LDFLAGS
-    CC                        LD_CXX
-    CFLAGS                    LD_STATIC_FLAG
-    CPICFLAG                  LFLAGS
-    CPPFLAGS                  LIBCRUFT
-    CXX                       LIBOCTAVE
-    CXXFLAGS                  LIBOCTINTERP
-    CXXPICFLAG                LIBREADLINE
-    DEPEND_EXTRA_SED_PATTERN  LIBS
-    DEPEND_FLAGS              OCTAVE_LIBS
-    DL_LD                     RDYNAMIC_FLAG
-    DL_LDFLAGS                RLD_FLAG
-    F2C                       SED
-    F2CFLAGS                  XTRA_CFLAGS
-    F77                       XTRA_CXXFLAGS
-    FFLAGS
+.Vb
+   ALL_CFLAGS                FFTW3F_LDFLAGS
+   ALL_CXXFLAGS              FFTW3F_LIBS
+   ALL_FFLAGS                FLIBS
+   ALL_LDFLAGS               FPICFLAG
+   BLAS_LIBS                 INCFLAGS
+   CC                        LAPACK_LIBS
+   CFLAGS                    LDFLAGS
+   CPICFLAG                  LD_CXX
+   CPPFLAGS                  LD_STATIC_FLAG
+   CXX                       LFLAGS
+   CXXFLAGS                  LIBCRUFT
+   CXXPICFLAG                LIBOCTAVE
+   DEPEND_EXTRA_SED_PATTERN  LIBOCTINTERP
+   DEPEND_FLAGS              LIBS
+   DL_LD                     OCTAVE_LIBS
+   DL_LDFLAGS                RDYNAMIC_FLAG
+   EXEEXT                    READLINE_LIBS
+   F77                       RLD_FLAG
+   F77_INTEGER_8_FLAG        SED
+   FFLAGS                    XTRA_CFLAGS
+   FFTW3_LDFLAGS             XTRA_CXXFLAGS
+   FFTW3_LIBS
+.Ve
 .RE
-.TP 8
-.B \-\-link-stand-alone
-Link a stand-alone executable file.
-.TP 8
-.B \-\-mex
-Assume we are creating a MEX file.  Set the default output extension
-to .mex.
-.TP 8
-.B \-s|--strip
-Strip the output file.
-.TP 8
-.B \-v|--verbose
+.TP
+.B \-v\fR,\fB --verbose
 Echo commands as they are executed.
-.TP 8
+.TP
 .B file
-Compile or link file. Recognised file types are
+Compile or link file.  Recognized file types are
 .RS
-    .c    C source
-    .cc   C++ source
-    .C    C++ source
-    .cpp  C++ source
-    .f    Fortran source
-    .F    Fortran source
-    .o    object file
-    .a    library file
-.SH SEE ALSO
-.BR octave (1).
+.Vb
+   .c    C source
+   .cc   C++ source
+   .C    C++ source
+   .cpp  C++ source
+   .f    Fortran source (fixed form)
+   .F    Fortran source (fixed form)
+   .f90  Fortran source (free form)
+   .F90  Fortran source (free form)
+   .o    object file
+   .a    library file
+.Ve
 .RE
+.SH "SEE ALSO"
+octave (1).
 .SH AUTHOR
 John W. Eaton <jwe@octave.org>
 
--- a/doc/interpreter/octave-config.1
+++ b/doc/interpreter/octave-config.1
@@ -17,62 +17,65 @@
 .\" <http://www.gnu.org/licenses/>.
 .\"
 .\" This page was contributed by Dirk Eddelbuettel <edd@debian.org>.
-.\" 
-.TH OCTAVE-CONFIG 1 "19 February 2003" "GNU Octave"
+.\" This page was completely re-written by Rik <octave@nomad.inbox5.com>
+.\" --------------------------------------------------------------------
+.de Vb \" (V)erbatim (b)egin.  Use fixed width font and no justification
+.ft CW
+.nf
+..
+.de Ve \" (V)erbatim (e)nd.  Return to regular font and justification
+.ft R
+.fi
+..
+.\" --------------------------------------------------------------------
+.TH OCTAVE-CONFIG 1 "4 February 2011" "GNU Octave"
 .SH NAME
 octave-config - GNU Octave component and library information retrieval
 .SH SYNOPSIS
-.B octave-config
-.RI [ options ]
+\fBoctave-config\fP [\fIOPTION\fP]...
 .SH DESCRIPTION
-.PP
 .B octave-config
-is a tool to obtain directory information for 
-.I .oct
-and 
-.I .m
-files for
+is a tool to obtain directory information for \fB.oct\fP and \fB.m\fP files for
 .BR octave (1).
 .SH OPTIONS
-.B octave-config
-accepts the following options:
 .TP 8
-.B \--m-site-dir
-Display the main directory for local, or site-specific, .m script files.
-.TP 8
-.B \--oct-site-dir
-Display the main directory for local, or site-specific, .oct dynamic-link libraries.
-.TP 8
-.B \-p|\-\-print VAR
-Print the default value of the Octave configuration variable VAR.
+.B \-\-m-site-dir
+Display the main directory for local, or site-specific, \fB.m\fP script files.
+.TP
+.B \-\-oct-site-dir
+Display the main directory for local, or site-specific, \fB.oct\fP dynamic-link libraries.
+.TP
+.B \-p \fIVAR\fP\fR,\fB \-\-print \fIVAR\fP
+Print the default value of the Octave configuration variable \fIVAR\fP.
 Recognized variables are:
 .RS
-    CANONICAL_HOST_TYPE    LOCALFCNFILEDIR    
-    DEFAULT_PAGER          LOCALFCNFILEPATH
-    ARCHLIBDIR             LOCALOCTFILEDIR
-    BINDIR                 LOCALOCTFILEPATH
-    DATADIR                LOCALSTARTUPFILEDIR
-    EXEC_PREFIX            LOCALVERARCHLIBDIR
-    FCNFILEDIR             LOCALVERFCNFILEDIR
-    FCNFILEPATH            LOCALVEROCTFILEDIR
-    IMAGEDIR               MAN1DIR
-    IMAGE_PATH             MAN1EXT
-    INCLUDEDIR             MANDIR
-    INFODIR                OCTFILEDIR
-    INFOFILE               OCTINCLUDEDIR
-    LIBDIR                 OCTLIBDIR
-    LIBEXECDIR             PREFIX
-    LIBEXECDIR             STARTUPFILEDIR
-    LOCALARCHLIBDIR        VERSION
+.Vb
+   API_VERSION             LOCALAPIOCTFILEDIR
+   ARCHLIBDIR              LOCALARCHLIBDIR
+   BINDIR                  LOCALFCNFILEDIR
+   CANONICAL_HOST_TYPE     LOCALOCTFILEDIR
+   DATADIR                 LOCALSTARTUPFILEDIR
+   DATAROOTDIR             LOCALVERARCHLIBDIR
+   DEFAULT_PAGER           LOCALVERFCNFILEDIR
+   EXEC_PREFIX             LOCALVEROCTFILEDIR
+   FCNFILEDIR              MAN1DIR
+   IMAGEDIR                MAN1EXT
+   INCLUDEDIR              MANDIR
+   INFODIR                 OCTFILEDIR
+   INFOFILE                OCTINCLUDEDIR
+   LIBDIR                  OCTLIBDIR
+   LIBEXECDIR              PREFIX
+   LOCALAPIARCHLIBDIR      STARTUPFILEDIR
+   LOCALAPIFCNFILEDIR      VERSION
+.Ve
 .RE
-.TP 8
-.B \-v|\-\-version
+.TP
+.B \-v\fR,\fB \-\-version
 Display the version number of 
 .BR octave (1).
-.TP 8
-.B \-h|-?|--help
-Display a help page about
-.B octave-config
+.TP
+\fB\-h\fP, \fB\-?\fP, \fB\-\-help\fP
+Print help message.
 .SH AUTHOR
 John W. Eaton <jwe@octave.org>
 
--- a/doc/interpreter/octave.1
+++ b/doc/interpreter/octave.1
@@ -15,60 +15,67 @@
 .\" You should have received a copy of the GNU General Public License
 .\" along with Octave; see the file COPYING.  If not, see
 .\" <http://www.gnu.org/licenses/>.
-.\"
-.TH Octave 1 "Jan 8 1996"
+.\" --------------------------------------------------------------------
+.de Vb \" (V)erbatim (b)egin.  Use fixed width font and no justification
+.ft CW
+.nf
+..
+.de Ve \" (V)erbatim (e)nd.  Return to regular font and justification
+.ft R
+.fi
+..
+.\" --------------------------------------------------------------------
+.TH OCTAVE 1 "4 February 2011" "GNU Octave"
 .SH NAME
 octave \- A high-level interactive language for numerical computations.
 .SH SYNOPSIS
-.nf
-octave [options]
-.fi
-.SH OPTIONS
-The complete set of command-line options for octave is available by
-running the command
-.nf
-
-    octave \-\-help
-
-.fi
+\fBoctave\fP [\fIoptions\fP]... [\fIfile\fP]
 .SH DESCRIPTION
 Octave is a high-level language, primarily intended for numerical
 computations.  It provides a convenient command line interface for
 solving linear and nonlinear problems numerically.
+.SH OPTIONS
+The complete set of command-line options for \fBoctave\fP is available by
+running the following command from the shell.
+.Vb
+
+    octave \-\-help
+.Ve
 .SH DOCUMENTATION
 The primary documentation for Octave is written using Texinfo, the GNU
 documentation system, which allows the same source files to be used to
 produce on-line and printed versions of the manual.
 .PP
 You can read the on-line copy of the Octave documentation by issuing
-the command
-.nf
-
-    octave:13> help \-i
+the following command from within \fBoctave\fP.
+.Vb
 
-.fi
-while running Octave interactively, by using the GNU Emacs info mode,
-or by running standalone programs like info or xinfo.
-.SH BUGS
-The best way to submit a bug report for Octave is to use the command
-.nf
-
-     octave:13> bug_report
+    octave:1> doc
 
-.fi
-while running Octave interactively.  This will create a template bug
-report file and start an editor on that file.  Your 
-message will be sent to the bug-octave mailing list
-once you are finished editing the template.
-.PP
-If you are unable to use the bug_report command, send your message
-to the
-.B bug@octave.org
-mailing list by some other means.  Please read the `Bugs' chapter in
-the Octave manual to find out how to submit a bug report that will
-enable the Octave maintainers to fix the problem.
+.Ve
+The Info files may also be read with a stand-alone program such as
+\fBinfo\fP or \fBxinfo\fP.  HTML, Postscript, or PDF versions of the
+documentation are installed on many systems as well.
+.SH BUGS
+The Octave project maintains a bug tracker at http://bugs.octave.org.
+Before submitting a new item please read the instructions at
+http://www.octave.org/bugs.html on how to submit a useful report.
+.SH FILES
+Upon startup Octave looks for four initialization files.  Each file
+may contain any number of valid Octave commands.
+.TP
+\fIoctave-home\fP/share/octave/site/m/startup/octaverc
+Site-wide initialization file which changes options for all users.
+\fIoctave-home\fP is the directory where Octave was installed such as
+\fB/usr/local\fP.
+.TP
+\fIoctave-home\fP/share/octave/\fIversion\fP/m/startup/octaverc
+Site-wide initialization file for Octave version \fIversion\fP.
+.TP
+~/.octaverc
+User's personal initialization file.
+.TP
+\&\.octaverc
+Project-specific initialization file located in the current directory.
 .SH AUTHOR
-.nf
-John W. Eaton
-<jwe@octave.org>
-.fi
+John W. Eaton <jwe@octave.org>
--- a/mkoctfile.in
+++ b/mkoctfile.in
@@ -198,56 +198,61 @@
 
   -DDEF                   Add -DDEF to compile commands.
 
-  -lLIB                   Add library LIB to link command.
+  -lLIB                   Add -lLIB to link command.
 
   -LDIR                   Add -LDIR to link command.
 
+  -RDIR                   Add -RDIR to link command.
+
+  -g                      Enable debugging option for all compilers.
+
+  -pthread                Add -pthread to link command.
+
+  -W...                   Pass flags to the compiler such as -Wa,OPTION.
+
+  -Wl,...                 Pass flags to the linker such as -Wl,-rpath=...
+
   -M, --depend            Generate dependency files (.d) for C and C++
                           source files.
 
-  -RDIR                   Add -RDIR to link command.
+  -c, --compile           Compile, but do not link.
 
-  -Wl,...                 Pass flags though the linker like -Wl,-rpath=...
+  --link-stand-alone      Link a stand-alone executable file.
 
-  -W...                   Pass flags though the compiler like -Wa,OPTION.
+  -s, --strip             Strip output file.
 
-  -c, --compile           Compile, but do not link.
+  --mex                   Create a MEX file.  
+                          Set the default output extension to ".mex".
 
   -o FILE, --output FILE  Output file name.  Default extension is .oct
                           (or .mex if --mex is specified) unless linking
                           a stand-alone executable.
 
-  -g                      Enable debugging options for compilers.
-
   -p VAR, --print VAR     Print configuration variable VAR.  Recognized
                           variables are:
 
-                            ALL_CFLAGS                FLIBS
-                            ALL_CXXFLAGS              FPICFLAG
-                            ALL_FFLAGS                INCFLAGS
-                            ALL_LDFLAGS               LAPACK_LIBS
-                            BLAS_LIBS                 LDFLAGS
-                            CC                        LD_CXX
-                            CFLAGS                    LD_STATIC_FLAG
-                            CPICFLAG                  LFLAGS
-                            CPPFLAGS                  LIBCRUFT
-                            CXX                       LIBOCTAVE
-                            CXXFLAGS                  LIBOCTINTERP
-                            CXXPICFLAG                LIBS
-                            DEPEND_EXTRA_SED_PATTERN  OCTAVE_LIBS
-                            DEPEND_FLAGS              RDYNAMIC_FLAG
-                            DL_LD                     READLINE_LIBS
-                            DL_LDFLAGS                RLD_FLAG
-                            F77                       SED
+                            ALL_CFLAGS                FFTW3F_LDFLAGS
+                            ALL_CXXFLAGS              FFTW3F_LIBS
+                            ALL_FFLAGS                FLIBS
+                            ALL_LDFLAGS               FPICFLAG
+                            BLAS_LIBS                 INCFLAGS
+                            CC                        LAPACK_LIBS
+                            CFLAGS                    LDFLAGS
+                            CPICFLAG                  LD_CXX
+                            CPPFLAGS                  LD_STATIC_FLAG
+                            CXX                       LFLAGS
+                            CXXFLAGS                  LIBCRUFT
+                            CXXPICFLAG                LIBOCTAVE
+                            DEPEND_EXTRA_SED_PATTERN  LIBOCTINTERP
+                            DEPEND_FLAGS              LIBS
+                            DL_LD                     OCTAVE_LIBS
+                            DL_LDFLAGS                RDYNAMIC_FLAG
+                            EXEEXT                    READLINE_LIBS
+                            F77                       RLD_FLAG
+                            F77_INTEGER_8_FLAG        SED
                             FFLAGS                    XTRA_CFLAGS
-                            FFTW_LIBS                 XTRA_CXXFLAGS
-
-  --link-stand-alone      Link a stand-alone executable file.
-
-  --mex                   Assume we are creating a MEX file.  Set the
-                          default output extension to ".mex".
-
-  -s, --strip             Strip output file.
+                            FFTW3_LDFLAGS             XTRA_CXXFLAGS
+                            FFTW3_LIBS
 
   -v, --verbose           Echo commands as they are executed.
 
--- a/octave-config.in
+++ b/octave-config.in
@@ -118,23 +118,23 @@
   -p VAR, --print VAR   Print the value of the given configuration
 		        variable VAR.  Recognized variables are:
 
-			  API_VERSION	         LOCALAPIARCHLIBDIR
-			  CANONICAL_HOST_TYPE	 LOCALAPIFCNFILEDIR
-			  DEFAULT_PAGER	         LOCALAPIOCTFILEDIR
-			  ARCHLIBDIR	         LOCALARCHLIBDIR
-			  BINDIR	         LOCALFCNFILEDIR
-			  DATADIR	         LOCALOCTFILEDIR
-			  EXEC_PREFIX	         LOCALSTARTUPFILEDIR
-			  FCNFILEDIR	         LOCALVERARCHLIBDIR
-			  LOCALVEROCTFILEDIR	 LOCALVERFCNFILEDIR
-			  IMAGEDIR	         MAN1DIR
-			  MAN1EXT	         MANDIR
-			  INCLUDEDIR	         OCTFILEDIR
-			  INFODIR	         OCTINCLUDEDIR
-			  INFOFILE	         OCTLIBDIR
-			  LIBDIR	         PREFIX
-			  LIBEXECDIR	         STARTUPFILEDIR
-			  LIBEXECDIR		 VERSION
+                          API_VERSION             LOCALAPIOCTFILEDIR
+                          ARCHLIBDIR              LOCALARCHLIBDIR
+                          BINDIR                  LOCALFCNFILEDIR
+                          CANONICAL_HOST_TYPE     LOCALOCTFILEDIR
+                          DATADIR                 LOCALSTARTUPFILEDIR
+                          DATAROOTDIR             LOCALVERARCHLIBDIR
+                          DEFAULT_PAGER           LOCALVERFCNFILEDIR
+                          EXEC_PREFIX             LOCALVEROCTFILEDIR
+                          FCNFILEDIR              MAN1DIR
+                          IMAGEDIR                MAN1EXT
+                          INCLUDEDIR              MANDIR
+                          INFODIR                 OCTFILEDIR
+                          INFOFILE                OCTINCLUDEDIR
+                          LIBDIR                  OCTLIBDIR
+                          LIBEXECDIR              PREFIX
+                          LOCALAPIARCHLIBDIR      STARTUPFILEDIR
+                          LOCALAPIFCNFILEDIR      VERSION
 
   -v, --version         Print the Octave version number.