Adjust documentation source to current asciidoc version
This meant fixing old tables syntax, adjusting some overly long header
underlines and some other small issues.
Change-Id: I2701a5040d225454225034ed5ef7861580743707
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 72e3f86..f167cc5 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -29,7 +29,6 @@
DOC_HTML := $(patsubst %.txt,%.html,$(wildcard *.txt))
LOCAL_ROOT := .published
-SCRIPTSDIR := $(shell pwd)/javascript
COMMIT := $(shell git describe HEAD | sed s/^v//)
PUB_DIR := $(PUB_ROOT)/$(VERSION)
PRIOR = PRIOR
@@ -71,13 +70,13 @@
$(SVN) commit -m "Updated $(VERSION) documentation to v$(COMMIT)"
@-rm -rf $(LOCAL_ROOT)
-$(DOC_HTML): %.html : %.txt $(SCRIPTSDIR)/toc.js
+$(DOC_HTML): %.html : %.txt
@echo "FORMAT $@"
@rm -f $@+ $@
- @$(ASCIIDOC) --unsafe \
- -a toc \
+ @$(ASCIIDOC) -a toc \
-a 'revision=$(REVISION)' \
- -a 'scriptsdir=$(SCRIPTSDIR)' \
- -b xhtml11 -f asciidoc.conf \
- $(ASCIIDOC_EXTRA) -o $@+ $<
+ -b xhtml11 \
+ -f asciidoc.conf \
+ $(ASCIIDOC_EXTRA) \
+ -o $@+ $<
@mv $@+ $@
diff --git a/Documentation/access-control.txt b/Documentation/access-control.txt
index 7c9fcbf..e98ed2e 100644
--- a/Documentation/access-control.txt
+++ b/Documentation/access-control.txt
@@ -131,14 +131,13 @@
groups in an approval category. For example, a user is a member of
`Foo Leads`, and the following ACLs are granted on a project:
-[grid="all"]
-`---------------`---------------`-------------`-------
-Group Reference Name Category Range
-------------------------------------------------------
-Anonymous Users refs/heads/* Code Review -1..+1
-Registered Users refs/heads/* Code Review -1..+2
-Foo Leads refs/heads/* Code Review -2..0
-------------------------------------------------------
+[options="header"]
+|=================================================
+|Group |Reference Name |Category|Range
+|Anonymous Users |refs/heads/*|Code Review|-1..+1
+|Registered Users|refs/heads/*|Code Review|-1..+2
+|Foo Leads |refs/heads/*|Code Review|-2..0
+|=================================================
Then the effective range permitted to be used by the user is
`-2..+2`, as the user is a member of all three groups (see above
@@ -173,14 +172,13 @@
the `refs/heads/qa` branch, and the following ACLs are granted
on the project:
-[grid="all"]
-`---------------`---------------`-------------`-------
-Group Reference Name Category Range
-------------------------------------------------------
-Registered Users refs/heads/* Code Review -1..+1
-Foo Leads refs/heads/* Code Review -2..+2
-QA Leads refs/heads/qa Code Review -2..+2
-------------------------------------------------------
+[options="header"]
+|=====================================================
+|Group |Reference Name|Category |Range
+|Registered Users |refs/heads/* |Code Review| -1..+1
+|Foo Leads |refs/heads/* |Code Review| -2..+2
+|QA Leads |refs/heads/qa |Code Review| -2..+2
+|=====================================================
Then the effective range permitted to be used by the user is
`-2..+2`, as the user's membership of `Foo Leads` effectively grant
@@ -197,14 +195,13 @@
review a change destined for branch `refs/heads/qa` in a project,
and the following ACLs are granted:
-[grid="all"]
-`---------------`----------------`--------------`-------
-Group Reference Name Category Range
---------------------------------------------------------
-Registered Users refs/heads/* Code Review -1..+1
-Foo Leads refs/heads/* Code Review -2..+2
-QA Leads -refs/heads/qa Code Review -2..+2
---------------------------------------------------------
+[options="header"]
+|=====================================================
+|Group |Reference Name|Category |Range
+|Registered Users|refs/heads/* |Code Review| -1..+1
+|Foo Leads |refs/heads/* |Code Review| -2..+2
+|QA Leads |-refs/heads/qa|Code Review| -2..+2
+|=====================================================
Then this user will not have `Code Review` rights on that change,
since there is an exclusive access right in place for the
@@ -216,15 +213,14 @@
`Foo Leads`, in `refs/heads/qa` then the following access rights
would be needed:
-[grid="all"]
-`---------------`----------------`--------------`-------
-Group Reference Name Category Range
---------------------------------------------------------
-Registered Users refs/heads/* Code Review -1..+1
-Foo Leads refs/heads/* Code Review -2..+2
-QA Leads -refs/heads/qa Code Review -2..+2
-Foo Leads refs/heads/qa Code Review -2..+2
---------------------------------------------------------
+[options="header"]
+|=====================================================
+|Group |Reference Name|Category |Range
+|Registered Users|refs/heads/* |Code Review| -1..+1
+|Foo Leads |refs/heads/* |Code Review| -2..+2
+|QA Leads |-refs/heads/qa|Code Review| -2..+2
+|Foo Leads |refs/heads/qa |Code Review| -2..+2
+|=====================================================
OpenID Authentication
diff --git a/Documentation/cmd-create-project.txt b/Documentation/cmd-create-project.txt
index f698d5c..71c0d1f 100644
--- a/Documentation/cmd-create-project.txt
+++ b/Documentation/cmd-create-project.txt
@@ -8,18 +8,18 @@
SYNOPSIS
--------
[verse]
-'ssh' -p <port> <host> 'gerrit create-project' \
-\--name <NAME> \
-[--branch <REF>] \
-[\--owner <GROUP> ...] \
-[\--parent <NAME>] \
-[\--permissions-only] \
-[\--description <DESC>] \
-[\--submit-type <TYPE>] \
-[\--use-content-merge] \
-[\--use-contributor-agreements] \
-[\--use-signed-off-by]
-[\--empty-commit]
+ 'ssh' -p <port> <host> 'gerrit create-project' \
+ --name <NAME> \
+ [--branch <REF>] \
+ [\--owner <GROUP> ...] \
+ [\--parent <NAME>] \
+ [\--permissions-only] \
+ [\--description <DESC>] \
+ [\--submit-type <TYPE>] \
+ [\--use-content-merge] \
+ [\--use-contributor-agreements] \
+ [\--use-signed-off-by] \
+ [\--empty-commit]
DESCRIPTION
-----------
diff --git a/Documentation/cmd-flush-caches.txt b/Documentation/cmd-flush-caches.txt
index 795af04..573cd78 100644
--- a/Documentation/cmd-flush-caches.txt
+++ b/Documentation/cmd-flush-caches.txt
@@ -8,8 +8,8 @@
SYNOPSIS
--------
[verse]
-'ssh' -p <port> <host> 'gerrit flush-caches' \
-[\--all | \--list | \--cache <NAME> ...]
+ 'ssh' -p <port> <host> 'gerrit flush-caches' \
+ [\--all | \--list | \--cache <NAME> ...]
DESCRIPTION
-----------
diff --git a/Documentation/cmd-gsql.txt b/Documentation/cmd-gsql.txt
index 43ba682..7fc8a9b 100644
--- a/Documentation/cmd-gsql.txt
+++ b/Documentation/cmd-gsql.txt
@@ -8,9 +8,9 @@
SYNOPSIS
--------
[verse]
-'ssh' -p <port> <host> 'gerrit gsql' \
-[\--format \{PRETTY | JSON\}] \
-[\-c QUERY]
+ 'ssh' -p <port> <host> 'gerrit gsql' \
+ [\--format \{PRETTY | JSON\}] \
+ [\-c QUERY]
DESCRIPTION
-----------
diff --git a/Documentation/cmd-query.txt b/Documentation/cmd-query.txt
index 9047202..c8996eb 100644
--- a/Documentation/cmd-query.txt
+++ b/Documentation/cmd-query.txt
@@ -8,14 +8,14 @@
SYNOPSIS
--------
[verse]
-'ssh' -p <port> <host> 'gerrit query' \
-[\--format {TEXT | JSON}] \
-[\--current-patch-set] \
-[\--patch-sets|--all-approvals] \
-[\--] \
-<query> \
-[limit:<n>] \
-[resume\_sortkey:<sortKey>]
+ 'ssh' -p <port> <host> 'gerrit query' \
+ [\--format {TEXT | JSON}] \
+ [\--current-patch-set] \
+ [\--patch-sets|--all-approvals] \
+ [\--] \
+ <query> \
+ [limit:<n>] \
+ [resume\_sortkey:<sortKey>]
DESCRIPTION
-----------
diff --git a/Documentation/dev-design.txt b/Documentation/dev-design.txt
index 0353b09..861fbe0d 100644
--- a/Documentation/dev-design.txt
+++ b/Documentation/dev-design.txt
@@ -450,18 +450,17 @@
amounts to parameters such as the following:
.Design Parameters
-[grid="all"]
-`-----------------'----------------
-Parameter Estimated Maximum
------------------------------------
-Projects 500
-Contributors 2,000
-Changes/Day 400
-Revisions/Change 2.0
-Files/Change 4
-Comments/File 2
-Reviewers/Change 1.0
------------------------------------
+[options="header"]
+|====================================
+|Parameter | Estimated Maximum
+|Projects | 500
+|Contributors | 2,000
+|Changes/Day | 400
+|Revisions/Change | 2.0
+|Files/Change | 4
+|Comments/File | 2
+|Reviewers/Change | 1.0
+|====================================
CPU Usage
~~~~~~~~~
diff --git a/Documentation/error-you-are-not-author.txt b/Documentation/error-you-are-not-author.txt
index 3f14d2f..47a7652 100644
--- a/Documentation/error-you-are-not-author.txt
+++ b/Documentation/error-you-are-not-author.txt
@@ -1,5 +1,5 @@
you are not author ...
-=========================
+======================
Gerrit verifies for every pushed commit that the e-mail address of
the author matches one of the registered e-mail addresses of the
@@ -9,9 +9,9 @@
link:access-control.html#category_FORG['Forge Identity'] category.
This error may happen for two reasons:
-1. incorrect configuration of the e-mail address on client or server
- side
-2. missing privileges to push commits of other authors
+
+. incorrect configuration of the e-mail address on client or server side
+. missing privileges to push commits of other authors
Incorrect configuration of the e-mail address on client or server side
@@ -35,7 +35,7 @@
was caught by your spam filter.
Incorrect author information
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For every commit Git maintains the author. If not explicitly
specified Git computes the author on commit out of the Git
diff --git a/Documentation/install.txt b/Documentation/install.txt
index 394bebd..d926ada 100644
--- a/Documentation/install.txt
+++ b/Documentation/install.txt
@@ -125,7 +125,7 @@
if existing Git repositories were not imported during 'init'.
-[[rc.d]]
+[[rc_d]]
Start/Stop Daemon
-----------------
diff --git a/Documentation/javascript/toc.js b/Documentation/javascript/toc.js
deleted file mode 100644
index 36023f8..0000000
--- a/Documentation/javascript/toc.js
+++ /dev/null
@@ -1,115 +0,0 @@
-/* Author: Mihai Bazon, September 2002
- * http://students.infoiasi.ro/~mishoo
- *
- * Table Of Content generator
- * Version: 0.4.sp
- *
- * Feel free to use this script under the terms of the GNU General Public
- * License, as long as you do not remove or alter this notice.
- */
-
- /* modified by Troy D. Hanson, September 2006. License: GPL */
- /* modified by Stuart Rackham, October 2006. License: GPL */
- /* modified by Shawn Pearce, August 2009. License: GPL */
-
-function getText(el) {
- var text = "";
- for (var i = el.firstChild; i != null; i = i.nextSibling) {
- if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
- text += i.data;
- else if (i.firstChild != null)
- text += getText(i);
- }
- return text;
-}
-
-function TocEntry(el, text, toclevel) {
- this.element = el;
- this.text = text;
- this.toclevel = toclevel;
- this.assigned = false;
-
- if (el.id != '') {
- this.id = el.id;
-
- } else {
- var a = el.firstChild;
- if ((a.tagName == "a" || a.tagName == "A") && a.id != "") {
- this.id = a.id;
- } else {
- this.id = '';
- }
- }
-}
-
-function tocEntries(el, toclevels) {
- var result = new Array;
- var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
- // Function that scans the DOM tree for header elements (the DOM2
- // nodeIterator API would be a better technique but not supported by all
- // browsers).
- var iterate = function (el) {
- for (var i = el.firstChild; i != null; i = i.nextSibling) {
- if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
- var mo = re.exec(i.tagName)
- if (mo)
- result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
- iterate(i);
- }
- }
- }
- iterate(el);
- return result;
-}
-
-// This function does the work. toclevels = 1..4.
-function generateToc(toclevels) {
- var simple_re = new RegExp('^[a-zA-Z._ -]{1,}$');
- var entries = tocEntries(document.getElementsByTagName("body")[0], toclevels);
- var usedIds = new Array();
-
- for (var i = 0; i < entries.length; ++i) {
- var entry = entries[i];
- if (entry.id != "")
- usedIds[entry.id] = entry;
- }
-
- for (var i = 0; i < entries.length; ++i) {
- var entry = entries[i];
- if (entry.id != "" || !simple_re.exec(entry.text))
- continue;
-
- var n = entry.text.replace(/ /g, '_').toLowerCase();
- var e = usedIds[n];
- if (e) {
- if (e.assigned)
- e.id = '';
- continue;
- }
-
- entry.assigned = true;
- entry.id = n;
- entry.element.id = entry.id;
- usedIds[n] = entry;
- }
-
- for (var i = 0; i < entries.length; ++i) {
- var entry = entries[i];
- if (entry.id == '') {
- entry.id = "toc" + i;
- entry.element.id = entry.id;
- }
- }
-
- var toc = document.getElementById("toc");
- for (var i = 0; i < entries.length; ++i) {
- var entry = entries[i];
- var a = document.createElement("a");
- a.href = "#" + entry.id;
- a.appendChild(document.createTextNode(entry.text));
- var div = document.createElement("div");
- div.appendChild(a);
- div.className = "toclevel" + entry.toclevel;
- toc.appendChild(div);
- }
-}
diff --git a/Documentation/licenses.txt b/Documentation/licenses.txt
index 25194a9..c95b1b1 100644
--- a/Documentation/licenses.txt
+++ b/Documentation/licenses.txt
@@ -8,50 +8,49 @@
Included Components
-------------------
-[grid="all"]
-`---------------------------`------------------------------
-Included Package License
------------------------------------------------------------
-Gerrit Code Review <<apache2,Apache License 2.0>>
-gwtexpui <<apache2,Apache License 2.0>>
-gwtjsonrpc <<apache2,Apache License 2.0>>
-gwtorm <<apache2,Apache License 2.0>>
-Google Gson <<apache2,Apache License 2.0>>
-Google Web Toolkit <<apache2,Apache License 2.0>>
-Guice <<apache2,Apache License 2.0>>
-Apache Commons Codec <<apache2,Apache License 2.0>>
-Apache Commons DBCP <<apache2,Apache License 2.0>>
-Apache Commons Http Client <<apache2,Apache License 2.0>>
-Apache Commons Lang <<apache2,Apache License 2.0>>
-Apache Commons Logging <<apache2,Apache License 2.0>>
-Apache Commons Net <<apache2,Apache License 2.0>>
-Apache Commons Pool <<apache2,Apache License 2.0>>
-Apache Log4J <<apache2,Apache License 2.0>>
-Apache MINA <<apache2,Apache License 2.0>>
-Apache Tomact Servlet API <<apache2,Apache License 2.0>>
-Apache SSHD <<apache2,Apache License 2.0>>, see also <<sshd,NOTICE>>
-Apache Velocity <<apache2,Apache License 2.0>>
-Apache Xerces <<apache2,Apache License 2.0>>
-OpenID4Java <<apache2,Apache License 2.0>>
-Neko HTML <<apache2,Apache License 2.0>>
-Ehcache <<apache2,Apache License 2.0>>
-mime-util <<apache2,Apache License 2.0>>
-Jetty <<apache2,Apache License 2.0>>, or link:http://www.eclipse.org/legal/epl-v10.html[EPL]
-Google Code Prettify <<apache2,Apache License 2.0>>
-JGit <<jgit,New-Style BSD>>
-JSch <<sshd,New-Style BSD>>
-PostgreSQL JDBC Driver <<postgresql,New-Style BSD>>
-H2 Database <<h2,EPL or modified MPL>>
-ObjectWeb ASM <<asm,New-Style BSD>>
-ANTLR <<antlr,New-Style BSD>>
-args4j <<args4j,MIT License>>
-SLF4J <<slf4j,MIT License>>
-Clippy <<clippy,MIT License>>
-juniversalchardet <<mpl1_1,MPL 1.1>>
-AOP Alliance Public Domain
-JSR 305 <<jsr305,New-Style BSD>>
-dk.brics.automaton <<automaton,New-Style BSD>>
------------------------------------------------------------
+[options="header"]
+|======================================================================
+|Included Package | License
+|Gerrit Code Review | <<apache2,Apache License 2.0>>
+|gwtexpui | <<apache2,Apache License 2.0>>
+|gwtjsonrpc | <<apache2,Apache License 2.0>>
+|gwtorm | <<apache2,Apache License 2.0>>
+|Google Gson | <<apache2,Apache License 2.0>>
+|Google Web Toolkit | <<apache2,Apache License 2.0>>
+|Guice | <<apache2,Apache License 2.0>>
+|Apache Commons Codec | <<apache2,Apache License 2.0>>
+|Apache Commons DBCP | <<apache2,Apache License 2.0>>
+|Apache Commons Http Client | <<apache2,Apache License 2.0>>
+|Apache Commons Lang | <<apache2,Apache License 2.0>>
+|Apache Commons Logging | <<apache2,Apache License 2.0>>
+|Apache Commons Net | <<apache2,Apache License 2.0>>
+|Apache Commons Pool | <<apache2,Apache License 2.0>>
+|Apache Log4J | <<apache2,Apache License 2.0>>
+|Apache MINA | <<apache2,Apache License 2.0>>
+|Apache Tomact Servlet API | <<apache2,Apache License 2.0>>
+|Apache SSHD | <<apache2,Apache License 2.0>>, see also <<sshd,NOTICE>>
+|Apache Velocity | <<apache2,Apache License 2.0>>
+|Apache Xerces | <<apache2,Apache License 2.0>>
+|OpenID4Java | <<apache2,Apache License 2.0>>
+|Neko HTML | <<apache2,Apache License 2.0>>
+|Ehcache | <<apache2,Apache License 2.0>>
+|mime-util | <<apache2,Apache License 2.0>>
+|Jetty | <<apache2,Apache License 2.0>>, or link:http://www.eclipse.org/legal/epl-v10.html[EPL]
+|Google Code Prettify | <<apache2,Apache License 2.0>>
+|JGit | <<jgit,New-Style BSD>>
+|JSch | <<sshd,New-Style BSD>>
+|PostgreSQL JDBC Driver | <<postgresql,New-Style BSD>>
+|H2 Database | <<h2,EPL or modified MPL>>
+|ObjectWeb ASM | <<asm,New-Style BSD>>
+|ANTLR | <<antlr,New-Style BSD>>
+|args4j | <<args4j,MIT License>>
+|SLF4J | <<slf4j,MIT License>>
+|Clippy | <<clippy,MIT License>>
+|juniversalchardet | <<mpl1_1,MPL 1.1>>
+|AOP Alliance | Public Domain
+|JSR 305 | <<jsr305,New-Style BSD>>
+|dk.brics.automaton | <<automaton,New-Style BSD>>
+|======================================================================
Cryptography Notice
-------------------
diff --git a/Documentation/user-search.txt b/Documentation/user-search.txt
index e1d6145..5f0f004 100644
--- a/Documentation/user-search.txt
+++ b/Documentation/user-search.txt
@@ -10,18 +10,17 @@
matches the search, the change will be presented instead of a list.
-[grid="all"]
-`---------------------------`------------------------------
-Description Default Query
------------------------------------------------------------
-All > Open status:open '(or is:open)'
-All > Merged status:merged
-All > Abandoned status:abandoned
-My > Dafts has:draft
-My > Watched Changes status:open is:watched
-My > Starred Changes is:starred
-Open changes in Foo status:open project:Foo
------------------------------------------------------------
+[options="header"]
+|=================================================
+|Description | Default Query
+|All > Open | status:open '(or is:open)'
+|All > Merged | status:merged
+|All > Abandoned | status:abandoned
+|My > Dafts | has:draft
+|My > Watched Changes | status:open is:watched
+|My > Starred Changes | is:starred
+|Open changes in Foo | status:open project:Foo
+|=================================================
Basic Change Search
-------------------
@@ -29,16 +28,15 @@
Similar to many popular search engines on the web, just enter some
text and let Gerrit figure out the meaning:
-[grid="all"]
-`---------------------------------`------------------------------
-Description Examples
------------------------------------------------------------------
-Legacy numerical id 15183
-Full or abbreviated Change-Id Ic0ff33
-Full or abbreviated commit SHA-1 d81b32ef
-Email address user@example.com
-Approval requirement CodeReview>=+2, Verified=1
------------------------------------------------------------------
+[options="header"]
+|=============================================================
+|Description | Examples
+|Legacy numerical id | 15183
+|Full or abbreviated Change-Id | Ic0ff33
+|Full or abbreviated commit SHA-1 | d81b32ef
+|Email address | user@example.com
+|Approval requirement | CodeReview>=+2, Verified=1
+|=============================================================
Search Operators
@@ -123,7 +121,7 @@
If 'REF' starts with `^` it matches reference names by regular
expression patterns.
-[[tr]][[bug]]
+[[tr,bug]]
tr:'ID', bug:'ID'::
+
Search for changes whose commit message contains 'ID' and matched
@@ -146,13 +144,13 @@
Changes that matches 'MESSAGE' arbitrary string in body commit messages.
[[file]]
-file:\^'REGEX'::
+file:^'REGEX'::
+
Matches any change where REGEX matches a file that was affected
by the change. The regular expression pattern must start with
-`\^`. For example, to match all XML files use `file:^.*\.xml$`.
+`^`. For example, to match all XML files use `file:^.*\.xml$`.
+
-The `\^` required at the beginning of the regular expression not only
+The `^` required at the beginning of the regular expression not only
denotes a regular expression, but it also has the usual meaning of
anchoring the match to the start of the string. To match all Java
files, use `file:^.*\.java`.
@@ -370,14 +368,14 @@
preferences. Including it in a web query may lead to unpredictable
results with regards to pagination.
-resume\_sortkey:'KEY'::
+resume_sortkey:'KEY'::
+
Positions the low level scan routine to start from 'KEY' and
continue through changes from this point. This is most often used
for paginating result sets. Including this in a web query may lead
to unpredictable results.
-sortkey\_after:'KEY', sortkey\_before:'KEY'::
+sortkey_after:'KEY', sortkey_before:'KEY'::
+
Restart the low level scan routine from 'KEY'. This is automatically
set by the pagination system as the user navigates through results
