Page MenuHomePhabricator

[docs] Convert remaining command guide entries from md to rst.

Authored by rupprecht on Aug 15 2019, 10:17 AM.



Linking between markdown and rst files is currently not supported very well, e.g. the current llvm-addr2line docs [1] link to "llvm-symbolizer" instead of "llvm-symbolizer.html". This is weirdly broken in different ways depending on which versions of sphinx and recommonmark are being used, so workaround the bug by using rst everywhere.


Diff Detail

Event Timeline

rupprecht created this revision.Aug 15 2019, 10:17 AM
Herald added a project: Restricted Project. · View Herald TranscriptAug 15 2019, 10:17 AM

Note that despite being a plain translation from md to rst, git doesn't think these are close enough and shows them as deletion+addition instead of moves.

Yay, thank you for working on this!

Unrelated, but i think it would be great for the next step to ensure that
every [installable] binary has a doc/man page,
and ideally require that via tooling for future binaries.

jhenderson added inline comments.Aug 16 2019, 3:42 AM

Please add .. program:: llvm-addr2line etc to the tops of these files.


Here and elsewhere, use :program:'llvm-addr2line' (using backticks instead of apostrophe) etc to match llvm-readelf, llvm-symbolizer etc.


Does using the :manpage: link make more sense for the link here, since you use it in the "See Also" block below?




"print segment sizes" is factually wrong. llvm-size doesn't look at program headers at all. Perhaps "print size information".




llvm-strings actually prints strings in all files, not just object files.

rupprecht marked 7 inline comments as done.
  • Use :program: rst syntax
  • Correct some mistakes about tool uses
  • Use :manpage: formatted link instead of :doc:
jhenderson added inline comments.Aug 20 2019, 2:05 AM

Use :program:<program-name> instead of **<program-name>** throughout. Same for other docs.

  • Use :program: syntax everywhere
  • Use `` instead of ** for llvm-ar usage
rupprecht marked 2 inline comments as done.Aug 20 2019, 12:05 PM
rupprecht added inline comments.

Sorry, didn't realize that worked everywhere.

For the Running **llvm-ranlib** is equivalent to running **llvm-ar s** line, I changed the **llvm-ar s** to ``llvm-ar s`` to be styled more like a code snippet, not a program name (since it's two words). The rest are updated to :program:

This revision is now accepted and ready to land.Aug 21 2019, 1:31 AM
This revision was automatically updated to reflect the committed changes.
rupprecht marked an inline comment as done.