[Docs] fixes

Stylistic and other fixes

R=andybons@chromium.org
BUG=524256

Review URL: https://codereview.chromium.org/1318153003

Cr-Commit-Position: refs/heads/master@{#346569}

docs/how_to_extend_layout_test_framework.md

@@ -31,17 +31,12 @@ what exactly exactly is being tested.
 This part isn’t too difficult. There are basically two classes that need to be
 extended (ideally, just inherited from). These classes are:
 
-    Driver
-
-Located in `layout_tests/port/driver.py`. Each instance of this is the class
-that will actually an instance of the program that produces the test data
-(program in Part 2).
-
-    Port
-
-Located in `layout_tests/port/base.py`. This class is responsible creating
-drivers with the correct settings, giving access to certain OS functionality to
-access expected files, etc.
+*   `Driver`. Located in `layout_tests/port/driver.py`. Each instance of this is
+    the class that will actually an instance of the program that produces the
+    test data (program in Part 2).
+*   `Port`. Located in `layout_tests/port/base.py`. This class is responsible
+    creating drivers with the correct settings, giving access to certain OS
+    functionality to access expected files, etc.
 
 #### Extending Driver
 
@@ -119,6 +114,7 @@ tests in that directory, but it will find the correct TestExpectations file, the
 platform specific expected files, etc.
 
 Here are some of the functions that most likely need to be overridden.
+
 *   `driver_class`
     *   This should be overridden to allow the testing program to actually run.
         By default the code will run content_shell, which might or might not be

docs/linux_build_instructions.md

@@ -26,10 +26,12 @@ Here's an overview of the steps you'll run:
 *   [Get the Code](http://dev.chromium.org/developers/how-tos/get-the-code):
     check out the source code.
 
-**Note**. If you are working on Chromium OS and already have sources in
+*** note
+Note: if you are working on Chromium OS and already have sources in
 `chromiumos/chromium`, you **must** run `chrome_set_ver --runhooks` to set the
 correct dependencies. This step is otherwise performed by `gclient` as part of
 your checkout.
+***
 
 ## First Time Build Bootstrap
 

docs/linux_build_instructions_prerequisites.md

@@ -45,7 +45,7 @@ Before setting up the environment, make sure you install the
 
 ### Ubuntu Setup
 
-Run [build/install-build-deps.sh](build/install-build-deps.sh) The script only
+Run [build/install-build-deps.sh](/build/install-build-deps.sh) The script only
 supports current releases as listed on https://wiki.ubuntu.com/Releases.
 
 Building on Linux requires software not usually installed with the
@@ -98,21 +98,21 @@ The msttcorefonts packages can be obtained by following the instructions present
 here: http://www.fedorafaq.org/#installfonts
 
 For the optional packages:
+
 *   php-cgi is provided by the php-cli package
 *   wdiff doesn't exist in Fedora repositories, a possible alternative would be
     dwdiff
 *   sun-java6-fonts doesn't exist in Fedora repositories, needs investigating
 
     su -c 'yum install httpd mod_ssl php php-cli wdiff'
 
-
 #### Arch Linux Setup
 
 Most of these packages are probably already installed since they're often used,
 and the parameter --needed ensures that packages up to date are not reinstalled.
 
 ```shell
-$ sudo pacman -S --needed python perl gcc gcc-libs bison flex gperf pkgconfig \
+sudo pacman -S --needed python perl gcc gcc-libs bison flex gperf pkgconfig \
   nss alsa-lib gconf glib2 gtk2 nspr ttf-ms-fonts freetype2 cairo dbus \
   libgnome-keyring
 ```
@@ -139,17 +139,24 @@ lib64pango1.0-devel lib64cairo-devel lib64nss-devel lib64nspr-devel g++ python \
 perl bison flex subversion gperf
 ```
 
+*** note
 Note 1: msttcorefonts are not available, you will need to build your own (see
 instructions, not hard to do, see
 [mandriva_msttcorefonts.md](mandriva_msttcorefonts.md)) or use drakfont to
 import the fonts from a windows installation
+***
 
+*** note
 Note 2: these packages are for 64 bit, to download the 32 bit packages,
 substitute lib64 with lib
+***
 
+*** note
 Note 3: some of these packages might not be explicitly necessary as they come as
 dependencies, there is no harm in including them however.
+***
 
+*** note
 Note 4: to build on 64 bit systems use, instead of
 `GYP_DEFINES=target_arch=x64`, as mentioned in the general notes for building on
 64 bit:
@@ -158,6 +165,7 @@ Note 4: to build on 64 bit systems use, instead of
 export GYP_DEFINES="target_arch=x64"
 gclient runhooks --force
 ```
+***
 
 #### Gentoo setup
 

docs/linux_cert_management.md

@@ -1,8 +1,10 @@
 # Linux Cert Management
 
+*** note
 **NOTE:** SSL client authentication with personal certificates does not work
 completely in Linux, see [issue 16830](https://crbug.com/16830) and
 [issue 25241](https://crbug.com/25241).
+***
 
 The easy way to manage certificates is navigate to chrome://settings/search#ssl.
 Then click on the "Manage Certificates" button. This will load a built-in

docs/linux_chromium_arm.md

@@ -56,22 +56,22 @@ Chromium's testing infrastructure for ARM/Linux is (to say the least)
 in its infancy. There are currently two builders setup, one on the
 FYI waterfall and one the the trybot waterfall:
 
-http://build.chromium.org/p/chromium.fyi/builders/Linux%20ARM%20Cross-Compile
-http://build.chromium.org/p/tryserver.chromium.linux/builders/linux_arm
+*   [Linux ARM Cross-Compile](http://build.chromium.org/p/chromium.fyi/builders/Linux%20ARM%20Cross-Compile)
+*   [linux_arm](http://build.chromium.org/p/tryserver.chromium.linux/builders/linux_arm)
 
 These builders cross compile on x86-64 and then trigger testing on real ARM hard
 bots:
 
-http://build.chromium.org/p/chromium.fyi/builders/Linux%20ARM%20Tests%20%28Panda%29/
-http://build.chromium.org/p/tryserver.chromium.linux/builders/linux_arm_tester
+*   [Linux ARM Tests (Panda)](http://build.chromium.org/p/chromium.fyi/builders/Linux%20ARM%20Tests%20%28Panda%29/)
+*   [linux_arm_tester](http://build.chromium.org/p/tryserver.chromium.linux/builders/linux_arm_tester)
 
 Unfortunately, even those the builders are usually green, the testers are not
 yet well maintained or monitored.
 
 There is compile-only trybot and fyi bot also:
 
-http://build.chromium.org/p/chromium.fyi/builders/Linux%20ARM
-http://build.chromium.org/p/tryserver.chromium.linux/builders/linux_arm_compile
+*   [Linux ARM](http://build.chromium.org/p/chromium.fyi/builders/Linux%20ARM)
+*   [linux_arm_compile](http://build.chromium.org/p/tryserver.chromium.linux/builders/linux_arm_compile)
 
 ### Testing with QEMU
 

docs/linux_debugging.md

@@ -16,7 +16,9 @@ needed. Talk to security@chromium.org.
 
 ## GDB
 
-**GDB-7.7 is required in order to debug Chrome on Linux.**
+*** promo
+GDB-7.7 is required in order to debug Chrome on Linux.
+***
 
 Any prior version will fail to resolve symbols or segfault.
 
@@ -59,17 +61,19 @@ if you're also running the main process in gdb, won't work at all (the two
 instances will fight over the terminal). To auto-start the renderers in the
 debugger, send the "run" command to the debugger:
 
-    chrome --no-sandbox --renderer-cmd-prefix='xterm -title renderer -e gdb -ex \
-        run --args
+    chrome --no-sandbox --renderer-cmd-prefix='xterm -title renderer -e gdb \
+        -ex run --args
 
 If you're using Emacs and `M-x gdb`, you can do
 
     chrome "--renderer-cmd-prefix=gdb --args"
 
+*** note
 Note: using the `--renderer-cmd-prefix` option bypasses the zygote launcher, so
 the renderers won't be sandboxed. It is generally not an issue, except when you
 are trying to debug interactions with the sandbox. If that's what you are doing,
 you will need to attach your debugger to a running renderer process (see below).
+***
 
 You may also want to pass `--disable-hang-monitor` to suppress the hang monitor,
 which is rather annoying.
@@ -177,8 +181,10 @@ Same strategies as renderers above, but the flag is called `--plugin-launcher`:
 
     chrome --plugin-launcher='xterm -e gdb --args'
 
-_Note: For now, this does not currently apply to PPAPI plugins because they
-currently run in the renderer process._
+*** note
+Note: For now, this does not currently apply to PPAPI plugins because they
+currently run in the renderer process.
+***
 
 #### Single-Process mode
 
@@ -257,7 +263,7 @@ Use the `gdb-add-index` script (e.g.
 `build/gdb-add-index out/Debug/browser_tests`)
 
 Only makes sense if you run the binary multiple times or maybe if you use the
-component build since most .so files won't require reindexing on a rebuild.
+component build since most `.so` files won't require reindexing on a rebuild.
 
 See
 https://groups.google.com/a/chromium.org/forum/#!searchin/chromium-dev/gdb-add-index/chromium-dev/ELRuj1BDCL4/5Ki4LGx41CcJ
@@ -364,7 +370,7 @@ Alternatively, you can use testing/xvfb.py to set up your environment for you:
     testing/xvfb.py out/Debug out/Debug/browser_tests \
         --gtest_filter="MyBrowserTest.MyActivateWindowTest"
 
-### `BROWSER_WRAPPER`
+### BROWSER_WRAPPER
 
 You can also get the browser under a debugger by setting the `BROWSER_WRAPPER`
 environment variable.  (You can use this for `browser_tests` too, but see above
@@ -391,8 +397,7 @@ Default log level hides `LOG(INFO)`. Run with `--log-level=0` and
 `--enable-logging=stderr` flags.
 
 Newer versions of chromium with VLOG may need --v=1 too. For more VLOG tips, see
-the chromium-dev thread:
-http://groups.google.com/a/chromium.org/group/chromium-dev/browse_thread/thread/dcd0cd7752b35de6?pli=1
+[the chromium-dev thread](http://groups.google.com/a/chromium.org/group/chromium-dev/browse_thread/thread/dcd0cd7752b35de6?pli=1).
 
 ### Seeing IPC debug messages
 
@@ -405,9 +410,9 @@ or within gdb:
     set environment CHROME_IPC_LOGGING 1
 
 If some messages show as unknown, check if the list of IPC message headers in
-`chrome/common/logging_chrome.cc` is up-to-date. In case this file reference
-goes out of date, try looking for usage of macros like `IPC_MESSAGE_LOG_ENABLED`
-or `IPC_MESSAGE_MACROS_LOG_ENABLED`.
+[chrome/common/logging_chrome.cc](/chrome/common/logging_chrome.cc) is
+up-to-date. In case this file reference goes out of date, try looking for usage
+of macros like `IPC_MESSAGE_LOG_ENABLED` or `IPC_MESSAGE_MACROS_LOG_ENABLED`.
 
 ## Using valgrind
 
@@ -469,7 +474,7 @@ with the appropriate instructions if you know what they are.)
 
 ## Breakpad
 
-See the last section of [linux_crash_dumping.md](linux_crash_dumping.md); you
+See the last section of [Linux Crash Dumping](linux_crash_dumping.md); you
 need to set a gyp variable and an environment variable for the crash dump tests
 to work.
 
@@ -478,14 +483,15 @@ to work.
 If you break in a debugger during a drag, Chrome will have grabbed your mouse
 and keyboard so you won't be able to interact with the debugger!  To work around
 this, run via `Xephyr`. Instructions for how to use `Xephyr` are on the
-[layout_tests_linux.md](layout_tests_linux.md) page.
+[Running layout tests on Linux](layout_tests_linux.md) page.
 
 ## Tracking Down Bugs
 
 ### Isolating Regressions
 
 Old builds are archived here:
 http://build.chromium.org/buildbot/snapshots/chromium-rel-linux/
+(TODO: does not exist).
 
 `tools/bisect-builds.py` in the tree automates bisecting through the archived
 builds. Despite a computer science education, I am still amazed how quickly
@@ -533,7 +539,7 @@ Some strategies are:
 
 To test on various window managers, you can use a nested X server like `Xephyr`.
 Instructions for how to use `Xephyr` are on the
-[layout_tests_linux.md](layout_tests_linux.md) page.
+[Running layout tests on Linux](layout_tests_linux.md) page.
 
 If you need to test something with hardware accelerated compositing
 (e.g., compiz), you can use `Xgl` (`sudo apt-get install xserver-xgl`). E.g.:

docs/linux_debugging_gtk.md

@@ -54,7 +54,7 @@ gtkparasite, you can do:
     scp bunny.sfo:/usr/lib/gtk-2.0/modules/libgtkparasite.so /tmp
     sudo cp /tmp/libgtkparasite.so /usr/lib/gtk-2.0/modules/libgtkparasite.so
 
-## `GDK_DEBUG`
+## GDK_DEBUG
 
 Use `GDK_DEBUG=nograbs` to run GTK+ without grabs. This is useful for gdb
 sessions.

docs/linux_debugging_ssl.md

@@ -10,9 +10,9 @@ In order to use a debugger with the NSS library, it helps to build NSS yourself.
 Here's how I did it:
 
 First, read
-http://www.mozilla.org/projects/security/pki/nss/nss-3.11.4/nss-3.11.4-build.html
+[Network Security Services](http://www.mozilla.org/projects/security/pki/nss/nss-3.11.4/nss-3.11.4-build.html)
 and/or
-https://developer.mozilla.org/En/NSS_reference/Building_and_installing_NSS/Build_instructions
+[Build instructions](https://developer.mozilla.org/En/NSS_reference/Building_and_installing_NSS/Build_instructions).
 
 Then, to build the most recent source tarball:
 
@@ -137,6 +137,6 @@ be set automatically.)
 
 ## Support forums
 
-If you have nonconfidential questions about NSS, check the newsgroup
-http://groups.google.com/group/mozilla.dev.tech.crypto The NSS maintainer
-monitors that group and gives good answers.
+If you have nonconfidential questions about NSS, check
+[the newsgroup](http://groups.google.com/group/mozilla.dev.tech.crypto).
+The NSS maintainer monitors that group and gives good answers.

docs/linux_development.md

@@ -1,16 +1,18 @@
 # Linux Development
 
-**Please join us on IRC for the most up-to-date development discussion:
-`irc.freenode.net`, `#chromium`**
+*** promo
+Please join us on IRC for the most up-to-date development discussion:
+`irc.freenode.net`, `#chromium`.
+***
 
 ## Checkout and Build
 
 See the [Linux build instructions](linux_build_instructions.md).
 
 ## What Needs Work
 
-Look at the Chromium bug tracker for open Linux issues:
-http://code.google.com/p/chromium/issues/list?can=2&q=os%3Alinux
+Look at the Chromium bug tracker for
+[open Linux issues](http://code.google.com/p/chromium/issues/list?can=2&q=os%3Alinux).
 
 Issues marked "Available" are ready for someone to claim. To claim an issue, add
 a comment and then a project member will mark it "Assigned". If none of the
@@ -31,12 +33,12 @@ issues. If you can't find a related bug, please create a
 
 ## Contributing code
 
-See [ContributingCode](http://dev.chromium.org/developers/contributing-code).
+See [Contributing code](http://dev.chromium.org/developers/contributing-code).
 
 ## Debugging
 
-See [linux_debugging.md](linux_debugging.md).
+See [Linux debugging](linux_debugging.md).
 
 ## Documents
 
-[linux_graphics_pipeline.md](linux_graphics_pipeline.md)
+[Linux Graphics Pipeline](linux_graphics_pipeline.md)

docs/linux_eclipse_dev.md

@@ -22,10 +22,9 @@ developing Chromium. It's unpolished, but here's what works:
 
 Eclipse 4.3 (Kepler) is known to work with Chromium for Linux.
 
-*   Download the distribution appropriate for your OS. For example, for Linux
-    64-bit/Java 64-bit, use the Linux 64 bit package from
-    http://www.eclipse.org/downloads/ (Eclipse Packages Tab -> Linux 64 bit
-    (link in bottom right)).
+*   [Download](http://www.eclipse.org/downloads/) the distribution appropriate
+    for your OS. For example, for Linux 64-bit/Java 64-bit, use the Linux 64 bit
+    package (Eclipse Packages Tab -> Linux 64 bit (link in bottom right)).
     *   Tip: The packaged version of eclipse in distros may not work correctly
         with the latest CDT plugin (installed below). Best to get them all from
         the same source.
@@ -38,8 +37,10 @@ Eclipse 4.3 (Kepler) is known to work with Chromium for Linux.
         `-Xmx3072m` (maximum heap).
     *   Googlers: Edit `~/.eclipse/init.sh` to add this:
 
-    export ECLIPSE_MEM_START="1024M"
-    export ECLIPSE_MEM_MAX="3072M"
+```
+export ECLIPSE_MEM_START="1024M"
+export ECLIPSE_MEM_MAX="3072M"
+```
 
 The large heap size prevents out of memory errors if you include many Chrome
 subprojects that Eclipse is maintaining code indices for.
@@ -93,11 +94,10 @@ same directory as your checkout.
 
 1.  From the Help menu, select Install New Software...
     1.  Select the 'Workd with' URL for the CDT
-        1.  If it's not there you can click Add... and add it.
-            1.  See https://eclipse.org/cdt/downloads.php for up to date
-                versions.
-                1.  e.g. with CDT 8.7.0 for Eclipse Mars, use
-                    http://download.eclipse.org/tools/cdt/releases/8.7
+        If it's not there you can click Add... and add it.
+        See https://eclipse.org/cdt/downloads.php for up to date versions,
+        e.g. with CDT 8.7.0 for Eclipse Mars, use
+        http://download.eclipse.org/tools/cdt/releases/8.7
     1.  Googlers: We have a local mirror, but be sure you run prodaccess before
         trying to use it.
 1.  Select & install the Main and Optional features.

docs/linux_faster_builds.md

@@ -144,9 +144,11 @@ As root:
 
     mount -t tmpfs -o size=20G,nr_inodes=40k,mode=1777 tmpfs /path/to/out
 
+*** note
 **Caveat:** You need to have enough RAM + swap to back the tmpfs. For a full
 debug build, you will need about 20 GB. Less for just building the chrome target
 or for a release build.
+***
 
 Quick and dirty benchmark numbers on a HP Z600 (Intel core i7, 16 cores
 hyperthreaded, 12 GB RAM)