Re: How do you define a new texinfo macro?

[John W. Eaton]

On 10-May-2012, Jordi Gutiérrez Hermoso wrote:

| On 9 May 2012 11:16, John W. Eaton <address@hidden> wrote:
| > On  9-May-2012, John W. Eaton wrote:
| >
| > | On  9-May-2012, Jordi Gutiérrez Hermoso wrote:
| > |
| > | | We have a tiny problem with the docstring for mldivide and
| > | | ldivide. It's using backslashes in a the xcode macro, and
| > | | texinfo has problems with that:
| > | |
| > | |     http://old.nabble.com/backslashes-in-macro-arguments-td28884883.html
| > | |
| > | | A suggested workaround is to define a new macro just for
| > | | backslashes instead of passing backslashes as macro arguments. I
| > | | was unable to figure out how to do this. I tried monkeying the
| > | | xcode macro, but I was unable to make it work, so I thought I'd
| > | | just ask.
| > |
| > | You mean the @address@hidden \\ y}} part of the docstring?
| > |
| > | Hmm, when I do "help mldivide", the backslash from that shows up
| > | but when I look at the Info version of the manual with "doc
| > | mldivide" it does not.  That's odd, since both are supposed to be
| > | processed with makeinfo.
| >
| > Oh, I see the difference now is probably due to mk_doc_cache.m
| > stripping out our user-defined macros before passing the text to
| > makeinfo.  So maybe something like the attached patch will work?
| 
| Oh, thanks, that seemed to work. Well, I mean, something happened, but
| it didn't seem to work as a workaround as advertised in the texinfo
| mailing list. That produced no backslash in plain text mode but
| backslashes in texinfo and pdf output.

How about the following changes?  The backslash change seems to work
for me.  The other larger change for handling the macros consistently
is something that I think is worth doing anyway.  I don't think it was
good that we were handling them separately in three different places.

jwe

# HG changeset patch
# User John W. Eaton <address@hidden>
# Date 1336664928 14400
# Node ID 88e67d58b06b1397c4894c091b2692080f7c06f0
# Parent  4e9dc46d412552df71f45bf38e612dbd817ed5a9
avoid makeinfo problem with backslash in macro argument

* macros.texi (xbackslashchar): New macro.
* data.cc (Fmldivide, Fldivide): Use it.

diff --git a/doc/interpreter/macros.texi b/doc/interpreter/macros.texi
--- a/doc/interpreter/macros.texi
+++ b/doc/interpreter/macros.texi
@@ -16,6 +16,13 @@
 @c along with Octave; see the file COPYING.  If not, see
 @c <http://www.gnu.org/licenses/>.
 
address@hidden FIXME -- someday, we might replace this with @backslashchar, 
which
address@hidden has been added to Texinfo.
+
address@hidden xbackslashchar
+\\
address@hidden macro
+
 @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
diff --git a/src/data.cc b/src/data.cc
--- a/src/data.cc
+++ b/src/data.cc
@@ -5477,7 +5477,7 @@
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} mldivide (@var{x}, @var{y})\n\
 Return the matrix left division of @var{x} and @var{y}.\n\
-This function and @address@hidden \\ y}} are equivalent.\n\
+This function and @address@hidden @xbackslashchar{} y}} are equivalent.\n\
 @seealso{mrdivide, ldivide}\n\
 @end deftypefn")
 {
@@ -5594,7 +5594,7 @@
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} ldivide (@var{x}, @var{y})\n\
 Return the element-by-element left division of @var{x} and @var{y}.\n\
-This function and @address@hidden .\\ y}} are equivalent.\n\
+This function and @address@hidden address@hidden y}} are equivalent.\n\
 @seealso{rdivide, mldivide}\n\
 @end deftypefn")
 {

# HG changeset patch
# User John W. Eaton <address@hidden>
# Date 1336665702 14400
# Node ID 4e9dc46d412552df71f45bf38e612dbd817ed5a9
# Parent  e7c8e31f8e5d7a14c9d446b4fea35de0d701ac4f
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.

diff --git a/build-aux/common.mk b/build-aux/common.mk
--- 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
diff --git a/configure.ac b/configure.ac
--- 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')
diff --git a/doc/interpreter/Makefile.am b/doc/interpreter/Makefile.am
--- 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)
 
