Page MenuHomeFreeBSD

llvm-objdump: initial man page
ClosedPublic

Authored by emaste on Nov 23 2018, 3:58 PM.

Details

Summary

Based on llvm-objdump's online documentation and usage information.

Also being submitted upstream as http://reviews.llvm.org/D54864. New features and option parsing improvements are being made upstream; I expect to use this one for LLVM 6 and 7, then switch to the upstream one when we import 8.

Diff Detail

Repository
rS FreeBSD src repository
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

emaste created this revision.Nov 23 2018, 3:58 PM
emaste added reviewers: dim, jhb, brooks.
yuripv added a subscriber: yuripv.Nov 23 2018, 4:15 PM
yuripv added inline comments.
usr.bin/clang/llvm-objdump/llvm-objdump.1
11 ↗(On Diff #51005)

Just IMO: listing all the long options in the synopsis section makes it unreadable (see diff(1), for example); if there are no short ones, just say llvm-objdump [OPTIONS] objfile ... like some of gnu utilities do (yeah, I know...), e.g., gnugrep(1).

emaste marked an inline comment as done.Nov 23 2018, 4:26 PM
emaste added inline comments.
usr.bin/clang/llvm-objdump/llvm-objdump.1
11 ↗(On Diff #51005)

There are a mix of long and short options, some short ones not documented.

I had this discussion with Ingo Schwarze about the ld.lld.1 man page as well; he does not like eliminating the options in the synopsis, but also does not like long options at all.

I think you're right that the giant collection of long options is not that helpful, although note that GNU objdump does list all of its options in the synopsis.

emaste updated this revision to Diff 51017.Nov 23 2018, 6:49 PM

Split mach-o options to subsection.

bcr added a subscriber: bcr.Nov 23 2018, 7:16 PM

Did you ran the man page through "mandoc -Tlint" and textproc/igor to see if they spot any errors?
I found just one issue. Good to have a man page for it and even better to upstream it!

usr.bin/clang/llvm-objdump/llvm-objdump.1
151 ↗(On Diff #51017)

Line break after the sentence stop.

emaste updated this revision to Diff 51018.Nov 23 2018, 7:24 PM

Clean up mandoc -Tlint and/or igor complaints.

bcr accepted this revision.Nov 23 2018, 7:28 PM

OK from manpages, others may have comments on the content itself.

This revision is now accepted and ready to land.Nov 23 2018, 7:28 PM
In D18309#388676, @bcr wrote:

OK from manpages, others may have comments on the content itself.

Thanks @bcr, I'll wait a bit for comments from others. I don't think this is a great man page, but is a starting point. I expect to iterate on it both in our tree and upstream.

This revision was automatically updated to reflect the committed changes.