changeset 29117:10a35049bad7

doc: Cleanup Texinfo macros use in documentation. * macros.texi: Delete @xbackslashchar macro which was needed for Texinfo versions < 5.1 (2013 release date). Alphabetize macros. Document macros more clearly. * func.txi, data.cc, error.cc, file-io.cc, regexp.cc, strfns.cc, utils.cc, pt-eval.cc, beep.m, dlmwrite.m, strread.m, textread.m, asctime.m, ctime.m: Replace "@xbackslashchar" with just "@backslashchar". * graphics.cc (Fwaitfor): Replace '\' in @qcode macro with @backslashchar. * input.cc (FPS1): Replace '\' in @qcode macro with @backslashchar. Use single quotes in @example block to avoid "\\" construct. * jsonencode.cc (Fjsonencode): Replace '\' in @qcode macro with @backslashchar. * sysdep.cc (Fwinqueryreg): Replace '\' in @qcode macro with @backslashchar.
author Rik <rik@octave.org>
date Fri, 27 Nov 2020 17:01:47 -0800
parents 14545c8b1b73
children 9d25ef0db8a5
files doc/interpreter/func.txi doc/interpreter/io.txi doc/interpreter/macros.texi libinterp/corefcn/data.cc libinterp/corefcn/error.cc libinterp/corefcn/file-io.cc libinterp/corefcn/graphics.cc libinterp/corefcn/input.cc libinterp/corefcn/jsonencode.cc libinterp/corefcn/regexp.cc libinterp/corefcn/strfns.cc libinterp/corefcn/sysdep.cc libinterp/corefcn/utils.cc libinterp/parse-tree/pt-eval.cc scripts/io/beep.m scripts/io/dlmwrite.m scripts/legacy/strread.m scripts/legacy/textread.m scripts/time/asctime.m scripts/time/ctime.m
diffstat 20 files changed, 79 insertions(+), 76 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/func.txi	Fri Nov 27 13:49:11 2020 -0500
+++ b/doc/interpreter/func.txi	Fri Nov 27 17:01:47 2020 -0800
@@ -115,7 +115,7 @@
 @end example
 
 The @code{printf} statement (@pxref{Input and Output}) simply tells
-Octave to print the string @qcode{"@xbackslashchar{}a"}.  The special character
+Octave to print the string @qcode{"@backslashchar{}a"}.  The special character
 @samp{\a} stands for the alert character (ASCII 7).  @xref{Strings}.
 
 Once this function is defined, you can ask Octave to evaluate it by
--- a/doc/interpreter/io.txi	Fri Nov 27 13:49:11 2020 -0500
+++ b/doc/interpreter/io.txi	Fri Nov 27 17:01:47 2020 -0800
@@ -399,7 +399,7 @@
 performance of printing vector and matrix values.
 
 Implementation Note: For compatibility with @sc{matlab}, escape sequences in
-the template string (e.g., @qcode{"@xbackslashchar{}n"} => newline) are
+the template string (e.g., @qcode{"@backslashchar{}n"} => newline) are
 expanded even when the template string is defined with single quotes.
 
 @DOCSTRING(printf)
--- a/doc/interpreter/macros.texi	Fri Nov 27 13:49:11 2020 -0500
+++ b/doc/interpreter/macros.texi	Fri Nov 27 17:01:47 2020 -0800
@@ -34,7 +34,9 @@
 
 @c The following macro works around the Info/plain text expansion of @code{XXX}
 @c which is `XXX'.  This looks particularly bad when the macro body is
-@c single or double-quoted text, such as a property value `"position"'
+@c single or double-quoted text, such as a property value `"position"'.
+@c The mnemonic to remember this macro is Quoted CODE.
+
 @ifinfo
 @macro qcode{arg}
 \arg\
@@ -46,20 +48,35 @@
 @end macro
 @end ifnotinfo
 
-@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).
+@c The following macro works around the Info/plain text expansion of @code{XXX}
+@c which is `XXX'.  This can be confusing when the macro body itself
+@c ends with a transpose character, such as `x''.
+@c The mnemonic to remember this macro is Transpose CODE.
+
+@ifinfo
+@macro tcode{arg}
+\arg\
+@end macro
+@end ifinfo
+@ifnotinfo
+@macro tcode{arg}
+@code{\arg\}
+@end macro
+@end ifnotinfo
+
+@c The following macro is used for the on-line help system, but we don't want
+@c lots of `See also: foo, bar, and baz' strings cluttering the printed manual
+@c (that information should be in the supporting text for each group of
+@c functions and variables).
 @c
 @c Implementation Note:
 @c For TeX, @vskip produces a nice separation.
 @c For Texinfo, '@sp 1' should work, but in practice produces ugly results
