Mercurial > hg > octave-nkf
changeset 14614:4e9dc46d4125
handle texinfo macros consistently in help system and manual
* macros.texi: New file. Move macro definitions here from octave.texi.
* doc/interpreter/Makefile.am (octetc_DATA): Include it in the list.
(doc-cache): Pass macros.texi to mk_doc_cache.m.
* octave.texi: Include macros.texi.
* mk_doc_cache.m, __makeinfo__.m: Copy macros file to makeinfo input
instead of handling macros specially.
* configure.ac (texi_macros_file): New variable.
* build-aux/common.mk (texi_macros_file, do_subst_default_vals):
Substitute it.
* run-octave.in (TEXIMACROSFILE): New variable.
Pass --texi-macros-file to Octave.
* defaults.in.h (OCTAVE_DEFAULT_TEXI_MACROS_FILE): New variable.
* default.cc (set_default_texi_macros_file): New function.
(install_defaults): Call it.
* help.cc (Vtexi_macros_file): New variable.
(Ftexi_macros_file): New function.
* help.h (Vtexi_macros_file): Provide decl.
* octave.cc (TEXI_MACROS_FILE_OPTION): New long option value.
(long_opts): Include --texi-macros-file in the list.
(octave_main): Handle TEXI_MACROS_FILE_OPTION.
author | John W. Eaton <jwe@octave.org> |
---|---|
date | Thu, 10 May 2012 12:01:42 -0400 |
parents | e7c8e31f8e5d |
children | 88e67d58b06b |
files | build-aux/common.mk configure.ac doc/interpreter/Makefile.am doc/interpreter/macros.texi doc/interpreter/mk_doc_cache.m doc/interpreter/octave.texi run-octave.in scripts/help/__makeinfo__.m src/defaults.cc src/defaults.in.h src/help.cc src/help.h src/octave.cc |
diffstat | 13 files changed, 145 insertions(+), 62 deletions(-) [+] |
line wrap: on
line diff
--- a/build-aux/common.mk +++ b/build-aux/common.mk @@ -342,6 +342,9 @@ # The full path to the default doc cache file. doc_cache_file = @doc_cache_file@ +# The full path to the default texi macros file. +texi_macros_file_file = @texi_macros_file@ + # Where to install and expect the info files describing Octave.. infodir = @infodir@ @@ -632,6 +635,7 @@ -e "s|%OCTAVE_PREFIX%|\"${prefix}\"|" \ -e "s|%OCTAVE_API_VERSION%|\"${api_version}\"|" \ -e "s|%OCTAVE_RELEASE%|\"${OCTAVE_RELEASE}\"|" \ + -e "s|%OCTAVE_TEXI_MACROS_FILE%|\"${texi_macros_file}\"|" \ -e "s|%OCTAVE_VERSION%|\"${version}\"|" $(simple_move_if_change_rule) endef
--- a/configure.ac +++ b/configure.ac @@ -118,6 +118,7 @@ OCTAVE_SET_DEFAULT(man1dir, '$(mandir)/man1') OCTAVE_SET_DEFAULT(man1ext, '.1') OCTAVE_SET_DEFAULT(doc_cache_file, '$(octetcdir)/doc-cache') +OCTAVE_SET_DEFAULT(texi_macros_file, '$(octetcdir)/macros.texi') OCTAVE_SET_DEFAULT(infofile, '$(infodir)/octave.info') OCTAVE_SET_DEFAULT(octincludedir, '$(includedir)/octave-$(version)/octave') OCTAVE_SET_DEFAULT(fcnfiledir, '$(datadir)/octave/$(version)/m')
--- a/doc/interpreter/Makefile.am +++ b/doc/interpreter/Makefile.am @@ -179,12 +179,12 @@ @$(GREP) '#define HAVE_UMFPACK 1' $(top_builddir)/config.h > /dev/null || { echo "Documentation creation requires missing UMFPACK library. Cannot package distribution!" ; exit 1; } @$(GREP) '#define HAVE_QHULL 1' $(top_builddir)/config.h > /dev/null || { echo "Documentation creation requires missing QHULL library. Cannot package distribution!" ; exit 1; } -octetc_DATA = doc-cache +octetc_DATA = doc-cache macros.texi DOCSTRING_FILES = $(shell $(srcdir)/find-docstring-files.sh "$(top_srcdir)") doc-cache: $(DOCSTRING_FILES) mk_doc_cache.m - $(top_builddir)/run-octave -f -q -H $(srcdir)/mk_doc_cache.m doc-cache $(DOCSTRING_FILES) || { rm -f doc-cache; exit 1; } + $(top_builddir)/run-octave -f -q -H $(srcdir)/mk_doc_cache.m doc-cache $(srcdir)/macros.texi $(DOCSTRING_FILES) || { rm -f doc-cache; exit 1; } $(MUNGED_TEXI_SRC): $(DOCSTRING_FILES) $(munge_texi_SOURCES)
new file mode 100644 --- /dev/null +++ b/doc/interpreter/macros.texi @@ -0,0 +1,58 @@ +@c Copyright (C) 2012 John W. Eaton +@c +@c This file is part of Octave. +@c +@c Octave is free software; you can redistribute it and/or modify it +@c under the terms of the GNU General Public License as published by the +@c Free Software Foundation; either version 3 of the License, or (at +@c your option) any later version. +@c +@c Octave is distributed in the hope that it will be useful, but WITHOUT +@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +@c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +@c for more details. +@c +@c You should have received a copy of the GNU General Public License +@c along with Octave; see the file COPYING. If not, see +@c <http://www.gnu.org/licenses/>. + +@c The following macro is used for the on-line help system, but we don't +@c want lots of `See also: foo, bar, and baz' strings cluttering the +@c printed manual (that information should be in the supporting text for +@c each group of functions and variables). + +@macro seealso {args} +@iftex +@vskip 2pt +@end iftex +@ifnottex +@c Texinfo @sp should work but in practice produces ugly results for HTML. +@c A simple blank line produces the correct behavior. +@c @sp 1 + +@end ifnottex +@noindent +@strong{See also:} \args\. +@end macro + +@c The following macro marks words that aspell should ignore during +@c spellchecking. Within Texinfo it has no effect as it merely replaces +@c the macro call with the argument itself. + +@macro nospell {arg} +\arg\ +@end macro + +@c The following macro works around a situation where the Info/plain text +@c expansion of the @code{XXX} macro is `XXX'. The use of the apostrophe +@c can be confusing if the code segment itself ends with a transpose operator. +@ifinfo +@macro xcode{arg} +\arg\ +@end macro +@end ifinfo +@ifnotinfo +@macro xcode{arg} +@code{\arg\} +@end macro +@end ifnotinfo
--- a/doc/interpreter/mk_doc_cache.m +++ b/doc/interpreter/mk_doc_cache.m @@ -38,17 +38,20 @@ error ("unable to open %s for reading", file); else tmp = fread (fid, Inf, "*char")'; - ## Strip off header lines - [~, text{i}] = strtok (tmp, doc_delim); + if (isempty (strfind (tmp, doc_delim))) + ## No delimiter, copy verbatim (this is the case for the file + ## containing macro definitions, for example). + text{i} = tmp; + else + ## Strip off header lines + [~, text{i}] = strtok (tmp, doc_delim); + endif endif endfor text = [text{:}, doc_delim]; -## Modify Octave-specific macros before passing to makeinfo +## Strip Texinfo markers and docstring separators. text = regexprep (text, "-\\*- texinfo -\\*-[ \t]*[\r\n]*", ""); -text = regexprep (text, '@seealso *\{([^}]*)\}', "See also: $1."); -text = regexprep (text, '@nospell *\{([^}]*)\}', "$1"); -text = regexprep (text, '@xcode *\{([^}]*)\}', "$1"); text = strrep (text, '@', "@@"); ## Write data to temporary file for input to makeinfo
--- a/doc/interpreter/octave.texi +++ b/doc/interpreter/octave.texi @@ -19,46 +19,7 @@ \input texinfo @setfilename octave.info -@c The following macro is used for the on-line help system, but we don't -@c want lots of `See also: foo, bar, and baz' strings cluttering the -@c printed manual (that information should be in the supporting text for -@c each group of functions and variables). - -@macro seealso {args} -@iftex -@vskip 2pt -@end iftex -@ifnottex -@c Texinfo @sp should work but in practice produces ugly results for HTML. -@c A simple blank line produces the correct behavior. -@c @sp 1 - -@end ifnottex -@noindent -@strong{See also:} \args\. -@end macro - -@c The following macro marks words that aspell should ignore during -@c spellchecking. Within Texinfo it has no effect as it merely replaces -@c the macro call with the argument itself. - -@macro nospell {arg} -\arg\ -@end macro - -@c The following macro works around a situation where the Info/plain text -@c expansion of the @code{XXX} macro is `XXX'. The use of the apostrophe -@c can be confusing if the code segment itself ends with a transpose operator. -@ifinfo -@macro xcode{arg} -\arg\ -@end macro -@end ifinfo -@ifnotinfo -@macro xcode{arg} -@code{\arg\} -@end macro -@end ifnotinfo +@include macros.texi @ifinfo @format
--- a/run-octave.in +++ b/run-octave.in @@ -45,6 +45,7 @@ LOADPATH="$d1_path:$d2_path:$d3_path" IMAGEPATH="$top_srcdir/scripts/image" DOCFILE="$builddir/doc/interpreter/doc-cache" +TEXIMACROSFILE="$top_srcdir/doc/interpreter/macros.texi" INFOFILE="$top_srcdir/doc/interpreter/octave.info" ## Checking for string equality below with prepended x's in order to @@ -70,4 +71,4 @@ exec $builddir/libtool --mode=execute $driver \ "$builddir/src/octave" --no-init-path --path="$LOADPATH" \ --image-path="$IMAGEPATH" --doc-cache-file="$DOCFILE" \ - --info-file="$INFOFILE" "$@" + --texi-macros-file="$TEXIMACROSFILE" --info-file="$INFOFILE" "$@"
--- a/scripts/help/__makeinfo__.m +++ b/scripts/help/__makeinfo__.m @@ -94,18 +94,15 @@ ## Texinfo crashes if @end tex does not appear first on the line. text = regexprep (text, '^ +@end tex', '@end tex', 'lineanchors'); - ## Handle @seealso macro - see_also_pat = '@seealso *\{(.*)\}'; - args = regexp (text, see_also_pat, 'tokens'); - for ii = 1:numel (args) - expanded = fsee_also (strtrim (strsplit (args{ii}{:}, ',', true))); - text = regexprep (text, see_also_pat, expanded, 'once'); - endfor - - ## Handle @nospell macro - text = regexprep (text, '@nospell *\{([^}]*)\}', "$1"); - ## Handle @xcode macro - text = regexprep (text, '@xcode *\{([^}]*)\}', "$1"); + file = texi_macros_file (); + fid = fopen (file, "r"); + if (fid < 0) + error ("unable to open %s for reading", file); + else + macros_text = fread (fid, Inf, "*char")'; + text = cstrcat (macros_text, text); + endif + fclose (fid); if (strcmpi (output_type, "texinfo")) status = 0;
--- a/src/defaults.cc +++ b/src/defaults.cc @@ -294,6 +294,16 @@ } static void +set_default_texi_macros_file (void) +{ + std::string def_file = subst_octave_home (OCTAVE_TEXI_MACROS_FILE); + + std::string env_file = octave_env::getenv ("OCTAVE_TEXI_MACROS_FILE"); + + Vtexi_macros_file = env_file.empty () ? def_file : env_file; +} + +static void set_default_info_file (void) { std::string std_info_file = subst_octave_home (OCTAVE_INFOFILE); @@ -393,6 +403,8 @@ set_default_doc_cache_file (); + set_default_texi_macros_file (); + set_default_info_file (); set_default_info_prog ();
--- a/src/defaults.in.h +++ b/src/defaults.in.h @@ -56,6 +56,10 @@ #define OCTAVE_DOC_CACHE_FILE %OCTAVE_DOC_CACHE_FILE% #endif +#ifndef OCTAVE_TEXI_MACROS_FILE +#define OCTAVE_TEXI_MACROS_FILE %OCTAVE_TEXI_MACROS_FILE% +#endif + #ifndef OCTAVE_EXEC_PREFIX #define OCTAVE_EXEC_PREFIX %OCTAVE_EXEC_PREFIX% #endif
--- a/src/help.cc +++ b/src/help.cc @@ -71,6 +71,11 @@ // (--doc-cache-file file) std::string Vdoc_cache_file; +// Name of the file containing local Texinfo macros that are prepended +// to doc strings before processing. +// (--texi-macros-file) +std::string Vtexi_macros_file; + // Name of the info file specified on command line. // (--info-file file) std::string Vinfo_file; @@ -1291,6 +1296,30 @@ return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (doc_cache_file); } +DEFUN (texi_macros_file, args, nargout, + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {@var{val} =} texi_macros_file ()\n\ +@deftypefnx {Built-in Function} {@var{old_val} =} texi_macros_file (@var{new_val})\n\ +@deftypefnx {Built-in Function} {} texi_macros_file (@var{new_val}, \"local\")\n\ +Query or set the internal variable that specifies the name of the\n\ +file containing Texinfo macros that are prepended to doc strings\n\ +before they are passed to makeinfo. The default value is \n\ +@file{@var{octave-home}/share/octave/@var{version}/etc/macros.texi},\n\ +in which @var{octave-home} is the root directory of the Octave installation,\n\ +and @var{version} is the Octave version number.\n\ +The default value may be overridden by the environment variable\n\ +@w{@env{OCTAVE_TEXI_MACROS_FILE}}, or the command line argument\n\ +@samp{--texi-macros-file NAME}.\n\ +\n\ +When called from inside a function with the \"local\" option, the variable is\n\ +changed locally for the function and any subroutines it calls. The original\n\ +variable value is restored when exiting the function.\n\ +@seealso{lookfor, info_program, doc, help, makeinfo_program}\n\ +@end deftypefn") +{ + return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (texi_macros_file); +} + DEFUN (info_file, args, nargout, "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {@var{val} =} info_file ()\n\
--- a/src/help.h +++ b/src/help.h @@ -36,6 +36,11 @@ // (--doc-cache-file file) extern std::string Vdoc_cache_file; +// Name of the file containing local Texinfo macros that are prepended +// to doc strings before processing. +// (--texi-macros-file) +extern std::string Vtexi_macros_file; + // Name of the info file specified on command line. // (--info-file file) extern std::string Vinfo_file;
--- a/src/octave.cc +++ b/src/octave.cc @@ -150,7 +150,8 @@ #define NO_SITE_FILE_OPTION 11 #define NO_WINDOW_SYSTEM_OPTION 12 #define PERSIST_OPTION 13 -#define TRADITIONAL_OPTION 14 +#define TEXI_MACROS_FILE_OPTION 14 +#define TRADITIONAL_OPTION 15 struct option long_opts[] = { { "braindead", no_argument, 0, TRADITIONAL_OPTION }, @@ -176,6 +177,7 @@ { "persist", no_argument, 0, PERSIST_OPTION }, { "quiet", no_argument, 0, 'q' }, { "silent", no_argument, 0, 'q' }, + { "texi-macros-file", required_argument, 0, TEXI_MACROS_FILE_OPTION }, { "traditional", no_argument, 0, TRADITIONAL_OPTION }, { "verbose", no_argument, 0, 'V' }, { "version", no_argument, 0, 'v' }, @@ -534,6 +536,7 @@ --path PATH, -p PATH Add PATH to head of function search path.\n\ --persist Go interactive after --eval or reading from FILE.\n\ --silent, -q Don't print message at startup.\n\ + --texi-macros-file FILE Use doc cache file FILE.\n\ --traditional Set variables for closer MATLAB compatibility.\n\ --verbose, -V Enable verbose output in some cases.\n\ --version, -v Print version number and exit.\n\ @@ -811,6 +814,11 @@ persist = true; break; + case TEXI_MACROS_FILE_OPTION: + if (optarg) + bind_internal_variable ("texi_macros_file", optarg); + break; + case TRADITIONAL_OPTION: traditional = true; break;