[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–69

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

72

Half-open <.

99

Only this line starts with an uppercase letter.

[bd1976llvm]

updated diff to address review comments

[bd1976llvm]

tools/llvm-ar/llvm-ar.cpp

68–69

I removed the description entirely.

72

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.

99

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.

tools/llvm-ar/llvm-ar.cpp

 OPTIONS:
   -help                             - Display available options
   -version                          - Display the version of this program
 )";
 
 const char ArHelp[] = R"(
 OVERVIEW: LLVM Archiver (llvm-ar)
 
-  This program archives bitcode files into single libraries
+  This program is similar to the common Unix utility, ar. 
+  It archives several files together into a single file.
 
-USAGE: llvm-ar [options] [relpos] [count] <archive-file> [members]...
+USAGE: llvm-ar [options] <operation>[modifiers...] [relpos] <archive-file> [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
+  -plugin=<string>                  - Plugin (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
+  d            - delete file(s) from the archive
+  m[abi]       - move file(s) in the archive
+  p            - print file(s) found in the archive
+  q            - quick append file(s) to the archive
+  r[abiu]      - replace or insert file(s) into the archive
+  s            - act as ranlib
   t            - display contents of archive
-  x[No]        - extract file(s) from the archive
+  x[o]         - extract file(s) from the archive
 
 MODIFIERS (operation specific):
   [a] - put file(s) after [relpos]
   [b] - put file(s) before [relpos] (same as [i])
   [D] - use zero for timestamps and uids/gids (default)
   [i] - put file(s) before [relpos] (same as [b])
   [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] - use actual timestamps and uids/gids
 
 MODIFIERS (generic):
-  [c] - do not warn if the library had to be created
+  [c] - do not warn if the archive had to be created
+  [s] - create an archive index (cf. ranlib)
+  [S] - do not build a symbol table
   [v] - be verbose about actions taken
 )";
 
 void printHelpMessage() {
   if (Stem.contains_lower("ranlib"))
     outs() << RanlibHelp;
   else if (Stem.contains_lower("ar"))
     outs() << ArHelp;