[PATCH] D68998: [docs][llvm-ar] Update llvm-ar command guide

[Jordan Rupprecht via Phabricator via llvm-commits]

rupprecht added a comment.

Mostly nits, I have a couple larger suggestions that I'm ok skipping because better documentation is better than bad documentation :)



================
Comment at: llvm/docs/CommandGuide/llvm-ar.rst:15
+The :program:`llvm-ar` command is similar to the common Unix utility,
+:program:`ar`.It archives several files, such as objects and LLVM bitcode
+files into a single archive library that can be linked into a program. However,
----------------
nit: missing space after period before "It"


================
Comment at: llvm/docs/CommandGuide/llvm-ar.rst:28-29
 
-Here's where **llvm-ar** departs from previous ``ar`` implementations:
+Here's where :program:`llvm-ar` departs from previous :program:`ar` 
+implementations:
 
----------------
I compared what options were provided on the GNU ar on my workstation, and found the following not implemented by llvm-ar:
```
[f] - truncate inserted filenames
[O] - display offsets of files
[V] - display version
```
(actually, we should note the first two, but just implement `llvm-ar V`... I might take a look at that now)

I *think* we do actually implement all of them, i.e. there are none that we "implement but ignore for compatibility", but it would be good to double check that -- if there are any like that, we should also add them here.


================
Comment at: llvm/docs/CommandGuide/llvm-ar.rst:36-38
 *Long Paths*
 
+ :program:`llvm-ar` can read and write GNU, BSD and Darwin long file names.
----------------
Is this a difference anymore? It sounds like this used to be a limitation that no longer holds.


================
Comment at: llvm/docs/CommandGuide/llvm-ar.rst:39
+ :program:`llvm-ar` can read and write GNU, BSD and Darwin long file names.
 
 OPTIONS
----------------
Additionally llvm-ar is deterministic by default, vs GNU ar (and GNU binutils in general), which is only deterministic if it's been configured that way at build time (and I think the default is non-deterministic). So I think that's an important thing to call out. For example:

```
*Deterministic Archives*

By default, :program:`llvm-ar` always uses zero for timestamps and UIDs/GIDs to write archives in a deterministic mode.
This is equivalent to the :option:`D` modifier being enabled by default. If you wish to maintain compatibility with other
:program:`ar` implementations, you can pass the :option:`U` modifier to write actual timestamps and UIDs/GIDs.

```


================
Comment at: llvm/docs/CommandGuide/llvm-ar.rst:324
 
-ar(1)
+:manpage:`ar(1)`
----------------
This is a dead link for me - https://llvm.org/docs/CommandGuide/ar.html


Repository:
  rL LLVM

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D68998/new/

https://reviews.llvm.org/D68998