Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[lldb][Docs] Various style improvements to the tutorial #90594

Merged
merged 4 commits into from
May 1, 2024

Conversation

DavidSpickett
Copy link
Collaborator

  • Replace "we" with either "you" (when talking to the reader) or "lldb" (when talking about the project).
  • Always refer to lldb as lldb not LLDB, to match what the user sees on the command line.
  • Remove a bunch of contractions for example "won't". Which don't (pun intended) seem like a big deal at first but even I as a native English speaker find the text clearer with them expanded.
  • Use RST's plain text highlighting for keywords and command names.
  • Split some very long lines for easier editing in future.

* Remove some unnecessary phrases
* Use RST plain text highlights for key words and commands
* Split some very long lines to ~80 columns for easier editing
@llvmbot
Copy link
Collaborator

llvmbot commented Apr 30, 2024

@llvm/pr-subscribers-lldb

Author: David Spickett (DavidSpickett)

Changes
  • Replace "we" with either "you" (when talking to the reader) or "lldb" (when talking about the project).
  • Always refer to lldb as lldb not LLDB, to match what the user sees on the command line.
  • Remove a bunch of contractions for example "won't". Which don't (pun intended) seem like a big deal at first but even I as a native English speaker find the text clearer with them expanded.
  • Use RST's plain text highlighting for keywords and command names.
  • Split some very long lines for easier editing in future.

Patch is 34.48 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/90594.diff

1 Files Affected:

  • (modified) lldb/docs/use/tutorial.rst (+171-154)
diff --git a/lldb/docs/use/tutorial.rst b/lldb/docs/use/tutorial.rst
index ff956d750c29f2..c7f89976156ca4 100644
--- a/lldb/docs/use/tutorial.rst
+++ b/lldb/docs/use/tutorial.rst
@@ -1,89 +1,94 @@
 Tutorial
 ========
 
-Here's a short precis of how to run lldb if you are familiar with the gdb
-command set. We will start with some details on lldb command structure and
-syntax to help orient you.
+This document describes how to use lldb if you are already familiar with
+gdb's command set. We will start with some details on lldb command structure and
+syntax.
 
 Command Structure
 -----------------
 
-Unlike gdb's command set, which is rather free-form, we tried to make the lldb command syntax fairly structured. The commands are all of the form:
+Unlike gdb's quite free-form commands, lldb's are more structured. All commands
+are of the form:
 
 ::
 
    <noun> <verb> [-options [option-value]] [argument [argument...]]
 
-The command line parsing is done before command execution, so it is uniform
-across all the commands. The command syntax for basic commands is very simple,
-arguments, options and option values are all white-space separated, and
-either single or double-quotes (in pairs) are used to protect white-spaces
-in an argument.  If you need to put a backslash or double-quote character in an
-argument you back-slash it in the argument. That makes the command syntax more
-regular, but it also means you may have to quote some arguments in lldb that
-you wouldn't in gdb.
+The command line parsing is done before command execution, so it is the same for
+all commands. The command syntax for basic commands is very simple.
 
