Subject: Making ls(1)'s --format clearer

From: Samuel Thibault <[email-masked]>
Date: Tue, 28 Jan 2025 21:00:37 +0100

Hello,

ls(1) says this about --format:

--format=WORD
       across  -x,  commas -m, horizontal -x, long -l, single-column -1,
       verbose -l, vertical -C

It was not clear at all for my students (and not for me either,
actually), that it's the words that should be used, and not the letters.

The attached patch makes this much more explicit:

--format=WORD where WORD can be
       across  (like  -x),  commas (like -m), horizontal (like -x), long
       (like -l), single-column (like -1), verbose (like  -l),  vertical
       (like -C)

Samuel
--- ./man/ls.1.original	2025-01-28 20:51:07.959926088 +0100
+++ ./man/ls.1	2025-01-28 20:58:01.681557095 +0100
@@ -59,9 +59,11 @@
 \fB\-\-file\-type\fR
 likewise, except do not append '*'
 .TP
-\fB\-\-format\fR=\fI\,WORD\/\fR
-across \fB\-x\fR, commas \fB\-m\fR, horizontal \fB\-x\fR, long \fB\-l\fR,
-single\-column \fB\-1\fR, verbose \fB\-l\fR, vertical \fB\-C\fR
+\fB\-\-format\fR=\fI\,WORD\/\fR where WORD can be
+\fBacross\fR (like \fB\-x\fR), \fBcommas\fR (like \fB\-m\fR),
+\fBhorizontal\fR (like \fB\-x\fR), \fBlong\fR (like \fB\-l\fR),
+\fBsingle\-column\fR (like \fB\-1\fR), \fBverbose\fR (like \fB\-l\fR),
+\fBvertical\fR (like \fB\-C\fR)
 .TP
 \fB\-\-full\-time\fR
 like \fB\-l\fR \fB\-\-time\-style\fR=\fI\,full\-iso\/\fR