[PATCH 01/25] Adjust style of "export-completions" documentation.

[G. Branden Robinson]

* doc/bash.1:
  + Drop explicit `sp` request in favor of inter-paragraph spacing.
  + Set items returned by Readline command as bulleted list.
  + Identify "N" as the parameter replaced by the number of matches.
  + Set "readline" in boldface, for consistency with rest of page.
  + Set parameters "N", "S", and "E" in italics.
  + Use page-local `Q` macro to set an output literal.
  + Break lines in the same places as the Texinfo documentation.

* lib/readline/doc/readline.3: Parallelize with "bash.1".

* lib/readline/doc/rluser.texi: Port/parallelize with "bash.1".
  + Use Texinfo @itemize and @bullet commands to set list of items
    returned by the Readline command, which are more idiomatic for this
    purpose than @example.
  + Sync wording with man page.
  + Use Texinfo @var command to typeset parameters.
  + Use quotation marks to set an output literal.
  + Break lines in the same places as the man pages.
---
 doc/bash.1                   | 62 ++++++++++++++++++++++++------------
 lib/readline/doc/readline.3  | 62 ++++++++++++++++++++++++------------
 lib/readline/doc/rluser.texi | 59 +++++++++++++++++++++++-----------
 3 files changed, 122 insertions(+), 61 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index 27ed4057..f68eecc3 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -7706,35 +7706,55 @@ .SS Completing
 .B export\-completions
 Perform completion on the word before point as described above
 and write the list of possible completions to \fBreadline\fP's output
-stream using the following format, writing information on separate lines:
-.sp
-.IP
+stream using the following format,
+writing information on separate lines:
 .RS
-.nf
-The number of matches; 
-The word being completed;
-S:E, where S and E are the start and end offsets of the word
-in the readline line buffer; then
-Each match, one per line
-.fi
+.IP \(bu
+the number of matches
+.IR N ;
+.IP \(bu
+the word being completed;
+.IP \(bu
+.IR S : E ,
+where
+.I S
+and
+.I E
+are the start and end offsets of the word
+in the \fBreadline\fP line buffer;
+then
+.IP \(bu
+each match,
+one per line.
 .RE
-.sp
+.PD
 .IP
-If there are no matches, the first line will be 0, and this command will
-not print any output after the S:E.
-If there is only a single match, this prints a single line containing it.
-If there is more than one match, this prints the common prefix of the
-matches, which may be empty, on the first line after the S:E,
+If there are no matches,
+the first line will be
+.Q 0 ,
+and this command will not print any output after the
+.IR S : E .
+If there is only a single match,
+this prints a single line containing it.
+If there is more than one match,
+this prints the common prefix of the matches,
+which may be empty,
+on the first line after the
+.IR S : E ,
 then the matches on subsequent lines.
-In this case, N will include the first line with the common prefix.
-.PD
+In this case,
+.I N
+will include the first line with the common prefix.
 .IP
-.PD 0
 The user or application
 should be able to accommodate the possibility of a blank line.
-The intent is that the user or application reads N lines after the line
-containing S:E to obtain the match list.
+The intent is that the user or application reads
+.I N
+lines after the line containing
+.IR S : E
+to obtain the match list.
 This command is unbound by default.
+.PD 0
 .TP
 .B delete\-char\-or\-list
 Deletes the character under the cursor if not at the beginning or
diff --git a/lib/readline/doc/readline.3 b/lib/readline/doc/readline.3
index 7915bcce..7b7dc9d2 100644
--- a/lib/readline/doc/readline.3
+++ b/lib/readline/doc/readline.3
@@ -1413,35 +1413,55 @@ .SS Completing
 .B export\-completions
 Perform completion on the word before point as described above
 and write the list of possible completions to \fBreadline\fP's output
-stream using the following format, writing information on separate lines:
-.sp
-.IP
+stream using the following format,
+writing information on separate lines:
 .RS
-.nf
-The number of matches; 
-The word being completed;
-S:E, where S and E are the start and end offsets of the word
-in the readline line buffer; then
-Each match, one per line
-.fi
+.IP \(bu
+The number of matches
+.IR N ;
+.IP \(bu
+the word being completed;
+.IP \(bu
+.IR S : E ,
+where
+.I S
+and
+.I E
+are the start and end offsets of the word
+in the \fBreadline\fP line buffer;
+then
+.IP \(bu
+each match,
+one per line.
 .RE
-.sp
+.PD
 .IP
-If there are no matches, the first line will be 0, and this command will
-not print any output after the S:E.
-If there is only a single match, this prints a single line containing it.
-If there is more than one match, this prints the common prefix of the
-matches, which may be empty, on the first line after the S:E,
+If there are no matches,
+the first line will be
+.Q 0 ,
+and this command will not print any output after the
+.IR S : E .
+If there is only a single match,
+this prints a single line containing it.
+If there is more than one match,
+this prints the common prefix of the matches,
+which may be empty,
+on the first line after the
+.IR S : E ,
 then the matches on subsequent lines.
-In this case, N will include the first line with the common prefix.
-.PD
+In this case,
+.I N
+will include the first line with the common prefix.
 .IP
-.PD 0
 The user or application
 should be able to accommodate the possibility of a blank line.
-The intent is that the user or application reads N lines after the line
-containing S:E to obtain the match list.
+The intent is that the user or application reads
+.I N
+lines after the line containing
+.IR S : E
+to obtain the match list.
 This command is unbound by default.
+.PD 0
 .TP
 .B delete\-char\-or\-list
 Deletes the character under the cursor if not at the beginning or
diff --git a/lib/readline/doc/rluser.texi b/lib/readline/doc/rluser.texi
index 00f5c825..caab87d4 100644
--- a/lib/readline/doc/rluser.texi
+++ b/lib/readline/doc/rluser.texi
@@ -1787,29 +1787,50 @@
 
 @item export-completions ()
 Perform completion on the word before point as described above
-and write the list of possible completions to Readline's output stream
-using the following format, writing information on separate lines:
-
-@example
-The number of matches;
-The word being completed;
-S:E, where S and E are the start and end offsets of the word
-in the readline line buffer; then
-Each match, one per line
-@end example
-
-If there are no matches, the first line will be 0, and this command will
-not print any output after the S:E.
-If there is only a single match, this prints a single line containing it.
-If there is more than one match, this prints the common prefix of the
-matches, which may be empty, on the first line after the S:E,
+and write the list of possible completions to Readline's output
+stream using the following format,
+writing information on separate lines:
+
+@itemize @bullet
+@item
+The number of matches
+@var{N};
+@item
+the word being completed;
+@item
+@var{S}:@var{E},
+where S and E are the start and end offsets of the word
+in the Readline line buffer;
+then
+@item
+each match,
+one per line
+@end itemize
+
+If there are no matches,
+the first line will be
+``0'',
+and this command will not print any output after the
+@var{S}:@var{E}.
+If there is only a single match,
+this prints a single line containing it.
+If there is more than one match,
+this prints the common prefix of the matches,
+which may be empty,
+on the first line after the
+@var{S}:@var{E}.
 then the matches on subsequent lines.
-In this case, N will include the first line with the common prefix.
+In this case,
+@var{N}
+will include the first line with the common prefix.
 
 The user or application
 should be able to accommodate the possibility of a blank line.
-The intent is that the user or application reads N lines after the line
-containing S:E to obtain the match list.
+The intent is that the user or application reads
+@var{N}
+lines after the line containing
+@var{S}:@var{E}
+to obtain the match list.
 This command is unbound by default.
 
 @item delete-char-or-list ()
-- 
2.30.2

signature.asc
Description: PGP signature