Mercurial > octave-libtiff
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}