Use the new section title style in Asciidoctor.

We previous use the section title style like:

Section level 1
===============

Section level 2
---------------

Which have a problem in Asciidoctor that the number of "="s or "-"s must match
the number of characters in the header exactly, as a result it's easy to make
mistakes while changing the titles. Asciidoctor provides a better style like:

= Section level 1

== Section level 2

So we switched to this style.

Also fixed a bug in replace_macros.py, which will not cause any problem in the
old style.

Change-Id: I811dd7238735d98f662767c17086152cd69aea02

Documentation/access-control.txt

@@ -1,5 +1,4 @@
-Gerrit Code Review - Access Controls
+= Gerrit Code Review - Access Controls
-====================================
 
 Access controls in Gerrit are group based.  Every user account is a
 member of one or more groups, and access and privileges are granted
@@ -7,8 +6,7 @@ to those groups.  Access rights cannot be granted to individual
 users.
 
 
-System Groups
+== System Groups
--------------
 
 Gerrit comes with following system groups:
 
@@ -26,8 +24,7 @@ if desired.
 
 
 [[administrators]]
-Administrators
+=== Administrators
-~~~~~~~~~~~~~~
 
 This is the Gerrit "root" identity.
 
@@ -45,8 +42,7 @@ other normal user would, without needing two different accounts.
 
 
 [[anonymous_users]]
-Anonymous Users
+=== Anonymous Users
-~~~~~~~~~~~~~~~
 
 All users are automatically a member of this group.  Users who are
 not signed in are a member of only this group, and no others.
@@ -61,8 +57,7 @@ identity for all other operations.
 
 
 [[non-interactive_users]]
-Non-Interactive Users
+=== Non-Interactive Users
-~~~~~~~~~~~~~~~~~~~~~
 
 This is an internal user group, members of this group are not expected
 to perform interactive operations on the Gerrit web front-end.
@@ -77,8 +72,7 @@ resources are tight.
 
 
 [[project_owners]]
-Project Owners
+=== Project Owners
-~~~~~~~~~~~~~~
 
 Access rights assigned to this group are always evaluated within the
 context of a project to which the access rights apply. These rights
@@ -95,8 +89,7 @@ newly created child projects.
 
 
 [[change_owner]]
-Change Owner
+=== Change Owner
-~~~~~~~~~~~~
 
 Access rights assigned to this group are always evaluated within the
 context of a change to which the access rights apply. These rights
@@ -107,8 +100,7 @@ owner to vote on his change, but not actually cause it to become
 approved or rejected.
 
 [[registered_users]]
-Registered Users
+=== Registered Users
-~~~~~~~~~~~~~~~~
 
 All signed-in users are automatically a member of this group (and
 also <<anonymous_users,'Anonymous Users'>>, see above).
@@ -127,8 +119,7 @@ Registered users are always permitted to make and publish comments
 on any change in any project they have `Read` access to.
 
 
-Account Groups
+== Account Groups
---------------
 
 Account groups contain a list of zero or more user account members,
 added individually by a group owner.  Any user account listed as
@@ -162,8 +153,7 @@ members of `Foo` have submit rights on a project, and the members of
 
 
 [[ldap_groups]]
-LDAP Groups
+== LDAP Groups
------------
 
 LDAP groups are Account Groups that are maintained inside of your
 LDAP instance. If you are using LDAP to manage your groups they will
@@ -173,8 +163,7 @@ Access Control for a project. For example "ldap/foo-project" will
 add the LDAP "foo-project" group to the access list.
 
 
-Project Access Control Lists
+== Project Access Control Lists
-----------------------------
 
 A system wide access control list affecting all projects is stored in
 project "`All-Projects`".  This inheritance can be configured
@@ -283,8 +272,7 @@ would be needed:
 |==============================================================
 
 
-OpenID Authentication
+=== OpenID Authentication
-~~~~~~~~~~~~~~~~~~~~~
 
 If the Gerrit instance is configured to use OpenID authentication,
 an account's effective group membership will be restricted to only
@@ -293,8 +281,7 @@ of its OpenID identities match one or more of the patterns listed
 in the `auth.trustedOpenID` list from `gerrit.config`.
 
 
-All Projects
+=== All Projects
-~~~~~~~~~~~~
 
 Any access right granted to a group within `All-Projects`
 is automatically inherited by every other project in the same
@@ -313,8 +300,7 @@ group gives nearly the same level of access as membership in
 permissions for every managed project including global capabilities.
 
 
-Per-Project
+=== Per-Project
-~~~~~~~~~~~
 
 The per-project ACL is evaluated before the global `All-Projects` ACL,
 permitting some limited override capability to project owners. This
@@ -323,8 +309,7 @@ granting 'DENY' within a specific project to deny a group access.
 
 
 [[references]]
-Special and magic references
+== Special and magic references
-----------------------------
 
 The reference namespaces used in git are generally two, one for branches and
 one for tags:
@@ -339,8 +324,7 @@ special meaning.
 
 
 [[references_special]]
-Special references
+=== Special references
-~~~~~~~~~~~~~~~~~~
 
 The special references have content that's either generated by Gerrit or
 contains important project configuration that Gerrit needs. When making
@@ -348,8 +332,7 @@ changes to these references, Gerrit will take extra precautions to verify the
 contents compatibility at upload time.
 
 