-@c for HTML.  We use a simple blank line to produce the correct
-@c behavior.
+@c for HTML.  We use a simple blank line to produce the correct behavior.
 @c
-@c We use @xseealso now because Texinfo introduced its own @seealso
-@c command.  But instead of modifying all source files, we'll have the
-@c munge-texi script convert @seealso to @xseealso.
+@c The macro is named @xseealso now because Texinfo introduced its own @seealso
+@c command.  But, instead of modifying all source files, the build system uses
+@c the munge-texi script to convert @seealso to @xseealso.
 
 @macro xseealso {args}
 @iftex
@@ -78,26 +95,9 @@
 @end ifinfo
 @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 tcode{arg}
-\arg\
-@end macro
-@end ifinfo
-@ifnotinfo
-@macro tcode{arg}
-@code{\arg\}
-@end macro
-@end ifnotinfo
-
-@c FIXME: someday, when Texinfo 5.X is standard, we might replace this with
-@c @backslashchar, which is a new addition to Texinfo.
-
-@macro xbackslashchar
-\\
-@end macro
+@c ------------------------------------------------------------
+@c non-macro items
+@c ------------------------------------------------------------
 
 @c These may be useful for all, not just for octave.texi.
 @tex
@@ -121,5 +121,6 @@
   \fi
 @end tex
 
-@c Make the apostrophe in code examples cut-and-paste friendly.
+@c Make the apostrophe in code examples cut-and-paste friendly so programmers
+@c can take examples from the Octave manual and directly run them in Octave.
 @codequoteundirected on
--- a/libinterp/corefcn/data.cc	Fri Nov 27 13:49:11 2020 -0500
+++ b/libinterp/corefcn/data.cc	Fri Nov 27 17:01:47 2020 -0800
@@ -6334,7 +6334,7 @@
 @deftypefn {} {} mldivide (@var{x}, @var{y})
 Return the matrix left division of @var{x} and @var{y}.
 
-This function and @w{@tcode{@var{x} @xbackslashchar{} @var{y}}} are equivalent.
+This function and @w{@tcode{@var{x} @backslashchar{} @var{y}}} are equivalent.
 @seealso{mrdivide, ldivide, rdivide}
 @end deftypefn */)
 {
@@ -6461,7 +6461,7 @@
 @deftypefn {} {} ldivide (@var{x}, @var{y})
 Return the element-by-element left division of @var{x} and @var{y}.
 
-This function and @w{@tcode{@var{x} .@xbackslashchar{} @var{y}}} are
+This function and @w{@tcode{@var{x} .@backslashchar{} @var{y}}} are
 equivalent.
 @seealso{rdivide, mldivide, times, plus}
 @end deftypefn */)
--- a/libinterp/corefcn/error.cc	Fri Nov 27 13:49:11 2020 -0500
+++ b/libinterp/corefcn/error.cc	Fri Nov 27 17:01:47 2020 -0800
@@ -1240,11 +1240,11 @@
 which will only stop execution if an error has been found.
 
 Implementation Note: For compatibility with @sc{matlab}, escape
-sequences in @var{template} (e.g., @qcode{"@xbackslashchar{}n"} =>
+sequences in @var{template} (e.g., @qcode{"@backslashchar{}n"} =>
 newline) are processed regardless of whether @var{template} has been defined
 with single quotes, as long as there are two or more input arguments.  To
 disable escape sequence expansion use a second backslash before the sequence
-(e.g., @qcode{"@xbackslashchar{}@xbackslashchar{}n"}) or use the
+(e.g., @qcode{"@backslashchar{}@backslashchar{}n"}) or use the
 @code{regexptranslate} function.
 @seealso{warning, lasterror}
 @end deftypefn */)
