[llvm-ar] Correct help text

[bd1976llvm]

Summary

Corrected and simplified the help text.
It was clearly too difficult to maintain before (see e.g. @227296) making it simpler and more consistent it should help people keep it up to date.

• I took the description from https://llvm.org/docs/CommandGuide/llvm-ar.html.
• I removed the "count" positional argument only used by removed "N" modifier.
• It is pretty clear from the modifier description which modifiers apply to which operations, so I removed the (currently incorrect) list of modifiers from each operation.
• Removed the distinction between generic and specific modifiers. This is artificial anyway - for example the "c" modifier is currently listed as generic but only applies some operations.
• Used "archive" rather than "library" - more correct (library is a subset of archive).
• Used "files" rather than "members" - for consistency with the rest of the help text.
• "s" is both an operation key letter and a modifier.
• Added all the accepted modifiers to the list.
• Used a consistent rule that if something is in square brackets in the usage text then it is written with square brackets in the rest of the help text.

[bd1976llvm]

Having thought about this I have decided to try to simplify the help text as much as possible to aid maintenance.

Updated the diff and the summary.

[ruiu]

tools/llvm-ar/llvm-ar.cpp

68 ↗

(On Diff #152879)

llvm-ar is not only similar but is actually an ar command, no?

72 ↗

(On Diff #152879)

Half-open <.

100 ↗

(On Diff #152879)

Only this line starts with an uppercase letter.

[bd1976llvm]

updated diff to address review comments

[bd1976llvm]

tools/llvm-ar/llvm-ar.cpp

68 ↗

(On Diff #152879)

I removed the description entirely.

72 ↗

(On Diff #152879)

This is a convention used in the gnu tools help text. It is mean't to convey that if invoked with just -M then the program enters an interactive mode where you enter the script line by line but if you pipe in a script then the program reads the script non-interactively. See: https://sourceware.org/binutils/docs/binutils/ar-scripts.html#ar-scripts. Use of MRI scripts should be rare and they are only supported for compatibility with a long defunct toolchain.

100 ↗

(On Diff #152879)

Thanks!

[bd1976llvm]

ping!

[bd1976llvm]

This wasn't committed in time for the 7.0 release but I wonder if rL338703 + rL338709 should be put on the release branch? The current output is slightly embarrassing.

[hans]

In D48577#1186042, @bd1976llvm wrote:

This wasn't committed in time for the 7.0 release but I wonder if rL338703 + rL338709 should be put on the release branch? The current output is slightly embarrassing.

Merged both in r338840, thanks.

llvm/trunk/tools/llvm-ar/llvm-ar.cpp

 USAGE: llvm-ranlib <archive-file>
 
 OPTIONS:
   -help                             - Display available options
   -version                          - Display the version of this program
 )";
 
 const char ArHelp[] = R"(
-OVERVIEW: LLVM Archiver (llvm-ar)
+OVERVIEW: LLVM Archiver
 
-  This program archives bitcode files into single libraries
-
-USAGE: llvm-ar [options] [relpos] [count] <archive-file> [members]...
+USAGE: llvm-ar [options] [-]<operation>[modifiers] [relpos] <archive> [files]
+       llvm-ar -M [<mri-script]
 
 OPTIONS:
-  -M                                -
-  -format                           - Archive format to create
-    =default                        -   default
-    =gnu                            -   gnu
-    =darwin                         -   darwin
-    =bsd                            -   bsd
-  -plugin=<string>                  - plugin (ignored for compatibility
-  -help                             - Display available options
-  -version                          - Display the version of this program
+  --format              - Archive format to create
+    =default            -   default
+    =gnu                -   gnu
+    =darwin             -   darwin
+    =bsd                -   bsd
+  --plugin=<string>     - Ignored for compatibility
+  --help                - Display available options
+  --version             - Display the version of this program
 
 OPERATIONS:
-  d[NsS]       - delete file(s) from the archive
-  m[abiSs]     - move file(s) in the archive
-  p[kN]        - print file(s) found in the archive
-  q[ufsS]      - quick append file(s) to the archive
-  r[abfiuRsS]  - replace or insert file(s) into the archive
-  t            - display contents of archive
-  x[No]        - extract file(s) from the archive
+  d - delete [files] from the archive
+  m - move [files] in the archive
+  p - print [files] found in the archive
+  q - quick append [files] to the archive
+  r - replace or insert [files] into the archive
+  s - act as ranlib
+  t - display contents of archive
+  x - extract [files] from the archive
 
-MODIFIERS (operation specific):
-  [a] - put file(s) after [relpos]
-  [b] - put file(s) before [relpos] (same as [i])
+MODIFIERS:
+  [a] - put [files] after [relpos]
+  [b] - put [files] before [relpos] (same as [i])
+  [c] - do not warn if archive had to be created
   [D] - use zero for timestamps and uids/gids (default)
-  [i] - put file(s) before [relpos] (same as [b])
+  [i] - put [files] before [relpos] (same as [b])
+  [l] - ignored for compatibility
   [o] - preserve original dates
   [s] - create an archive index (cf. ranlib)
   [S] - do not build a symbol table
   [T] - create a thin archive
-  [u] - update only files newer than archive contents
+  [u] - update only [files] newer than archive contents
   [U] - use actual timestamps and uids/gids
-
-MODIFIERS (generic):
-  [c] - do not warn if the library had to be created
   [v] - be verbose about actions taken
 )";
 
 void printHelpMessage() {
   if (Stem.contains_lower("ranlib"))
     outs() << RanlibHelp;
   else if (Stem.contains_lower("ar"))
     outs() << ArHelp;