diff --git a/doc/interpreter/macros.texi b/doc/interpreter/macros.texi
new file mode 100644
--- /dev/null
+++ b/doc/interpreter/macros.texi
@@ -0,0 +1,58 @@
address@hidden Copyright (C) 2012 John W. Eaton
address@hidden
address@hidden This file is part of Octave.
address@hidden
address@hidden Octave is free software; you can redistribute it and/or modify it
address@hidden under the terms of the GNU General Public License as published 
by the
address@hidden Free Software Foundation; either version 3 of the License, or (at
address@hidden your option) any later version.
address@hidden 
address@hidden Octave is distributed in the hope that it will be useful, but 
WITHOUT
address@hidden ANY WARRANTY; without even the implied warranty of 
MERCHANTABILITY or
address@hidden FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public 
License
address@hidden for more details.
address@hidden 
address@hidden You should have received a copy of the GNU General Public License
address@hidden along with Octave; see the file COPYING.  If not, see
address@hidden <http://www.gnu.org/licenses/>.
+
address@hidden The following macro is used for the on-line help system, but we 
don't
address@hidden want lots of `See also: foo, bar, and baz' strings cluttering the
address@hidden printed manual (that information should be in the supporting 
text for
address@hidden each group of functions and variables).
+
address@hidden seealso {args}
address@hidden
address@hidden 2pt
address@hidden iftex
address@hidden
address@hidden Texinfo @sp should work but in practice produces ugly results 
for HTML.
address@hidden A simple blank line produces the correct behavior. 
address@hidden @sp 1
+
address@hidden ifnottex
address@hidden
address@hidden also:} \args\.
address@hidden macro
+
address@hidden The following macro marks words that aspell should ignore during
address@hidden spellchecking.  Within Texinfo it has no effect as it merely 
replaces
address@hidden the macro call with the argument itself.
+
address@hidden nospell {arg}
+\arg\
address@hidden macro
+
address@hidden The following macro works around a situation where the 
Info/plain text
address@hidden expansion of the @code{XXX} macro is `XXX'.  The use of the 
apostrophe
address@hidden can be confusing if the code segment itself ends with a 
transpose operator.
address@hidden
address@hidden xcode{arg}
+\arg\
address@hidden macro
address@hidden ifinfo
address@hidden
address@hidden xcode{arg}
address@hidden
address@hidden macro
address@hidden ifnotinfo
diff --git a/doc/interpreter/mk_doc_cache.m b/doc/interpreter/mk_doc_cache.m
--- 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
diff --git a/doc/interpreter/octave.texi b/doc/interpreter/octave.texi
--- a/doc/interpreter/octave.texi
+++ b/doc/interpreter/octave.texi
@@ -19,46 +19,7 @@
 \input texinfo
 @setfilename octave.info
 
address@hidden The following macro is used for the on-line help system, but we 
don't
address@hidden want lots of `See also: foo, bar, and baz' strings cluttering the
address@hidden printed manual (that information should be in the supporting 
text for
address@hidden each group of functions and variables).
-
address@hidden seealso {args}
address@hidden
address@hidden 2pt
address@hidden iftex
address@hidden
address@hidden Texinfo @sp should work but in practice produces ugly results 
for HTML.
address@hidden A simple blank line produces the correct behavior. 
address@hidden @sp 1
-
address@hidden ifnottex
address@hidden
address@hidden also:} \args\.
address@hidden macro
-
address@hidden The following macro marks words that aspell should ignore during
address@hidden spellchecking.  Within Texinfo it has no effect as it merely 
replaces
address@hidden the macro call with the argument itself.
-
address@hidden nospell {arg}
-\arg\
address@hidden macro
-
address@hidden The following macro works around a situation where the 
Info/plain text
address@hidden expansion of the @code{XXX} macro is `XXX'.  The use of the 
apostrophe
address@hidden can be confusing if the code segment itself ends with a 
transpose operator.
address@hidden
address@hidden xcode{arg}
-\arg\
address@hidden macro
address@hidden ifinfo
address@hidden
address@hidden xcode{arg}
address@hidden
address@hidden macro
address@hidden ifnotinfo
address@hidden macros.texi
 
 @ifinfo
 @format
diff --git a/run-octave.in b/run-octave.in
--- 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" "$@"
diff --git a/scripts/help/__makeinfo__.m b/scripts/help/__makeinfo__.m
--- 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, '^ address@hidden 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;
diff --git a/src/defaults.cc b/src/defaults.cc
--- 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 ();
diff --git a/src/defaults.in.h b/src/defaults.in.h
--- 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
diff --git a/src/help.cc b/src/help.cc
--- 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\
address@hidden  {Built-in Function} address@hidden =} texi_macros_file ()\n\
address@hidden {Built-in Function} address@hidden =} texi_macros_file 
(@var{new_val})\n\
address@hidden {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\
address@hidden@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\
address@hidden@env{OCTAVE_TEXI_MACROS_FILE}}, or the command line argument\n\
address@hidden 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\
address@hidden, info_program, doc, help, makeinfo_program}\n\
address@hidden deftypefn")
+{
+  return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (texi_macros_file);
+}
+
 DEFUN (info_file, args, nargout,
   "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} address@hidden =} info_file ()\n\
diff --git a/src/help.h b/src/help.h
--- 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;
diff --git a/src/octave.cc b/src/octave.cc
--- 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;