# HG changeset patch # User Rik # Date 1296935478 28800 # Node ID 2186c54528c4930c003dafcdc9c6c4301f6b2fa0 # Parent ab838df8de9049173a5d1d9e9ad3cf8fbbaa8aa9 Overhaul usage strings and man pages for octave, octave-config, mkoctfile. diff --git a/ChangeLog b/ChangeLog --- a/ChangeLog +++ b/ChangeLog @@ -8,6 +8,10 @@ (OCTAVE_API_VERSION_NUMBER): Now 45. (OCTAVE_RELEASE_DATE): Now 2011-01-31. +2010-02-05 Rik + + * mkoctfile.in, octave-config.in: Update usage strings. + 2010-02-04 Rik * configure.ac: Add new doc/icons/Makefile to list of Makefiles to build diff --git a/doc/ChangeLog b/doc/ChangeLog --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2010-02-05 Rik + + * interpreter/mkoctfile.1, interpreter/octave-config.1, + interpreter/octave.1: Overhaul man pages for release 3.4. + 2010-02-04 Rik * icons/octave-logo.ico: Add logo format left out of last changeset. diff --git a/doc/interpreter/mkoctfile.1 b/doc/interpreter/mkoctfile.1 --- a/doc/interpreter/mkoctfile.1 +++ b/doc/interpreter/mkoctfile.1 @@ -17,98 +17,130 @@ .\" . .\" .\" This page was contributed by Dirk Eddelbuettel -.\" -.TH MKOCTFILE 1 "1 November 2002" "GNU Octave" +.\" This page was completely re-written by Rik +.\" -------------------------------------------------------------------- +.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 diff --git a/doc/interpreter/octave-config.1 b/doc/interpreter/octave-config.1 --- a/doc/interpreter/octave-config.1 +++ b/doc/interpreter/octave-config.1 @@ -17,62 +17,65 @@ .\" . .\" .\" This page was contributed by Dirk Eddelbuettel . -.\" -.TH OCTAVE-CONFIG 1 "19 February 2003" "GNU Octave" +.\" This page was completely re-written by Rik +.\" -------------------------------------------------------------------- +.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 diff --git a/doc/interpreter/octave.1 b/doc/interpreter/octave.1 --- 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 .\" . -.\" -.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 - -.fi +John W. Eaton diff --git a/mkoctfile.in b/mkoctfile.in --- 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. diff --git a/octave-config.in b/octave-config.in --- 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.