-refs/changes/*
+==== refs/changes/*
-^^^^^^^^^^^^^^
 
 Under this namespace each uploaded patch set for every change gets a static
 reference in their git.  The format is convenient but still intended to scale to
@@ -365,8 +348,7 @@ need the change number and patch set number.
 You can also find these static references linked on the page of each change.
 
 
-refs/meta/config
+==== refs/meta/config
-^^^^^^^^^^^^^^^^
 
 This is where the Gerrit configuration of each project resides.  This
 branch contains several files of importance: +project.config+, +groups+ and
@@ -374,15 +356,13 @@ branch contains several files of importance: +project.config+, +groups+ and
 review process.
 
 
-refs/meta/dashboards/*
+==== refs/meta/dashboards/*
-^^^^^^^^^^^^^^^^^^^^^^
 
 There's a dedicated page where you can read more about
 link:user-dashboards.html[User Dashboards].
 
 
-refs/notes/review
+==== refs/notes/review
-^^^^^^^^^^^^^^^^^
 
 Autogenerated copy of review notes for all changes in the git.  Each log entry
 on the refs/notes/review branch also references the patch set on which the
@@ -390,14 +370,12 @@ review is made.  This functionality is provided by the review-notes plugin.
 
 
 [[references_magic]]
-Magic references
+=== Magic references
-~~~~~~~~~~~~~~~~
 
 These are references with added functionality to them compared to a regular
 git push operation.
 
-refs/for/<branch ref>
+==== refs/for/<branch ref>
-^^^^^^^^^^^^^^^^^^^^^
 
 Most prominent is the `refs/for/<branch ref>` reference which is the reference
 upon which we build the code review intercept before submitting a commit to
@@ -407,15 +385,13 @@ Further documentation on how to push can be found on the
 link:user-upload.html#push_create[Upload changes] page.
 
 
-refs/publish/*
+==== refs/publish/*
-^^^^^^^^^^^^^^
 
 `refs/publish/*` is an alternative name to `refs/for/*` when pushing new changes
 and patch sets.
 
 
-refs/drafts/*
+==== refs/drafts/*
-^^^^^^^^^^^^^
 
 Push to `refs/drafts/*` creates a change like push to `refs/for/*`, except the
 resulting change remains hidden from public review.  You then have the option
@@ -425,8 +401,7 @@ draft patch sets of a change into public patch sets for review.
 
 
 [[access_categories]]
-Access Categories
+== Access Categories
------------------
 
 Gerrit has several permission categories that can be granted to groups
 within projects, enabling functionality for that group's members.
@@ -434,8 +409,7 @@ within projects, enabling functionality for that group's members.
 
 
 [[category_abandon]]
-Abandon
+=== Abandon
-~~~~~~~
 
 This category controls whether users are allowed to abandon changes
 to projects in Gerrit. It can give permission to abandon a specific
@@ -447,8 +421,7 @@ ref.
 
 
 [[category_create]]
-Create Reference
+=== Create Reference
-~~~~~~~~~~~~~~~~
 
 The create reference category controls whether it is possible to
 create new references, branches or tags.  This implies that the
@@ -482,8 +455,7 @@ stale branches.
 
 
 [[category_forge_author]]
-Forge Author
+=== Forge Author
-~~~~~~~~~~~~
 
 Normally Gerrit requires the author and the committer identity
 lines in a Git commit object (or tagger line in an annotated tag) to
@@ -503,8 +475,7 @@ is required.
 
 
 [[category_forge_committer]]
-Forge Committer
+=== Forge Committer
-~~~~~~~~~~~~~~~
 
 Normally Gerrit requires the author and the committer identity
 lines in a Git commit object (or tagger line in an annotated tag) to
@@ -518,8 +489,7 @@ required when mirroring commits from an upstream project repository.
 
 
 [[category_forge_server]]
-Forge Server
+=== Forge Server
-~~~~~~~~~~~~
 
 Normally Gerrit requires the author and the committer identity
 lines in a Git commit object (or tagger line in an annotated tag) to
@@ -535,8 +505,7 @@ Review server.
 
 
 [[category_owner]]
-Owner
+=== Owner
-~~~~~
 
 The `Owner` category controls which groups can modify the project's
 configuration.  Users who are members of an owner group can:
@@ -559,8 +528,7 @@ out more about this role.
 
 
 [[category_push]]
-Push
+=== Push
-~~~~
 
 This category controls how users are allowed to upload new commits
 to projects in Gerrit. It can either give permission to push
@@ -571,8 +539,7 @@ permission is granted to.
 
 
 [[category_push_direct]]
-Direct Push
+==== Direct Push
-^^^^^^^^^^^
 
 Any existing branch can be fast-forwarded to a new commit.
 Creation of new branches is controlled by the
@@ -595,8 +562,7 @@ reviews should not grant this category.
 
 
 [[category_push_review]]
-Upload To Code Review
+==== Upload To Code Review
-^^^^^^^^^^^^^^^^^^^^^
 
 The `Push` access right granted on the namespace
 `refs/for/refs/heads/BRANCH` permits the user to upload a non-merge
@@ -620,8 +586,7 @@ The force option has no function when granted to a branch in the
 
 
 [[category_push_merge]]
-Push Merge Commits
+=== Push Merge Commits
-~~~~~~~~~~~~~~~~~~
 
 The `Push Merge Commit` access right permits the user to upload merge
 commits.  It's an add-on to the <<category_push,Push>> access right, and
@@ -639,8 +604,7 @@ of merge commits.
 
 
 [[category_push_annotated]]
-Push Annotated Tag
+=== Push Annotated Tag
-~~~~~~~~~~~~~~~~~~
 
 This category permits users to push an annotated tag object into the
 project's repository.  Typically this would be done with a command line
@@ -680,8 +644,7 @@ requires the same permission as deleting a branch.
 
 
 [[category_push_signed]]
-Push Signed Tag
+=== Push Signed Tag
-~~~~~~~~~~~~~~~
 
 This category permits users to push a PGP signed tag object into the
 project's repository.  Typically this would be done with a command
@@ -702,8 +665,7 @@ Tags must be signed (created with `git tag -s`), should exist in the
 
 
 [[category_read]]
-Read
+=== Read
-~~~~
 
 The `Read` category controls visibility to the project's
 changes, comments, code diffs, and Git access over SSH or HTTP.
@@ -734,8 +696,7 @@ is already restricted to the correct set of users.
 
 
 [[category_rebase]]
-Rebase
+=== Rebase
-~~~~~~
 
 This category permits users to rebase changes via the web UI by pushing
 the `Rebase Change` button.
@@ -749,8 +710,7 @@ patch set.
 
 
 [[category_remove_reviewer]]
-Remove Reviewer
+=== Remove Reviewer
-~~~~~~~~~~~~~~~
 
 This category permits users to remove other users from the list of
 reviewers on a change.
@@ -764,8 +724,7 @@ reviewer list on a change.
 
 
 [[category_review_labels]]
-Review Labels
+=== Review Labels
-~~~~~~~~~~~~~
 
 For every configured label `My-Name` in the project, there is a
 corresponding permission `label-My-Name` with a range corresponding to
@@ -779,8 +738,7 @@ defined globally or on a per-project basis.
 
 
 [[category_submit]]
-Submit
+=== Submit
-~~~~~~
 
 This category permits users to push the `Submit Patch Set n` button
 on the web UI.
@@ -799,8 +757,7 @@ the caller needs to have the Submit permission on `refs/for/<ref>`
 
 
 [[category_view_drafts]]
-View Drafts
+=== View Drafts
-~~~~~~~~~~~
 
 This category permits users to view draft changes uploaded by other
 users.
@@ -811,8 +768,7 @@ assigned).
 
 
 [[category_publish_drafts]]
-Publish Drafts
+=== Publish Drafts
-~~~~~~~~~~~~~~
 
 This category permits users to publish draft changes uploaded by other
 users.
@@ -822,8 +778,7 @@ the `Publish Drafts` access right assigned).
 
 
 [[category_delete_drafts]]
-Delete Drafts
+=== Delete Drafts
-~~~~~~~~~~~~~
 
 This category permits users to delete draft changes uploaded by other
 users.
@@ -833,8 +788,7 @@ the `Delete Drafts` access right assigned).
 
 
 [[category_edit_topic_name]]
-Edit Topic Name
+=== Edit Topic Name
-~~~~~~~~~~~~~~~
 
 This category permits users to edit the topic name of a change that
 is uploaded for review.
@@ -848,8 +802,7 @@ by the 'Force Edit' flag. If this flag is not set the topic can only be
 edited on open changes.
 
 
-Examples of typical roles in a project
+== Examples of typical roles in a project
---------------------------------------
 
 Below follows a set of typical roles on a server and which access
 rights these roles typically should be granted. You may see them as
@@ -858,8 +811,7 @@ brand new Gerrit instance.
 
 
 [[examples_contributor]]
-Contributor
+=== Contributor
-~~~~~~~~~~~
 
 This is the typical user on a public server. They are able to read
 your project and upload new changes to it. They are able to give
@@ -874,8 +826,7 @@ Suggested access rights to grant:
 
 
 [[examples_developer]]
-Developer
+=== Developer
-~~~~~~~~~
 
 This is the typical core developer on a public server.  They are able
 to read the project, upload changes to a branch.  They are allowed to
@@ -910,8 +861,7 @@ Optional access rights to grant:
 
 
 [[examples_cisystem]]
-CI system
+=== CI system
-~~~~~~~~~
 
 A typical Continuous Integration system should be able to download new changes
 to build and then leave a verdict somehow.
@@ -959,8 +909,7 @@ Optional access rights to grant:
 
 
 [[examples_integrator]]
-Integrator
+=== Integrator
-~~~~~~~~~~
 
 Integrators are like developers but with some additional rights granted due
 to their administrative role in a project.  They can upload or push any commit
@@ -978,8 +927,7 @@ Suggested access rights to grant:
 
 
 [[examples_project-owner]]
-Project owner
+=== Project owner
-~~~~~~~~~~~~~
 
 The project owner is almost like an integrator but with additional destructive
 power in the form of being able to delete branches.  Optionally these users
@@ -1002,8 +950,7 @@ Optional access right to grant:
 
 
 [[examples_administrator]]
-Administrator
+=== Administrator
-~~~~~~~~~~~~~
 
 The administrator role is the most powerful role known in the Gerrit universe.
 This role may grant itself (or others) any access right, and it already has
@@ -1019,8 +966,7 @@ Suggested access rights to grant:
 * <<examples_project-owner,Project owner rights>>
 
 
-Enforcing site wide access policies
+== Enforcing site wide access policies
------------------------------------
 
 By granting the <<category_owner,`Owner`>> access right on the `refs/*` to a
 group, Gerrit administrators can delegate the responsibility of maintaining
@@ -1045,8 +991,7 @@ non-blocked rules as they wish. This gives best of both worlds:
 
 
 [[block]]
-'BLOCK' access rule
+=== 'BLOCK' access rule
-~~~~~~~~~~~~~~~~~~~
 
 The 'BLOCK' rule blocks a permission globally. An inherited 'BLOCK' rule cannot
 be overridden in the inheriting project. Any 'ALLOW' rule, from a different
@@ -1072,8 +1017,7 @@ The interpretation of the 'min..max' range in case of a blocking rule is: block
 every vote from '-INFINITE..min' and 'max..INFINITE'. For the example above it
 means that the range '-1..+1' is not affected by this block.
 
-'BLOCK' and 'ALLOW' rules in the same access section
+=== 'BLOCK' and 'ALLOW' rules in the same access section
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 When an access section of a project contains a 'BLOCK' and an 'ALLOW' rule for
 the same permission then this 'ALLOW' rule overrides the 'BLOCK' rule:
@@ -1093,13 +1037,11 @@ different access section of the same project or in any access section in an
 inheriting project cannot override a 'BLOCK' rule.
 
 
-Examples
+=== Examples
-~~~~~~~~
 
 The following examples show some possible use cases for the 'BLOCK' rules.
 
-Make sure no one can update or delete a tag
+==== Make sure no one can update or delete a tag
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This requirement is quite common in a corporate deployment where
 reproducibility of a build must be guaranteed. To achieve that we block 'push'
@@ -1123,8 +1065,7 @@ owners>> are allowed to create tags, we would extend the example above:
 ====
 
 
-Let only a dedicated group vote in a special category
+==== Let only a dedicated group vote in a special category
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Assume there is a more restrictive process for submitting changes in stable
 release branches which is manifested as a new voting category
@@ -1141,8 +1082,7 @@ category. In the "`All-Projects`" we define the following rules:
 ====
 
 [[global_capabilities]]
-Global Capabilities
+== Global Capabilities
--------------------
 
 The global capabilities control actions that the administrators of
 the server can perform which usually affect the entire
@@ -1162,15 +1102,13 @@ Below you find a list of capabilities available:
 
 
 [[capability_accessDatabase]]
-Access Database
+=== Access Database
-~~~~~~~~~~~~~~~
 
 Allow users to access the database using the `gsql` command.
 
 
 [[capability_administrateServer]]
-Administrate Server
+=== Administrate Server
-~~~~~~~~~~~~~~~~~~~
 
 This is in effect the owner and administrator role of the Gerrit
 instance.  Any members of a group granted this capability will be
@@ -1179,8 +1117,7 @@ capabilities granted to them automatically.
 
 
 [[capability_createAccount]]
-Create Account
+=== Create Account
-~~~~~~~~~~~~~~
 
 Allow link:cmd-create-account.html[account creation over the ssh prompt].
 This capability allows the granted group members to create non-interactive
@@ -1190,8 +1127,7 @@ link:access-control.html#non-interactive_users['Non-Interactive users'] group.
 
 
 [[capability_createGroup]]
-Create Group
+=== Create Group
-~~~~~~~~~~~~
 
 Allow group creation.  Groups are used to grant users access to different
 actions in projects.  This capability allows the granted group members to
@@ -1199,8 +1135,7 @@ either link:cmd-create-group.html[create new groups via ssh] or via the web UI.
 
 
 [[capability_createProject]]
-Create Project
+=== Create Project
-~~~~~~~~~~~~~~
 
 Allow project creation.  This capability allows the granted group to
 either link:cmd-create-project.html[create new git projects via ssh]
@@ -1208,8 +1143,7 @@ or via the web UI.
 
 
 [[capability_emailReviewers]]
-Email Reviewers
+=== Email Reviewers
-~~~~~~~~~~~~~~~
 
 Allow or deny sending email to change reviewers and watchers.  This can be used
 to deny build bots from emailing reviewers and people who watch the change.
@@ -1219,8 +1153,7 @@ is to allow emailing, if no explicit rule is matched.
 
 
 [[capability_flushCaches]]
-Flush Caches
+=== Flush Caches
-~~~~~~~~~~~~
 
 Allow the flushing of Gerrit's caches.  This capability allows the granted
 group to link:cmd-flush-caches.html[flush some or all Gerrit caches via ssh].
@@ -1231,16 +1164,14 @@ you need the <<capability_viewCaches,view caches capability>>.
 
 
 [[capability_generateHttpPassword]]
-Generate HTTP Password
+=== Generate HTTP Password
-~~~~~~~~~~~~~~~~~~~~~~
 
 Allow the user to generate HTTP passwords for other users.  Typically this would
 be assigned to a non-interactive users group.
 
 
 [[capability_kill]]
-Kill Task
+=== Kill Task
-~~~~~~~~~
 
 Allow the operation of the link:cmd-kill.html[kill command over ssh].  The
 kill command ends tasks that currently occupy the Gerrit server, usually
@@ -1249,8 +1180,7 @@ receive-pack.
 
 
 [[capability_priority]]
-Priority
+=== Priority
-~~~~~~~~
 
 This capability allows users to use
 link:config-gerrit.html#sshd.batchThreads[the thread pool reserved] for
@@ -1278,8 +1208,7 @@ regardless if they also have the 'BATCH' option or not, they are in the
 
 
 [[capability_queryLimit]]
-Query Limit
+=== Query Limit
-~~~~~~~~~~~
 
 Allow site administrators to configure the query limit for users to
 be above the default hard-coded value of 500.  Administrators can add
@@ -1294,8 +1223,7 @@ command, but also to the web UI results pagination size.
 
 
 [[capability_runAs]]
-Run As
+=== Run As
-~~~~~~
 
 Allow users to impersonate any other user with the `X-Gerrit-RunAs`
 HTTP header on REST API calls, or the link:cmd-suexec.html[suexec]
@@ -1315,16 +1243,14 @@ be explicitly granted.
 
 
 [[capability_runGC]]
-Run Garbage Collection
+=== Run Garbage Collection
-~~~~~~~~~~~~~~~~~~~~~~
 
 Allow users to run the Git garbage collection for the repositories of
 all projects.
 
 
 [[capability_streamEvents]]
-Stream Events
+=== Stream Events
-~~~~~~~~~~~~~
 
 Allow performing streaming of Gerrit events. This capability
 allows the granted group to
@@ -1332,8 +1258,7 @@ link:cmd-stream-events.html[stream Gerrit events via ssh].
 
 
 [[capability_viewCaches]]
-View Caches
+=== View Caches
-~~~~~~~~~~~
 
 Allow querying for status of Gerrit's internal caches.  This capability allows
 the granted group to
@@ -1341,8 +1266,7 @@ link:cmd-show-caches.html[look at some or all Gerrit caches via ssh].
 
 
 [[capability_viewConnections]]
-View Connections
+=== View Connections
-~~~~~~~~~~~~~~~~
 
 Allow querying for status of Gerrit's current client connections.  This
 capability allows the granted group to
@@ -1350,8 +1274,7 @@ link:cmd-show-connections.html[look at Gerrit's current connections via ssh].
 
 
 [[capability_viewQueue]]
-View Queue
+=== View Queue
-~~~~~~~~~~
 
 Allow querying for status of Gerrit's internal task queue.  This capability
 allows the granted group to

Documentation/cmd-apropos.txt

@@ -1,34 +1,27 @@
-gerrit apropos
+= gerrit apropos
-==============
 
-NAME
+== NAME
-----
 gerrit apropos - Search Gerrit documentation index
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit apropos'
   <query>
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Queries the documentation index and returns results with the title and URL
 from the matched documents.
 
-ACCESS
+== ACCESS
-------
 Any user who has configured an SSH key.
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
 Note: this feature is only available if documentation index was built.
 
-EXAMPLES
+== EXAMPLES
---------
 
 =====
 $ ssh -p 29418 review.example.com gerrit apropos capabilities
@@ -54,8 +47,7 @@ $ ssh -p 29418 review.example.com gerrit apropos capabilities
     http://localhost:8080/Documentation/rest-api-access.html
 =====
 
-SEE ALSO
+== SEE ALSO
---------
 
 * link:access-control.html[Access Controls]
 

Documentation/cmd-ban-commit.txt

@@ -1,12 +1,9 @@
-gerrit ban-commit
+= gerrit ban-commit
-=================
 
-NAME
+== NAME
-----
 gerrit ban-commit - Bans a commit from a project's repository.
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit ban-commit'
   [--reason <REASON>]
@@ -14,8 +11,7 @@ SYNOPSIS
   <COMMIT> ...
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Marks a commit as banned for the specified repository.  If a commit is
 banned Gerrit rejects every push that includes this commit with
 link:error-contains-banned-commit.html[contains banned commit ...].
@@ -25,17 +21,14 @@ This command just marks the commit as banned, but it does not remove
 the commit from the history of any central branch.  This needs to be
 done manually.
 
-ACCESS
+== ACCESS
-------
 Caller must be owner of the project or be a member of the privileged
 'Administrators' group.
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-OPTIONS
+== OPTIONS
--------
 <PROJECT>::
 	Required; name of the project for which the commit should be
 	banned.
@@ -46,8 +39,7 @@ OPTIONS
 --reason::
 	Reason for banning the commit.
 
-EXAMPLES
+== EXAMPLES
---------
 Ban commit `421919d015c062fd28901fe144a78a555d0b5984` from project
 `myproject`:
 

Documentation/cmd-cherry-pick.txt

@@ -1,20 +1,16 @@
-gerrit-cherry-pick
+= gerrit-cherry-pick
-==================
 
-NAME
+== NAME
-----
 gerrit-cherry-pick - Download and cherry pick one or more changes
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'gerrit-cherry-pick' <remote> <changeid>...
 'gerrit-cherry-pick' --continue | --skip | --abort
 'gerrit-cherry-pick' --close <remote>
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Downloads the listed changes specified on the command line and
 proceeds to cherry-pick them (rewriting commit SHA-1s as it goes)
 onto the current branch.
@@ -32,8 +28,7 @@ existing changes post cherry-pick is better handled simply by
 ensuring link:user-changeid.html[Change-Id lines] are present in
 each commit message.
 
-OBTAINING
+== OBTAINING
----------
 To obtain the 'gerrit-cherry-pick' script use scp, curl or wget to
 copy it to your local system:
 

Documentation/cmd-create-account.txt

@@ -1,12 +1,9 @@
-gerrit create-account
+= gerrit create-account
-=====================
 
-NAME
+== NAME
-----
 gerrit create-account - Create a new user account.
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit create-account'
   [--group <GROUP>]
@@ -17,8 +14,7 @@ SYNOPSIS
   <USERNAME>
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Creates a new internal-only user account.
 
 If the account is created without an email address, it may only be
@@ -33,18 +29,15 @@ If LDAP authentication is being used, the user account is created
 without checking the LDAP directory.  Consequently users can be
 created in Gerrit that do not exist in the underlying LDAP directory.
 
-ACCESS
+== ACCESS
-------
 Caller must be a member of the privileged 'Administrators' group,
 or have been granted
 link:access-control.html#capability_createAccount[the 'Create Account' global capability].
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-OPTIONS
+== OPTIONS
--------
 <USERNAME>::
 	Required; SSH username of the user account.
 
@@ -70,8 +63,7 @@ This most likely requires double quoting the value, for example
 --http-password::
     HTTP password for the user account.
 
-EXAMPLES
+== EXAMPLES
---------
 Create a new batch/role access user account called `watcher` in
 the 'Non-Interactive Users' group.
 

Documentation/cmd-create-branch.txt

@@ -1,12 +1,9 @@
-gerrit create-branch
+= gerrit create-branch
-====================
 
-NAME
+== NAME
-----
 gerrit create-branch - Create a new branch
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit create-branch'
   <PROJECT>
@@ -14,24 +11,20 @@ SYNOPSIS
   <REVISION>
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Creates a new branch for a project.
 
-ACCESS
+== ACCESS
-------
 Caller should have link:access-control.html#category_create[Create Reference]
 permission on the project.
 
 Administrators do not automatically have permission to create branches. It must
 be granted via the Create Reference permission.
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-OPTIONS
+== OPTIONS
--------
 <PROJECT>::
     Required; name of the project.
 
@@ -41,8 +34,7 @@ OPTIONS
 <REVISION>::
     Required; base revision of the new branch.
 
-EXAMPLES
+== EXAMPLES
---------
 Create a new branch called 'newbranch' from the 'master' branch of
 the project 'myproject'.
 

Documentation/cmd-create-group.txt

@@ -1,12 +1,9 @@
-gerrit create-group
+= gerrit create-group
-===================
 
-NAME
+== NAME
-----
 gerrit create-group - Create a new account group.
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit create-group'
   [--owner <GROUP> | -o <GROUP>]
@@ -17,8 +14,7 @@ SYNOPSIS
   <GROUP>
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Creates a new account group.  The group creating user (the user that
 fired the create-group command) is not automatically added to
 the created group.  In case the creating user wants to be a member of
@@ -26,18 +22,15 @@ the group he/she must list itself in the --member option.  This is
 slightly different from Gerrit's Web UI where the creating user automatically
 becomes a member of the newly created group.
 
-ACCESS
+== ACCESS
-------
 Caller must be a member of the privileged 'Administrators' group,
 or have been granted
 link:access-control.html#capability_createGroup[the 'Create Group' global capability].
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-OPTIONS
+== OPTIONS
--------
 <GROUP>::
 	Required; name of the new group.
 
@@ -69,8 +62,7 @@ to the group.
 --visible-to-all::
 	If specified, the group members will be visible to all users.
 
-EXAMPLES
+== EXAMPLES
---------
 Create a new account group called `gerritdev` with two initial members
 `developer1` and `developer2`.  The group should be owned by itself:
 

Documentation/cmd-create-project.txt

@@ -1,12 +1,9 @@
-gerrit create-project
+= gerrit create-project
-=====================
 
-NAME
+== NAME
-----
 gerrit create-project - Create a new hosted project
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit create-project'
   [--owner <GROUP> ... | -o <GROUP> ...]
@@ -25,8 +22,7 @@ SYNOPSIS
   { <NAME> | --name <NAME> }
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Creates a new bare Git repository under `gerrit.basePath`, using
 the project name supplied.  The newly created repository is empty
 (has no commits), but is registered in the Gerrit database so that
@@ -38,18 +34,15 @@ the configured remote systems over SSH and uses command line git
 on the remote system to create the empty repository.
 
 
-ACCESS
+== ACCESS
-------
 Caller must be a member of the privileged 'Administrators' group,
 or have been granted
 link:access-control.html#capability_createProject[the 'Create Project' global capability].
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-OPTIONS
+== OPTIONS
--------
 <NAME>::
 	Required; name of the new project to create.  If name ends
 	with `.git` the suffix will be automatically removed.
@@ -160,8 +153,7 @@ Change Submit Actions].
 Common unit suffixes of 'k', 'm', or 'g' are supported.
 
 
-EXAMPLES
+== EXAMPLES
---------
 Create a new project called `tools/gerrit`:
 
 ====
@@ -179,8 +171,7 @@ shell needs double quotes around the value to ensure the single quotes
 are passed through SSH as-is to the remote Gerrit server, which uses
 the single quotes to delimit the value.
 
-REPLICATION
+== REPLICATION
------------
 If the replication plugin is installed, the plugin will attempt to
 perform remote repository creation by a Bourne shell script:
 
@@ -197,8 +188,7 @@ A custom extension or plugin may also be developed to implement the
 NewProjectCreatedListener extension point and handle custom logic
 for remote repository creation.
 
-SEE ALSO
+== SEE ALSO
---------
 
 * link:project-setup.html[Project Setup]
 

Documentation/cmd-flush-caches.txt

@@ -1,20 +1,16 @@
-gerrit flush-caches
+= gerrit flush-caches
-===================
 
-NAME
+== NAME
-----
 gerrit flush-caches - Flush some/all server caches from memory
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit flush-caches' --all
 'ssh' -p <port> <host> 'gerrit flush-caches' --list
 'ssh' -p <port> <host> 'gerrit flush-caches' --cache <NAME> ...
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Clear an in-memory cache, forcing Gerrit to reconsult the ground
 truth when it needs the information again.
 
@@ -24,18 +20,15 @@ the Gerrit web interface.
 
 If no options are supplied, defaults to `--all`.
 
-ACCESS
+== ACCESS
-------
 Caller must be a member of the privileged 'Administrators' group,
 or in a group that have been granted
 link:access-control.html#capability_flushCaches[the 'Flush Caches' global capability].
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-OPTIONS
+== OPTIONS
--------
 --all::
 	Flush all known caches.  This is like applying a big hammer,
 	it will force everything out, potentially more than was
@@ -53,8 +46,7 @@ OPTIONS
 	than once to flush multiple caches in a single command
 	execution.
 
-EXAMPLES
+== EXAMPLES
---------
 List caches available for flushing:
 
 ====
@@ -95,8 +87,7 @@ Flush "web_sessions", forcing all users to sign-in again:
 	$ ssh -p 29418 review.example.com gerrit flush-caches --cache web_sessions
 ====
 
-SEE ALSO
+== SEE ALSO
---------
 
 * link:cmd-show-caches.html[gerrit show-caches]
 * link:config-gerrit.html#cache[Cache Configuration]

Documentation/cmd-gc.txt

@@ -1,12 +1,9 @@
-gerrit gc
+= gerrit gc
-=========
 
-NAME
+== NAME
-----
 gerrit gc - Run the Git garbage collection
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit gc'
   [--all]
@@ -14,8 +11,7 @@ SYNOPSIS
   <NAME> ...
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Runs the Git garbage collection for the specified projects.
 
 A Gerrit system administrator can define the default parameters that
@@ -28,19 +24,16 @@ configuration on repository level it is possible to specify
 repository specific parameters for the garbage collection in the Git
 repository configuration of every project.
 
-ACCESS
+== ACCESS
-------
 Caller must be a member of the privileged 'Administrators' group,
 or have been granted the
 link:access-control.html#capability_runGC[Run Garbage Collection]
 global capability.
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-OPTIONS
+== OPTIONS
--------
 <NAME>::
 	Name of the projects for which the Git garbage collection should be run.
 
@@ -51,8 +44,7 @@ OPTIONS
 --show-progress::
 	If specified progress information is shown.
 
-EXAMPLES
+== EXAMPLES
---------
 
 Run the Git garbage collection for the projects 'myProject' and
 'yourProject':

Documentation/cmd-gsql.txt

@@ -1,26 +1,21 @@
-gerrit gsql
+= gerrit gsql
-===========
 
-NAME
+== NAME
-----
 gerrit gsql - Administrative interface to active database
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit gsql'
   [--format {PRETTY | JSON | JSON_SINGLE}]
   [-c QUERY]
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Provides interactive query support directly against the underlying
 SQL database used by the host Gerrit server.  All SQL statements
 are supported, including SELECT, UPDATE, INSERT, DELETE and ALTER.
 
-OPTIONS
+== OPTIONS
--------
 --format::
 	Set the format records are output in.  In PRETTY (the
 	default) records are displayed in a tabular output suitable
@@ -33,19 +28,16 @@ OPTIONS
 -c::
 	Execute the single query statement supplied, and then exit.
 
-ACCESS
+== ACCESS
-------
 Caller must have been granted the
 link:access-control.html#capability_accessDatabase[Access Database]
 global capability.
 
-SCRIPTING
+== SCRIPTING
----------
 Intended for interactive use only, unless format is JSON, or
 JSON_SINGLE.
 
-EXAMPLES
+== EXAMPLES
---------
 To manually correct a user's SSH user name:
 
 ====

Documentation/cmd-hook-commit-msg.txt

@@ -1,15 +1,12 @@
-commit-msg Hook
+= commit-msg Hook
-===============
 
 
-NAME
+== NAME
-----
 
 
 commit-msg - Edit commit messages to insert a `Change-Id` tag.
 
-DESCRIPTION
+== DESCRIPTION
------------
 
 
 A Git hook automatically invoked by `git commit`, and most other
@@ -58,8 +55,7 @@ change viewed on the web.
 The `Change-Id` will not be added if `gerrit.createChangeId` is set
 to `false` in the git config.
 
-OBTAINING
+== OBTAINING
----------
 
 
 To obtain the `commit-msg` script use `scp`, `wget` or `curl` to download
@@ -88,16 +84,14 @@ Make sure the hook file is executable:
   $ chmod u+x ~/duhproject/.git/hooks/commit-msg
 ====
 
-SEE ALSO
+== SEE ALSO
---------
 
 
 * link:user-changeid.html[Change-Id Lines]
 * link:http://www.kernel.org/pub/software/scm/git/docs/git-commit.html[git-commit(1)]
 * link:http://www.kernel.org/pub/software/scm/git/docs/githooks.html[githooks(5)]
 
-IMPLEMENTATION
+== IMPLEMENTATION
---------------
 
 
 The hook generates unique `Change-Id` lines by creating a virtual

Documentation/cmd-index.txt

@@ -1,8 +1,6 @@
-Gerrit Code Review - Command Line Tools
+= Gerrit Code Review - Command Line Tools
-=======================================
 
-Client
+== Client
-------
 
 Client commands and hooks can be downloaded via scp, wget or curl
 from Gerrit's daemon, and then executed on the client system.
@@ -18,14 +16,12 @@ To download a client command or hook, use scp or an http client:
 For more details on how to determine the correct SSH port number,
 see link:user-upload.html#test_ssh[Testing Your SSH Connection].
 
-[[client_commands]]Commands
+=== [[client_commands]]Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 link:cmd-cherry-pick.html[gerrit-cherry-pick]::
   Download and cherry-pick one or more changes (commits).
 
-[[client_hooks]]Hooks
+=== [[client_hooks]]Hooks
-~~~~~~~~~~~~~~~~~~~~~
 
 Client hooks can be installed into a local Git repository, improving
 the developer experience when working with a Gerrit Code Review
@@ -35,8 +31,7 @@ link:cmd-hook-commit-msg.html[commit-msg]::
   Automatically generate `Change-Id: ` tags in commit messages.
 
 
-Server
+== Server
-------
 
 Aside from the standard Git server side actions, Gerrit supports
 several other commands over its internal SSH daemon.  As Gerrit does
@@ -48,8 +43,7 @@ from an ssh client, for example:
 For more details on how to determine the correct SSH port number,
 see link:user-upload.html#test_ssh[Testing Your SSH Connection].
 
-[[user_commands]]User Commands
+=== [[user_commands]]User Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 link:cmd-apropos.html[gerrit apropos]::
 	Search Gerrit documentation index.

Documentation/cmd-kill.txt

@@ -1,29 +1,23 @@
-kill
+= kill
-====
 
-NAME
+== NAME
-----
 kill - Cancel or abort a background task
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'kill' <ID> ...
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Cancels a scheduled task from the queue.  If the task has already
 been started, requests for the task to cancel as soon as it reaches
 its next cancellation point (which is usually blocking IO).
 
-ACCESS
+== ACCESS
-------
 Caller must be a member of the privileged 'Administrators' group,
 or have been granted link:access-control.html#capability_kill[the 'Kill Task' global capability].
 
-SCRIPTING
+== SCRIPTING
----------
 Intended for interactive use only.
 
 GERRIT

Documentation/cmd-ls-groups.txt

@@ -1,12 +1,9 @@
-gerrit ls-groups
+= gerrit ls-groups
-================
 
-NAME
+== NAME
-----
 gerrit ls-groups - List groups visible to caller
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit ls-groups'
   [--project <NAME> | -p <NAME>]
@@ -18,20 +15,17 @@ SYNOPSIS
   [--verbose | -v]
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Displays the list of group names, one per line, that are visible to
 the account of the calling user.
 
 If the caller is a member of the privileged 'Administrators' group,
 all groups are listed.
 
-ACCESS
+== ACCESS
-------
 Any user who has configured an SSH key.
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
 All non-printable characters (ASCII value 31 or less) are escaped
@@ -40,8 +34,7 @@ employing standard sequences like `\n` and `\t`, and `\xNN` for all
 others. In shell scripts, the `printf` command can be used to unescape
 the output.
 
-OPTIONS
+== OPTIONS
--------
 --project::
 -p::
 	Name of the project for which the groups should be listed. Only
@@ -100,8 +93,7 @@ This option can't be used together with the '--project' option.
 If a group has been "orphaned", i.e. its owner group UUID refers to a
 nonexistent group, the owner group name field will read `n/a`.
 
-EXAMPLES
+== EXAMPLES
---------
 
 List visible groups:
 =====

Documentation/cmd-ls-members.txt

@@ -1,29 +1,24 @@
 gerrit ls-members
 ================
 
-NAME
+== NAME
-----
 gerrit ls-members - Show members of a given group
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit ls-members GROUPNAME'
   [--recursive]
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Displays the members of the given group, one per line, so long as the given
 group is visible to the user. The users' id, username, full name and email are
 shown tab-separated.
 
-ACCESS
+== ACCESS
-------
 Any user who has configured an SSH key.
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts. Output is either an error
 message or a heading followed by zero or more lines, one for each member of the
 group. If any field is not set, or if the field is the user's full name and the
@@ -35,15 +30,13 @@ employing standard sequences like `\n` and `\t`, and `\xNN` for all
 others. In shell scripts, the `printf` command can be used to unescape
 the output.
 
-OPTIONS
+== OPTIONS
--------
 --recursive::
 	If a member of the group is itself a group, the sub-group's
 	members are included in the list. Otherwise members of any sub-group
 	are not shown and no indication is given that a sub-group is present
 
-EXAMPLES
+== EXAMPLES
---------
 
 List members of the Administrators group:
 =====

Documentation/cmd-ls-projects.txt

@@ -1,12 +1,9 @@
-gerrit ls-projects
+= gerrit ls-projects
-==================
 
-NAME
+== NAME
-----
 gerrit ls-projects - List projects visible to caller
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit ls-projects'
   [--show-branch <BRANCH> ...]
@@ -19,24 +16,20 @@ SYNOPSIS
   [--has-acl-for GROUP]
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Displays the list of project names, one per line, that the
 calling user account has been granted 'READ' access to.
 
 If the caller is a member of the privileged 'Administrators'
 group, all projects are listed.
 
-ACCESS
+== ACCESS
-------
 Any user who has configured an SSH key, or by an user over HTTP.
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-OPTIONS
+== OPTIONS
--------
 --show-branch::
 -b::
 	Branch for which the command will display the sha of each project.
@@ -100,8 +93,7 @@ used to unescape the output.
 +
 With this option you can find out on which projects a group is used.
 
-HTTP
+== HTTP
-----
 This command is also available over HTTP, as `/projects/` for
 anonymous access and `/a/projects/` for authenticated access.
 Named options are available as query parameters. Results can
@@ -118,8 +110,7 @@ to prevent a browser from executing the response in a script tag.
 Output will be gzip compressed if `Accept-Encoding: gzip` was used
 by the client in the request headers.
 
-EXAMPLES
+== EXAMPLES
---------
 
 List visible projects:
 =====
@@ -147,8 +138,7 @@ Clone any project visible to the user:
 	done
 ====
 
-SEE ALSO
+== SEE ALSO
---------
 
 * link:access-control.html[Access Controls]
 

Documentation/cmd-ls-user-refs.txt

@@ -1,12 +1,9 @@
-gerrit ls-user-refs
+= gerrit ls-user-refs
-===================
 
-NAME
+== NAME
-----
 gerrit ls-user-refs - List refs visible to a specific user
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit ls-user-refs'
   [--project PROJECT> | -p <PROJECT>]
@@ -14,8 +11,7 @@ SYNOPSIS
   [--only-refs-heads]
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Displays all refs that the specified user can see.
 
 Allows an administrator to query which refs are visible for
@@ -24,12 +20,10 @@ user cannot access certain refs and also to help admins
 verify that certain secret refs are not exposed to the wrong
 groups.
 
-ACCESS
+== ACCESS
-------
 Administrators
 
-OPTIONS
+== OPTIONS
--------
 --project::
 -p::
 	Required; Name of the project for which the refs should be listed.
@@ -43,8 +37,7 @@ OPTIONS
 --only-refs-heads::
 	Only list the refs found under refs/heads/*
 
-EXAMPLES
+== EXAMPLES
---------
 
 List visible refs for the user "mr.developer" in project "gerrit"
 =====

Documentation/cmd-plugin-enable.txt

@@ -1,39 +1,31 @@
-plugin enable
+= plugin enable
-=============
 
-NAME
+== NAME
-----
 plugin enable - Enable plugins.
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit plugin enable'
   <NAME> ...
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Enable plugins currently disabled. The plugins will be enabled by renaming
 the plugin jars in the site path's `plugins` directory from
 `<plugin-jar-name>.disabled` to `<plugin-jar-name>`.
 
-ACCESS
+== ACCESS
-------
 Caller must be a member of the privileged 'Administrators' group.
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-OPTIONS
+== OPTIONS
--------
 <NAME>::
 	Name of the plugin that should be enabled.  Multiple names of
 	plugins that should be enabled may be specified.
 
-EXAMPLES
+== EXAMPLES
---------
 Enable a plugin:
 
 ====

Documentation/cmd-plugin-install.txt

@@ -1,35 +1,28 @@
-plugin install
+= plugin install
-==============
 
-NAME
+== NAME
-----
 plugin install - Install/Add a plugin.
 
 plugin add - Install/Add a plugin.
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit plugin install | add'
   [--name <NAME> | -n <NAME>]
   - | <URL> | <PATH>
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Install/Add a plugin. The plugin will be copied into the site path's
 `plugins` directory.
 
-ACCESS
+== ACCESS
-------
 Caller must be a member of the privileged 'Administrators' group.
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-OPTIONS
+== OPTIONS
--------
 -::
 	Plugin jar or js as piped input.
 
@@ -46,8 +39,7 @@ OPTIONS
 	provides its own name in the MANIFEST file, then the plugin name from the
 	MANIFEST file has precedence over this option.
 
-EXAMPLES
+== EXAMPLES
---------
 Install a plugin from an absolute file path on the server's host:
 
 ====

Documentation/cmd-plugin-ls.txt

@@ -1,32 +1,25 @@
-plugin ls
+= plugin ls
-=========
 
-NAME
+== NAME
-----
 plugin ls - List the installed plugins.
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit plugin ls'
   [--all | -a]
   [--format {text | json | json_compact}]
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 List the installed plugins and show their version and status.
 
-ACCESS
+== ACCESS
-------
 Caller must be a member of the privileged 'Administrators' group.
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-OPTIONS
+== OPTIONS
--------
 --all::
 -a::
 	List all plugins, including disabled plugins.

Documentation/cmd-plugin-reload.txt

@@ -1,19 +1,15 @@
-plugin reload
+= plugin reload
-=============
 
-NAME
+== NAME
-----
 plugin reload - Reload/Restart plugins.
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit plugin reload'
   <NAME> ...
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Reload/Restart plugins.
 
 Whether a plugin is reloaded or restarted is defined by the plugin's
@@ -22,22 +18,18 @@ link:dev-plugins.html#reload_method[reload method].
 E.g. a plugin needs to be reloaded if its configuration is modified to
 make the new configuration data become active.
 
-ACCESS
+== ACCESS
-------
 Caller must be a member of the privileged 'Administrators' group.
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-OPTIONS
+== OPTIONS
--------
 <NAME>::
 	Name of the plugin that should be reloaded.  Multiple names of
 	plugins that should be reloaded may be specified.
 
-EXAMPLES
+== EXAMPLES
---------
 Reload a plugin:
 
 ====

Documentation/cmd-plugin-remove.txt

@@ -1,40 +1,32 @@
-plugin remove
+= plugin remove
-=============
 
-NAME
+== NAME
-----
 plugin remove - Disable plugins.
 
 plugin rm - Disable plugins.
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit plugin remove | rm'
   <NAME> ...
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Disable plugins. The plugins will be disabled by renaming the plugin
 jars in the site path's `plugins` directory to `<plugin-jar-name>.disabled`.
 
-ACCESS
+== ACCESS
-------
 Caller must be a member of the privileged 'Administrators' group.
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-OPTIONS
+== OPTIONS
--------
 <NAME>::
 	Name of the plugin that should be disabled.  Multiple names of
 	plugins that should be disabled may be specified.
 
-EXAMPLES
+== EXAMPLES
---------
 Disable a plugin:
 
 ====

Documentation/cmd-query.txt

@@ -1,12 +1,9 @@
-gerrit query
+= gerrit query
-============
 
-NAME
+== NAME
-----
 gerrit query - Query the change database
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit query'
   [--format {TEXT | JSON}]
@@ -24,8 +21,7 @@ SYNOPSIS
   [resume_sortkey:<sortKey>]
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 
 Queries the change database and returns results describing changes
 that match the input query.  More recently updated changes appear
@@ -50,8 +46,7 @@ Query operators may quote values using matched curly braces
 levels of shell quoting (caller shell invoking SSH, and the SSH
 command line parser in the server).
 
-OPTIONS
+== OPTIONS
--------
 --format::
 	Formatting method for the results. `TEXT` is the default,
 	presenting a human readable display. `JSON` returns
@@ -112,16 +107,13 @@ resume_sortkey:<sortKey>::
 	resume a prior query.  This is actually a query operator,
 	and not a command line option.
 
-ACCESS
+== ACCESS
-------
 Any user who has configured an SSH key.
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-EXAMPLES
+== EXAMPLES
---------
 
 Find the 2 most recent open changes in the tools/gerrit project:
 ====
@@ -140,8 +132,7 @@ Resume the same query and obtain the final results:
 ====
 
 
-SCHEMA
+== SCHEMA
-------
 The JSON messages consist of nested objects referencing the
 link:json.html#change[change],
 link:json.html#patchSet[patchset],
@@ -151,8 +142,7 @@ involved, and other attributes as appropriate.
 Note that any field may be missing in the JSON messages, so consumers
 of this JSON stream should deal with that appropriately.
 
-SEE ALSO
+== SEE ALSO
---------
 
 * link:user-search.html[Query Operators]
 * link:json.html[JSON Data Formats]

Documentation/cmd-receive-pack.txt

@@ -1,12 +1,9 @@
-git-receive-pack
+= git-receive-pack
-================
 
-NAME
+== NAME
-----
 git-receive-pack - Receive what is pushed into the repository
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'git receive-pack'
   [--reviewer <address> | --re <address>]
@@ -14,16 +11,14 @@ SYNOPSIS
   <project>
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Invoked by 'git push' and updates the project's repository with
 the information fed from the 'git push' end.
 
 End users can supply options to this command by passing them through
 to 'git push', which will relay them automatically.
 
-OPTIONS
+== OPTIONS
--------
 
 <project>::
 	The remote repository that will receive the pushed objects,
@@ -40,12 +35,10 @@ OPTIONS
 	Carbon-copy <address> on the created or updated changes.
 	Deprecated, use `refs/for/branch%cc=address` instead.
 
-ACCESS
+== ACCESS
-------
 Any user who has configured an SSH key.
 
-EXAMPLES
+== EXAMPLES
---------
 
 Send a review for a change on the master branch to charlie@example.com:
 =====
@@ -81,8 +74,7 @@ alice and bob is much easier:
 	git push charlie
 ====
 
-SEE ALSO
+== SEE ALSO
---------
 
 * link:user-upload.html[Uploading Changes]
 

Documentation/cmd-rename-group.txt

@@ -1,41 +1,33 @@
-gerrit rename-group
+= gerrit rename-group
-===================
 
-NAME
+== NAME
-----
 gerrit rename-group - Rename an account group.
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit rename-group'
   <GROUP>
   <NEWNAME>
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Renames an account group.
 
-ACCESS
+== ACCESS
-------
 Caller must be a member of the group owning the group to be renamed
 or be a member of the privileged 'Administrators' group.
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-OPTIONS
+== OPTIONS
--------
 <GROUP>::
 	Required; name of the group to be renamed.
 
 <NEWNAME>::
 	Required; new name of the group.
 
-EXAMPLES
+== EXAMPLES
---------
 Rename the group "MyGroup" to "MyCommitters".
 
 ====

Documentation/cmd-review.txt

@@ -1,12 +1,10 @@
 gerrit review
 ==============
 
-NAME
+== NAME
-----
 gerrit review - Verify, approve and/or submit one or more patch sets
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit review'
   [--project <PROJECT> | -p <PROJECT>]
@@ -22,8 +20,7 @@ SYNOPSIS
   {COMMIT | CHANGEID,PATCHSET}...
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Updates the current user's approval status of the specified patch
 sets and/or submits them for merging, sending out email
 notifications and updating the database.
@@ -40,8 +37,7 @@ may be used to limit where Gerrit searches for changes to only the specified
 branch.
 
 
-OPTIONS
+== OPTIONS
--------
 
 --project::
 -p::
@@ -113,16 +109,13 @@ OPTIONS
 	or invalid value) and votes that are not permitted for the user are
 	silently ignored.
 
-ACCESS
+== ACCESS
-------
 Any user who has configured an SSH key.
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-EXAMPLES
+== EXAMPLES
---------
 
 Approve the change with commit c0ff33 as "Verified +1"
 =====
@@ -157,8 +150,7 @@ Abandon an active change:
   $ ssh -p 29418 review.example.com gerrit review --abandon c0ff33
 ====
 
-SEE ALSO
+== SEE ALSO
---------
 
 * link:access-control.html[Access Controls]
 

Documentation/cmd-set-account.txt

@@ -1,12 +1,9 @@
-gerrit set-account
+= gerrit set-account
-==================
 
-NAME
+== NAME
-----
 gerrit set-account - Change an account's settings.
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 set-account [--full-name <FULLNAME>] [--active|--inactive] \
             [--add-email <EMAIL>] [--delete-email <EMAIL> | ALL] \
@@ -15,8 +12,7 @@ set-account [--full-name <FULLNAME>] [--active|--inactive] \
             [--http-password <PASSWORD>] <USER>
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Modifies a given user's settings. This command can be useful to
 deactivate an account, set HTTP password, add/delete ssh keys without
 going through the UI.
@@ -24,16 +20,13 @@ going through the UI.
 It also allows managing email addresses, which bypasses the
 verification step we force within the UI.
 
-ACCESS
+== ACCESS
-------
 Caller must be a member of the privileged 'Administrators' group.
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-OPTIONS
+== OPTIONS
--------
 <USER>::
     Required; Full name, email-address, SSH username or account id.
 
@@ -84,8 +77,7 @@ This most likely requires double quoting the value, for example
 --http-password::
     Set the HTTP password for the user account.
 
-EXAMPLES
+== EXAMPLES
---------
 Add an email and SSH key to `watcher`'s account:
 
 ====

Documentation/cmd-set-members.txt

@@ -1,12 +1,9 @@
-gerrit set-members
+= gerrit set-members
-==================
 
-NAME
+== NAME
-----
 gerrit set-members - Set group members
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit set-members'
   [--add USER ...]
@@ -17,12 +14,10 @@ SYNOPSIS
   <GROUP> ...
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Set the group members for the specified groups.
 
-OPTIONS
+== OPTIONS
--------
 <GROUP>::
 	Required; name of the group for which the members should be set.
 	The members for multiple groups can be set at once by specifying
@@ -52,16 +47,13 @@ OPTIONS
 The `set-members` command is processing the options in the following
 order: `--remove`, `--exclude`, `--add`, `--include`
 
-ACCESS
+== ACCESS
-------
 Any user who has configured an SSH key.
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-EXAMPLES
+== EXAMPLES
---------
 
 Add alice and bob, but remove eve from the groups my-committers and
 my-verifiers.

Documentation/cmd-set-project-parent.txt

@@ -1,12 +1,9 @@
-gerrit set-project-parent
+= gerrit set-project-parent
-=========================
 
-NAME
+== NAME
-----
 gerrit set-project-parent - Change the project permissions are inherited from.
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit set-project-parent'
   [--parent <NAME>]
@@ -15,23 +12,19 @@ SYNOPSIS
   <NAME> ...
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Changes the project that permissions are inherited through.
 Every project inherits permissions from another project, by
 default this is `All-Projects`.  This command sets
 the project to inherit through another one.
 
-ACCESS
+== ACCESS
-------
 Caller must be a member of the privileged 'Administrators' group.
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-OPTIONS
+== OPTIONS
--------
 --parent::
 	Name of the parent to inherit through. If not specified,
 	the parent is set back to the default `All-Projects`.
@@ -49,8 +42,7 @@ OPTIONS
 	specifying the --exclude option multiple times. Excluding a
 	project that is not a child project has no effect.
 
-EXAMPLES
+== EXAMPLES
---------
 Configure `kernel/omap` to inherit permissions from `kernel/common`:
 
 ====
@@ -64,8 +56,7 @@ Reparent all children of `myParent` to `myOtherParent`:
 	  --children-of myParent --parent myOtherParent
 ====
 
-SEE ALSO
+== SEE ALSO
---------
 
 * link:access-control.html[Access Controls]
 

Documentation/cmd-set-project.txt

@@ -1,12 +1,9 @@
-gerrit set-project
+= gerrit set-project
-==================
 
-NAME
+== NAME
-----
 gerrit set-project - Change a project's settings.
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit set-project'
   [--description <DESC> | -d <DESC>]
@@ -20,24 +17,20 @@ SYNOPSIS
   <NAME>
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Modifies a given project's settings. This command can be useful to
 batch change projects.
 
 The command is argument-safe, that is, if no argument is given the
 previous settings are kept intact.
 
-ACCESS
+== ACCESS
-------
 Caller must be a member of the privileged 'Administrators' group.
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-OPTIONS
+== OPTIONS
--------
 <NAME>::
     Required; name of the project to edit.  If name ends
     with `.git` the suffix will be automatically removed.
@@ -105,8 +98,7 @@ is granted, but all modification operations are disabled.
 +
 Common unit suffixes of 'k', 'm', or 'g' are supported.
 
-EXAMPLES
+== EXAMPLES
---------
 Change project `example` to be hidden, require change id, don't use content merge
 and use 'merge if necessary' as merge strategy:
 

Documentation/cmd-set-reviewers.txt

@@ -1,12 +1,9 @@
-gerrit set-reviewers
+= gerrit set-reviewers
-====================
 
-NAME
+== NAME
-----
 gerrit set-reviewers - Add or remove reviewers to a change
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit set-reviewers'
   [--project <PROJECT> | -p <PROJECT>]
@@ -16,8 +13,7 @@ SYNOPSIS
   {COMMIT | CHANGE-ID}...
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Adds or removes reviewers to the specified change, sending email
 notifications when changes are made.
 
@@ -26,8 +22,7 @@ such as 'Iac6b2ac2'.  They may also be specified by numeric change
 identifiers, such as '8242' or by complete or abbreviated commit
 SHA-1s.
 
-OPTIONS
+== OPTIONS
--------
 
 --project::
 -p::
@@ -51,16 +46,13 @@ OPTIONS
 -h::
 	Display site-specific usage information
 
-ACCESS
+== ACCESS
-------
 Any user who has configured an SSH key.
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-EXAMPLES
+== EXAMPLES
---------
 
 Add reviewers alice and bob, but remove eve from change Iac6b2ac2.
 =====

Documentation/cmd-show-caches.txt

@@ -1,22 +1,18 @@
 gerrit show-caches
 ===================
 
-NAME
+== NAME
-----
 gerrit show-caches - Display current cache statistics
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit show-caches' [--gc] [--show-jvm]
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Display statistics about the size and hit ratio of in-memory caches.
 
-OPTIONS
+== OPTIONS
--------
 --gc::
 	Request Java garbage collection before displaying information
 	about the Java memory heap.
@@ -30,18 +26,15 @@ OPTIONS
 -w::
 	Width of the output table.
 
-ACCESS
+== ACCESS
-------
 Caller must be a member of the privileged 'Administrators' group,
 or have been granted
 link:access-control.html#capability_viewCaches[the 'View Caches' global capability].
 
-SCRIPTING
+== SCRIPTING
----------
 Intended for interactive use only.
 
-EXAMPLES
+== EXAMPLES
---------
 
 ====
 	$ ssh -p 29418 review.example.com gerrit show-caches
@@ -74,8 +67,7 @@ EXAMPLES
 	           0 open files,        6 cpus available,       23 threads
 ====
 
-SEE ALSO
+== SEE ALSO
---------
 
 * link:cmd-flush-caches.html[gerrit flush-caches]
 * link:config-gerrit.html#cache[Cache Configuration]

Documentation/cmd-show-connections.txt

@@ -1,34 +1,27 @@
-gerrit show-connections
+= gerrit show-connections
-=======================
 
-NAME
+== NAME
-----
 gerrit show-connections - Display active client SSH connections
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit show-connections' [--numeric | -n]
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Presents a table of the active SSH connections, the users who
 are currently connected to the internal server and performing
 an activity.
 
-ACCESS
+== ACCESS
-------
 Caller must be a member of the privileged 'Administrators' group,
 or have been granted
 link:access-control.html#capability_viewConnections[the 'View Connections' global capability].
 
-SCRIPTING
+== SCRIPTING
----------
 Intended for interactive use only.
 
-OPTIONS
+== OPTIONS
--------
 --numeric::
 -n::
 	Show client hostnames as IP addresses instead of DNS hostname.
@@ -38,8 +31,7 @@ OPTIONS
 	Do not format the output to the terminal width (default of
 	80 columns).
 
-DISPLAY
+== DISPLAY
--------
 
 Session::
 	Unique session identifier on this server.  Session
@@ -65,8 +57,7 @@ Remote Host::
 	Reverse lookup hostname, or if -n option is used, the remote
 	IP address.
 
-EXAMPLES
+== EXAMPLES
---------
 
 With reverse DNS lookup (default):
 ====

Documentation/cmd-show-queue.txt

@@ -1,19 +1,15 @@
-gerrit show-queue
+= gerrit show-queue
-=================
 
-NAME
+== NAME
-----
 gerrit show-queue - Display the background work queues, including replication
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit show-queue'
 'ssh' -p <port> <host> 'ps'
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Presents a table of the pending activity the Gerrit daemon
 is currently performing, or will perform in the near future.
 Gerrit contains an internal scheduler, similar to cron, that it
@@ -23,8 +19,7 @@ Tasks that are completed or canceled exit the queue very quickly
 once they enter this state, but it can be possible to observe tasks
 in these states.
 
-ACCESS
+== ACCESS
-------
 End-users may see a task in the queue only if they can also see
 the project the task is associated with. Tasks operating on other
 projects, or that do not have a specific project are hidden.
@@ -34,19 +29,16 @@ granted
 link:access-control.html#capability_viewQueue[the 'View Queue' capability]
 can see all queue entries.
 
-SCRIPTING
+== SCRIPTING
----------
 Intended for interactive use only.
 
-OPTIONS
+== OPTIONS
--------
 --wide::
 -w::
 	Do not format the output to the terminal width (default of
 	80 columns).
 
-DISPLAY
+== DISPLAY
--------
 
 Task::
 	Unique task identifier on this server.	May be passed into
@@ -71,8 +63,7 @@ Command::
 	Short text description of the task that will be performed
 	at the given time.
 
-EXAMPLES
+== EXAMPLES
---------
 
 The following queue contains two tasks scheduled to replicate the
 `tools/gerrit.git` project to two different remote systems, `dst1`

Documentation/cmd-stream-events.txt

@@ -1,18 +1,14 @@
-gerrit stream-events
+= gerrit stream-events
-====================
 
-NAME
+== NAME
-----
 gerrit stream-events - Monitor events occurring in real time
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit stream-events'
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 
 Provides a portal into the major events occurring on the server,
 outputting activity data in real-time to the client.  Events are
@@ -22,18 +18,15 @@ the project repository.
 
 Event output is in JSON, one event per line.
 
-ACCESS
+== ACCESS
-------
 Caller must be a member of the privileged 'Administrators' group,
 or have been granted
 link:access-control.html#capability_streamEvents[the 'Stream Events' global capability].
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-EXAMPLES
+== EXAMPLES
---------
 
 ====
   $ ssh -p 29418 review.example.com gerrit stream-events
@@ -41,8 +34,7 @@ EXAMPLES
   {"type":"comment-added",change:{"project":"tools/gerrit", ...}, ...}
 ====
 
-SCHEMA
+== SCHEMA
-------
 The JSON messages consist of nested objects referencing the *change*,
 *patchSet*, *account* involved, and other attributes as appropriate.
 The currently supported message types are *patchset-created*,
@@ -54,10 +46,8 @@ Note that any field may be missing in the JSON messages, so consumers of
 this JSON stream should deal with that appropriately.
 
 [[events]]
-Events
+=== Events
-~~~~~~
+==== Patchset Created
-Patchset Created
-^^^^^^^^^^^^^^^^
 type:: "patchset-created"
 
 change:: link:json.html#change[change attribute]
@@ -66,8 +56,7 @@ patchSet:: link:json.html#patchSet[patchSet attribute]
 
 uploader:: link:json.html#account[account attribute]
 
-Draft Published
+==== Draft Published
-^^^^^^^^^^^^^^^
 type:: "draft-published"
 
 change:: link:json.html#change[change attribute]
@@ -76,8 +65,7 @@ patchSet:: link:json.html#patchSet[patchSet attribute]
 
 uploader:: link:json.html#account[account attribute]
 
-Change Abandoned
+==== Change Abandoned
-^^^^^^^^^^^^^^^^
 type:: "change-abandoned"
 
 change:: link:json.html#change[change attribute]
@@ -88,8 +76,7 @@ abandoner:: link:json.html#account[account attribute]
 
 reason:: Reason for abandoning the change.
 
-Change Restored
+==== Change Restored
-^^^^^^^^^^^^^^^
 type:: "change-restored"
 
 change:: link:json.html#change[change attribute]
@@ -100,8 +87,7 @@ restorer:: link:json.html#account[account attribute]
 
 reason:: Reason for restoring the change.
 
-Change Merged
+==== Change Merged
-^^^^^^^^^^^^^
 type:: "change-merged"
 
 change:: link:json.html#change[change attribute]
@@ -110,8 +96,7 @@ patchSet:: link:json.html#patchSet[patchSet attribute]
 
 submitter:: link:json.html#account[account attribute]
 
-Merge Failed
+==== Merge Failed
-^^^^^^^^^^^^
 type:: "merge-failed"
 
 change:: link:json.html#change[change attribute]
@@ -122,8 +107,7 @@ submitter:: link:json.html#account[account attribute]
 
 reason:: Reason that the merge failed.
 
-Comment Added
+==== Comment Added
-^^^^^^^^^^^^^
 type:: "comment-added"
 
 change:: link:json.html#change[change attribute]
@@ -136,16 +120,14 @@ approvals:: All link:json.html#approval[approval attributes] granted.
 
 comment:: Comment text author had written
 
-Ref Updated
+==== Ref Updated
-^^^^^^^^^^^
 type:: "ref-updated"
 
 submitter:: link:json.html#account[account attribute]
 
 refUpdate:: link:json.html#refUpdate[refUpdate attribute]
 
-Reviewer Added
+==== Reviewer Added
-^^^^^^^^^^^^^^
 type:: "reviewer-added"
 
 change:: link:json.html#change[change attribute]
@@ -154,8 +136,7 @@ patchSet:: link:json.html#patchSet[patchSet attribute]
 
 reviewer:: link:json.html#account[account attribute]
 
-Topic Changed
+==== Topic Changed
-^^^^^^^^^^^^^
 type:: "topic-changed"
 
 change:: link:json.html#change[change attribute]
@@ -164,8 +145,7 @@ changer:: link:json.html#account[account attribute]
 
 oldTopic:: Topic name before it was changed.
 
-SEE ALSO
+== SEE ALSO
---------
 
 * link:json.html[JSON Data Formats]
 * link:access-control.html[Access Controls]

Documentation/cmd-suexec.txt

@@ -1,12 +1,9 @@
-suexec
+= suexec
-======
 
-NAME
+== NAME
-----
 suexec - Execute a command as any registered user account
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port>
   -i SITE_PATH/etc/ssh_host_rsa_key
@@ -18,8 +15,7 @@ SYNOPSIS
   [COMMAND]
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 The suexec command permits executing any other command as any other
 registered user account.
 
@@ -28,8 +24,7 @@ or any user granted granted the link:access-control.html#capability_runAs[Run As
 capability. The run as capability is permitted to be used only if
 link:config-gerrit.html[auth.enableRunAs] is true.
 
-OPTIONS
+== OPTIONS
--------
 
 --as::
 	Email address of the user you want to impersonate.
@@ -41,18 +36,15 @@ OPTIONS
 COMMAND::
 	Gerrit command you want to run.
 
-ACCESS
+== ACCESS
-------
 Caller must be the magic user Gerrit Code Review using the SSH
 daemon's host key, or a key on this daemon's peer host key ring,
 or a user granted the Run As capability.
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-EXAMPLES
+== EXAMPLES
---------
 
 Approve the change with commit c0ff33 as "Verified +1" as user bob@example.com
 =====

Documentation/cmd-test-submit-rule.txt

@@ -1,12 +1,9 @@
-gerrit test-submit rule
+= gerrit test-submit rule
-=======================
 
-NAME
+== NAME
-----
 gerrit test-submit rule - Test prolog submit rules with a chosen changeset.
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit test-submit rule'
   [-s]
@@ -14,24 +11,20 @@ SYNOPSIS
   CHANGE
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Provides a way to test prolog link:prolog-cookbook.html[submit rules].
 
-OPTIONS
+== OPTIONS
--------
 -s::
 	Reads a rules.pl file from stdin instead of rules.pl in refs/meta/config.
 
 --no-filters::
 	Don't run the submit_filter/2 from the parent projects of the specified change.
 
-ACCESS
+== ACCESS
-------
 Can be used by anyone that has permission to read the specified changeset.
 
-EXAMPLES
+== EXAMPLES
---------
 
 Test submit_rule from stdin and return the results as JSON.
 ====
@@ -60,8 +53,7 @@ Test the active submit_rule from the refs/meta/config branch, ignoring filters i
  ]
 ====
 
-SCRIPTING
+== SCRIPTING
----------
 Can be used either interactively for testing new prolog submit rules, or from a script to check the submit status of a change.
 
 GERRIT

Documentation/cmd-test-submit-type.txt

@@ -1,12 +1,9 @@
-gerrit test-submit type
+= gerrit test-submit type
-=======================
 
-NAME
+== NAME
-----
 gerrit test-submit type - Test prolog submit type with a chosen change.
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit test-submit type'
   [-s]
@@ -14,24 +11,20 @@ SYNOPSIS
   CHANGE
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Provides a way to test prolog submit type.
 
-OPTIONS
+== OPTIONS
--------
 -s::
 	Reads a rules.pl file from stdin instead of rules.pl in refs/meta/config.
 
 --no-filters::
 	Don't run the submit_type_filter/2 from the parent projects of the specified change.
 
-ACCESS
+== ACCESS
-------
 Can be used by anyone that has permission to read the specified change.
 
-EXAMPLES
+== EXAMPLES
---------
 
 Test submit_type from stdin and return the submit type.
 ====
@@ -45,8 +38,7 @@ Test the active submit_type from the refs/meta/config branch, ignoring filters i
  "MERGE_IF_NECESSARY"
 ====
 
-SCRIPTING
+== SCRIPTING
----------
 Can be used either interactively for testing new prolog submit type, or from a script to check the submit type of a change.
 
 GERRIT

Documentation/cmd-version.txt

@@ -1,18 +1,14 @@
-gerrit version
+= gerrit version
-==============
 
-NAME
+== NAME
-----
 gerrit version - Show the version of the currently executing Gerrit server
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'ssh' -p <port> <host> 'gerrit version'
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Displays a one-line response with the string `gerrit version` followed
 by the currently executing version of Gerrit.
 
@@ -28,16 +24,13 @@ the seven-character abbreviated SHA-1 of the commit. See the `git
 describe` documentation for details on how `<tagname>` is chosen and how
 `<n>` is computed.
 
-ACCESS
+== ACCESS
-------
 Any user who has configured an SSH key.
 
-SCRIPTING
+== SCRIPTING
----------
 This command is intended to be used in scripts.
 
-EXAMPLES
+== EXAMPLES
---------
 
 =====
 	$ ssh -p 29418 review.example.com gerrit version

Documentation/config-auto-site-initialization.txt

@@ -1,8 +1,6 @@
-Gerrit Code Review - Automatic Site Initialization on Startup
+= Gerrit Code Review - Automatic Site Initialization on Startup
-=============================================================
 
-Description
+== Description
------------
 
 Gerrit supports automatic site initialization on server startup
 when Gerrit runs in a servlet container. Both creation of a new site
@@ -16,8 +14,7 @@ the init from their local machine prior to deploying Gerrit on such a
 server. It may also make deployment and testing in a local servlet
 container faster to setup as the init step could be skipped.
 
-Gerrit Configuration
+== Gerrit Configuration
---------------------
 
 The site initialization will be performed only if the `gerrit.init`
 system property exists (the value of the property is not used, only the
@@ -40,8 +37,7 @@ if defined, will be used to determine the site path. The database
 connectivity, also for this case, is defined by the `jdbc/ReviewDb`
 JNDI property.
 
-Example 1
+=== Example 1
-~~~~~~~~~
 
 Prepare Tomcat so that a site is initialized at a given path using
 the H2 database (if the site doesn't exist yet) or using whatever
@@ -52,8 +48,7 @@ database is defined in `etc/gerrit.config` of that site:
   $ catalina.sh start
 ----
 
-Example 2
+=== Example 2
-~~~~~~~~~
 
 Prepare Tomcat so that an existing site with the path defined in the
 `system_config` table is initialized (upgraded) on Gerrit startup. The
@@ -65,8 +60,7 @@ Tomcat:
   $ catalina.sh start
 ----
 
-Example 3
+=== Example 3
-~~~~~~~~~
 
 Assuming the database schema doesn't exist in the database defined
 via the `jdbc/ReviewDb` JNDI property, initialize a new site using that

Documentation/config-cla.txt

@@ -1,5 +1,4 @@
-Gerrit Code Review - Contributor Agreements
+= Gerrit Code Review - Contributor Agreements
-===========================================
 
 Users can be required to sign one or more contributor agreements before
 being able to submit a change in a project.

Documentation/config-contact.txt

@@ -1,5 +1,4 @@
-Gerrit Code Review - Contact Information
+= Gerrit Code Review - Contact Information
-========================================
 
 To help ensure contributor privacy, but still support gathering of
 contributor agreements as necessary, Gerrit encrypts all offline
@@ -12,8 +11,7 @@ and the `contactstore.url` setting in `gerrit.config` is not set,
 Gerrit will not collect contact information from users.
 
 
-Setup
+== Setup
------
 
 Ensure Bouncy Castle Crypto API is available in the web application's
 CLASSPATH (e.g. in `'JETTY_HOME'/lib/plus` for Jetty).  Gerrit needs
@@ -85,8 +83,7 @@ URL (in `contactstore.url`), and if needed, APPSEC value (in
 ====
 
 
-Contact Store Protocol
+== Contact Store Protocol
-----------------------
 
 To implement a new contact store, the following details are useful.
 
@@ -135,8 +132,7 @@ Using `https://` for the store URL is *highly* encouraged, as it
 prevents man-in-the-middle attacks from reading the shared secret
 APPSEC token, or messing with the data field.
 
-Data Format
+=== Data Format
-~~~~~~~~~~~
 
 Once decrypted the `data` field looks something like the following:
 

Documentation/config-gerrit.txt

@@ -1,8 +1,6 @@
-Gerrit Code Review - Configuration
+= Gerrit Code Review - Configuration
-==================================
 
-File `etc/gerrit.config`
+== File `etc/gerrit.config`
-------------------------
 
 The optional file `'$site_path'/etc/gerrit.config` is a Git-style
 config file that controls many host specific settings for Gerrit.
@@ -22,8 +20,7 @@ Sample `etc/gerrit.config`:
 ----
 
 [[accounts]]
-Section accounts
+=== Section accounts
-~~~~~~~~~~~~~~~~
 
 [[accounts.visibility]]accounts.visibility::
 +
@@ -44,8 +41,7 @@ If `NONE`, no users other than the current user are visible.
 Default is `ALL`.
 
 [[addreviewer]]
-Section addreviewer
+=== Section addreviewer
-~~~~~~~~~~~~~~~~~~~
 
 [[addreviewer.maxWithoutConfirmation]]addreviewer.maxWithoutConfirmation::
 +
@@ -72,8 +68,7 @@ be added at once by adding a group as reviewer.
 Default is 20.
 
 [[auth]]
-Section auth
+=== Section auth
-~~~~~~~~~~~~
 
 See also link:config-sso.html[SSO configuration].
 
@@ -468,8 +463,7 @@ editing gerrit.config and restarting the server.
 Default is true.
 
 [[cache]]
-Section cache
+=== Section cache
-~~~~~~~~~~~~~
 
 [[cache.directory]]cache.directory::
 +
@@ -546,8 +540,7 @@ Default is 128 MiB per cache.
 +
 If 0, disk storage for the cache is disabled.
 
-[[cache_names]]Standard Caches
+==== [[cache_names]]Standard Caches
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 cache `"accounts"`::
 +
@@ -709,8 +702,7 @@ this cache is approximately 346 bytes.
 
 See also link:cmd-flush-caches.html[gerrit flush-caches].
 
-[[cache_options]]Cache Options
+==== [[cache_options]]Cache Options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 [[cache.diff_intraline.maxIdleWorkers]]cache.diff_intraline.maxIdleWorkers::
 +
@@ -772,8 +764,7 @@ link:cmd-flush-caches.html[gerrit flush-caches].
 Default is 5 minutes.
 
 [[change]]
-Section change
+=== Section change
-~~~~~~~~~~~~~~
 
 [[change.largeChange]]change.largeChange::
 +
@@ -806,8 +797,7 @@ If 0 the update polling is disabled.
 Default is 30 seconds.
 
 [[changeMerge]]
-Section changeMerge
+=== Section changeMerge
-~~~~~~~~~~~~~~~~~~~
 
 [[changeMerge.checkFrequency]]changeMerge.checkFrequency::
 +
@@ -827,8 +817,7 @@ changes is updated.
 Default is 1.
 
 [[commentlink]]
-Section commentlink
+=== Section commentlink
-~~~~~~~~~~~~~~~~~~~
 
 Comment links are find/replace strings applied to change descriptions,
 patch comments, in-line code comments and approval category value descriptions
@@ -916,8 +905,7 @@ link:rest-api-projects.html#get-config[REST API].
 
 
 [[contactstore]]
-Section contactstore
+=== Section contactstore
-~~~~~~~~~~~~~~~~~~~~
 
 [[contactstore.url]]contactstore.url::
 +
@@ -933,8 +921,7 @@ Shared secret of the web based contact store.
 
 
 [[container]]
-Section container
+=== Section container
-~~~~~~~~~~~~~~~~~
 
 These settings are applied only if Gerrit is started as the container
 process through Gerrit's 'gerrit.sh' rc.d compatible wrapper script.
@@ -990,8 +977,7 @@ If not set, defaults to '$site_path/bin/gerrit.war', or to
 
 
 [[core]]
-Section core
+=== Section core
-~~~~~~~~~~~~
 
 [[core.packedGitWindowSize]]core.packedGitWindowSize::
 +
@@ -1098,8 +1084,7 @@ conflicts.
 Default is false, but in a future release may default to true.
 
 [[database]]
-Section database
+=== Section database
-~~~~~~~~~~~~~~~~
 
 The database section configures where Gerrit stores its metadata
 records about user accounts and change reviews.
@@ -1237,8 +1222,7 @@ This setting only applies if
 <<database.connectionPool,database.connectionPool>> is true.
 
 [[download]]
-Section download
+=== Section download
-~~~~~~~~~~~~~~~~
 
 ----
 [download]
@@ -1319,8 +1303,7 @@ If `download.scheme` is not specified, SSH, HTTP and Anonymous HTTP
 downloads are allowed.
 
 [[gerrit]]
-Section gerrit
+=== Section gerrit
-~~~~~~~~~~~~~~
 
 [[gerrit.basePath]]gerrit.basePath::
 +
@@ -1406,8 +1389,7 @@ Default change screen UI to direct users to. Valid values are
 `OLD_UI` and `CHANGE_SCREEN2`. Default is `CHANGE_SCREEN2`.
 
 [[gitweb]]
-Section gitweb
+=== Section gitweb
-~~~~~~~~~~~~~~
 
 Gerrit can forward requests to either an internally managed gitweb
 (which allows Gerrit to enforce some access controls), or to an
@@ -1539,8 +1521,7 @@ the links to draft patch sets from the change review screen.
 Valid values are "true" and "false," default is "true".
 
 [[groups]]
-Section groups
+=== Section groups
-~~~~~~~~~~~~~~
 
 [[groups.newGroupsVisibleToAll]]groups.newGroupsVisibleToAll::
 +
@@ -1550,8 +1531,7 @@ all registered users.
 By default, false.
 
 [[hooks]]
-Section hooks
+=== Section hooks
-~~~~~~~~~~~~~
 
 See also link:config-hooks.html[Hooks].
 
@@ -1625,8 +1605,7 @@ Optional timeout value in seconds for synchronous hooks, if not specified
 then 30 seconds will be used.
 
 [[http]]
-Section http
+=== Section http
-~~~~~~~~~~~~
 
 [[http.proxy]]http.proxy::
 +
@@ -1648,8 +1627,7 @@ appear in the http.proxy property above.
 
 
 [[httpd]]
-Section httpd
+=== Section httpd
-~~~~~~~~~~~~~
 
 The httpd section configures the embedded servlet container.
 
@@ -1882,8 +1860,7 @@ If the file doesn't exist or can't be read the default robots.txt file
 bundled with the .war will be used instead.
 
 [[index]]
-Section index
+=== Section index
-~~~~~~~~~~~~~
 
 The index section configures the secondary index.
 
@@ -1908,8 +1885,7 @@ using the link:pgm-reindex.html[reindex program] before restarting the
 Gerrit server.
 
 [[ldap]]
-Section ldap
+=== Section ldap
-~~~~~~~~~~~~
 
 LDAP integration is only enabled if `auth.type` is set to
 `HTTP_LDAP`, `LDAP` or `CLIENT_SSL_CERT_LDAP`.  See above for a
@@ -2196,8 +2172,7 @@ must have the DWORD value `allowtgtsessionkey` set to 1 and the account must not
 have local administrator privileges.
 
 [[mimetype]]
-Section mimetype
+=== Section mimetype
-~~~~~~~~~~~~~~~~
 
 [[mimetype.name.safe]]mimetype.<name>.safe::
 +
@@ -2226,8 +2201,7 @@ Common examples:
 
 
 [[pack]]
-Section pack
+=== Section pack
-~~~~~~~~~~~~
 
 Global settings controlling how Gerrit Code Review creates pack
 streams for Git clients running clone, fetch, or pull.  Most of these
@@ -2253,8 +2227,7 @@ By default, 1.
 
 
 [[plugins]]
-Section plugins
+=== Section plugins
-~~~~~~~~~~~~~~~
 
 [[plugins.checkFrequency]]plugins.checkFrequency::
 +
@@ -2270,8 +2243,7 @@ Default is 1 minute.
 
 
 [[receive]]
-Section receive
+=== Section receive
-~~~~~~~~~~~~~~~
 
 This section is used to set who can execute the 'receive-pack' and
 to limit the maximum Git object size that 'receive-pack' will accept.
@@ -2373,8 +2345,7 @@ is assumed.
 
 
 [[repository]]
-Section repository
+=== Section repository
-~~~~~~~~~~~~~~~~~~
 
 Repositories in this sense are the same as projects.
 
@@ -2405,8 +2376,7 @@ groups are allowed.  Each on its own line.  Groups which don't exist
 in the database are ignored.
 
 [[rules]]
-Section rules
+=== Section rules
-~~~~~~~~~~~~~
 
 [[rules.enable]]rules.enable::
 +
@@ -2417,8 +2387,7 @@ only the default internal rules will be used.
 Default is true, to execute project specific rules.
 
 [[sendemail]]
-Section sendemail
+=== Section sendemail
-~~~~~~~~~~~~~~~~~
 
 [[sendemail.enable]]sendemail.enable::
 +
@@ -2547,8 +2516,7 @@ By default, unset, so no Expiry-Date header is generated.
 
 
 [[site]]
-Section site
+=== Section site
-~~~~~~~~~~~~
 
 [[site.checkUserAgent]]site.checkUserAgent::
 +
@@ -2571,8 +2539,7 @@ and text results for changes. If false, the URL is disabled and
 returns 404 to clients. Default is true, enabling `/query`.
 
 [[ssh-alias]]
-Section ssh-alias
+=== Section ssh-alias
-~~~~~~~~~~~~~~~~~
 
 Variables in section ssh-alias permit the site administrator to alias
 another command from Gerrit or a plugin into the `gerrit` command
@@ -2584,8 +2551,7 @@ namespace. To alias `replication start` to `gerrit replicate`:
 ----
 
 [[sshd]]
-Section sshd
+=== Section sshd
-~~~~~~~~~~~~
 
 [[sshd.backend]]sshd.backend::
 +
@@ -2797,8 +2763,7 @@ programmatic configuration.
 By default, true.
 
 [[suggest]]
-Section suggest
+=== Section suggest
-~~~~~~~~~~~~~~~
 
 [[suggest.accounts]]suggest.accounts::
 +
@@ -2825,8 +2790,7 @@ are provided. If set to 0, suggestions are always provided.
 By default 0.
 
 [[theme]]
-Section theme
+=== Section theme
-~~~~~~~~~~~~~
 
 [[theme.backgroundColor]]theme.backgroundColor::
 +
@@ -2924,8 +2888,7 @@ As example, here is the theme configuration to have the old green look:
 ----
 
 [[trackingid]]
-Section trackingid
+=== Section trackingid
-~~~~~~~~~~~~~~~~~~
 
 Tagged footer lines containing references to external
 tracking systems, parsed out of the commit message and
@@ -2978,8 +2941,7 @@ It is possible to have several trackingid entries for the same
 tracking system.
 
 [[transfer]]
-Section transfer
+=== Section transfer
-~~~~~~~~~~~~~~~~
 
 [[transfer.timeout]]transfer.timeout::
 +
@@ -2997,8 +2959,7 @@ Defaults to 0 seconds, wait indefinitely.
 
 
 [[upload]]
-Section upload
+=== Section upload
-~~~~~~~~~~~~~~
 
 Sets the group of users allowed to execute 'upload-pack' on the
 server, 'upload-pack' is what runs on the server during a user's
@@ -3020,8 +2981,7 @@ If no groups are added, any user will be allowed to execute
 
 
 [[user]]
-Section user
+=== Section user
-~~~~~~~~~~~~
 
 [[user.name]]user.name::
 +
@@ -3048,8 +3008,7 @@ notifications if the full name of the user is not set.
 By default "Anonymous Coward" is used.
 
 
-File `etc/secure.config`
+== File `etc/secure.config`
-------------------------
 The optional file `'$site_path'/etc/secure.config` overrides (or
 supplements) the settings supplied by `'$site_path'/etc/gerrit.config`.
 The file should be readable only by the daemon process and can be
@@ -3079,8 +3038,7 @@ Sample `etc/secure.config`:
   password = s3kr3t
 ----
 
-File `etc/peer_keys`
+== File `etc/peer_keys`
---------------------
 
 The optional file `'$site_path'/etc/peer_keys` controls who can
 login as the 'Gerrit Code Review' user, required for the link:cmd-suexec.html[suexec]
@@ -3089,8 +3047,7 @@ command.
 The format is one Base-64 encoded public key per line.
 
 
-Database system_config
+== Database system_config
-----------------------
 
 Several columns in the `system_config` table within the metadata
 database may be set to control how Gerrit behaves.
@@ -3100,8 +3057,7 @@ The contents of the `system_config` table are cached at startup
 by Gerrit.  If you modify any columns in this table, Gerrit needs
 to be restarted before it will use the new values.
 
-Configurable Parameters
+=== Configurable Parameters
-~~~~~~~~~~~~~~~~~~~~~~~
 
 site_path::
 +

Documentation/config-gitweb.txt

@@ -1,12 +1,10 @@
-Gitweb Integration
+== Gitweb Integration
-------------------
 
 Gerrit Code Review can manage and generate hyperlinks to gitweb,
 allowing users to jump from Gerrit content to the same information,
 but shown by gitweb.
 
-Internal/Managed gitweb
+=== Internal/Managed gitweb
-~~~~~~~~~~~~~~~~~~~~~~~
 
 In the internal configuration, Gerrit inspects the request, enforces
 its project level access controls, and directly executes `gitweb.cgi`
@@ -37,16 +35,14 @@ To enable this feature, set both: `gitweb.cgi` and `gitweb.url`.
 After updating `'$site_path'/etc/gerrit.config`, the Gerrit server must
 be restarted and clients must reload the host page to see the change.
 
-Configuration
+==== Configuration
-^^^^^^^^^^^^^
 
 Most of the gitweb configuration file is handled automatically
 by Gerrit Code Review.  Site specific overrides can be placed in
 `'$site_path'/etc/gitweb_config.perl`, as this file is loaded as
 part of the generated configuration file.
 
-Logo and CSS
+==== Logo and CSS
-^^^^^^^^^^^^
 
 If the package-manager installed CGI (`/usr/lib/cgi-bin/gitweb.cgi`)
 is being used, the stock CSS and logo files will be served from
@@ -56,8 +52,7 @@ Otherwise, Gerrit expects `gitweb.css` and `git-logo.png` to be found
 in the same directory as the CGI script itself.  This matches with
 the default source code distribution, and most custom installations.
 
-Access Control
+==== Access Control
-^^^^^^^^^^^^^^
 
 Access controls for internally managed gitweb page views are enforced
 using the standard project READ +1 permission.
@@ -68,19 +63,16 @@ refs/meta/config, refs/meta/dashboards/*, etc.). If you have exclusive read
 permissions for any references, make sure to include all parties that should be
 able to read the gitweb info for any of the branches in that project.
 
-External/Unmanaged gitweb
+=== External/Unmanaged gitweb
-~~~~~~~~~~~~~~~~~~~~~~~~~
 
 For the external configuration, gitweb runs under the control of an
 external web server, and Gerrit access controls are not enforced. Gerrit
 provides configuration parameters for integration with GitWeb.
 
 [[linuxGitWeb]]
-Linux Installation
+==== Linux Installation
-^^^^^^^^^^^^^^^^^^
 
-Install GitWeb
+===== Install GitWeb
-++++++++++++++
 
 On Ubuntu:
 
@@ -94,8 +86,7 @@ With Yum:
   $ yum install gitweb
 ====
 
-Configure GitWeb
+===== Configure GitWeb
-++++++++++++++++
 
 
 Update `/etc/gitweb.conf`, add the public GIT repositories:
@@ -126,11 +117,9 @@ $logo = "git-logo.png";
 $favicon = "git-favicon.png";
 ----
 
-Configure & Restart Apache Web Server
+==== Configure & Restart Apache Web Server
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Configure Apache
+===== Configure Apache
-++++++++++++++++
 
 
 Link gitweb to `/var/www/gitweb`, check `/etc/gitweb.conf` if unsure of paths:
@@ -159,8 +148,7 @@ AllowOverride None
 *NOTE* This may have already been added by yum/apt-get. If that's the case, leave as
 is.
 
-Restart the Apache Web Server
+===== Restart the Apache Web Server
-+++++++++++++++++++++++++++++
 
 ====
 $ sudo /etc/init.d/apache2 restart
@@ -171,8 +159,7 @@ Now you should be able to view your repository projects online:
 link:http://localhost/gitweb[http://localhost/gitweb]
 
 [[WindowsGitWeb]]
-Windows Installation
+==== Windows Installation
-^^^^^^^^^^^^^^^^^^^^
 
 Instructions are available for installing the GitWeb module distributed with
 MsysGit:
@@ -220,8 +207,7 @@ contents: `bin/` `lib/` `site/`
 
 copy the contents of lib into `msysgit/lib/perl5/5.8.8` and overwrite existing files.
 
-Enable GitWeb Integration
+==== Enable GitWeb Integration
-^^^^^^^^^^^^^^^^^^^^^^^^^
 
 To enable the external gitweb integration, set
 link:config-gerrit.html#gitweb.url[gitweb.url] with the URL of your
@@ -258,23 +244,20 @@ specified for all of the `project`, `revision`, `branch`, `roottree`,
 `file`, and `filehistory` settings, otherwise the configuration will
 not be used.
 
-Access Control
+===== Access Control
-++++++++++++++
 
 Gitweb access controls can be implemented using standard web server
 access controls.  This isn't typically integrated with Gerrit's own
 access controls.  Caution must be taken to ensure the controls are
 consistent if access needs to be restricted.
 
-Caching Gitweb
+===== Caching Gitweb
-++++++++++++++
 
 If your repository set is large and you are expecting a lot
 of users, you may want to look at the caching forks used by
 high-traffic sites like kernel.org or repo.or.cz.
 
-Alternatives to gitweb
+=== Alternatives to gitweb
-~~~~~~~~~~~~~~~~~~~~~~
 There are other alternatives to gitweb that can also be used with
 Gerrit, such as cgit.
 
@@ -282,8 +265,7 @@ cgit can be used by specifying `gitweb.type` to be 'cgit'.
 
 It is also possible to define custom patterns.
 
-See Also
+=== See Also
-~~~~~~~~
 
 * link:config-gerrit.html#gitweb[Section gitweb]
 * link:http://hjemli.net/git/cgit/[cgit]

Documentation/config-hooks.txt

@@ -1,5 +1,4 @@
-Gerrit Code Review - Hooks
+= Gerrit Code Review - Hooks
-==========================
 
 Gerrit does not run any of the standard git hooks in the
 repositories it works with, but it does have its own hook mechanism
@@ -17,11 +16,9 @@ the outcome of any given change. Because of the fact the hooks are
 run in the background after the activity, a hook might not be notified
 about an event if the server is shutdown before the hook can be invoked.
 
-Supported Hooks
+== Supported Hooks
----------------
 
-ref-update
+=== ref-update
-~~~~~~~~~~
 
 This is called when a push request is received by Gerrit. It allows
 a push to be rejected before it is committed to the Gerrit repository.
@@ -38,8 +35,7 @@ for configuration details.
   ref-update --project <project name> --refname <refname> --uploader <uploader> --oldrev <sha1> --newrev <sha1>
 ====
 
-patchset-created
+=== patchset-created
-~~~~~~~~~~~~~~~~
 
 This is called whenever a patchset is created (this includes new
 changes and drafts).
@@ -48,8 +44,7 @@ changes and drafts).
   patchset-created --change <change id> --is-draft <boolean> --change-url <change url> --project <project name> --branch <branch> --topic <topic> --uploader <uploader> --commit <sha1> --patchset <patchset id>
 ====
 
-draft-published
+=== draft-published
-~~~~~~~~~~~~~~~
 
 This is called whenever a draft change is published.
 
@@ -57,8 +52,7 @@ This is called whenever a draft change is published.
   draft-published --change <change id> --change-url <change url> --project <project name> --branch <branch> --topic <topic> --uploader <uploader> --commit <sha1> --patchset <patchset id>
 ====
 
-comment-added
+=== comment-added
-~~~~~~~~~~~~~
 
 This is called whenever a comment is added to a change.
 
@@ -66,8 +60,7 @@ This is called whenever a comment is added to a change.
   comment-added --change <change id> --is-draft <boolean> --change-url <change url> --project <project name> --branch <branch> --topic <topic> --author <comment author> --commit <commit> --comment <comment> [--<approval category id> <score> --<approval category id> <score> ...]
 ====
 
-change-merged
+=== change-merged
-~~~~~~~~~~~~~
 
 Called whenever a change has been merged.
 
@@ -75,8 +68,7 @@ Called whenever a change has been merged.
   change-merged --change <change id> --change-url <change url> --project <project name> --branch <branch> --topic <topic> --submitter <submitter> --commit <sha1>
 ====
 
-merge-failed
+=== merge-failed
-~~~~~~~~~~~~
 
 Called whenever a change has failed to merge.
 
@@ -84,8 +76,7 @@ Called whenever a change has failed to merge.
   merge-failed --change <change id> --change-url <change url> --project <project name> --branch <branch> --topic <topic> --submitter <submitter> --commit <sha1> --reason <reason>
 ====
 
-change-abandoned
+=== change-abandoned
-~~~~~~~~~~~~~~~~
 
 Called whenever a change has been abandoned.
 
@@ -93,8 +84,7 @@ Called whenever a change has been abandoned.
   change-abandoned --change <change id> --change-url <change url> --project <project name> --branch <branch> --topic <topic> --abandoner <abandoner> --commit <sha1> --reason <reason>
 ====
 
-change-restored
+=== change-restored
-~~~~~~~~~~~~~~~
 
 Called whenever a change has been restored.
 
@@ -102,8 +92,7 @@ Called whenever a change has been restored.
   change-restored --change <change id> --change-url <change url> --project <project name> --branch <branch> --topic <topic> --restorer <restorer> --commit <sha1> --reason <reason>
 ====
 
-ref-updated
+=== ref-updated
-~~~~~~~~~~~
 
 Called whenever a ref has been updated.
 
@@ -111,8 +100,7 @@ Called whenever a ref has been updated.
   ref-updated --oldrev <old rev> --newrev <new rev> --refname <ref name> --project <project name> --submitter <submitter>
 ====
 
-reviewer-added
+=== reviewer-added
-~~~~~~~~~~~~~~
 
 Called whenever a reviewer is added to a change.
 
@@ -120,8 +108,7 @@ Called whenever a reviewer is added to a change.
   reviewer-added --change <change id> --change-url <change url> --project <project name> --branch <branch> --reviewer <reviewer>
 ====
 
-topic-changed
+=== topic-changed
-~~~~~~~~~~~~~
 
 Called whenever a change's topic is changed from the Web UI or via the REST API.
 
@@ -129,8 +116,7 @@ Called whenever a change's topic is changed from the Web UI or via the REST API.
   topic-changed --change <change id> --project <project name> --branch <branch> --changer <changer> --old-topic <old topic> --new-topic <new topic>
 ====
 
-cla-signed
+=== cla-signed
-~~~~~~~~~~
 
 Called whenever a user signs a contributor license agreement.
 
@@ -139,8 +125,7 @@ Called whenever a user signs a contributor license agreement.
 ====
 
 
-Configuration Settings
+== Configuration Settings
-----------------------
 
 It is possible to change where Gerrit looks for hooks, and what
 filenames it looks for, by adding a [hooks] section in gerrit.config.
@@ -152,8 +137,7 @@ hooks.draftPublishedHook, hooks.commentAddedHook, hooks.changeMergedHook,
 hooks.changeAbandonedHook, hooks.changeRestoredHook, hooks.refUpdatedHook,
 hooks.refUpdateHook, hooks.reviewerAddedHook and hooks.claSignedHook.
 
-Missing Change URLs
+== Missing Change URLs
--------------------
 
 If link:config-gerrit.html#gerrit.canonicalWebUrl[gerrit.canonicalWebUrl]
 is not set in `gerrit.config` the `--change-url` flag may not be
@@ -161,8 +145,7 @@ passed to all hooks.  Hooks started out of an SSH context (for example
 the patchset-created hook) don't know the server's web URL, unless
 this variable is configured.
 
-See Also
+== See Also
---------
 
 * link:config-gerrit.html#hooks[Section hooks]
 

Documentation/config-labels.txt

@@ -1,5 +1,4 @@
-Gerrit Code Review - Review Labels
+= Gerrit Code Review - Review Labels
-==================================
 
 As part of the code review process, reviewers score each change with
 values for each label configured for the project.  The label values that
@@ -10,8 +9,7 @@ groups within projects, enabling functionality for that group's members.
 
 
 [[label_Code-Review]]
-Label: Code-Review
+== Label: Code-Review
-------------------
 
 The code review label is the second of two default labels that is
 configured upon the creation of a Gerrit instance.  It may have any
@@ -83,8 +81,7 @@ value if present blocks a submit, while the highest positive value is
 required to enable submit.
 
 [[label_Verified]]
-Label: Verified
+== Label: Verified
----------------
 
 The Verified label was originally invented by the Android Open Source
 Project to mean 'compiles, passes basic unit tests'.  Some CI tools
@@ -131,8 +128,7 @@ behavior.
 
 
 [[label_custom]]
-Your Label Here
+== Your Label Here
----------------
 
 Site administrators and project owners can also define their own labels.
 
@@ -159,16 +155,14 @@ with inherited labels appearing first, providing some layout control to
 the administrator.
 
 [[label_name]]
-`label.Label-Name`
+=== `label.Label-Name`
-~~~~~~~~~~~~~~~~~~
 
 The name for a label, consisting only of alphanumeric characters and
 `-`.
 
 
 [[label_value]]
-`label.Label-Name.value`
+=== `label.Label-Name.value`
-~~~~~~~~~~~~~~~~~~~~~~~~
 
 A multi-valued key whose values are of the form `"<#> Value description
 text"`. The `<#>` may be any positive or negative number with an
@@ -176,8 +170,7 @@ optional leading `+`.
 
 
 [[label_abbreviation]]
-`label.Label-Name.abbreviation`
+=== `label.Label-Name.abbreviation`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 An abbreviated name for a label shown as a compact column header, for
 example on project dashboards. Defaults to all the uppercase characters
@@ -185,8 +178,7 @@ in the label name, e.g. `Label-Name` is abbreviated by default as `LN`.
 
 
 [[label_function]]
-`label.Label-Name.function`
+=== `label.Label-Name.function`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The name of a function for evaluating multiple votes for a label.  This
 function is only applied if the default submit rule is used for a label.
@@ -221,15 +213,13 @@ determining whether a change is submittable.
 
 
 [[label_copyMinScore]]
-`label.Label-Name.copyMinScore`
+=== `label.Label-Name.copyMinScore`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If true, the lowest possible negative value for the label is copied
 forward when a new patch set is uploaded.
 
 [[label_copyMaxScore]]
-`label.Label-Name.copyMaxScore`
+=== `label.Label-Name.copyMaxScore`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If true, the highest possible positive value for the label is copied
 forward when a new patch set is uploaded. This can be used to enable
@@ -237,8 +227,7 @@ sticky approvals, reducing turn-around for trivial cleanups prior to
 submitting a change.
 
 [[label_copyAllScoresOnTrivialRebase]]
-`label.Label-Name.copyAllScoresOnTrivialRebase`
+=== `label.Label-Name.copyAllScoresOnTrivialRebase`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If true, all scores for the label are copied forward when a new patch
 set is uploaded that is a trivial rebase. A new patch set is considered
@@ -249,8 +238,7 @@ This can be used to enable sticky approvals, reducing turn-around for
 trivial rebases prior to submitting a change. Defaults to false.
 
 [[label_copyAllScoresIfNoCodeChange]]
-`label.Label-Name.copyAllScoresIfNoCodeChange`
+=== `label.Label-Name.copyAllScoresIfNoCodeChange`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If true, all scores for the label are copied forward when a new patch
 set is uploaded that has the same parent commit as the previous patch
@@ -261,16 +249,14 @@ if only the commit message is changed prior to submitting a change.
 Defaults to false.
 
 [[label_canOverride]]
-`label.Label-Name.canOverride`
+=== `label.Label-Name.canOverride`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If false, the label cannot be overridden by child projects. Any
 configuration for this label in child projects will be ignored. Defaults
 to true.
 
 [[label_branch]]
-`label.Label-Name.branch`
+=== `label.Label-Name.branch`
-~~~~~~~~~~~~~~~~~~~~~~~~~
 
 By default a given project's label applicable scope is all changes
 on all branches of this project and its child projects.
@@ -294,8 +280,7 @@ assign permissions for that label on a branch, but this permission is then
 ignored if the label doesn't apply for that branch.
 
 [[label_example]]
-Example
+=== Example
-~~~~~~~
 
 To define a new 3-valued category that behaves exactly like `Verified`,
 but has different names/labels:

Documentation/config-login-register.txt

@@ -1,6 +1,5 @@
 [[usersetup]]
-Initial Login
+== Initial Login
--------------
 It's time to exit the gerrit2 account as you now have Gerrit running on your
 host and setup your first workspace.
 
@@ -21,8 +20,7 @@ If you have the files, you may skip the key generating step.
 If you don't see the files in your listing, your will have to generate rsa
 keys for your ssh sessions:
 
-SSH key generation
+=== SSH key generation
-~~~~~~~~~~~~~~~~~~
 
 *Please don't generate new keys if you already have a valid keypair!*
 *They will be overwritten!*
@@ -53,8 +51,7 @@ SSH key generation
   user@host:~$
 ----
 
-Registering your key in Gerrit
+=== Registering your key in Gerrit
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Open a browser and enter the canonical url of your Gerrit server.  You can
 find the url in the settings file.

Documentation/config-mail.txt

@@ -1,5 +1,4 @@
-Gerrit Code Review - Mail Templates
+= Gerrit Code Review - Mail Templates
-===================================
 
 Gerrit uses velocity templates for the bulk of the standard mails it sends out.
 There are builtin default templates which are used if they are not overridden.
@@ -7,8 +6,7 @@ These defaults are also provided as examples so that administrators may copy
 them and easily modify them to tweak their contents.
 
 
-Template Locations and Extensions:
+== Template Locations and Extensions:
-----------------------------------
 
 The default example templates reside under:  `'$site_path'/etc/mail` and are
 terminated with the double extension `.vm.example`. Modifying these example
@@ -17,77 +15,66 @@ example template to an equivalently named file without the `.example` extension
 and modifying it will allow an administrator to customize the template.
 
 
-Supported Mail Templates:
+== Supported Mail Templates:
--------------------------
 
 Each mail that Gerrit sends out is controlled by at least one template.  These
 are listed below.  Change emails are influenced by two additional templates,
 one to set the subject line, and one to set the footer which gets appended to
 all the change emails (see `ChangeSubject.vm` and `ChangeFooter.vm` below.)
 
-Abandoned.vm
+=== Abandoned.vm
-~~~~~~~~~~~~
 
 The `Abandoned.vm` template will determine the contents of the email related
 to a change being abandoned.  It is a `ChangeEmail`: see `ChangeSubject.vm` and
 `ChangeFooter.vm`.
 
-ChangeFooter.vm
+=== ChangeFooter.vm
-~~~~~~~~~~~~~~~
 
 The `ChangeFooter.vm` template will determine the contents of the footer
 text that will be appended to emails related to changes (all `ChangeEmail`s).
 
-ChangeSubject.vm
+=== ChangeSubject.vm
-~~~~~~~~~~~~~~~~
 
 The `ChangeSubject.vm` template will determine the contents of the email
 subject line for ALL emails related to changes.
 
-Comment.vm
+=== Comment.vm
-~~~~~~~~~~
 
 The `Comment.vm` template will determine the contents of the email related to
 a user submitting comments on changes.  It is a `ChangeEmail`: see
 `ChangeSubject.vm`, `ChangeFooter.vm` and `CommentFooter.vm`.
 
-CommentFooter.vm
+=== CommentFooter.vm
-~~~~~~~~~~~~~~~~
 
 The `CommentFooter.vm` template will determine the contents of the footer
 text that will be appended to emails related to a user submitting comments on
 changes.  See `ChangeSubject.vm`, `Comment.vm` and `ChangeFooter.vm`.
 
-CommitMessageEdited.vm
+=== CommitMessageEdited.vm
-~~~~~~~~~~~~~~~~~~~~~~
 
 The `CommitMessageEdited.vm` template will determine the contents of the email
 related to a user editing the commit message through the Gerrit UI.  It is a
 `ChangeEmail`: see `ChangeSubject.vm` and `ChangeFooter.vm`.
 
-Footer.vm
+=== Footer.vm
-~~~~~~~~~
 
 The `Footer.vm` template will determine the contents of the footer text
 appended to the end of all outgoing emails after the ChangeFooter and
 CommentFooter.
 
-Merged.vm
+=== Merged.vm
-~~~~~~~~~
 
 The `Merged.vm` template will determine the contents of the email related to
 a change successfully merged to the head.  It is a `ChangeEmail`: see
 `ChangeSubject.vm` and `ChangeFooter.vm`.
 
-MergeFail.vm
+=== MergeFail.vm
-~~~~~~~~~~~~
 
 The `MergeFail.vm` template will determine the contents of the email related
 to a failure upon attempting to merge a change to the head.  It is a
 `ChangeEmail`: see `ChangeSubject.vm` and `ChangeFooter.vm`.
 
-NewChange.vm
+=== NewChange.vm
-~~~~~~~~~~~~
 
 The `NewChange.vm` template will determine the contents of the email related
 to a user submitting a new change for review. This includes changes created
@@ -95,14 +82,12 @@ by actions made by the user in the Web UI such as cherry picking a commit or
 reverting a change.  It is a `ChangeEmail`: see `ChangeSubject.vm` and
 `ChangeFooter.vm`.
 
-RegisterNewEmail.vm
+=== RegisterNewEmail.vm
-~~~~~~~~~~~~~~~~~~~
 
 The `RegisterNewEmail.vm` template will determine the contents of the email
 related to registering new email accounts.
 
-ReplacePatchSet.vm
+=== ReplacePatchSet.vm
-~~~~~~~~~~~~~~~~~~
 
 The `ReplacePatchSet.vm` template will determine the contents of the email
 related to a user submitting a new patchset for a change.  This includes
@@ -110,23 +95,20 @@ patchsets created by actions made by the user in the Web UI such as editing
 the commit message, cherry picking a commit, or rebasing a change.  It is a
 `ChangeEmail`: see `ChangeSubject.vm` and `ChangeFooter.vm`.
 
-Restored.vm
+=== Restored.vm
-~~~~~~~~~~~
 
 The `Restored.vm` template will determine the contents of the email related
 to a change being restored.  It is a `ChangeEmail`: see `ChangeSubject.vm` and
 `ChangeFooter.vm`.
 
-Reverted.vm
+=== Reverted.vm
-~~~~~~~~~~~
 
 The `Reverted.vm` template will determine the contents of the email related
 to a change being reverted.  It is a `ChangeEmail`: see `ChangeSubject.vm` and
 `ChangeFooter.vm`.
 
 
-Mail Variables and Methods
+== Mail Variables and Methods
---------------------------
 
 Mail templates can access and display objects currently made available to them
 via the velocity context.  While the base objects are documented here, it is
@@ -137,16 +119,14 @@ that writing templates for Gerrit emails is likely to require some basic
 knowledge of the class structure to be useful.  Browsing the source code might
 be necessary for anything more than a minor formatting change.
 
-Warning
+=== Warning
-~~~~~~~
 
 Be aware that modifying templates can cause them to fail to parse and therefore
 not send out the actual email, or worse, calling methods on the available
 objects could have internal side effects which would adversely affect the
 health of your Gerrit server and/or data.
 
-All OutgoingEmails
+=== All OutgoingEmails
-~~~~~~~~~~~~~~~~~~
 
 All outgoing emails have the following variables available to them:
 
@@ -165,8 +145,7 @@ $StringUtils::
 A reference to the Apache `StringUtils` class.  This can be very useful for
 formatting strings.
 
-Change Emails
+=== Change Emails
-~~~~~~~~~~~~~
 
 All change related emails have the following additional variables available to them:
 
@@ -203,8 +182,7 @@ $patchSetInfo::
 A reference to the current `PatchSetInfo`.
 
 
-See Also
+== See Also
---------
 
 * link:http://velocity.apache.org/[velocity]
 

Documentation/config-project-config.txt

@@ -1,5 +1,4 @@
-Gerrit Code Review - Project Configuration File Format
+= Gerrit Code Review - Project Configuration File Format
-======================================================
 
 This page explains the storage format of Gerrit's project configuration
 and access control models.
@@ -10,8 +9,7 @@ affected project.  Direct manipulation of these files is mainly
 relevant in an automation scenario of the access controls.
 
 
-The +refs/meta/config+ namespace
+== The +refs/meta/config+ namespace
---------------------------------
 
 The namespace contains three different files that play different
 roles in the permission model.  With read permission to that reference,
@@ -24,8 +22,7 @@ space if you'd like to use the possibility to automate permission updates.
 
 
 [[file-project_config]]
-The file +project.config+
+== The file +project.config+
--------------------------
 
 The +project.config+ file contains the link between groups and their
 permitted actions on reference patterns in this project and any projects
@@ -75,8 +72,7 @@ on a global level.  You can find examples of these
 
 
 [[project-section]]
-Project section
+=== Project section
-~~~~~~~~~~~~~~~
 
 The project section includes configuration of project settings.
 
@@ -86,8 +82,7 @@ These are the keys:
 
 
 [[receive-section]]
-Receive section
+=== Receive section
-~~~~~~~~~~~~~~~
 
 The receive section includes configuration of project-specific
 receive settings:
@@ -135,8 +130,7 @@ Default is zero.
 Common unit suffixes of k, m, or g are supported.
 
 [[submit-section]]
-Submit section
+=== Submit section
-~~~~~~~~~~~~~~
 
 The submit section includes configuration of project-specific
 submit settings:
@@ -152,8 +146,7 @@ Merge strategy
 
 
 [[access-section]]
-Access section
+=== Access section
-~~~~~~~~~~~~~~
 
 Each +access+ section includes a reference and access rights connected
 to groups.  Each group listed must exist in the link:#file-groups[+groups+ file].
@@ -164,8 +157,7 @@ documentation for a full list of available access rights.
 
 
 [[capability-section]]
-Capability section
+=== Capability section
-~~~~~~~~~~~~~~~~~~
 
 The +capability+ section only appears once, and only in the +All-Projects+
 repository.  It controls Gerrit administration capabilities that are configured
@@ -177,8 +169,7 @@ documentation for a full list of available capabilities.
 
 
 [[file-groups]]
-The file +groups+
+== The file +groups+
------------------
 
 Each group in this list is linked with its UUID so that renaming of
 groups is possible without having to rewrite every +groups+ file
@@ -209,8 +200,7 @@ link:cmd-ls-groups.html[the +ls-groups+ SSH command].
 
 
 [[file-rules_pl]]
-The file +rules.pl+
+== The file +rules.pl+
--------------------
 
 The +rules.pl+ files allows you to replace or amend the default Prolog
 rules that control e.g. what conditions need to be fulfilled for a

Documentation/config-reverseproxy.txt

@@ -1,8 +1,6 @@
-Gerrit Code Review - Reverse Proxy
+= Gerrit Code Review - Reverse Proxy
-==================================
 
-Description
+== Description
------------
 
 Gerrit can be configured to run behind a third-party web server.
 This allows the other web server to bind to the privileged port 80
@@ -10,8 +8,7 @@ This allows the other web server to bind to the privileged port 80
 from Java to optimized native C code.
 
 
-Gerrit Configuration
+== Gerrit Configuration
---------------------
 
 Ensure `'$site_path'/etc/gerrit.config` has the property
 link:config-gerrit.html#httpd.listenUrl[httpd.listenUrl] configured
@@ -25,8 +22,7 @@ during 'init'.
 ----
 
 
-Apache 2 Configuration
+== Apache 2 Configuration
-----------------------
 
 To run Gerrit behind an Apache server using 'mod_proxy', enable the
 necessary Apache2 modules:
@@ -62,8 +58,7 @@ or links will redirect to incorrect locations.
 The two options 'AllowEncodedSlashes On' and 'ProxyPass .. nocanon' are required
 since Gerrit 2.6.
 
-SSL
+=== SSL
-~~~
 
 To enable Apache to perform the SSL processing, use 'proxy-https://'
 in httpd.listenUrl within Gerrit's configuration file, and enable
@@ -83,8 +78,7 @@ See the Apache 'mod_ssl' documentation for more details on how to
 configure SSL within the server, like controlling how strong of an
 encryption algorithm is required.
 
-Troubleshooting
+=== Troubleshooting
-~~~~~~~~~~~~~~~
 
 If you are encountering 'Page Not Found' errors when opening the change
 screen, your Apache proxy is very likely decoding the passed URL.
@@ -93,8 +87,7 @@ Make sure to either use 'AllowEncodedSlashes On' together with
 'AllowEncodedSlashes NoDecode' set.
 
 
-Nginx Configuration
+== Nginx Configuration
--------------------
 
 To run Gerrit behind an Nginx server, use a server statement such
 as this one:
@@ -112,8 +105,7 @@ as this one:
 	}
 ----
 
-SSL
+=== SSL
-~~~
 
 To enable Nginx to perform the SSL processing, use 'proxy-https://'
 in httpd.listenUrl within Gerrit's configuration file, and enable
@@ -136,8 +128,7 @@ See the Nginx 'http ssl module' documentation for more details on
 how to configure SSL within the server, like controlling how strong
 of an encryption algorithm is required.
 
-Troubleshooting
+=== Troubleshooting
-~~~~~~~~~~~~~~~
 
 If you are encountering 'Page Not Found' errors when opening the change
 screen, your Nginx proxy is very likely decoding the passed URL.

Documentation/config-sso.txt

@@ -1,12 +1,10 @@
-Gerrit Code Review - Single Sign-On Security
+= Gerrit Code Review - Single Sign-On Security
-============================================
 
 Gerrit supports integration with some types of single sign-on
 security solutions, making it possible for end-users to setup
 and manage accounts, without administrator involvement.
 
-OpenID
+== OpenID
-------
 
 By default a new Gerrit installation relies upon OpenID to perform
 user authentication services.  To enable OpenID, the auth.type
@@ -50,8 +48,7 @@ To trust only Google Accounts:
   git config --file $site_path/etc/gerrit.config auth.trustedOpenID 'https://www.google.com/accounts/o8/id?id='
 ====
 
-Database Schema
+=== Database Schema
-~~~~~~~~~~~~~~~
 
 User identities obtained from OpenID providers are stored into the
 `account_external_ids` table.  Users may link more than one OpenID
@@ -61,8 +58,7 @@ in to Gerrit if they are frequently switching between different
 unique OpenID accounts.
 
 
-HTTP Basic/Digest Authentication
+== HTTP Basic/Digest Authentication
---------------------------------
 
 When using HTTP authentication, Gerrit assumes that the servlet
 container or the frontend web server has performed all user
@@ -107,8 +103,7 @@ authentication at the proper time:
   </Location>
 ====
 
-Database Schema
+=== Database Schema
-~~~~~~~~~~~~~~~
 
 User identities are stored in the `account_external_ids` table.
 The user string obtained from the authorization header has the prefix
@@ -117,8 +112,7 @@ if a username was "foo" then the external_id field would be populated
 with "gerrit:foo".
 
 
-Computer Associates Siteminder
+== Computer Associates Siteminder
-------------------------------
 
 Siteminder is a commercial single sign on solution marketed by
 Computer Associates.  It is very common in larger enterprise
@@ -167,8 +161,7 @@ Add the following to `$JETTY_HOME/etc/jetty.xml` under
 ====
 
 
-Database Schema
+=== Database Schema
-~~~~~~~~~~~~~~~
 
 User identities are stored in the `account_external_ids` table.
 The user string obtained from Siteminder (e.g. the value in the

Documentation/config-themes.txt

@@ -1,5 +1,4 @@
-Gerrit Code Review - Themes
+= Gerrit Code Review - Themes
-===========================
 
 Gerrit supports some customization of the HTML it sends to
 the browser, allowing organizations to alter the look and
@@ -15,8 +14,7 @@ only served from a single theme directory; if you want to modify or
 extend an inherited theme, you must copy it into the appropriate
 per-project directory.
 
-HTML Header/Footer
+== HTML Header/Footer
-------------------
 
 At startup Gerrit reads the following files (if they exist) and
 uses them to customize the HTML page it sends to clients:
@@ -44,8 +42,7 @@ typically a single `<div>` tag.  The server parses it as XML, and
 then inserts the root element into the host page.  If a file has
 more than one root level element, Gerrit will not start.
 
-Static Images
+== Static Images
--------------
 
 Static image files can also be served from `'$site_path'/static`,
 and may be referenced in `GerritSite{Header,Footer}.html`
@@ -58,8 +55,7 @@ being served from this location by enforcing the rule that file names
 cannot contain `/` or `\`.  (Client requests for `static/foo/bar`
 will result in 404 Not Found responses.)
 
-HTTP Caching
+== HTTP Caching
-------------
 
 The header, footer, and CSS files are inlined into the host page,
 which is always sent with a no-cache header.  Clients will see any
@@ -87,8 +83,7 @@ disk cache.  If the image needs to be modified, create a new file,
 `my_logo2.cache.png` and update the header (or footer) HTML to
 reference the new image path.
 
-Google Analytics Integration
+== Google Analytics Integration
-----------------------------
 
 To connect Gerrit to Google Analytics add the following to your
 `GerritSiteFooter.html`:

Documentation/config-validation.txt

@@ -1,12 +1,10 @@
-Gerrit Code Review - Commit Validation
+= Gerrit Code Review - Commit Validation
-======================================
 
 Gerrit supports link:dev-plugins.html[plugin-based] validation of
 commits.
 
 [[new-commit-validation]]
-New commit validation
+== New commit validation
----------------------
 
 
 Plugins implementing the `CommitValidationListener` interface can
@@ -24,8 +22,7 @@ Out of the box, Gerrit includes a plugin that checks the length of the
 subject and body lines of commit messages on uploaded commits.
 
 [[pre-merge-validation]]
-Pre-merge validation
+== Pre-merge validation
---------------------
 
 
 Plugins implementing the `MergeValidationListener` interface can

Documentation/database-setup.txt

@@ -1,12 +1,10 @@
 [[createdb]]
-Database Setup
+== Database Setup
---------------
 
 During the init phase of Gerrit you will need to specify which database to use.
 
 [[createdb_h2]]
-H2
+=== H2
-~~
 
 If you choose H2, Gerrit will automatically set up the embedded H2 database as
 backend so no set up or configuration is necessary.
@@ -21,8 +19,7 @@ and it's not possible to set up H2 in a load balanced/hotswap configuration.
 If this option interests you, you might want to consider link:install-quick.html[the quick guide].
 
 [[createdb_postgres]]
-PostgreSQL
+=== PostgreSQL
-~~~~~~~~~~
 
 This option is more complicated than the H2 option but is recommended
 for larger installations. It's the database backend with the largest userbase
@@ -41,8 +38,7 @@ Visit PostgreSQL's link:http://www.postgresql.org/docs/9.1/interactive/index.htm
 using PostgreSQL.
 
 [[createdb_mysql]]
-MySQL
+=== MySQL
-~~~~~
 
 This option is also more complicated than the H2 option. Just as with
 PostgreSQL it's also recommended for larger installations.
@@ -65,8 +61,7 @@ Visit MySQL's link:http://dev.mysql.com/doc/[documentation] for further
 information regarding using MySQL.
 
 [[createdb_oracle]]
-Oracle
+=== Oracle
-~~~~~~
 
 PostgreSQL or H2 is the recommended database for Gerrit Code Review.
 Oracle is supported for environments where running on an existing Oracle

Documentation/dev-buck.txt

@@ -1,9 +1,7 @@
-Gerrit Code Review - Building with Buck
+= Gerrit Code Review - Building with Buck
-=======================================
 
 
-Installation
+== Installation
-------------
 
 There is currently no binary distribution of Buck, so it has to be manually
 built and installed.  Apache Ant is required.  Currently only Linux and Mac
@@ -50,12 +48,10 @@ the script's header comments for installation instructions.
 
 
 [[eclipse]]
-Eclipse Integration
+== Eclipse Integration
--------------------
 
 
-Generating the Eclipse Project
+=== Generating the Eclipse Project
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Create the Eclipse project:
 
@@ -75,8 +71,7 @@ Filters on a folder, they will be overwritten the next time you run
 `tools/eclipse/project.py`.
 
 
-Refreshing the Classpath
+=== Refreshing the Classpath
-~~~~~~~~~~~~~~~~~~~~~~~~
 
 If an updated classpath is needed, the Eclipse project can be
 refreshed and missing dependency JARs can be downloaded:
@@ -86,8 +81,7 @@ refreshed and missing dependency JARs can be downloaded:
 ----
 
 
-Attaching Sources
+=== Attaching Sources
-~~~~~~~~~~~~~~~~~
 
 To save time and bandwidth source JARs are only downloaded by the buck
 build where necessary to compile Java source into JavaScript using the
@@ -100,12 +94,10 @@ show documentation or dive into the implementation of a library JAR:
 
 
 [[build]]
-Building on the Command Line
+== Building on the Command Line
-----------------------------
 
 
-Gerrit Development WAR File
+=== Gerrit Development WAR File
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To build the Gerrit web application:
 
@@ -120,8 +112,7 @@ The output executable WAR will be placed in:
 ----
 
 
-Extension and Plugin API JAR Files
+=== Extension and Plugin API JAR Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To build the extension, plugin and GWT API JAR files:
 
@@ -159,8 +150,7 @@ for the repository need to be
 link:dev-release-deploy-config.html#deploy-configuration-settings-xml[
 configured in Maven's settings.xml file].
 
-Plugins
+=== Plugins
-~~~~~~~
 
 To build all core plugins:
 
@@ -213,8 +203,7 @@ next time project.py is run:
 
 
 [[documentation]]
-Documentation
+=== Documentation
-~~~~~~~~~~~~~
 
 To build only the documentation:
 
@@ -247,8 +236,7 @@ The WAR file will be placed in:
 ----
 
 [[release]]
-Gerrit Release WAR File
+=== Gerrit Release WAR File
-~~~~~~~~~~~~~~~~~~~~~~~
 
 To build the release of the Gerrit web application, including documentation and
 all core plugins:
@@ -264,8 +252,7 @@ The output release WAR will be placed in:
 ----
 
 [[tests]]
-Running Unit Tests
+== Running Unit Tests
-------------------
 
 To run all tests including acceptance tests:
 
@@ -287,8 +274,7 @@ To run a specific test, e.g. the acceptance test
 ----
 
 
-Dependencies
+== Dependencies
-------------
 
 Dependency JARs are normally downloaded automatically, but Buck can inspect
 its graph and download any missing JAR files.  This is useful to enable
@@ -319,8 +305,7 @@ The `local.properties` file may be placed in the root of the gerrit repository
 being built, or in `~/.gerritcodereview/`.  The file in the root of the gerrit
 repository has precedence.
 
-Building against unpublished Maven JARs
+== Building against unpublished Maven JARs
----------------------------------------
 
 To build against unpublished Maven JARs, like gwtorm or PrologCafe, the custom
 JARs must be installed in the local Maven repository (`mvn clean install`) and
@@ -337,8 +322,7 @@ that artifact:
  )
 ----
 
-Building against artifacts from custom Maven repositories
+== Building against artifacts from custom Maven repositories
----------------------------------------------------------
 
 To build against custom Maven repositories, two modes of operations are
 supported: with rewrite in local.properties and without.
@@ -382,8 +366,7 @@ And corresponding BUCK excerpt:
  )
 ----
 
-Caching Build Results
+=== Caching Build Results
-~~~~~~~~~~~~~~~~~~~~~
 
 Build results can be locally cached, saving rebuild time when
 switching between Git branches. Buck's documentation covers
@@ -399,8 +382,7 @@ The trivial case using a local directory is:
 ----
 
 [[buck-daemon]]
-Using Buck daemon
+=== Using Buck daemon
-~~~~~~~~~~~~~~~~~
 
 Buck ships with a daemon command `buckd`, which uses the
 link:https://github.com/martylamb/nailgun[Nailgun] protocol for running
@@ -426,8 +408,7 @@ run `buck` as usual:
   [-] BUILDING...FINISHED 0.2s
 ----
 
-Override Buck's settings
+=== Override Buck's settings
-~~~~~~~~~~~~~~~~~~~~~~~~
 
 Additional JVM args for Buck can be set in `.buckjavaargs` in the
 project root directory. For example to override Buck's default 1GB

Documentation/dev-contributing.txt

@@ -1,5 +1,4 @@
-Gerrit Code Review - Contributing
+= Gerrit Code Review - Contributing
-=================================
 
 Gerrit is developed as a self-hosting open source project and
 very much welcomes contributions from anyone with a contributor's
@@ -44,8 +43,7 @@ haven't replied or made a fix, so it helps them know if you
 missed it or decided against it.
 
 
-Review Criteria
+== Review Criteria
----------------
 
 Here are some hints as to what approvers may be looking for
 before approving or submitting changes to the Gerrit project.
@@ -58,8 +56,7 @@ spans, we really do want your code.
 
 
 [[commit-message]]
-Commit Message
+== Commit Message
---------------
 
 It is essential to have a good commit message if you want your
 change to be reviewed.
@@ -74,8 +71,7 @@ change to be reviewed.
   * Include a Change-Id line
 
 
-A sample good Gerrit commit message:
+=== A sample good Gerrit commit message:
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ====
   Add sample commit message to guidelines doc
 
@@ -122,8 +118,7 @@ link:https://gerrit-review.googlesource.com/#/settings/http-password[HTTP
 Password tab of the user settings page].
 
 
-Style
+== Style
------
 
 The basic coding style is covered by the tools/GoogleFormat.xml
 doc, see the link:dev-eclipse.html#Formatting[Eclipse Setup]
@@ -157,8 +152,7 @@ examples:
     between internal ones.
 
 
-Code Organization
+== Code Organization
------------------
 
 Do your best to organize classes and methods in a logical way.
 Here are some guidelines that Gerrit uses:
@@ -191,8 +185,7 @@ Naturally new classes are a little harder; you may want to come
 back and consult this section when creating them.
 
 
-Design
+== Design
-------
 
 Here are some design level objectives that you should keep in mind
 when coding:
@@ -224,14 +217,12 @@ when coding:
   * ...and so is Guava (previously known as Google Collections).
 
 
-Tests
+== Tests
------
 
   * Tests for new code will greatly help your change get approved.
 
 
-Change Size/Number of Files Touched
+== Change Size/Number of Files Touched
------------------------------------
 
 And finally, I probably cannot say enough about change sizes.
 Generally, smaller is better, hopefully within reason.  Do try to
@@ -269,11 +260,9 @@ especially if changing one without the other will break something!
   * Use topic branches to link your separate changes together.
 
 [[process]]
-Process
+== Process
--------
 
-Backporting to stable branches
+=== Backporting to stable branches
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 From time to time bug fix releases are made for existing stable branches.
 

Documentation/dev-design.txt

@@ -1,8 +1,6 @@
-Gerrit Code Review - System Design
+= Gerrit Code Review - System Design
-==================================
 
-Objective
+== Objective
----------
 
 Gerrit is a web based code review system, facilitating online code
 reviews for projects using the Git version control system.
@@ -17,8 +15,7 @@ hand by the project maintainer.  This functionality enables a more
 centralized usage of Git.
 
 
-Background
+== Background
-----------
 
 Google developed Mondrian, a Perforce based code review tool to
 facilitate peer-review of changes prior to submission to the central
@@ -74,8 +71,7 @@ on a J2EE servlet container and an SQL database.
 * link:http://source.android.com/[Android Open Source Project]
 
 
-Overview
+== Overview
---------
 
 Developers create one or more changes on their local desktop system,
 then upload them for review to Gerrit using the standard `git push`
@@ -121,8 +117,7 @@ are maintained, the user pressing the submit button does not need
 to be the author of the change.
 
 
-Infrastructure
+== Infrastructure
---------------
 
 End-user web browsers make HTTP requests directly to Gerrit's
 HTTP server.  As nearly all of the user interface is implemented
@@ -184,8 +179,7 @@ has been migrated out of the database and into the git
 repositories for each project.
 
 
-Project Information
+== Project Information
--------------------
 
 Gerrit is developed as a self-hosting open source project:
 
@@ -196,8 +190,7 @@ Gerrit is developed as a self-hosting open source project:
 * link:https://review.source.android.com/[Change Review]
 
 
-Internationalization and Localization
+== Internationalization and Localization
--------------------------------------
 
 As a source code review system for open source projects, where the
 commonly preferred language for communication is typically English,
@@ -220,8 +213,7 @@ before translating the UI to an RTL language.
 * link:i18n-readme.html[Gerrit's i18n Support]
 
 
-Accessibility Considerations
+== Accessibility Considerations
-----------------------------
 
 Whenever possible Gerrit displays raw text rather than image icons,
 so screen readers should still be able to provide useful information
@@ -239,8 +231,7 @@ When possible, Gerrit uses the ARIA properties on DOM widgets to
 provide hints to screen readers.
 
 
-Browser Compatibility
+== Browser Compatibility
----------------------
 
 Supporting non-JavaScript enabled browsers is a non-goal for Gerrit.
 
@@ -281,8 +272,7 @@ Therefore the lack of support for most search engine spiders is a
 non-issue for most Gerrit deployments.
 
 
-Product Integration
+== Product Integration
--------------------
 
 Gerrit integrates with an existing gitweb installation by optionally
 creating hyperlinks to reference changes on the gitweb server.
@@ -328,8 +318,7 @@ Gerrit does not integrate with any Google service, or any other
 services other than those listed above.
 
 
-Standards / Developer APIs
+== Standards / Developer APIs
---------------------------
 
 Gerrit uses an XSRF protected variant of JSON-RPC 1.1 to communicate
 between the browser client and the server.
@@ -356,8 +345,7 @@ to be used with the JSON-RPC interface.
 * link:http://code.google.com/p/gerrit/source/browse/README?repo=gwtjsonrpc&name=master[XSRF JSON-RPC]
 
 
-Privacy Considerations
+== Privacy Considerations
-----------------------
 
 Gerrit stores the following information per user account:
 
@@ -409,8 +397,7 @@ really left to the discretion of the Gerrit site administrator as
 to when it is reasonable to reveal this information to a 3rd party.
 
 
-Spam and Abuse Considerations
+== Spam and Abuse Considerations
------------------------------
 
 Gerrit makes no attempt to detect spam changes or comments.  The
 somewhat high barrier to entry makes it unlikely that a spammer
@@ -441,8 +428,7 @@ These assumptions may need to be revisited in the future if any
 public Gerrit site actually notices spam.
 
 
-Latency
+== Latency
--------
 
 Gerrit targets for sub-250 ms per page request, mostly by using
 very compact JSON payloads between client and server.  However, as
@@ -451,8 +437,7 @@ database) is out of control of the Gerrit developers, no real
 guarantees can be made about latency.
 
 
-Scalability
+== Scalability
------------
 
 Gerrit is designed for a very large scale open source project, or
 large commercial development project.  Roughly this amounts to
@@ -477,8 +462,7 @@ to run closer to the estimated maximum if sufficient memory is made
 available to the JVM and the relevant cache.*.memoryLimit variables
 are increased from their defaults.
 
-Discussion
+=== Discussion
-~~~~~~~~~~
 
 Very few, if any open source projects have more than a handful of
 Git repositories associated with them.  Since Gerrit treats each
@@ -548,8 +532,7 @@ less than 10 files modified in any single change. Changes larger than
 version of an upstream library, where the reviewer has little to do
 beyond verifying the project compiles and passes a test suite.
 
-CPU Usage - Web UI
+=== CPU Usage - Web UI
-~~~~~~~~~~~~~~~~~~
 
 Gerrit's web UI would require on average `4+F+F*C` HTTP requests to
 review a change and post comments.  Here `F` is the number of files
@@ -581,8 +564,7 @@ Given a more realistic estimate of 79 changes per day (from the
 Linux kernel) suggests only 8,532 queries per day, and a much lower
 0.29 QPS when spread out over an 8 hour work day.
 
-CPU Usage - Git over SSH/HTTP
+=== CPU Usage - Git over SSH/HTTP
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A 24 core server is able to handle ~25 concurrent `git fetch`
 operations per second. The issue here is each concurrent operation
@@ -609,8 +591,7 @@ If the server's own network interface is 1 Gib/sec (Gigabit Ethernet),
 the system can really only serve about 10 concurrent clients at the
 10 MiB/sec speed, no matter how many cores it has.
 
-Disk Usage
+=== Disk Usage
-~~~~~~~~~~
 
 The average size of a revision in the Linux kernel once compressed by
 Git is 2,327 bytes, or roughly 2 KiB.  Over the course of a year a
@@ -630,8 +611,7 @@ clients from needing to clone unnecessary materials (for example a C
 developer does not need every 800+ megabyte firmware image created by
 the product's quality assurance team).
 
-Redundancy & Reliability
+== Redundancy & Reliability
-------------------------
 
 Gerrit largely assumes that the local filesystem where Git repository
 data is stored is always available.  Important data written to disk
@@ -666,8 +646,7 @@ of time on the Gerrit site anyway in order to ensure any interested
 parties around the world have had a chance to comment.  This expected
 lag largely allows for some downtime in a disaster scenario.
 
-Backups
+=== Backups
-~~~~~~~
 
 PostgreSQL and MySQL can be configured to replicate their data to
 other systems, where they are applied to a warm-standby backup in
@@ -683,8 +662,7 @@ to send copies of all changes over SSH to other servers, or to the
 Amazon S3 blob storage service.
 
 
-Logging Plan
+== Logging Plan
-------------
 
 Gerrit does not maintain logs on its own.
 
@@ -711,8 +689,7 @@ logs may be mined for usage information.  This is outside of the
 scope of Gerrit.
 
 
-Testing Plan
+== Testing Plan
-------------
 
 Gerrit is currently manually tested through its web UI.
 
@@ -721,8 +698,7 @@ changes to JGit are rejected unless corresponding automated unit
 tests are included.
 
 
-Caveats
+== Caveats
--------
 
 Rietveld can't be used as it does not provide the "submit over the
 web" feature that Gerrit provides for Git.

Documentation/dev-eclipse.txt

@@ -1,5 +1,4 @@
-Gerrit Code Review - Eclipse Setup
+= Gerrit Code Review - Eclipse Setup
-==================================
 
 This document is about configuring Gerrit Code Review into an
 Eclipse workspace for development and debugging with GWT.
@@ -9,8 +8,7 @@ runtime debugging environment.
 
 
 [[Formatting]]
-Code Formatter Settings
+== Code Formatter Settings
------------------------
 
 Import `tools/GoogleFormat.xml` using Window -> Preferences ->
 Java -> Code Style -> Formatter -> Import...
@@ -19,8 +17,7 @@ This will define the 'Google Format' profile, which the project
 settings prefer when formatting source code.
 
 
-Site Initialization
+== Site Initialization
--------------------
 
 Build once on the command line with
 link:dev-buck.html#build[Buck] and then follow
@@ -28,11 +25,9 @@ link:dev-readme.html#init[Site Initialization] in the
 Developer Setup guide to configure a local site for testing.
 
 
-Testing
+== Testing
--------
 
-Running the Daemon
+=== Running the Daemon
-~~~~~~~~~~~~~~~~~~
 
 Duplicate the existing launch configuration:
 
@@ -52,8 +47,7 @@ Duplicate the existing launch configuration:
 * Close the Debug Configurations dialog and save the changes when prompted.
 
 
-Running Hosted Mode
+=== Running Hosted Mode
-~~~~~~~~~~~~~~~~~~~
 
 Duplicate the existing launch configuration:
 
@@ -74,8 +68,7 @@ Duplicate the existing launch configuration:
 
 
 [[known-problems]]
-Known problems
+== Known problems
---------------
 
 * OpenID authentication won't work in hosted mode, so you need to change
 the link:config-gerrit.html#auth.type[auth.type] configuration parameter

Documentation/dev-inspector.txt

@@ -1,12 +1,9 @@
-Gerrit Inspector
+= Gerrit Inspector
-================
 
-NAME
+== NAME
-----
 Gerrit Inspector - Interactive Jython environment for Gerrit
 
-SYNOPSIS
+== SYNOPSIS
---------
 --
 'java' -jar gerrit.war 'daemon'
 	-d <SITE_PATH>
@@ -17,8 +14,7 @@ SYNOPSIS
 	-s
 --
 
-DESCRIPTION
+== DESCRIPTION
------------
 Runs the Gerrit network daemon on the local system as described
 in the link:pgm-daemon.html[Daemon documentation], additionally
 starting an interactive Jython shell for inspection
@@ -32,8 +28,7 @@ to introduce changes to the internal state of the system in
 an inconsistent way. Care must be taken not to break the running system
 and/or destroy the data.
 
-INSTALLATION
+== INSTALLATION
-------------
 
 Gerrit Inspector requires Jython library ('jython.jar') to be installed
 in the '$site_path/lib' directory. Jython, a Python interpreter for
@@ -42,8 +37,7 @@ website. Only 'jython.jar' file is needed, installation of Jython libraries
 is optional. Gerrit Inspector has been tested with Jython 2.5.2 but
 might work an earlier version.
 
-STARTUP
+== STARTUP
--------
 
 During startup Jython examines Java libraries found on the classpath.
 While libraries are inspected a large amount of messages is displayed on the console:
@@ -77,8 +71,7 @@ the interactive interpreter.
 When interactive interpreter exits (by issuing EOF on the command line),
 a whole Gerrit instance is shut down gracefully.
 
-USING THE INTERPRETER
+== USING THE INTERPRETER
----------------------
 
 Gerrit Inspector launches Jython interpreter in the context of the Gerrit
 Java Virtual Machine. All core facilities of the Jython (and Python)
@@ -219,8 +212,7 @@ And Gerrit should shut down all its subsystems and exit:
 [2012-04-17 15:31:08,458] INFO  com.google.gerrit.pgm.Daemon : caught shutdown, cleaning up
 ----
 
-TROUBLESHOOTING
+== TROUBLESHOOTING
----------------
 
 Gerrit Inspector is logging to the Gerrit error log.
 
@@ -281,16 +273,14 @@ by issuing the following command in the Gerrit Inspector console:
 Shell.reload()
 ----
 
-LOGGING
+== LOGGING
--------
 Error and warning messages from the server are automatically written
 to the log file under '$site_path/logs/error_log'.
 
 Output and error messages (including Java and Python exceptions)
 resulting from interactive work are logged to the console.
 
-KNOWN ISSUES
+== KNOWN ISSUES
-------------
 The Inspector does not yet recognize Google Guice bindings.
 
 IMPORTANT: Using the Inspector may void your warranty.

Documentation/dev-plugins.txt

@@ -1,5 +1,4 @@
-Gerrit Code Review - Plugin Development
+= Gerrit Code Review - Plugin Development
-=======================================
 
 The Gerrit server functionality can be extended by installing plugins.
 This page describes how plugins for Gerrit can be developed.
@@ -24,8 +23,7 @@ of server versions.
 Most of this documentation refers to either type as a plugin.
 
 [[getting-started]]
-Getting started
+== Getting started
----------------
 
 To get started with the development of a plugin there are two
 recommended ways:
@@ -66,8 +64,7 @@ Gerrit version (no `SNAPSHOT` version) then the URL for the
 `https://gerrit-api.storage.googleapis.com/release/`.
 
 [[API]]
-API
+== API
----
 
 There are two different API formats offered against which plugins can
 be developed:
@@ -88,8 +85,7 @@ gerrit-plugin-api.jar::
   that compiles against 2.5 will probably need source code level
   changes to work with 2.6, 2.7, and so on.
 
-Manifest
+== Manifest
---------
 
 Plugins may provide optional description information with standard
 manifest fields:
@@ -101,8 +97,7 @@ manifest fields:
   Implementation-URL: http://example.com/opensource/plugin-foo/
 ====
 
-ApiType
+=== ApiType
-~~~~~~~
 
 Plugins using the tightly coupled `gerrit-plugin-api.jar` must
 declare this API dependency in the manifest to gain access to server
@@ -114,8 +109,7 @@ loading a plugin that needs the plugin API.
   Gerrit-ApiType: plugin
 ====
 
-Explicit Registration
+=== Explicit Registration
-~~~~~~~~~~~~~~~~~~~~~
 
 Plugins that use explicit Guice registration must name the Guice
 modules in the manifest. Up to three modules can be named in the
@@ -133,8 +127,7 @@ will be performed by scanning all classes in the plugin JAR for
 ====
 
 [[plugin_name]]
-Plugin Name
+=== Plugin Name
-~~~~~~~~~~~
 
 A plugin can optionally provide its own plugin name.
 
@@ -215,8 +208,7 @@ The canonical web URL may be injected into any .jar plugin regardless of
 whether or not the plugin provides an HTTP servlet.
 
 [[reload_method]]
-Reload Method
+=== Reload Method
-~~~~~~~~~~~~~
 
 If a plugin holds an exclusive resource that must be released before
 loading the plugin again (for example listening on a network port or
@@ -258,8 +250,7 @@ To reload/restart a plugin the link:cmd-plugin-reload.html[plugin reload]
 command can be used.
 
 [[init_step]]
-Init step
+=== Init step
-~~~~~~~~~
 
 Plugins can contribute their own "init step" during the Gerrit init
 wizard. This is useful for guiding the Gerrit administrator through
@@ -358,8 +349,7 @@ public class MyInitStep implements InitStep {
 ----
 
 [[classpath]]
-Classpath
+== Classpath
----------
 
 Each plugin is loaded into its own ClassLoader, isolating plugins
 from each other. A plugin or extension inherits the Java runtime
@@ -374,8 +364,7 @@ to package additional dependencies. Relocating (or renaming) classes
 should not be necessary due to the ClassLoader isolation.
 
 [[events]]
-Listening to Events
+== Listening to Events
--------------------
 
 Certain operations in Gerrit trigger events. Plugins may receive
 notifications of these events by implementing the corresponding
@@ -404,8 +393,7 @@ Project deletion
 Update of HEAD on a project
 
 [[stream-events]]
-Sending Events to the Events Stream
+== Sending Events to the Events Stream
------------------------------------
 
 Plugins may send events to the events stream where consumers of
 Gerrit's `stream-events` ssh command will receive them.
@@ -415,8 +403,7 @@ methods in the `ChangeHookRunner` class, passing an instance of
 its own custom event class derived from `ChangeEvent`.
 
 [[ssh]]
-SSH Commands
+== SSH Commands
-------------
 
 Plugins may provide commands that can be accessed through the SSH
 interface (extensions do not have this option).
@@ -537,8 +524,7 @@ $ ssh -p 29418 review.example.com sh ps
 ----
 
 [[simple-configuration]]
-Simple Configuration in `gerrit.config`
+== Simple Configuration in `gerrit.config`
----------------------------------------
 
 In Gerrit, global configuration is stored in the `gerrit.config` file.
 If a plugin needs global configuration, this configuration should be
@@ -581,8 +567,7 @@ String language = cfg.getFromGerritConfig("helloworld")
 ----
 
 [[configuration]]
-Configuration in own config file
+== Configuration in own config file
---------------------------------
 
 Plugins can store their configuration in an own configuration file.
 This makes sense if the plugin configuration is rather complex and
@@ -624,8 +609,7 @@ Similar to changes in 'gerrit.config', changes to the plugin
 configuration file will only become effective after a Gerrit restart.
 
 [[simple-project-specific-configuration]]
-Simple Project Specific Configuration in `project.config`
+== Simple Project Specific Configuration in `project.config`
----------------------------------------------------------
 
 In Gerrit, project specific configuration is stored in the project's
 `project.config` file on the `refs/meta/config` branch.  If a plugin
@@ -688,8 +672,7 @@ Project owners can edit the project configuration by fetching the
 pushing the commit back.
 
 [[project-specific-configuration]]
-Project Specific Configuration in own config file
+== Project Specific Configuration in own config file
--------------------------------------------------
 
 Plugins can store their project specific configuration in an own
 configuration file in the projects `refs/meta/config` branch.
@@ -744,8 +727,7 @@ Project owners can edit the project configuration by fetching the
 `refs/meta/config` branch, editing the `<plugin-name>.config` file and
 pushing the commit back.
 
-React on changes in project configuration
+== React on changes in project configuration
------------------------------------------
 
 If a plugin wants to react on changes in the project configuration, it
 can implement a `GitReferenceUpdatedListener` and filter on events for
@@ -789,8 +771,7 @@ public class MyListener implements GitReferenceUpdatedListener {
 
 
 [[capabilities]]
-Plugin Owned Capabilities
+== Plugin Owned Capabilities
--------------------------
 
 Plugins may provide their own capabilities and restrict usage of SSH
 commands to the users who are granted those capabilities.
@@ -879,8 +860,7 @@ this can be specified by setting `scope = CapabilityScope.CORE`:
 ----
 
 [[ui_extension]]
-UI Extension
+== UI Extension
-------------
 
 Plugins can contribute UI actions on core Gerrit pages. This is useful
 for workflow customization or exposing plugin functionality through the
@@ -1148,8 +1128,7 @@ Gerrit.install(function(self) {
 ----
 
 [[top-menu-extensions]]
-Top Menu Extensions
+== Top Menu Extensions
--------------------
 
 Plugins can contribute items to Gerrit's top menu.
 
@@ -1266,8 +1245,7 @@ public class MyTopMenuExtension implements TopMenu {
 ----
 
 [[gwt_ui_extension]]
-GWT UI Extension
+== GWT UI Extension
-----------------
 Plugins can extend the Gerrit UI with own GWT code.
 
 The Maven archetype 'gerrit-plugin-gwt-archetype' can be used to
@@ -1521,8 +1499,7 @@ In order to be able to do REST calls the GWT module must inherit
 ----
 
 [[http]]
-HTTP Servlets
+== HTTP Servlets
--------------
 
 Plugins or extensions may register additional HTTP servlets, and
 wrap them with HTTP filters.
@@ -1572,8 +1549,7 @@ $ curl http://review.example.com/plugins/helloworld/print
 ----
 
 [[data-directory]]
-Data Directory
+== Data Directory
---------------
 
 Plugins can request a data directory with a `@PluginData` File
 dependency. A data directory will be created automatically by the
@@ -1590,8 +1566,7 @@ MyType(@PluginData java.io.File myDir) {
 ----
 
 [[download-commands]]
-Download Commands
+== Download Commands
------------------
 
 Gerrit offers commands for downloading changes using different
 download schemes (e.g. for downloading via different network
@@ -1604,8 +1579,7 @@ The download schemes and download commands which are used most often
 are provided by the Gerrit core plugin `download-commands`.
 
 [[documentation]]
-Documentation
+== Documentation
--------------
 
 If a plugin does not register a filter or servlet to handle URLs
 `/Documentation/*` or `/static/*`, the core Gerrit server will
@@ -1648,8 +1622,7 @@ Macros that start with `\` such as `\@KEEP@` will render as `@KEEP@`
 even if there is an expansion for `KEEP` in the future.
 
 [[auto-index]]
-Automatic Index
+=== Automatic Index
-~~~~~~~~~~~~~~~
 
 If a plugin does not handle its `/` URL itself, Gerrit will
 redirect clients to the plugin's `/Documentation/index.html`.
@@ -1701,8 +1674,7 @@ displayed as part of the index page, if present in the manifest:
 |===================================================
 
 [[deployment]]
-Deployment
+== Deployment
-----------
 
 Compiled plugins and extensions can be deployed to a running Gerrit
 server using the link:cmd-plugin-install.html[plugin install] command.
@@ -1724,8 +1696,7 @@ command can be used.
 Disabled plugins can be re-enabled using the
 link:cmd-plugin-enable.html[plugin enable] command.
 
-SEE ALSO
+== SEE ALSO
---------
 
 * link:js-api.html[JavaScript API]
 * link:dev-rest-api.html[REST API Developers' Notes]

Documentation/dev-readme.txt

@@ -1,13 +1,11 @@
-Gerrit Code Review - Developer Setup
+= Gerrit Code Review - Developer Setup
-====================================
 
 Facebook Buck is needed to compile the code, and an SQL database to
 house the review metadata.  H2 is recommended for development
 databases, as it requires no external server process.
 
 
-Getting the Source
+== Getting the Source
-------------------
 
 Create a new client workspace:
 
@@ -21,15 +19,13 @@ the core plugins, which are included as git submodules, are also
 cloned.
 
 
-Compiling
+== Compiling
----------
 
 For details on how to build the source code with Buck, refer to:
 link:dev-buck.html#build[Building on the command line with Buck].
 
 
-Switching between branches
+== Switching between branches
---------------------------
 
 When switching between branches with `git checkout`, be aware that
 submodule revisions are not altered.  This may result in the wrong
@@ -45,8 +41,7 @@ revisions for the new branch with the commands:
 ----
 
 
-Configuring Eclipse
+== Configuring Eclipse
--------------------
 
 To use the Eclipse IDE for development, please see
 link:dev-eclipse.html[Eclipse Setup].
@@ -55,8 +50,7 @@ For details on how to configure the Eclipse workspace with Buck,
 refer to: link:dev-buck.html#eclipse[Eclipse integration with Buck].
 
 
-Mac OS X
+== Mac OS X
---------
 
 On Mac OS X ensure "Java For Mac OS X 10.5 Upate 4" (or later) has
 been installed, and that `JAVA_HOME` is set to
@@ -67,8 +61,7 @@ version crash during the build due to a bug in the JIT compiler.
 
 
 [[init]]
-Site Initialization
+== Site Initialization
--------------------
 
 After compiling (above), run Gerrit's 'init' command to create a
 testing site for development use:
@@ -93,13 +86,11 @@ through the web interface:
 ----
 
 
-Testing
+== Testing
--------
 
 
 [[tests]]
-Running the Acceptance Tests
+=== Running the Acceptance Tests
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Gerrit has a set of integration tests that test the Gerrit daemon via
 REST, SSH and the git protocol.
@@ -113,8 +104,7 @@ please refer to:
 link:dev-buck.html#tests[Running integration tests with Buck].
 
 
-Running the Daemon
+=== Running the Daemon
-~~~~~~~~~~~~~~~~~~
 
 The daemon can be directly launched from the build area, without
 copying to the test site:
@@ -123,8 +113,7 @@ copying to the test site:
   java -jar buck-out/gen/gerrit.war daemon -d ../gerrit_testsite
 ----
 
-Running the Daemon with Gerrit Inspector
+=== Running the Daemon with Gerrit Inspector
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 link:dev-inspector.html[Gerrit Inspector] is an interactive scriptable
 environment to inspect and modify internal state of the system.
@@ -161,8 +150,7 @@ interfaces (HTTP, SSH etc.) are available.
 Care must be taken not to modify internal state of the system
 when using the Inspector.
 
-Querying the Database
+=== Querying the Database
-~~~~~~~~~~~~~~~~~~~~~
 
 The embedded H2 database can be queried and updated from the
 command line.  If the daemon is not currently running:
@@ -180,8 +168,7 @@ using an administrator user account:
 
 
 [[debug-javascript]]
-Debugging JavaScript
+=== Debugging JavaScript
-~~~~~~~~~~~~~~~~~~~~
 
 When debugging browser specific issues add `?dbg=1` to the URL so the
 resulting JavaScript more closely matches the Java sources.  The debug
@@ -200,8 +187,7 @@ To use the GWT DETAILED style the package must be recompiled and
 ----
 
 
-Release Builds
+== Release Builds
---------------
 
 To create a release build for a production server, or deployment
 through the download site:
@@ -219,8 +205,7 @@ an additional flag:
 ----
 
 
-Client-Server RPC
+== Client-Server RPC
------------------
 
 The client-server RPC implementation is gwtjsonrpc, not the stock RPC
 system that comes with GWT.  This buys us automatic XSRF protection.
@@ -231,15 +216,13 @@ The programming API is virtually identical, except service interfaces
 extend RemoteJsonService instead of RemoteService.
 
 
-Why GWT?
+== Why GWT?
---------
 
 We like it.  Plus we can write Java code once and run it both in
 the browser and on the server side.
 
 
-External Links
+== External Links
---------------
 
 Google Web Toolkit:
 

Documentation/dev-release-deploy-config.txt

@@ -1,5 +1,4 @@
-Deploy Gerrit Artifacts
+= Deploy Gerrit Artifacts
-=======================
 
 Gerrit Artifacts are stored on
 link:https://developers.google.com/storage/[Google Cloud Storage].
@@ -17,8 +16,7 @@ Jar.
 Bucket to store Gerrit Subproject Artifacts (e.g. `gwtjsonrpc` etc.).
 
 [[deploy-configuration-settings-xml]]
-Deploy Configuration in Maven `settings.xml`
+== Deploy Configuration in Maven `settings.xml`
---------------------------------------------
 
 To upload artifacts to a bucket the user must authenticate with a
 username and password. The username and password need to be retrieved
@@ -58,8 +56,7 @@ configured in the `~/.m2/settings.xml` file.
 ----
 
 [[deploy-configuration-subprojects]]
-Gerrit Subprojects
+=== Gerrit Subprojects
-~~~~~~~~~~~~~~~~~~
 
 * You will need to have the following in the `pom.xml` to make it
 deployable to the `gerrit-maven` storage bucket:

Documentation/dev-release-subproject.txt

@@ -1,9 +1,7 @@
-Making a Release of a Gerrit Subproject
+= Making a Release of a Gerrit Subproject
-=======================================
 
 [[make-snapshot]]
-Make a Snapshot
+== Make a Snapshot
----------------
 
 * Build the latest snapshot and install it into the local Maven
 repository:
@@ -15,8 +13,7 @@ repository:
 * Test Gerrit with this snapshot locally
 
 
-Publish Snapshot
+== Publish Snapshot
-----------------
 
 If a snapshot for a subproject was created that should be referenced by
 Gerrit while current Gerrit development is ongoing, this snapshot needs
@@ -42,8 +39,7 @@ and Gerrit has to reference the released subproject version.
 
 
 [[prepare-release]]
-Prepare the Release
+== Prepare the Release
--------------------
 
 * link:#make-snapshot[First create (and test) the latest snapshot for
 the subproject]
@@ -66,8 +62,7 @@ below)
 
 
 [[publish-release]]
-Publish the Release
+== Publish the Release
--------------------
 
 * Make sure you have done the configuration needed for deployment:
 ** link:dev-release-deploy-config.html#deploy-configuration-settings-xml[

Documentation/dev-release.txt

@@ -1,5 +1,4 @@
-Making a Gerrit Release
+= Making a Gerrit Release
-=======================
 
 [NOTE]
 ========================================================================
@@ -16,16 +15,14 @@ and as a checklist for those already familiar with these
 tasks.
 
 
-Gerrit Release Type
+== Gerrit Release Type
--------------------
 
 Here are some guidelines on release approaches depending on the
 type of release you want to make (`stable-fix`, `stable`, `RC0`,
 `RC1`...).
 
 [[stable]]
-Stable
+=== Stable
-~~~~~~
 
 A `stable` release is generally built from the `master` branch and may
 need to undergo some stabilization before releasing the final release.
@@ -51,8 +48,7 @@ There should be no new features in this release, only bug fixes
 * Finally create the `stable` release (no `RC`)
 
 
-Stable-Fix
+=== Stable-Fix
-~~~~~~~~~~
 
 `stable-fix` releases should likely only contain bug fixes and doc
 updates.
@@ -64,8 +60,7 @@ objectives are met
 
 
 [[security]]
-Security-Fix
+=== Security-Fix
-~~~~~~~~~~~~
 
 `security-fix` releases should only contain bug fixes for security
 issues.
@@ -82,8 +77,7 @@ the `gerrit-security-fixes` project be taken over into the public
 `gerrit` project.
 
 
-Create the Actual Release
+== Create the Actual Release
--------------------------
 
 To create a Gerrit release the following steps have to be done:
 
@@ -102,8 +96,7 @@ To create a Gerrit release the following steps have to be done:
 
 
 [[subproject]]
-Release Subprojects
+=== Release Subprojects
-~~~~~~~~~~~~~~~~~~~
 
 The subprojects to be released are:
 
@@ -128,8 +121,7 @@ for the Subproject in `/lib/BUCK` to the released version.
 
 
 [[build-gerrit]]
-Build Gerrit
+=== Build Gerrit
-~~~~~~~~~~~~
 
 * Build the Gerrit WAR and API JARs
 +
@@ -142,13 +134,11 @@ Build Gerrit
 * Test the new Gerrit version
 
 [[publish-gerrit]]
-Publish the Gerrit Release
+=== Publish the Gerrit Release
-~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 
 [[extension-and-plugin-api]]
-Publish the Extension and Plugin API Jars
+==== Publish the Extension and Plugin API Jars
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 * Make sure you have done the
 link:dev-release-deploy-config.html#deploy-configuration-settings-xml[
@@ -162,16 +152,14 @@ configuration needed for deployment]
 
 
 [[publish-gerrit-war]]
-Publish the Gerrit WAR (with Core Plugins)
+==== Publish the Gerrit WAR (with Core Plugins)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 * The WAR file to upload is `buck-out/gen/release.war`
 * Upload WAR to the storage bucket via `https://cloud.google.com/console` (manual via web browser)
 
 
 [[push-stable]]
-Push the Stable Branch
+==== Push the Stable Branch
-^^^^^^^^^^^^^^^^^^^^^^
 
 * create the stable branch `stable-2.5` in the `gerrit` project
 +
@@ -183,8 +171,7 @@ get them merged
 
 
 [[push-tag]]
-Push the Release Tag
+==== Push the Release Tag
-^^^^^^^^^^^^^^^^^^^^
 
 * Push the new Release Tag
 +
@@ -202,8 +189,7 @@ For a final `stable` release:
 
 
 [[upload-documentation]]
-Upload the Documentation
+==== Upload the Documentation
-^^^^^^^^^^^^^^^^^^^^^^^^
 
 Build the release notes:
 
@@ -221,8 +207,7 @@ Description text, and in the `Links` section.
 Description text
 
 [[update-issues]]
-Update the Issues
+==== Update the Issues
-^^^^^^^^^^^^^^^^^
 
 ====
  How do the issues get updated?  Do you run a script to do
@@ -242,8 +227,7 @@ because `Status=Submitted` is considered a closed issue.
 
 
 [[announce]]
-Announce on Mailing List
+==== Announce on Mailing List
-^^^^^^^^^^^^^^^^^^^^^^^^
 
 * Send an email to the mailing list to announce the release, consider
 including some or all of the following in the email:
@@ -295,8 +279,7 @@ To read more about the bug fixes:
 
 
 [[increase-version]]
-Increase Gerrit Version for Current Development
+=== Increase Gerrit Version for Current Development
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 All new development that is done in the `master` branch will be
 included in the next Gerrit release. Update the Gerrit version in the
@@ -305,8 +288,7 @@ for review and get it merged.
 
 
 [[merge-stable]]
-Merge `stable` into `master`
+=== Merge `stable` into `master`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 After every release, stable should be merged to master to ensure that
 none of the changes/fixes ever get lost.

Documentation/dev-rest-api.txt

@@ -1,17 +1,14 @@
-Gerrit Code Review - REST API Developers' Notes
+= Gerrit Code Review - REST API Developers' Notes
-===============================================
 
 This document is about developing the REST API.  For details of the
 actual APIs available in Gerrit, please see the
 link:rest-api.html[REST API interface reference].
 
 
-Testing REST API Functionality
+== Testing REST API Functionality
-------------------------------
 
 
-Basic Testing
+=== Basic Testing
-~~~~~~~~~~~~~
 
 Basic testing of REST API functionality can be done with `curl`:
 
@@ -29,8 +26,7 @@ or `DELETE`, an additional argument is required:
 ----
 
 
-Sending Data in the Request
+=== Sending Data in the Request
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Some REST APIs accept data in the request body of `PUT` and `POST` requests.
 
@@ -49,8 +45,7 @@ option instead:
 ----
 
 
-Authentication
+=== Authentication
-~~~~~~~~~~~~~~
 
 To test APIs that require authentication, the username and password must be specified on
 the command line:
@@ -71,8 +66,7 @@ file (on Windows, `_netrc`):
 In both cases, the password should be the user's link:user-upload.html#http[HTTP password].
 
 
-Verifying Header Content
+=== Verifying Header Content
-~~~~~~~~~~~~~~~~~~~~~~~~
 
 To verify the headers returned from a REST API call, use `curl` in verbose mode:
 

Documentation/error-branch-not-found.txt

@@ -1,5 +1,4 @@
-branch ... not found
+= branch ... not found
-====================
 
 With this error message Gerrit rejects to push a commit for code
 review if the specified target branch does not exist.

Documentation/error-change-closed.txt

@@ -1,11 +1,9 @@
-change ... closed
+= change ... closed
-=================
 
 With this error message Gerrit rejects to push a commit or submit a
 review label (approval) to a change that is already closed.
 
-When Pushing a Commit
+== When Pushing a Commit
----------------------
 
 This error occurs if you are trying to push a commit that contains
 the Change-Id of a closed change in its commit message. A change can
@@ -27,8 +25,7 @@ this change you may want to restore the change in the Gerrit WebUI
 'Restore Change' button). Afterwards the push should succeed and a
 new patch set for this change will be created.
 
-When Submitting a Review Label
+== When Submitting a Review Label
-------------------------------
 
 This error occurs if you are trying to submit a review label (approval) using
 the link:cmd-review.html[ssh review command] after the change has been closed.

Documentation/error-change-does-not-belong-to-project.txt

@@ -1,5 +1,4 @@
-change ... does not belong to project ...
+= change ... does not belong to project ...
-=========================================
 
 With this error message Gerrit rejects to push a commit to a change
 that belongs to another project.

Documentation/error-change-not-found.txt

@@ -1,5 +1,4 @@
-change ... not found
+= change ... not found
-====================
 
 With this error message Gerrit rejects to push a commit to a change
 that cannot be found.

Documentation/error-change-upload-blocked.txt

@@ -1,5 +1,4 @@
-One or more refs/for/ names blocks change upload
+= One or more refs/for/ names blocks change upload
-================================================
 
 With this error message Gerrit rejects to push a commit for code
 review if the remote git repository has a branch under the

Documentation/error-commit-already-exists.txt

@@ -1,5 +1,4 @@
-commit already exists
+= commit already exists
-=====================
 
 With this error message Gerrit rejects to push a commit to an
 existing change via `refs/changes/n` if the commit was already

Documentation/error-contains-banned-commit.txt

@@ -1,5 +1,4 @@
-contains banned commit ...
+= contains banned commit ...
-==========================
 
 With this error message Gerrit rejects to push a commit that is
 banned or that would merge in an ancestor that is banned.

Documentation/error-has-duplicates.txt

@@ -1,5 +1,4 @@
-\... has duplicates
+= \... has duplicates
-===================
 
 With this error message Gerrit rejects to push a commit if its commit
 message contains a Change-ID for which multiple changes can be found

Documentation/error-invalid-author.txt

@@ -1,5 +1,4 @@
-invalid author
+= invalid author
-==============
 
 For every pushed commit Gerrit verifies that the e-mail address of
 the author matches one of the registered e-mail addresses of the
@@ -14,8 +13,7 @@ This error may happen for two reasons:
 . missing privileges to push commits of other authors
 
 
-Incorrect configuration of the e-mail address on client or server side
+== Incorrect configuration of the e-mail address on client or server side
-----------------------------------------------------------------------
 
 If pushing to Gerrit fails with the error message "invalid author"
 and you are the author of the commit for which the push
@@ -23,8 +21,7 @@ fails, then either you have not successfully registered this e-mail
 address for your Gerrit account or the author information of the
 pushed commit is incorrect.
 
-Configuration of e-mail address in Gerrit
+=== Configuration of e-mail address in Gerrit
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Check in Gerrit under 'Settings -> Identities' which e-mail addresses
 you've configured for your Gerrit account.  If no e-mail address is
@@ -34,8 +31,7 @@ clicking on the link in the e-mail verification mail sent by Gerrit.
 If you don't receive the e-mail verification mail it might be that it
 was caught by your spam filter.
 
-Incorrect author information
+=== Incorrect author information
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 For every commit Git maintains the author. If not explicitly
 specified Git computes the author on commit out of the Git
@@ -128,8 +124,7 @@ For further details about git rebase please check the
 link:http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html[Git documentation].
 
 
-Missing privileges to push commits of other users
+== Missing privileges to push commits of other users
--------------------------------------------------
 
 If pushing to Gerrit fails with the error message "invalid author"
 and somebody else is author of the commit for which the

Documentation/error-invalid-changeid-line.txt

@@ -1,5 +1,4 @@
-invalid Change-Id line format in commit message footer
+= invalid Change-Id line format in commit message footer
-======================================================
 
 With this error message Gerrit rejects to push a commit if its commit
 message footer contains an invalid Change-Id line.
@@ -20,8 +19,7 @@ link:error-push-fails-due-to-commit-message.html#commit_hook[here]. In case you
 Change-Id will be automatically generated and inserted.
 
 
-SEE ALSO
+== SEE ALSO
---------
 
 * link:user-changeid.html[Change-Id Lines]
 

Documentation/error-invalid-committer.txt

@@ -1,5 +1,4 @@
-invalid committer
+= invalid committer
-=================
 
 For every pushed commit Gerrit verifies that the e-mail address of
 the committer matches one of the registered e-mail addresses of the
@@ -16,8 +15,7 @@ This error may happen for two reasons:
   users
 
 
-Incorrect configuration of the e-mail address on client or server side
+== Incorrect configuration of the e-mail address on client or server side
-----------------------------------------------------------------------
 
 If pushing to Gerrit fails with the error message "invalid committer"
 and you committed the change for which the push fails,
@@ -25,8 +23,7 @@ then either you have not successfully registered this e-mail address
 for your Gerrit account or the committer information of the pushed
 commit is incorrect.
 
-Configuration of e-mail address in Gerrit
+=== Configuration of e-mail address in Gerrit
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Check in Gerrit under 'Settings -> Identities' which e-mail addresses
 you've configured for your Gerrit account.  If no e-mail address is
@@ -34,8 +31,7 @@ registered go to 'Settings -> Contact Information' and register a new
 e-mail address there. Make sure you confirm your e-mail address by
 clicking on the link in the e-mail verification mail sent by Gerrit.
 
-Incorrect committer information
+=== Incorrect committer information
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 For every commit Git maintains the user who did the commit, the so
 called committer. Git computes the committer out of the Git
@@ -93,8 +89,7 @@ rewritten. For further details about git rebase please check the
 link:http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html[Git documentation].
 
 
-Missing privileges to push commits that were committed by other users
+== Missing privileges to push commits that were committed by other users
----------------------------------------------------------------------
 
 If pushing to Gerrit fails with the error message "invalid committer"
 and somebody else committed the change for which the

Documentation/error-messages.txt

@@ -1,13 +1,11 @@
-Gerrit Code Review - Error Messages
+= Gerrit Code Review - Error Messages
-===================================
 
 This page provides access to detailed explanations of Gerrit error
 messages. For each error message it is explained why the error is
 occurring and what can be done to solve it.
 
 
-Error Messages
+== Error Messages
---------------
 
 * link:error-branch-not-found.html[branch ... not found]
 * link:error-change-closed.html[change ... closed]
@@ -38,8 +36,7 @@ Error Messages
 * link:error-not-allowed-to-upload-merges.html[you are not allowed to upload merges]
 
 
-General Hints
+== General Hints
--------------
 
 * link:error-push-fails-due-to-commit-message.html[push fails due to commit message]
 

Documentation/error-missing-changeid.txt

@@ -1,5 +1,4 @@
-missing Change-Id in commit message footer
+= missing Change-Id in commit message footer
-==========================================
 
 With this error message Gerrit rejects to push a commit to a project
 which is configured to always require a Change-Id in the commit
@@ -21,8 +20,7 @@ automatically create and insert a unique Change-Id into the commit
 message on every commit.
 
 
-Missing Change-Id in the commit message
+== Missing Change-Id in the commit message
----------------------------------------
 
 If the commit message of a commit that you want to push does not
 contain a Change-Id you have to update its commit message and insert
@@ -41,8 +39,7 @@ insert it into the commit message. How to update the commit message
 is explained link:error-push-fails-due-to-commit-message.html[here].
 
 
-Change-Id is contained in the commit message but not in the last paragraph
+== Change-Id is contained in the commit message but not in the last paragraph
---------------------------------------------------------------------------
 
 To be picked up by Gerrit, a Change-Id must be in the last paragraph
 of a commit message, for details, see link:user-changeid.html[Change-Id Lines].
@@ -52,8 +49,7 @@ last paragraph you have to update the commit message and move the
 Change-ID into the last paragraph. How to update the commit message
 is explained link:error-push-fails-due-to-commit-message.html[here].
 
-Change-Id is the only line in the commit message
+== Change-Id is the only line in the commit message
-------------------------------------------------
 
 Gerrit does not parse the subject of a commit message for the
 Change-Id even if this is the only and last paragraph of the commit

Documentation/error-multiple-changeid-lines.txt

@@ -1,5 +1,4 @@
-multiple Change-Id lines in commit message footer
+= multiple Change-Id lines in commit message footer
-=================================================
 
 With this error message Gerrit rejects to push a commit if the commit
 message footer of the pushed commit contains several Change-Id lines.
@@ -20,8 +19,7 @@ link:error-push-fails-due-to-commit-message.html#commit_hook[here]. In case you
 will be automatically generated and inserted.
 
 
-SEE ALSO
+== SEE ALSO
---------
 
 * link:user-changeid.html[Change-Id Lines]
 

Documentation/error-no-changes-made.txt

@@ -1,5 +1,4 @@
-no changes made
+= no changes made
-===============
 
 With this error message Gerrit rejects to push a commit as a new
 patch set for a change, if the pushed commit is identical to the

Documentation/error-no-common-ancestry.txt

@@ -1,5 +1,4 @@
-no common ancestry
+= no common ancestry
-==================
 
 With this error message Gerrit rejects to push a commit for code
 review if the pushed commit and the commit at the tip of the target

Documentation/error-no-new-changes.txt

@@ -1,5 +1,4 @@
-no new changes
+= no new changes
-==============
 
 With this error message Gerrit rejects to push a commit if the pushed
 commit was already successfully pushed to Gerrit. In this case there

Documentation/error-non-fast-forward.txt

@@ -1,5 +1,4 @@
-non-fast forward
+= non-fast forward
-================
 
 With this error message Gerrit rejects a push if the remote branch can't
 be fast forwarded onto the pushed commit. This is the case if the
@@ -20,8 +19,7 @@ There are different reasons why this error can occur:
 . you are pushing the commit to the wrong project
 
 
-the remote branch has evolved since you started your development
+== the remote branch has evolved since you started your development
-----------------------------------------------------------------
 
 You start your development based on the current tip of the remote
 branch. While you implement your feature / bug-fix, a change in Gerrit
@@ -36,8 +34,7 @@ message 'non-fast forward'. To solve the problem you have to either
 Afterwards the push should be successful.
 
 
-you are pushing the commit to the wrong project
+== you are pushing the commit to the wrong project
------------------------------------------------
 
 If you do a commit in one project and then accidentally push this
 commit, with bypassing code review, to another project, this will fail

Documentation/error-not-a-gerrit-administrator.txt

@@ -1,5 +1,4 @@
-Not a Gerrit administrator
+= Not a Gerrit administrator
-==========================
 
 With this error message Gerrit rejects to execute an SSH command that
 requires administrator privileges if the user is not a Gerrit

Documentation/error-not-allowed-to-upload-merges.txt

@@ -1,5 +1,4 @@
-you are not allowed to upload merges
+= you are not allowed to upload merges
-====================================
 
 With this error message Gerrit rejects to push a merge commit if the
 pushing user has no permission to upload merge commits for the

Documentation/error-not-permitted-to-create.txt

@@ -1,5 +1,4 @@
-Not permitted to create ...
+= Not permitted to create ...
-===========================
 
 With this error message Gerrit rejects to create a new project in
 Gerrit if the user has no privileges for project creation.

Documentation/error-not-signed-off-by.txt

@@ -1,5 +1,4 @@
-not Signed-off-by author/committer/uploader in commit message footer
+= not Signed-off-by author/committer/uploader in commit message footer
-====================================================================
 
 Projects in Gerrit can be configured to require a link:user-signedoffby.html#Signed-off-by[Signed-off-by] in
 the footer of the commit message to enforce that every change is signed by the

Documentation/error-not-valid-ref.txt

@@ -1,5 +1,4 @@
-not valid ref
+= not valid ref
-=============
 
 With this error message Gerrit rejects to push a commit if the target
 ref in the push specification has an incorrect format (for example:
@@ -10,8 +9,7 @@ specification. Depending on whether you want to push your commit with
 or without code review the ref format is different:
 
 
-ref format for pushing a commit for code review:
+== ref format for pushing a commit for code review:
-------------------------------------------------
 
 If it was the intention to push a commit for code review the target
 ref in the push specification must be the project's magical ref
@@ -26,8 +24,7 @@ $ git push ssh://JohnDoe@host:29418/myProject HEAD:refs/for/master
 ----
 
 
-ref format for directly pushing a commit (without code review):
+== ref format for directly pushing a commit (without code review):
----------------------------------------------------------------
 
 If it was the intention to bypass code review and to push directly to
 a branch the target ref in the push specification must be the name of

Documentation/error-permission-denied.txt

@@ -1,5 +1,4 @@
-Permission denied (publickey)
+= Permission denied (publickey)
-=============================
 
 With this error message an SSH command to Gerrit is rejected if the
 SSH authentication is not successful.
@@ -23,8 +22,7 @@ If you are facing this problem, do the following:
   key is used.
 
 
-Test SSH authentication
+== Test SSH authentication
------------------------
 
 To test the SSH authentication you can run the following SSH command.
 This command will print out a detailed trace which is helpful to

Documentation/error-prohibited-by-gerrit.txt

@@ -1,5 +1,4 @@
-prohibited by Gerrit
+= prohibited by Gerrit
-====================
 
 This is a general error message that is returned by Gerrit if a push
 is not allowed, e.g. because the pushing user has no sufficient

Documentation/error-project-not-found.txt

@@ -1,5 +1,4 @@
-Project not found: ...
+= Project not found: ...
-======================
 
 With this error message Gerrit rejects to push a commit if the git
 repository to which the push is done does not exist as a project in

Documentation/error-push-fails-due-to-commit-message.txt

@@ -1,5 +1,4 @@
-Push fails due to commit message
+= Push fails due to commit message
-================================
 
 If Gerrit rejects pushing a commit it is often the case that there is
 an issue with the commit message of the pushed commit. In this case

Documentation/error-squash-commits-first.txt

@@ -1,5 +1,4 @@
-squash commits first
+= squash commits first
-====================
 
 With this error message Gerrit rejects to push a commit if it
 contains the same Change-ID as a predecessor commit.
@@ -19,8 +18,7 @@ changes to be reviewed and accidentally included the same Change-ID
 into the different commit messages.
 
 
-Example
+== Example
--------
 
 Here an example about how the push is failing. Please note that the
 two commits 'one commit' and 'another commit' both have the same

Documentation/i18n-readme.txt

@@ -1,19 +1,16 @@
-Gerrit Code Review - i18n
+= Gerrit Code Review - i18n
-=========================
 
 Aside from actually writing translations, there are some issues with
 the way the code produces output.  Most of the UI should support
 right-to-left (RTL) languages.
 
-Labels
+== Labels
-------
 
 Labels and their values are defined in project.config by the Gerrit
 administrator or project owners.  Only a single translation of these
 strings is supported.
 
-/Gerrit Gerrit.html
+== /Gerrit Gerrit.html
--------------------
 
 * The title of the host page is not translated.
 

Documentation/index.txt

@@ -1,8 +1,6 @@
-Gerrit Code Review for Git
+= Gerrit Code Review for Git
-==========================
 
-Tutorial
+== Tutorial
---------
 . Getting started
 .. link:intro-quick.html[A Quick Introduction to Gerrit]
 .. link:intro-change-screen.html[A Quick Introduction to the New Change Screen]
@@ -24,8 +22,7 @@ Tutorial
 ... link:user-signedoffby.html[Signed-off-by Lines]
 .. Patch sets
 
-Project Management
+== Project Management
-------------------
 . link:project-setup.html[Project Setup]
 . link:access-control.html[Access Controls]
 .. link:config-labels.html[Review Labels]
@@ -39,8 +36,7 @@ Project Management
 . link:user-submodules.html[Subscribing to Git Submodules]
 . Project sunset
 
-Customization and Integration
+== Customization and Integration
------------------------------
 . link:user-dashboards.html[Dashboards]
 . link:rest-api.html[REST API]
 . link:config-gitweb.html[Gitweb Integration]
@@ -50,8 +46,7 @@ Customization and Integration
 . link:config-mail.html[Mail Templates]
 . link:config-cla.html[Contributor Agreements]
 
-Server Administration
+== Server Administration
----------------------
 . link:install.html[Installation Guide]
 . link:config-gerrit.html[System Settings]
 . Backup
@@ -68,8 +63,7 @@ Server Administration
 . link:config-auto-site-initialization.html[Automatic Site Initialization on Startup]
 . link:pgm-index.html[Server Side Administrative Tools]
 
-Developer
+== Developer
----------
 . link:dev-readme.html[Developer Setup]
 . link:dev-buck.html[Building with Buck]
 . link:dev-eclipse.html[Eclipse Setup]
@@ -82,13 +76,11 @@ Developer
 .. link:js-api.html[JavaScript Plugin API]
 .. link:config-validation.html[Commit Validation]
 
-Maintainer
+== Maintainer
-----------
 . link:dev-release.html[Developer Release]
 . link:dev-release-subproject.html[Developer Subproject Release]
 
-Resources
+== Resources
----------
 * link:licenses.html[Licenses and Notices]
 * link:http://code.google.com/p/gerrit/[Homepage]
 * link:http://code.google.com/p/gerrit/downloads/list[Downloads]

Documentation/install-j2ee.txt

@@ -1,8 +1,6 @@
-Gerrit Code Review - J2EE Installation
+= Gerrit Code Review - J2EE Installation
-======================================
 
-Description
+== Description
------------
 
 Gerrit binary distributions include a standalone Jetty servlet
 container, but are packaged as a standard WAR file to permit easy
@@ -14,8 +12,7 @@ including popular open source containers such as Jetty or Tomcat, or
 any commercial server which supports the J2EE servlet specification.
 
 
-Installation
+== Installation
-------------
 
 * Complete the link:install.html#createdb[database setup] and
   link:install.html#init[site initialization] tasks described
@@ -50,8 +47,7 @@ directory so it's available to Gerrit Code Review.
 Configure Automatic Site Initialization on Startup]
 
 
-Jetty 7.x
+== Jetty 7.x
----------
 These directions will configure Gerrit as the default web
 application, allowing URLs like `http://example.com/4543` to jump
 directly to change 4543.

Documentation/install-quick.txt

@@ -1,5 +1,4 @@
-Gerrit Code Review - Quick get started guide
+= Gerrit Code Review - Quick get started guide
-============================================
 
 ****
 This guide was made with the impatient in mind, ready to try out Gerrit on their
@@ -21,8 +20,7 @@ OpenID provider you choose is necessary for both you and your Gerrit instance.
 
 
 [[requirements]]
-Requirements
+== Requirements
-------------
 
 Most distributions come with Java today. Do you already have Java installed?
 
@@ -39,8 +37,7 @@ If Java isn't installed, get it:
 
 
 [[user]]
-Create a user to host the Gerrit service
+== Create a user to host the Gerrit service
-----------------------------------------
 
 We will run the service as a non-privileged user on your system.
 First create the user and then become the user:
@@ -55,8 +52,7 @@ as your own user as well.
 
 
 [[download]]
-Download Gerrit
+== Download Gerrit
----------------
 
 It's time to download the archive that contains the Gerrit web and ssh service.
 
@@ -70,8 +66,7 @@ This tutorial is based on version 2.2.2, and you can download that from this lin
 
 
 [[initialization]]
-Initialize the Site
+== Initialize the Site
--------------------
 
 It's time to run the initialization, and with the batch switch enabled, we don't have to answer any questions at all:
 
@@ -111,16 +106,14 @@ commands to gerrit.sh.
 
 include::config-login-register.txt[]
 
-Project creation
+== Project creation
-----------------
 
 Your base Gerrit server is now running and you have a user that's ready
 to interact with it.  You now have two options, either you create a new
 test project to work with or you already have a git with history that
 you would like to import into Gerrit and try out code review on.
 
-New project from scratch
+=== New project from scratch
-~~~~~~~~~~~~~~~~~~~~~~~~
 If you choose to create a new repository from scratch, it's easier for
 you to create a project with an initial commit in it. That way first
 time setup between client and server is easier.
@@ -134,8 +127,7 @@ This is done via the SSH port:
 
 This will create a repository that you can clone to work with.
 
-Already existing project
+=== Already existing project
-~~~~~~~~~~~~~~~~~~~~~~~~
 
 The other alternative is if you already have a git project that you
 want to try out Gerrit on.
@@ -166,8 +158,7 @@ After that it's time to upload the previous history to the server:
 This will create a repository that you can clone to work with.
 
 
-My first change
+== My first change
----------------
 
 Download a local clone of the repository and move into it
 
@@ -216,8 +207,7 @@ You should now be able to access your change by browsing to the http URL
 suggested above, http://localhost:8080/1
 
 
-Quick Installation Complete
+== Quick Installation Complete
----------------------------
 
 This covers the scope of getting Gerrit started and your first change uploaded.
 It doesn't give any clue as to how the review workflow works, please read

Documentation/install.txt

@@ -1,9 +1,7 @@
-Gerrit Code Review - Standalone Daemon Installation Guide
+= Gerrit Code Review - Standalone Daemon Installation Guide
-=========================================================
 
 [[requirements]]
-Requirements
+== Requirements
-------------
 To run the Gerrit service, the following requirements must be met on
 the host:
 
@@ -14,8 +12,7 @@ choice of either using the embedded H2 or to host your own MySQL or PostgreSQL.
 
 
 [[download]]
-Download Gerrit
+== Download Gerrit
----------------
 
 Current and past binary releases of Gerrit can be obtained from
 the link:https://gerrit-releases.storage.googleapis.com/index.html[
@@ -31,8 +28,7 @@ the notes under link:dev-readme.html[developer setup].
 include::database-setup.txt[]
 
 [[init]]
-Initialize the Site
+== Initialize the Site
--------------------
 
 Gerrit stores configuration files, the server's SSH keys, and the
 managed Git repositories under a local directory, typically referred
@@ -90,8 +86,7 @@ permitting server management over the web and over SSH.  Subsequent
 users will be automatically registered as unprivileged users.
 
 
-Installation Complete
+== Installation Complete
----------------------
 
 Your base Gerrit server is now installed and running.  You're now ready to
 either set up more projects or start working with the projects you've already
@@ -99,8 +94,7 @@ imported.
 
 
 [[project_setup]]
-Project Setup
+== Project Setup
--------------
 
 See link:project-setup.html[Project Setup] for further details on
 how to register a new project with Gerrit.  This step is necessary
@@ -108,8 +102,7 @@ if existing Git repositories were not imported during 'init'.
 
 
 [[rc_d]]
-Start/Stop Daemon
+== Start/Stop Daemon
------------------
 
 To control the Gerrit Code Review daemon that is running in the
 background, use the rc.d style start script created by 'init':
@@ -149,8 +142,7 @@ link:install-j2ee.html[J2EE installation].
 
 
 [[customize]]
-Site Customization
+== Site Customization
-------------------
 
 Gerrit Code Review supports some site-specific customization options.
 For more information, see the related topics in this manual:
@@ -164,8 +156,7 @@ For more information, see the related topics in this manual:
 
 
 [[anonymous_access]]
-Anonymous Access
+== Anonymous Access
-----------------
 
 Exporting the Git repository directory
 (link:config-gerrit.html#gerrit.basePath[gerrit.basePath]) over the
@@ -177,14 +168,12 @@ for details on how to configure this if anonymous access is desired.
 
 
 [[plugins]]
-Plugins
+== Plugins
--------
 
 Place Gerrit plugins in the review_site/plugins directory to have them loaded on Gerrit startup.
 
 
-External Documentation Links
+== External Documentation Links
-----------------------------
 
 * http://www.postgresql.org/docs/[PostgreSQL Documentation]
 * http://dev.mysql.com/doc/[MySQL Documentation]

Documentation/intro-change-screen.txt

@@ -1,5 +1,4 @@
-Change Screen - Introduction
+= Change Screen - Introduction
-============================
 
 As of Gerrit 2.8 the change screen was redesigned from the ground up. The old
 change screen is deprecated and will be discontinued in one of the next Gerrit
@@ -25,8 +24,7 @@ link:https://groups.google.com/forum/#!topic/repo-discuss/6Ryz9p6AzgE[
 CodeScreen2 thread on the repo-discuss mailing list].
 
 [[configuration]]
-Configuration
+== Configuration
--------------
 
 The new change screen is activated by default. It can be deactivated
 system-wide by changing the link:config-gerrit.html[gerrit.changeScreen]
@@ -34,8 +32,7 @@ setting to `OLD_UI`.  Users can deactivate it by setting `OLD_UI` on their
 user preferences page.
 
 [[switching-between-patch-sets]]
-Switching between patch sets
+== Switching between patch sets
-----------------------------
 
 As already mentioned above, the main difference between the old and the new
 change screen is the fact that only one patch set is presented on the screen.
@@ -54,8 +51,7 @@ screen.
 Key bindings: "n" & "p" to navigate between the patch sets.
 
 [[download-commands]]
-Download commands
+== Download commands
------------------
 
 The download commands are moved to the 'Download' drop down box.  Patch files
 can be downloaded as base64 encoded or zipped versions. Download-plugin must
@@ -68,8 +64,7 @@ the cached state in the browser will be invalidated and the download commands
 will update. Another option to invalidate the cache is to use "Ctrl+Shift+R".
 
 [[included-in]]
-Included in
+== Included in
------------
 
 To see the branches a specific change was merged into and the list of the tags
 a change was tagged with, use the 'Included In' drop down on the change header,
@@ -78,8 +73,7 @@ to the left of the 'Revisions' drop down.
 Note that this list is only visible on merged changes.
 
 [[quick-approve]]
-Quick approve
+== Quick approve
--------------
 
 The so called 'Quick approve' button is some times confusing. Normal users (i.e.
 non-maintainers) see this as 'Verified+1' button to the right of the 'Reply'
@@ -100,8 +94,7 @@ using this button, hence the name 'Quick approve'. To provide comments, the
 'Reply' button should be used.
 
 [[reply-button]]
-Reply button
+== Reply button
-------------
 
 This button corresponds to the 'Review' button the on patch set panel on the old
 change screen. The user can optionally send an email during the vote. Inline
@@ -115,8 +108,7 @@ is selected.
 Key bindings: "a" to open the drop down. "ESC" to close it.
 
 [[edit-commit-message]]
-Edit commit message
+== Edit commit message
--------------------
 
 To edit the commit message use the 'Edit Message' button on the change header,
 which will open a drop-down editor box.
@@ -124,8 +116,7 @@ which will open a drop-down editor box.
 Key bindings: "e" to open the drop down. "ESC" to close it.
 
 [[star-change]]
-Star and unstar changes
+== Star and unstar changes
------------------------
 
 Star change icon allows to star the change, so that "starredby:self" query can
 retrieve the starred changes later. If the change is already starred, then
@@ -134,8 +125,7 @@ clicking the icon again unstars the change.
 Key bindings: "s" to star/unstar the change.
 
 [[permalink-change]]
-Permalink a change
+== Permalink a change
-------------------
 
 Hyperlink "Change <change link>" is a control that serves for two purposes:
 reload the change and permalink the change. To permalink,
@@ -144,23 +134,20 @@ Right mouse click -> Copy Link Address.
 Key bindings: "R" to reload the change.
 
 [[edit-change-topic]]
-Edit change topic
+== Edit change topic
------------------
 
 To edit the topic use the edit icon to the right of the topic field.
 
 Key bindings: "t" to open the drop down. "ESC" to close it.
 
 [[abandon-restore]]
-Abandon or Restore changes
+== Abandon or Restore changes
---------------------------
 
 When a change is abandoned or restored, a panel appears and a comment message
 can be provided.
 
 [[working-with-drafts]]
-Working with draft changes and patch sets
+== Working with draft changes and patch sets
------------------------------------------
 
 When a change or a patch set is a draft, then three additional buttons
 appear on the action panel: 'Publish', 'Delete Revision', and 'Delete
@@ -170,16 +157,14 @@ suffix is added to the patch set number to indicate that the patch set
 is a draft.
 
 [[draft-comments]]
-Highlight draft comments
+== Highlight draft comments
-------------------------
 
 If a patch set has draft comments that weren't published yet, then that patch
 set is marked on the list in the 'Patch Sets' drop down list. In addition a red
 "draft" prefix appears on the filenames in the file table.
 
 [[codemirror]]
-Codemirror
+== Codemirror
-----------
 
 On the user preferences page, 'Side By Side' or 'Unified Diff' view can be
 configured.  Use the "/" key to start the CodeMirror search, like in 'vim'.
@@ -206,8 +191,7 @@ Key bindings:
 * <Ctrl> + s: Save draft comment
 
 [[reviewers]]
-Reviewers
+== Reviewers
----------
 
 Reviewer are split into two groups: Reviewers who actually voted on the change
 in the 'Reviewers' field, and reviewers, who were added to the change but didn't
@@ -223,8 +207,7 @@ To remove reviewers click on the 'x' icon in the reviewer's "chip".
 Key bindings:  "c" to add a reviewer. "ESC" to close the drop down.
 
 [[auto-refresh]]
-Auto refresh of change data
+== Auto refresh of change data
----------------------------
 
 On the new change screen polling for updates to the currently open change is
 activated per default.  For example, if another user votes or comments on the
@@ -235,8 +218,7 @@ The default delay is 30 seconds.  It can be configured with the
 link:config-gerrit.html[change.updateDelay] setting.
 
 [[related-changes]]
-"Related changes"
+== "Related changes"
------------------
 
 A tab control on the third column shows the related changes. There are 4
 different tabs:
@@ -283,8 +265,7 @@ Key bindings: "J" & "K" to navigate between the related changes. "O" to
 open the currently selected change on one of the related changes tab page.
 
 [[file-table]]
-File table
+== File table
-----------
 
 The user can now manually toggle the 'reviewed' flag per file using the check
 box to the left of the filename.
@@ -294,8 +275,7 @@ Key bindings: "j" & "k" to navigate in the file table, "r" to toggle the
 view.
 
 [[diff-against]]
-Diff against
+== Diff against
-------------
 
 In the 'Diff against' dropdown, base reference version can be selected. On
 selecting an entry the file table list is reloaded and shows only the files
@@ -304,8 +284,7 @@ is passed to the side by side view, so that code mirror windows "remember"
 the base reference version choice made on the change screen.
 
 [[history]]
-History
+== History
--------
 
 The history table shows change messages and inline file comments. Expand All and
 Collapse All buttons show/hide the messages.