@@ -1453,11 +1453,11 @@
 @qcode{"off"}.
 
 Implementation Note: For compatibility with @sc{matlab}, escape sequences in
-@var{template} (e.g., @qcode{"@xbackslashchar{}n"} => newline) are processed
+@var{template} (e.g., @qcode{"@backslashchar{}n"} => newline) are processed
 regardless of whether @var{template} has been defined with single quotes, as
 long as there are two or more input arguments.  To disable escape sequence
 expansion use a second backslash before the sequence (e.g.,
-@qcode{"@xbackslashchar{}@xbackslashchar{}n"}) or use the
+@qcode{"@backslashchar{}@backslashchar{}n"}) or use the
 @code{regexptranslate} function.
 @seealso{warning_ids, lastwarn, error}
 @end deftypefn */)
--- a/libinterp/corefcn/file-io.cc	Fri Nov 27 13:49:11 2020 -0500
+++ b/libinterp/corefcn/file-io.cc	Fri Nov 27 17:01:47 2020 -0800
@@ -834,7 +834,7 @@
 The optional output returns the number of bytes written to the file.
 
 Implementation Note: For compatibility with @sc{matlab}, escape sequences in
-the template string (e.g., @qcode{"@xbackslashchar{}n"} => newline) are
+the template string (e.g., @qcode{"@backslashchar{}n"} => newline) are
 expanded even when the template string is defined with single quotes.
 @seealso{fputs, fdisp, fwrite, fscanf, printf, sprintf, fopen}
 @end deftypefn */)
@@ -857,7 +857,7 @@
 @end ifclear
 
 Implementation Note: For compatibility with @sc{matlab}, escape sequences in
-the template string (e.g., @qcode{"@xbackslashchar{}n"} => newline) are
+the template string (e.g., @qcode{"@backslashchar{}n"} => newline) are
 expanded even when the template string is defined with single quotes.
 @seealso{fprintf, sprintf, scanf}
 @end deftypefn */)
@@ -934,7 +934,7 @@
 string, automatically sized to hold all of the items converted.
 
 Implementation Note: For compatibility with @sc{matlab}, escape sequences in
-the template string (e.g., @qcode{"@xbackslashchar{}n"} => newline) are
+the template string (e.g., @qcode{"@backslashchar{}n"} => newline) are
 expanded even when the template string is defined with single quotes.
 @seealso{printf, fprintf, sscanf}
 @end deftypefn */)
@@ -1446,12 +1446,12 @@
 @item @qcode{"EndOfLine"}
 @var{value} can be either an empty or one character specifying the
 end-of-line character, or the pair
-@qcode{"@xbackslashchar{}r@xbackslashchar{}n"} (CRLF).
+@qcode{"@backslashchar{}r@backslashchar{}n"} (CRLF).
 In the latter case, any of
-@qcode{"@xbackslashchar{}r"}, @qcode{"@xbackslashchar{}n"} or
-@qcode{"@xbackslashchar{}r@xbackslashchar{}n"} is counted as a (single)
+@qcode{"@backslashchar{}r"}, @qcode{"@backslashchar{}n"} or
+@qcode{"@backslashchar{}r@backslashchar{}n"} is counted as a (single)
 newline.  If no value is given,
-@qcode{"@xbackslashchar{}r@xbackslashchar{}n"} is used.
+@qcode{"@backslashchar{}r@backslashchar{}n"} is used.
 @c If set to "" (empty string) EOLs are ignored as delimiters and added
 @c to whitespace.
 
@@ -1489,7 +1489,7 @@
 @c Note: the next line specifically has a newline which generates a space
 @c       in the output of qcode, but keeps the next line < 80 characters.
 @qcode{"
-@xbackslashchar{}b@xbackslashchar{}r@xbackslashchar{}n@xbackslashchar{}t"}
+@backslashchar{}b@backslashchar{}r@backslashchar{}n@backslashchar{}t"}
 (note the space).  Unless whitespace is set to @qcode{""} (empty) AND at
 least one @qcode{"%s"} format conversion specifier is supplied, a space is
 always part of whitespace.
--- a/libinterp/corefcn/graphics.cc	Fri Nov 27 13:49:11 2020 -0500
+++ b/libinterp/corefcn/graphics.cc	Fri Nov 27 17:01:47 2020 -0800
@@ -14350,7 +14350,7 @@
 not an integer, it is truncated towards 0.
 
 To define a condition on a property named @qcode{"timeout"}, use the string
-@qcode{'\timeout'} instead.
+@qcode{'@backslashchar{}timeout'} instead.
 
 In all cases, typing CTRL-C stops program execution immediately.
 @seealso{waitforbuttonpress, isequal}
--- a/libinterp/corefcn/input.cc	Fri Nov 27 13:49:11 2020 -0500
+++ b/libinterp/corefcn/input.cc	Fri Nov 27 17:01:47 2020 -0800
@@ -1396,11 +1396,11 @@
 When executing interactively, Octave displays the primary prompt when it is
 ready to read a command.
 
-The default value of the primary prompt string is @qcode{'octave:\#> '}.
-To change it, use a command like
+The default value of the primary prompt string is
+@qcode{'octave:@backslashchar{}#> '}.  To change it, use a command like
 
 @example
-PS1 ("\\u@@\\H> ")
+PS1 ('\u@@\H> ')
 @end example
 
 @noindent
--- a/libinterp/corefcn/jsonencode.cc	Fri Nov 27 13:49:11 2020 -0500
+++ b/libinterp/corefcn/jsonencode.cc	Fri Nov 27 17:01:47 2020 -0800
@@ -474,11 +474,12 @@
 classdef objects are first converted to structs and then encoded.
 
 @item
-To preserve escape characters (e.g., @qcode{"\n"}), use single-quoted strings.
+To preserve escape characters (e.g., @qcode{"@backslashchar{}n"}), use
+single-quoted strings.
 
 @item
-Every character after the null character (@qcode{"\0"}) in a double-quoted
-string will be dropped during encoding.
+Every character after the null character (@qcode{"@backslashchar{}0"}) in a
+double-quoted string will be dropped during encoding.
 
 @item
 Encoding and decoding an array is not guaranteed to preserve the dimensions
--- a/libinterp/corefcn/regexp.cc	Fri Nov 27 13:49:11 2020 -0500
+++ b/libinterp/corefcn/regexp.cc	Fri Nov 27 17:01:47 2020 -0800
@@ -752,10 +752,10 @@
 @end table
 
 Implementation Note: For compatibility with @sc{matlab}, escape sequences
-in @var{pat} (e.g., @qcode{"@xbackslashchar{}n"} => newline) are expanded
+in @var{pat} (e.g., @qcode{"@backslashchar{}n"} => newline) are expanded
 even when @var{pat} has been defined with single quotes.  To disable
 expansion use a second backslash before the escape sequence (e.g.,
-"@xbackslashchar{}@xbackslashchar{}n") or use the @code{regexptranslate}
+"@backslashchar{}@backslashchar{}n") or use the @code{regexptranslate}
 function.
 
 The outputs of @code{regexp} default to the order given below
@@ -1424,10 +1424,10 @@
 @end table
 
 Implementation Note: For compatibility with @sc{matlab}, escape sequences
-in @var{pat} (e.g., @qcode{"@xbackslashchar{}n"} => newline) are expanded
+in @var{pat} (e.g., @qcode{"@backslashchar{}n"} => newline) are expanded
 even when @var{pat} has been defined with single quotes.  To disable
 expansion use a second backslash before the escape sequence (e.g.,
-"@xbackslashchar{}@xbackslashchar{}n") or use the @code{regexptranslate}
+"@backslashchar{}@backslashchar{}n") or use the @code{regexptranslate}
 function.
 @seealso{regexp, regexpi, strrep}
 @end deftypefn */)
--- a/libinterp/corefcn/strfns.cc	Fri Nov 27 13:49:11 2020 -0500
+++ b/libinterp/corefcn/strfns.cc	Fri Nov 27 17:01:47 2020 -0800
@@ -1078,7 +1078,7 @@
 @deftypefn {} {} newline
 Return the character corresponding to a newline.
 
-This is equivalent to @qcode{"@xbackslashchar{}n"}.
+This is equivalent to @qcode{"@backslashchar{}n"}.
 
 Example Code
 
--- a/libinterp/corefcn/sysdep.cc	Fri Nov 27 13:49:11 2020 -0500
+++ b/libinterp/corefcn/sysdep.cc	Fri Nov 27 17:01:47 2020 -0800
@@ -1074,7 +1074,8 @@
 
 Examples:
 
-Get a list of value names at the key @nospell{@qcode{'HKCU\Environment'}}:
+Get a list of value names at the key
+@nospell{@qcode{'HKCU@backslashchar{}Environment'}}:
 
 @example
 @group
--- a/libinterp/corefcn/utils.cc	Fri Nov 27 13:49:11 2020 -0500
+++ b/libinterp/corefcn/utils.cc	Fri Nov 27 17:01:47 2020 -0800
@@ -944,8 +944,8 @@
 Convert escape sequences in @var{string} to the characters they represent.
 
 Escape sequences begin with a leading backslash
-(@qcode{'@xbackslashchar{}'}) followed by 1--3 characters
-(.e.g., @qcode{"@xbackslashchar{}n"} => newline).
+(@qcode{'@backslashchar{}'}) followed by 1--3 characters
+(.e.g., @qcode{"@backslashchar{}n"} => newline).
 @seealso{undo_string_escapes}
 @end deftypefn */)
 {
@@ -1661,7 +1661,7 @@
 
 Implementation Note: Strings are first converted to double values before the
 checks for valid indices are made.  Unless a string contains the NULL
-character @nospell{"@xbackslashchar{}0"}, it will always be a valid index.
+character @nospell{"@backslashchar{}0"}, it will always be a valid index.
 @end deftypefn */)
 {
   int nargin = args.length ();
--- a/libinterp/parse-tree/pt-eval.cc	Fri Nov 27 13:49:11 2020 -0500
+++ b/libinterp/parse-tree/pt-eval.cc	Fri Nov 27 17:01:47 2020 -0800
@@ -4584,7 +4584,7 @@
 
 The default format is:
 
-@qcode{"  %a:4; %ln:6; %cs:16:6:1;  %rb:12;  %lc:-1;@xbackslashchar{}n"}
+@qcode{"  %a:4; %ln:6; %cs:16:6:1;  %rb:12;  %lc:-1;@backslashchar{}n"}
 
 When called from inside a function with the @qcode{"local"} option, the
 variable is changed locally for the function and any subroutines it calls.
--- a/scripts/io/beep.m	Fri Nov 27 13:49:11 2020 -0500
+++ b/scripts/io/beep.m	Fri Nov 27 17:01:47 2020 -0800
@@ -27,7 +27,7 @@
 ## @deftypefn {} {} beep ()
 ## Produce a beep from the speaker (or visual bell).
 ##
-## This function sends the alarm character @qcode{"@xbackslashchar{}a"} to
+## This function sends the alarm character @qcode{"@backslashchar{}a"} to
 ## the terminal.  Depending on the user's configuration this may produce an
 ## audible beep, a visual bell, or nothing at all.
 ## @seealso{puts, fputs, printf, fprintf}
--- a/scripts/io/dlmwrite.m	Fri Nov 27 13:49:11 2020 -0500
+++ b/scripts/io/dlmwrite.m	Fri Nov 27 17:01:47 2020 -0800
@@ -58,9 +58,9 @@
 ##
 ## @item @qcode{"newline"}
 ## The character(s) to separate each row.  Three special cases exist for this
-## option.  @qcode{"unix"} is changed into @qcode{"@xbackslashchar{}n"},
-## @qcode{"pc"} is changed into @qcode{"@xbackslashchar{}r@xbackslashchar{}n"},
-## and @qcode{"mac"} is changed into @qcode{"@xbackslashchar{}r"}.  Any other
+## option.  @qcode{"unix"} is changed into @qcode{"@backslashchar{}n"},
+## @qcode{"pc"} is changed into @qcode{"@backslashchar{}r@backslashchar{}n"},
+## and @qcode{"mac"} is changed into @qcode{"@backslashchar{}r"}.  Any other
 ## value is used directly as the newline separator.
 ##
 ## @item @qcode{"roffset"}
--- a/scripts/legacy/strread.m	Fri Nov 27 13:49:11 2020 -0500
+++ b/scripts/legacy/strread.m	Fri Nov 27 17:01:47 2020 -0800
@@ -163,14 +163,14 @@
 ## @item @qcode{"whitespace"}
 ## Any character in @var{value} will be interpreted as whitespace and trimmed;
 ## the string defining whitespace must be enclosed in double quotes for proper
-## processing of special characters like @qcode{"@xbackslashchar{}t"}.  In
+## processing of special characters like @qcode{"@backslashchar{}t"}.  In
 ## each data field, multiple consecutive whitespace characters are collapsed
 ## into one space and leading and trailing whitespace is removed.  The default
 ## value for whitespace is
 ## @c Note: the next line specifically has a newline which generates a space
 ## @c       in the output of qcode, but keeps the next line < 80 characters.
 ## @qcode{"
-## @xbackslashchar{}b@xbackslashchar{}r@xbackslashchar{}n@xbackslashchar{}t"}
+## @backslashchar{}b@backslashchar{}r@backslashchar{}n@backslashchar{}t"}
 ## (note the space).  Whitespace is always added to the set of delimiter
 ## characters unless at least one @qcode{"%s"} format conversion specifier is
 ## supplied; in that case only whitespace explicitly specified in
@@ -186,11 +186,11 @@
 ## the last character of @var{str}:
 ##
 ## @table @asis
-## @item last character = @qcode{"@xbackslashchar{}n"}
+## @item last character = @qcode{"@backslashchar{}n"}
 ## Data columns are padded with empty fields or NaN so that all columns have
 ## equal length
 ##
-## @item last character is not @qcode{"@xbackslashchar{}n"}
+## @item last character is not @qcode{"@backslashchar{}n"}
 ## Data columns are not padded; strread returns columns of unequal length
 ##
 ## @end table
--- a/scripts/legacy/textread.m	Fri Nov 27 13:49:11 2020 -0500
+++ b/scripts/legacy/textread.m	Fri Nov 27 17:01:47 2020 -0800
@@ -47,7 +47,7 @@
 ##
 ## @item @qcode{"endofline"}:
 ## Specify a single character or
-## @qcode{"@xbackslashchar{}r@xbackslashchar{}n"}.  If no value is given, it
+## @qcode{"@backslashchar{}r@backslashchar{}n"}.  If no value is given, it
 ## will be inferred from the file.  If set to @qcode{""} (empty string) EOLs
 ## are ignored as delimiters.
 ## @end itemize
--- a/scripts/time/asctime.m	Fri Nov 27 13:49:11 2020 -0500
+++ b/scripts/time/asctime.m	Fri Nov 27 17:01:47 2020 -0800
@@ -26,14 +26,14 @@
 ## -*- texinfo -*-
 ## @deftypefn {} {} asctime (@var{tm_struct})
 ## Convert a time structure to a string using the following
-## format: @qcode{"ddd mmm mm HH:MM:SS yyyy@xbackslashchar{}n"}.
+## format: @qcode{"ddd mmm mm HH:MM:SS yyyy@backslashchar{}n"}.
 ##
 ## For example:
 ##
 ## @example
 ## @group
 ## asctime (localtime (time ()))
-##      @result{} "Mon Feb 17 01:15:06 1997@xbackslashchar{}n"
+##      @result{} "Mon Feb 17 01:15:06 1997@backslashchar{}n"
 ## @end group
 ## @end example
 ##
--- a/scripts/time/ctime.m	Fri Nov 27 13:49:11 2020 -0500
+++ b/scripts/time/ctime.m	Fri Nov 27 17:01:47 2020 -0800
@@ -35,7 +35,7 @@
 ## @example
 ## @group
 ## ctime (time ())
-##    @result{} "Mon Feb 17 01:15:06 1997@xbackslashchar{}n"
+##    @result{} "Mon Feb 17 01:15:06 1997@backslashchar{}n"
 ## @end group
 ## @end example
 ## @seealso{asctime, time, localtime}