[PATCH 1/9] 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                   | 50 ++++++++++++++++++++++++------------
 lib/readline/doc/readline.3  | 50 ++++++++++++++++++++++++------------
 lib/readline/doc/rluser.texi | 42 ++++++++++++++++++++----------
 3 files changed, 97 insertions(+), 45 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index a5a8e445..e58c1e8a 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -7793,37 +7793,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:
+stream using the following format,
+writing information on separate lines:
 .RS
-.PD
 .IP \(bu
-.PD 0
-the number of matches \fIN\fP;
+the number of matches
+.IR N ;
 .IP \(bu
 the word being completed;
 .IP \(bu
-\fIS\fP:\fIE\fP,
-where S and E are the start and end offsets of the word
-in the \fBreadline\fP line buffer; then
+.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
+each match,
+one per line.
 .RE
 .PD
 .IP
-If there are no matches, the first line will be
+If there are no matches,
+the first line will be
 .Q 0 ,
-and this command does not print any output after the \fIS\fP:\fIE\fP.
-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 \fIS\fP:\fIE\fP,
+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, \fIN\fP will include the first line with the common prefix.
+In this case,
+.I N
+will include the first line with the common prefix.
 .IP
 The user or application
 should be able to accommodate the possibility of a blank line.
-The intent is that the user or application reads \fIN\fP lines after
-the line containing \fIS\fP:\fIE\fP 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 3a66a9c7..fa1b1413 100644
--- a/lib/readline/doc/readline.3
+++ b/lib/readline/doc/readline.3
@@ -1428,37 +1428,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:
+stream using the following format,
+writing information on separate lines:
 .RS
-.PD
 .IP \(bu
-.PD 0
-the number of matches \fIN\fP;
+The number of matches
+.IR N ;
 .IP \(bu
 the word being completed;
 .IP \(bu
-\fIS\fP:\fIE\fP,
-where S and E are the start and end offsets of the word
-in the \fBreadline\fP line buffer; then
+.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
+each match,
+one per line.
 .RE
 .PD
 .IP
-If there are no matches, the first line will be
+If there are no matches,
+the first line will be
 .Q 0 ,
-and this command does not print any output after the \fIS\fP:\fIE\fP.
-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 \fIS\fP:\fIE\fP,
+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, \fIN\fP will include the first line with the common prefix.
+In this case,
+.I N
+will include the first line with the common prefix.
 .IP
 The user or application
 should be able to accommodate the possibility of a blank line.
-The intent is that the user or application reads \fIN\fP lines after
-the line containing \fIS\fP:\fIE\fP 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 757661ba..7f21dd34 100644
--- a/lib/readline/doc/rluser.texi
+++ b/lib/readline/doc/rluser.texi
@@ -1796,34 +1796,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:
+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};
+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
+in the Readline line buffer;
+then
 @item
-each match, one per line
+each match,
+one per line
 @end itemize
 
-If there are no matches, the first line will be ``0'',
-and this command does 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},
+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, @var{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 @var{N} lines after
-the line containing @var{S}:@var{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