This is an archive of the discontinued LLVM Phabricator instance.

[docs][llvm-objdump] Improve llvm-objdump documentation
ClosedPublic

Authored by jhenderson on Jun 20 2019, 8:40 AM.

Details

Summary

The llvm-objdump document was missing many options, and there were also some style issues with it. This patches fixes all but the first issue listed in https://bugs.llvm.org/show_bug.cgi?id=42249 by:

  1. Adding missing options and commands.
  2. Standardising on double dashes for long-options throughout.
  3. Moving Mach-O specific options to a separate section.
  4. Removing options that don't exist or aren't relevant to llvm-objdump.

Diff Detail

Repository
rL LLVM

Event Timeline

jhenderson created this revision.Jun 20 2019, 8:40 AM
Herald added a project: Restricted Project. · View Herald TranscriptJun 20 2019, 8:40 AM
MaskRay accepted this revision.Jun 20 2019, 8:14 PM

Nice!

This revision is now accepted and ready to land.Jun 20 2019, 8:14 PM

BTW, there is a manpage: llvm/docs/llvm-objdump.1. It'd be nice to check if it needs updates as well.

BTW, there is a manpage: llvm/docs/llvm-objdump.1. It'd be nice to check if it needs updates as well.

Do we know why there is a separate llvm-objdump.1 instead of just generating the man page from the rst file with Sphinx? Seems unfortunate to maintain two files with the same logical contents ...

mtrent accepted this revision.Jun 21 2019, 12:15 AM

BTW, there is a manpage: llvm/docs/llvm-objdump.1. It'd be nice to check if it needs updates as well.

Do we know why there is a separate llvm-objdump.1 instead of just generating the man page from the rst file with Sphinx? Seems unfortunate to maintain two files with the same logical contents ...

It was added in D54864 by @emaste. Also see https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=233437
Do you know how good rst is to generate the man page? If it is less ideal (mdoc is a complex format...), personally I think it is fine to stick with the current manually maintained manpage...

Many people prefer man llvm-objdump to an online document...

Do you know how good rst is to generate the man page? If it is less ideal (mdoc is a complex format...), personally I think it is fine to stick with the current manually maintained manpage...

I don't know about the quality, but there are build targets generated by cmake for creating man pages. I took a quick look and it looks like the current version of the man page is not in too bad a state. I'll see what happens when I try to build the docs.

This revision was automatically updated to reflect the committed changes.

I got the man pages building from the rst using ninja docs-llvm-man, and a set of man pages were built, including one for llvm-objdump that mirrors the html doc. I don't see any reason why this can't be used: it's built by the sphinx build bot (see http://lab.llvm.org:8011/builders/llvm-sphinx-docs/builds/32333 for an example build).

Aside: I couldn't get the man page build to work on my Windows VS-based build, but my Linux one was fine.

@emaste, is there anything stopping using the auto-built version of the man page of llvm-objdump instead of the hand-maintained one? If not, can we delete it?