-There is one other special quote character in lldb - the backtick.
+* Arguments, options and option values are all white-space separated.
+* Either single ``'`` or double-quotes ``"`` (in pairs) are used to protect white-spaces
+  in an argument.
+* Escape backslashes and double quotes within arguments should be escaped
+  with a backslash ``\``.
+
+This makes lldb's commands more regular, but it also means you may have to quote
+some arguments in lldb that you would not in gdb.
+
+There is one other special quote character in lldb - the backtick `````.
 If you put backticks around an argument or option value, lldb will run the text
 of the value through the expression parser, and the result of the expression
-will be passed to the command.  So for instance, if "len" is a local
-int variable with the value 5, then the command:
+will be passed to the command.  So for instance, if ``len`` is a local
+``int`` variable with the value ``5``, then the command:
 
 ::
 
    (lldb) memory read -c `len` 0x12345
 
-will receive the value 5 for the count option, rather than the string "len".
-
+Will receive the value ``5`` for the count option, rather than the string ``len``.
 
 Options can be placed anywhere on the command line, but if the arguments begin
-with a "-" then you have to tell lldb that you're done with options for the
-current command by adding an option termination: "--". So for instance, if you
-want to launch a process and give the "process launch" command the
-"--stop-at-entry" option, yet you want the process you are about to launch to
-be launched with the arguments "-program_arg value", you would type:
+with a ``-`` then you have to tell lldb that you are done with options for the
+current command by adding an option termination: ``--``.
+
+So for instance, if you want to launch a process and give the ``process launch``
+command the ``--stop-at-entry`` option, yet you want the process you are about
+to launch to be launched with the arguments ``-program_arg value``, you would type:
 
 ::
 
    (lldb) process launch --stop-at-entry -- -program_arg value
 
 We also tried to reduce the number of special purpose argument parsers, which
-sometimes forces the user to be a little more explicit about stating their
-intentions. The first instance you'll note of this is the breakpoint command.
-In gdb, to set a breakpoint, you might enter
+sometimes forces the user to be explicit about their intentions. The first
+instance you willl see of this is the breakpoint command. In gdb, to set a
+breakpoint, you might enter:
 
 ::
 
    (gdb) break foo.c:12
 
-to break at line 12 of foo.c, and:
+To break at line ``12`` of ``foo.c``, and:
 
 ::
 
    (gdb) break foo
 
-to break at the function foo. As time went on, the parser that tells foo.c:12
-from foo from foo.c::foo (which means the function foo in the file foo.c) got
-more and more complex and bizarre, and especially in C++ there are times where
-there's really no way to specify the function you want to break on. The lldb
-commands are more verbose but also more precise and allow for intelligent auto
-completion.
+To break at the function ``foo``. As time went on, the parser that tells ``foo.c:12``
+from ``foo`` from ``foo.c::foo`` (which means the function ``foo`` in the file ``foo.c``)
+got more and more complex. Especially in C++ there are times where there is
+really no way to specify the function you want to break on.
+
+The lldb commands are more verbose but also more precise and allow for
+intelligent auto completion.
 
-To set the same file and line breakpoint in LLDB you can enter either of:
+To set the same file and line breakpoint in lldb you can enter either of:
 
 ::
 
    (lldb) breakpoint set --file foo.c --line 12
    (lldb) breakpoint set -f foo.c -l 12
 
-To set a breakpoint on a function named foo in LLDB you can enter either of:
+To set a breakpoint on a function named ``foo`` in lldb you can enter either of:
 
 ::
 
    (lldb) breakpoint set --name foo
    (lldb) breakpoint set -n foo
 
-You can use the --name option multiple times to make a breakpoint on a set of
+You can use the ``--name`` option multiple times to make a breakpoint on a set of
 functions as well. This is convenient since it allows you to set common
 conditions or commands without having to specify them multiple times:
 
@@ -91,9 +96,9 @@ conditions or commands without having to specify them multiple times:
 
    (lldb) breakpoint set --name foo --name bar
 
-Setting breakpoints by name is even more specialized in LLDB as you can specify
+Setting breakpoints by name is even more specialized in lldb as you can specify
 that you want to set a breakpoint at a function by method name. To set a
-breakpoint on all C++ methods named foo you can enter either of:
+breakpoint on all C++ methods named ``foo`` you can enter either of:
 
 ::
 
@@ -101,7 +106,7 @@ breakpoint on all C++ methods named foo you can enter either of:
    (lldb) breakpoint set -M foo
 
 
-To set a breakpoint Objective-C selectors named alignLeftEdges: you can enter either of:
+To set a breakpoint Objective-C selectors named ``alignLeftEdges:`` you can enter either of:
 
 ::
 
@@ -109,14 +114,14 @@ To set a breakpoint Objective-C selectors named alignLeftEdges: you can enter ei
    (lldb) breakpoint set -S alignLeftEdges:
 
 You can limit any breakpoints to a specific executable image by using the
-"--shlib <path>" ("-s <path>" for short):
+``--shlib <path>`` (``-s <path>`` for short):
 
 ::
 
    (lldb) breakpoint set --shlib foo.dylib --name foo
    (lldb) breakpoint set -s foo.dylib -n foo
 
-The --shlib option can also be repeated to specify several shared libraries.
+The ``--shlib`` option can also be repeated to specify several shared libraries.
 
 Suggestions on more interesting primitives of this sort are also very welcome.
 
@@ -130,16 +135,16 @@ command:
    (lldb) br s -n "-[SKTGraphicView alignLeftEdges:]"
 
 lldb also supports command completion for source file names, symbol names, file
-names, etc. Completion is initiated by a hitting a TAB. Individual options in a
-command can have different completers, so for instance, the "--file <path>"
-option in "breakpoint" completes to source files, the "--shlib <path>" option
-to currently loaded shared libraries, etc. We can even do things like if you
-specify "--shlib <path>", and are completing on "--file <path>", we will only
-list source files in the shared library specified by "--shlib <path>".
-
-The individual commands are pretty extensively documented. You can use the help
+names, etc. Completion is initiated by hitting TAB. Individual options in a
+command can have different completers, so for instance, the ``--file <path>``
+option in ``breakpoint`` completes to source files, the ``--shlib <path>`` option
+to currently loaded shared libraries, etc. You can even do things like if you
+specify ``--shlib <path>``, and are completing on ``--file <path>``, lldb will only
+list source files in the shared library specified by ``--shlib <path>``.
+
+The individual commands are pretty extensively documented. You can use the ``help``
 command to get an overview of which commands are available or to obtain details
-about specific commands. There is also an apropos command that will search the
+about specific commands. There is also an ``apropos`` command that will search the
 help text for all commands for a particular word and dump a summary help string
 for each matching command.
 
@@ -150,78 +155,75 @@ For instance, if you get annoyed typing:
 
    (lldb) breakpoint set --file foo.c --line 12
 
-you can do:
+You can do:
 
 ::
 
    (lldb) command alias bfl breakpoint set -f %1 -l %2
    (lldb) bfl foo.c 12
 
-We have added a few aliases for commonly used commands (e.g. "step", "next" and
-"continue") but we haven't tried to be exhaustive because in our experience it
+lldb has a few aliases for commonly used commands (e.g. ``step``, ``next`` and
+``continue``) but it does not try to be exhaustive because in our experience it
 is more convenient to make the basic commands unique down to a letter or two,
 and then learn these sequences than to fill the namespace with lots of aliases,
 and then have to type them all the way out.
 
 However, users are free to customize lldb's command set however they like, and
-since lldb reads the file ~/.lldbinit at startup, you can store all your
+since lldb reads the file ``~/.lldbinit`` at startup, you can store all your
 aliases there and they will be generally available to you. Your aliases are
-also documented in the help command so you can remind yourself of what you've
+also documented in the ``help`` command so you can remind yourself of what you have
 set up.
 
-One alias of note that we do include by popular demand is a weak emulator of
-gdb's "break" command. It doesn't try to do everything that gdb's break command
-does (for instance, it doesn't handle foo.c::bar. But it mostly works, and
-makes the transition easier. Also, by popular demand, it is aliased to b. If you
+One alias of note that lldb does include by popular demand is a weak emulator of
+gdb's ``break`` command. It does not try to do everything that gdb's break command
+does (for instance, it does not handle ``foo.c::bar``). But it mostly works, and
+makes the transition easier. Also, by popular demand, it is aliased to ``b``. If you
 actually want to learn the lldb command set natively, that means it will get in
-the way of the rest of the breakpoint commands. Fortunately, if you don't like
-one of our aliases, you can easily get rid of it by running (for example):
+the way of the rest of the breakpoint commands. Fortunately, if you do not like
+one of our aliases, you can easily get rid of it by running, for example:
 
 ::
 
    (lldb) command unalias b
 
-I actually also do:
+You can also do:
 
 ::
 
    (lldb) command alias b breakpoint
 
-so I can run the native lldb breakpoint command with just b
+So you can run the native lldb breakpoint command with just ``b``.
 
 The lldb command parser also supports "raw" commands, where, after command
 options are stripped off, the rest of the command string is passed
 uninterpreted to the command. This is convenient for commands whose arguments
 might be some complex expression that would be painful to backslash protect.
-For instance, the "expression" command is a "raw" command for obvious reasons.
-The "help" output for a command will tell you if it is "raw" or not, so you
+For instance, the ``expression`` command is a "raw" command for obvious reasons.
+The ``help`` output for a command will tell you if it is "raw" or not, so you
 know what to expect. The one thing you have to watch out for is that since raw
 commands still can have options, if your command string has dashes in it,
-you'll have to indicate these are not option markers by putting "--" after the
+you will have to indicate these are not option markers by putting ``--`` after the
 command name, but before your command string.
 
 lldb also has a built-in Python interpreter, which is accessible by the
-"script" command. All the functionality of the debugger is available as classes
+``"script`` command. All the functionality of the debugger is available as classes
 in the Python interpreter, so the more complex commands that in gdb you would
-introduce with the "define" command can be done by writing Python functions
+introduce with the ``define`` command can be done by writing Python functions
 using the lldb-Python library, then loading the scripts into your running
-session and accessing them with the "script" command.
+session and accessing them with the ``script`` command.
 
-Having given an overview of lldb's command syntax, we proceed to lay out the
-stages of a standard debug session.
-
-
-Loading a Program into lldb
+Loading a Program Into lldb
 ---------------------------
 
-First we need to set the program to debug. As with gdb, you can start lldb and specify the file you wish to debug on the command line:
+First you need to set the program to debug. As with gdb, you can start lldb and
+specify the file you wish to debug on the command line:
 
 ::
 
    $ lldb /Projects/Sketch/build/Debug/Sketch.app
    Current executable set to '/Projects/Sketch/build/Debug/Sketch.app' (x86_64).
 
-or you can specify it after the fact with the "file" command:
+Or you can specify it after the fact with the ``file`` command:
 
 ::
 
@@ -232,15 +234,15 @@ or you can specify it after the fact with the "file" command:
 Setting Breakpoints
 -------------------
 
-We've discussed how to set breakpoints above. You can use help breakpoint set
-to see all the options for breakpoint setting. For instance, we might do:
+We have discussed how to set breakpoints above. You can use ``help breakpoint set``
+to see all the options for breakpoint setting. For instance, you could do:
 
 ::
 
    (lldb) breakpoint set --selector alignLeftEdges:
    Breakpoint created: 1: name = 'alignLeftEdges:', locations = 1, resolved = 1
 
-You can find out about the breakpoints you've set with:
+You can find out about the breakpoints you have set with:
 
 ::
 
@@ -257,12 +259,12 @@ your program. Similarly, a file and line breakpoint might result in multiple
 locations if that file and line were inlined in different places in your code.
 
 The logical breakpoint has an integer id, and its locations have an id within
-their parent breakpoint (the two are joined by a ".", e.g. 1.1 in the example
+their parent breakpoint (the two are joined by a ``.``, e.g. ``1.1`` in the example
 above).
 
-Also, the logical breakpoints remain live so that if another shared library were
-to be loaded that had another implementation of the "alignLeftEdges:" selector,
-the new location would be added to breakpoint 1 (e.g. a "1.2" breakpoint would
+Also logical breakpoints remain live so that if another shared library were
+to be loaded that had another implementation of the ``alignLeftEdges:`` selector,
+the new location would be added to breakpoint ``1`` (e.g. a ``1.2`` breakpoint would
 be set on the newly loaded selector).
 
 The other piece of information in the breakpoint listing is whether the
@@ -271,21 +273,19 @@ address it corresponds to gets loaded into the program you are debugging. For
 instance if you set a breakpoint in a shared library that then gets unloaded,
 that breakpoint location will remain, but it will no longer be resolved.
 
-
 One other thing to note for gdb users is that lldb acts like gdb with:
 
 ::
 
    (gdb) set breakpoint pending on
 
-That is, lldb will always make a breakpoint from your specification, even if it
-couldn't find any locations that match the specification. You can tell whether
+Which means that lldb will always make a breakpoint from your specification, even if it
+could not find any locations that match the specification. You can tell whether
 the expression was resolved or not by checking the locations field in
-"breakpoint list", and we report the breakpoint as "pending" when you set it so
-you can tell you've made a typo more easily, if that was indeed the reason no
+``breakpoint list``, and lldb reports the breakpoint as ``pending`` when you set it so
+you can tell you have made a typo more easily, if that was indeed the reason no
 locations were found:
 
-
 ::
 
    (lldb) breakpoint set --file foo.c --line 12
@@ -294,8 +294,8 @@ locations were found:
 
 You can delete, disable, set conditions and ignore counts either on all the
 locations generated by your logical breakpoint, or on any one of the particular
-locations your specification resolved to. For instance, if we wanted to add a
-command to print a backtrace when we hit this breakpoint we could do:
+locations your specification resolved to. For instance, if you wanted to add a
+command to print a backtrace when you hit this breakpoint you could do:
 
 ::
 
@@ -305,12 +305,12 @@ command to print a backtrace when we hit this breakpoint we could do:
    > DONE
 
 By default, the breakpoint command add command takes lldb command line
-commands. You can also specify this explicitly by passing the "--command"
-option. Use "--script" if you want to implement your breakpoint command using
+commands. You can also specify this explicitly by passing the ``--command``
+option. Use ``--script`` if you want to implement your breakpoint command using
 the Python script instead.
 
 This is a convenient point to bring up another feature of the lldb command
-help. Do:
+``help``. Do:
 
 ::
 
@@ -320,8 +320,8 @@ help. Do:
    Syntax: breakpoint command add <cmd-options> <breakpt-id>
    etc...
 
-When you see arguments to commands specified in the Syntax in angle brackets
-like <breakpt-id>, that indicates that that is some common argument type that
+When you see arguments to commands specified in the ``Syntax`` section in angle brackets
+like ``<breakpt-id>``, that indicates that that is some common argument type that
 you can get further help on from the command system. So in this case you could
 do:
 
@@ -330,35 +330,45 @@ do:
    (lldb) help <breakpt-id> <breakpt-id> -- Breakpoint ID's consist major and
    minor numbers; the major etc...
 
-
 Breakpoint Names
 ----------------
 
-Breakpoints carry two orthogonal sets of information: one specifies where to set the breakpoint, and the other how to react when the breakpoint is hit. The latter set of information (e.g. commands, conditions, hit-count, auto-continue...) we call breakpoint options.
+Breakpoints carry two orthogonal sets of information: one specifies where to set
+the breakpoint, and the other how to react when the breakpoint is hit. The latter
+set of information (e.g. commands, conditions, hit-count, auto-continue...) we
+call breakpoint options.
 
-It is fairly common to want to apply one set of options to a number of breakpoints. For instance, you might want to check that self == nil and if it is, print a backtrace and continue, on a number of methods. One convenient way to do that would be to make all the breakpoints, then configure the options with:
+It is fairly common to want to apply one set of options to a number of breakpoints.
+For instance, you might want to check that ``self == nil`` and if it is, print a
+backtrace and continue, on a number of methods. One convenient way to do that would
+be to make all the breakpoints, then configure the options with:
 
 ::
 
    (lldb) breakpoint modify -c "self == nil" -C bt --auto-continue 1 2 3
 
-That's not too bad, but you have to repeat this for every new breakpoint you make, and if you wanted to change the options, you have to remember all the ones you are using this way.
+That is not too bad, but you have to repeat this for every new breakpoint you make,
+and if you wanted to change the options, you have to remember all the ones you are
+usi...
[truncated]

@DavidSpickett
Copy link
Collaborator Author

Always refer to lldb as lldb not LLDB, to match what the user sees on the command line.

If this were any other doc I'd say it should always be LLDB and GDB as that's the projects' branding. In this doc I think it's better to imagine the user is looking at side by side command lines.

@medismailben
Copy link
Member

LGTM!

@JDevlieghere
Copy link
Member

Always refer to lldb as lldb not LLDB, to match what the user sees on the command line.

If this were any other doc I'd say it should always be LLDB and GDB as that's the projects' branding. In this doc I think it's better to imagine the user is looking at side by side command lines.

I'm not sure I follow that reasoning. In all fairness I might be biased as I try to consistently use "LLDB" unless I'm referring tot the binary or the prompt. Ignoring things like (lldb), lldb- and lldb., it looks like the docs favor "LLDB" as well.

$ rg 'LLDB' | wc -l
     605
$ rg 'lldb' | awk '!/\(lldb\)/ && !/lldb\./ && !/lldb-/' | wc -l
     362

Personally I'd lean towards more consistency.

@DavidSpickett
Copy link
Collaborator Author

Yes fair point the docs as a whole prefer the branding. As the document itself was mostly lower case that also influenced me.

I tried to put the name changes in their own commit but some are spread around, so I'll be a bit cheeky and land this as is then come back with a PR to properly brand the names, or mark places where we are talking about the binary.

@DavidSpickett DavidSpickett merged commit eb6097a into llvm:main May 1, 2024
7 checks passed
@DavidSpickett DavidSpickett deleted the lldb-tutorial branch May 1, 2024 09:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants