From 3085aea7ed4060807a679aa79e63ca0047fb9ea6 Mon Sep 17 00:00:00 2001
From: bentley <bentley@openbsd.org>
Date: Tue, 20 Jun 2017 07:32:56 +0000
Subject: [PATCH] Better document the :s ex command and its variants.

ok jmc@
---
 usr.bin/vi/docs/USD.doc/vi.man/vi.1 | 105 +++++++++++++++++++---------
 1 file changed, 72 insertions(+), 33 deletions(-)

diff --git a/usr.bin/vi/docs/USD.doc/vi.man/vi.1 b/usr.bin/vi/docs/USD.doc/vi.man/vi.1
index 080c52ad3dd..02a2d9fe9fa 100644
--- a/usr.bin/vi/docs/USD.doc/vi.man/vi.1
+++ b/usr.bin/vi/docs/USD.doc/vi.man/vi.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: vi.1,v 1.67 2017/06/15 06:44:47 bentley Exp $
+.\"	$OpenBSD: vi.1,v 1.68 2017/06/20 07:32:56 bentley Exp $
 .\"
 .\" Copyright (c) 1994
 .\"     The Regents of the University of California.  All rights reserved.
@@ -14,7 +14,7 @@
 .\"
 .\"     @(#)vi.1	8.51 (Berkeley) 10/10/96
 .\"
-.Dd $Mdocdate: June 15 2017 $
+.Dd $Mdocdate: June 20 2017 $
 .Dt VI 1
 .Os
 .Sh NAME
@@ -356,7 +356,7 @@ matches the end of the word.
 .It
 .Sq ~
 matches the replacement part of the last
-.Cm substitute
+.Cm s
 command.
 .El
 .Sh BUFFERS
@@ -1996,52 +1996,55 @@ Grow or shrink the current screen.
 Rewind the argument list.
 .Pp
 .It Xo
-.Cm se Ns Op Cm t
-.Sm off
-.Op option Oo = Oo value Oc Oc \ \&...
-.Sm on
-.Pf \ \& Op nooption ...
-.Op option? ...
-.Op Ar all
-.Xc
-Display or set editor options.
-.Pp
-.It Cm sh Ns Op Cm ell
-Run a shell program.
-.Pp
-.It Xo
-.Cm so Ns Op Cm urce
-.Ar file
-.Xc
-Read and execute
-.Nm ex
-commands from a file.
-.Pp
-.It Xo
 .Op Ar range
-.Cm s Ns Op Cm ubstitute
 .Sm off
-.Op / Ar pattern No / Ar replace  No /
-.Sm on
-.Pf \ \& Op Ar options
+.Cm s
+.Oo Cm / Ar pattern Cm / Ar replace Cm /
+.Op Ar options
 .Op Ar count
 .Op Ar flags
+.Oc
+.Sm on
 .Xc
 .It Xo
 .Op Ar range
+.Sm off
 .Cm &
 .Op Ar options
 .Op Ar count
 .Op Ar flags
+.Sm on
 .Xc
 .It Xo
 .Op Ar range
+.Sm off
 .Cm ~
 .Op Ar options
 .Op Ar count
 .Op Ar flags
+.Sm on
 .Xc
-Make substitutions.
+Substitute the regular expression
+.Ar pattern
+with
+.Ar replace .
+When invoked as
+.Cm & ,
+or if
+.Cm / Ns Ar pattern Ns Cm / Ns Ar replace Ns Cm /
+is omitted,
+.Ar pattern
+and
+.Ar replace
+from the most recent
+.Cm s
+command are used.
+.Cm ~
+behaves like
+.Cm & ,
+except the pattern used is the most recent regular expression used by any
+command.
+.Pp
 The
 .Ar replace
 field may contain any of the following sequences:
@@ -2051,13 +2054,13 @@ The text matched by
 .Ar pattern .
 .It Sq \(a~
 The replacement part of the previous
-.Cm substitute
+.Cm s
 command.
 .It Sq %
 If this is the entire
 .Ar replace
 pattern, the replacement part of the previous
-.Cm substitute
+.Cm s
 command.
 .It Sq \e#
 Where
@@ -2082,6 +2085,40 @@ to be converted to uppercase.
 Causes the next character to be converted to uppercase.
 .El
 .Pp
+The
+.Ar options
+field may contain any of the following characters:
+.Bl -tag -width Ds
+.It Sq c
+Prompt for confirmation before each replacement is done.
+.It Sq g
+Replace all instances of
+.Ar pattern
+in a line, not just the first.
+.El
+.Pp
+.It Xo
+.Cm se Ns Op Cm t
+.Sm off
+.Op option Oo = Oo value Oc Oc \ \&...
+.Sm on
+.Pf \ \& Op nooption ...
+.Op option? ...
+.Op Ar all
+.Xc
+Display or set editor options.
+.Pp
+.It Cm sh Ns Op Cm ell
+Run a shell program.
+.Pp
+.It Xo
+.Cm so Ns Op Cm urce
+.Ar file
+.Xc
+Read and execute
+.Nm ex
+commands from a file.
+.Pp
 .It Xo
 .Cm su Ns Op Cm spend Ns
 .Op Cm !\&
@@ -2291,7 +2328,9 @@ Remember the values of the
 and
 .Sq g
 suffixes to the
-.Cm substitute
+.Cm s , &
+and
+.Cm ~
 commands, instead of initializing them as unset for each new command.
 .It Cm escapetime Bq 1
 The tenths of a second
-- 
2.20.1