From 3e740b0a0b308d8c392a93e679c1c22465e48d84 Mon Sep 17 00:00:00 2001
From: Adolfo Perez Alvarez <adolfopa@sdf.org>
Date: Thu, 18 Dec 2025 22:12:17 +0100
Subject: [PATCH] Minor manpage clean up; add some examples

---
 bwrap.1    |  2 +-
 hppt.1     |  2 +-
 mkgmap.1   |  2 +-
 newp.1     |  2 +-
 osc.1      | 10 +++++-----
 p.1        |  2 +-
 pick.1     | 29 ++++++++++++++++++++++++-----
 rot.1      |  2 +-
 scmfmt.1   |  2 +-
 ts.1       |  2 +-
 unpage.1   |  2 +-
 upcasetl.1 |  2 +-
 12 files changed, 39 insertions(+), 20 deletions(-)

diff --git a/bwrap.1 b/bwrap.1
index e4a8571..c2bd8fc 100644
--- a/bwrap.1
+++ b/bwrap.1
@@ -3,7 +3,7 @@
 .Os
 .Sh NAME
 .Nm bwrap
-.Nd Wrap input text as a unit
+.Nd wrap input text as a unit
 .Sh SYNOPSIS
 .Nm
 .Sh DESCRIPTION
diff --git a/hppt.1 b/hppt.1
index d534c9e..4d70286 100644
--- a/hppt.1
+++ b/hppt.1
@@ -3,7 +3,7 @@
 .Os
 .Sh NAME
 .Nm hppt
-.Nd Reformat stdin as a horizontal paper tape
+.Nd reformat stdin as a horizontal paper tape
 .Sh SYNOPSIS
 .Nm
 .Sh DESCRIPTION
diff --git a/mkgmap.1 b/mkgmap.1
index 85b37e8..f327d5c 100644
--- a/mkgmap.1
+++ b/mkgmap.1
@@ -3,7 +3,7 @@
 .Os
 .Sh NAME
 .Nm mkgmap
-.Nd Create a simple Gophermap for the current directory
+.Nd create a simple Gophermap for the current directory
 .Sh SYNOPSIS
 .Nm
 .Sh DESCRIPTION
diff --git a/newp.1 b/newp.1
index 25b7235..1c4d898 100644
--- a/newp.1
+++ b/newp.1
@@ -3,7 +3,7 @@
 .Os
 .Sh NAME
 .Nm newp
-.Nd Create a new phlog post
+.Nd create a new phlog post
 .Sh SYNOPSIS
 .Nm
 .Ar word ...
diff --git a/osc.1 b/osc.1
index 1b6d2c7..6f97ac9 100644
--- a/osc.1
+++ b/osc.1
@@ -3,7 +3,7 @@
 .Os
 .Sh NAME
 .Nm osc
-.Nd Print OSC escape sequences
+.Nd print OSC escape sequences
 .Sh SYNOPSIS
 .Nm
 .Cm pwd
@@ -19,12 +19,12 @@ prints an OSC escape sequence to stdout if connected to a tty.
 If stdout is not a TTY, prints nothing.
 .Pp
 Three escape sequences are supported:
-.Bl -tag
-.It pwd
+.Bl -tag -width Ds
+.It Cm pwd
 ESC 7, set current working directory.
-.It link
+.It Cm link
 ESC 8, display an URI.
-.It title
+.It Cm title
 ESC 2, set a title for the current window.
 .El
 .Pp
diff --git a/p.1 b/p.1
index 2c9897e..11e4d8d 100644
--- a/p.1
+++ b/p.1
@@ -3,7 +3,7 @@
 .Os
 .Sh NAME
 .Nm p
-.Nd Paginate
+.Nd paginate
 .Sh SYNOPSIS
 .Nm
 .Op Fl number
diff --git a/pick.1 b/pick.1
index 4f72112..44fd739 100644
--- a/pick.1
+++ b/pick.1
@@ -1,18 +1,20 @@
-.Dd Sep 13, 2023
+.Dd December 15, 2025
 .Dt PICK 1
 .Os
 .Sh NAME
 .Nm pick
-.Nd Choose interactively from the set of arguments and input lines
+.Nd choose interactively from a set of arguments and input lines
 .Sh SYNOPSIS
 .Nm
 .Ar arg ...
 .Sh DESCRIPTION
 .Nm
-will display a Korn shell style selection menu with stdin contents and
-arguments as options.
+will display a Korn shell style selection menu with any arguments as options.
+The special argument
+.Ar --
+will read stdin and present each line as a choice.
 .Pp
-When a selection is made, the command will print its value to stdout.
+When a selection is made, the command will print its value to stdout;
 If the selection is aborted, nothing will be printed.
 .Sh ENVIRONMENT
 .Bl -tag -width PS3
@@ -21,5 +23,22 @@ Prompt string displayed to the user (default: #?).
 .El
 .Sh EXIT STATUS
 .Ex -std
+.Sh EXAMPLES
+.Bd -literal -offset indent
+$ pick 1 2 -- 3 4 <<.
+> a
+> b
+> c
+> .
+1) 1
+2) 2
+3) a
+4) b
+5) c
+6) 3
+7) 4
+#? 4
+b
+.Ed
 .Sh AUTHORS
 .An Adolfo Perez Alvarez Aq Mt adolfopa@sdf.org
diff --git a/rot.1 b/rot.1
index ce5a8a8..f2827df 100644
--- a/rot.1
+++ b/rot.1
@@ -3,7 +3,7 @@
 .Os
 .Sh NAME
 .Nm rot
-.Nd Rotate stdin 90 degrees
+.Nd rotate stdin 90 degrees
 .Sh SYNOPSIS
 .Nm
 .Sh DESCRIPTION
diff --git a/scmfmt.1 b/scmfmt.1
index c375b68..423934e 100644
--- a/scmfmt.1
+++ b/scmfmt.1
@@ -3,7 +3,7 @@
 .Os
 .Sh NAME
 .Nm scmfmt
-.Nd Format a commit message
+.Nd format a commit message
 .Sh SYNOPSIS
 .Nm
 .Sh DESCRIPTION
diff --git a/ts.1 b/ts.1
index 3299756..15ee2e7 100644
--- a/ts.1
+++ b/ts.1
@@ -3,7 +3,7 @@
 .Os
 .Sh NAME
 .Nm ts
-.Nd Run shell tests 
+.Nd run shell tests 
 .Sh SYNOPSIS
 .Nm
 .Op Fl b
diff --git a/unpage.1 b/unpage.1
index 4aa6b12..18afe62 100644
--- a/unpage.1
+++ b/unpage.1
@@ -3,7 +3,7 @@
 .Os
 .Sh NAME
 .Nm unpage
-.Nd Remove page headers and footers from text documents
+.Nd remove page headers and footers from text documents
 .Sh SYNOPSIS
 .Nm
 .Sh DESCRIPTION
diff --git a/upcasetl.1 b/upcasetl.1
index a3e42fc..aaa8f25 100644
--- a/upcasetl.1
+++ b/upcasetl.1
@@ -3,7 +3,7 @@
 .Os
 .Sh NAME
 .Nm upcasetl
-.Nd Upcase titles and section headers in an ms troff document
+.Nd upcase titles and section headers in an ms troff document
 .Sh SYNOPSIS
 .Nm
 .Sh DESCRIPTION