Unify the docs, samples and extensions

1 file changed, 25 insertions, 32 deletions

diff --git a/README.txt b/README.txtindex 55f33de..d19950e 100644--- a/README.txt+++ b/README.txt@@ -9,45 +9,40 @@ Installation ------------  Building cgit involves building a proper version of Git. How to do this depends-on how you obtained the cgit sources:+on how you obtained the cgit sources. -a) If you're working in a cloned cgit repository, you first need to initialize-and update the Git submodule:+In a cloned cgit repository, first initialize and update the Git submodule.      $ git submodule init     # register the Git submodule in .git/config     $ $EDITOR .git/config    # if you want to specify a different url for git     $ git submodule update   # clone/fetch and checkout correct git version -b) If you're building from a cgit tarball, you can download a proper git version-like this:+From a cgit tarball, download a proper git version instead.      $ make get-git -When either a) or b) has been performed, you can build and install cgit like-this:+With the Git tree in place, build and install cgit.      $ make     $ sudo make install -This will install `cgit.cgi` and `cgit.css` into `/var/www/htdocs/cgit`. You can-configure this location (and a few other things) by providing a `cgit.conf` file-(see the Makefile for details).+This installs cgit.cgi and cgit.css into /var/www/htdocs/cgit. The location and+a few other things can be changed by providing a cgit.conf file, see the+Makefile for details.  The only required library is zlib. cgit builds without OpenSSL or libcurl, so no development packages for those are needed. -Lua is optional and only powers the lua: filter extensions (the filters in-custom/extensions/). A plain build auto-detects a Lua through pkg-config,-preferring LuaJIT, and falls back to a Lua-less binary when none is found.--To pin an implementation:+Lua is optional and only powers the lua: filter extensions, the filters in+custom/extensions/. A plain build auto-detects a Lua through pkg-config,+preferring LuaJIT, and falls back to a Lua-less binary when none is found. To+pin an implementation, name its pkg-config module.      $ make LUA_PKGCONFIG=lua5.4  Acceptable LUA_PKGCONFIG values include "luajit", "lua", "lua5.4", "lua5.3",-"lua5.2" and "lua5.1".--To build without Lua, so the binary needs no Lua at runtime:+"lua5.2" and "lua5.1". To build without Lua, so the binary needs no Lua at+runtime, turn it off.      $ make NO_LUA=1 @@ -56,32 +51,30 @@ Setup -----  cgit is a CGI program. Complete, commented configurations for nginx, Apache and-lighttpd live in `custom/servers/`, each explaining how that server routes+lighttpd live in custom/servers/, each explaining how that server routes requests to the binary and serves the static assets off disk. -At runtime cgit reads `/etc/cgitrc` for its options and for the list of+At runtime cgit reads /etc/cgitrc for its options and for the list of repositories to display. A fully commented starting point with every option at-its default is in `custom/cgitrc`, and `MANUAL.txt` documents each option in-full.+its default is in custom/cgitrc, and MANUAL.txt documents each option in full.   Filter extensions ----------------- -The optional Lua filters in `custom/extensions/` mostly need extra Lua modules,+The optional Lua filters in custom/extensions/ mostly need extra Lua modules, and each script's header lists the exact install commands for its own. -* The auth filters (`auth-file.lua`, `auth-inline.lua`) need `luaossl` and-  `luaposix`.-* The email filters (`email-gravatar.lua`, `email-libravatar.lua`) need-  `luaossl`.-* The syntax highlighter (`syntax-highlight.lua`) needs `lpeg` and a Scintillua+* The auth filters, auth-file.lua and auth-inline.lua, need luaossl and+  luaposix.+* The email filters, email-gravatar.lua and email-libravatar.lua, need luaossl.+* The syntax highlighter, syntax-highlight.lua, needs lpeg and a Scintillua   lexer set.-* The about-page renderer (`about-render.lua`) needs `lpeg` for markdown and man+* The about-page renderer, about-render.lua, needs lpeg for markdown and man   pages. Plain text needs only Lua.-* `link-commits.lua` and `link-trailers.lua` need nothing beyond Lua itself.+* link-commits.lua and link-trailers.lua need nothing beyond Lua itself. -`luaossl` has no Lua 5.5 build, so build cgit against 5.1 to 5.4 if you use the+luaossl has no Lua 5.5 build, so build cgit against 5.1 to 5.4 if you use the auth or email filters.  @@ -115,7 +108,7 @@ one, where a value of all marks the few not tied to particular pages. | id2      | diff patch rawdiff   | second object of a diff, paired with id    | | ofs      | index log refs stats | offset into a paged listing                | | path     | all                  | restrict the page to one path              |-| q        | log                  | the search term                            |+| q        | log                  | the search term, matched literally         | | qt       | log                  | one of grep, author, committer or range    | | s        | index                | sort key for the listing                   | | showmsg  | log                  | show full commit messages                  |
diff --git a/README.txt b/README.txt
index 55f33de..d19950e 100644
--- a/README.txt
+++ b/README.txt
@@ -9,45 +9,40 @@ Installation
 ------------
 
 Building cgit involves building a proper version of Git. How to do this depends
-on how you obtained the cgit sources:
+on how you obtained the cgit sources.
 
-a) If you're working in a cloned cgit repository, you first need to initialize
-and update the Git submodule:
+In a cloned cgit repository, first initialize and update the Git submodule.
 
     $ git submodule init     # register the Git submodule in .git/config
     $ $EDITOR .git/config    # if you want to specify a different url for git
     $ git submodule update   # clone/fetch and checkout correct git version
 
-b) If you're building from a cgit tarball, you can download a proper git version
-like this:
+From a cgit tarball, download a proper git version instead.
 
     $ make get-git
 
-When either a) or b) has been performed, you can build and install cgit like
-this:
+With the Git tree in place, build and install cgit.
 
     $ make
     $ sudo make install
 
-This will install `cgit.cgi` and `cgit.css` into `/var/www/htdocs/cgit`. You can
-configure this location (and a few other things) by providing a `cgit.conf` file
-(see the Makefile for details).
+This installs cgit.cgi and cgit.css into /var/www/htdocs/cgit. The location and
+a few other things can be changed by providing a cgit.conf file, see the
+Makefile for details.
 
 The only required library is zlib. cgit builds without OpenSSL or libcurl, so no
 development packages for those are needed.
 
-Lua is optional and only powers the lua: filter extensions (the filters in
-custom/extensions/). A plain build auto-detects a Lua through pkg-config,
-preferring LuaJIT, and falls back to a Lua-less binary when none is found.
-
-To pin an implementation:
+Lua is optional and only powers the lua: filter extensions, the filters in
+custom/extensions/. A plain build auto-detects a Lua through pkg-config,
+preferring LuaJIT, and falls back to a Lua-less binary when none is found. To
+pin an implementation, name its pkg-config module.
 
     $ make LUA_PKGCONFIG=lua5.4
 
 Acceptable LUA_PKGCONFIG values include "luajit", "lua", "lua5.4", "lua5.3",
-"lua5.2" and "lua5.1".
-
-To build without Lua, so the binary needs no Lua at runtime:
+"lua5.2" and "lua5.1". To build without Lua, so the binary needs no Lua at
+runtime, turn it off.
 
     $ make NO_LUA=1
 
@@ -56,32 +51,30 @@ Setup
 -----
 
 cgit is a CGI program. Complete, commented configurations for nginx, Apache and
-lighttpd live in `custom/servers/`, each explaining how that server routes
+lighttpd live in custom/servers/, each explaining how that server routes
 requests to the binary and serves the static assets off disk.
 
-At runtime cgit reads `/etc/cgitrc` for its options and for the list of
+At runtime cgit reads /etc/cgitrc for its options and for the list of
 repositories to display. A fully commented starting point with every option at
-its default is in `custom/cgitrc`, and `MANUAL.txt` documents each option in
-full.
+its default is in custom/cgitrc, and MANUAL.txt documents each option in full.
 
 
 Filter extensions
 -----------------
 
-The optional Lua filters in `custom/extensions/` mostly need extra Lua modules,
+The optional Lua filters in custom/extensions/ mostly need extra Lua modules,
 and each script's header lists the exact install commands for its own.
 
-* The auth filters (`auth-file.lua`, `auth-inline.lua`) need `luaossl` and
-  `luaposix`.
-* The email filters (`email-gravatar.lua`, `email-libravatar.lua`) need
-  `luaossl`.
-* The syntax highlighter (`syntax-highlight.lua`) needs `lpeg` and a Scintillua
+* The auth filters, auth-file.lua and auth-inline.lua, need luaossl and
+  luaposix.
+* The email filters, email-gravatar.lua and email-libravatar.lua, need luaossl.
+* The syntax highlighter, syntax-highlight.lua, needs lpeg and a Scintillua
   lexer set.
-* The about-page renderer (`about-render.lua`) needs `lpeg` for markdown and man
+* The about-page renderer, about-render.lua, needs lpeg for markdown and man
   pages. Plain text needs only Lua.
-* `link-commits.lua` and `link-trailers.lua` need nothing beyond Lua itself.
+* link-commits.lua and link-trailers.lua need nothing beyond Lua itself.
 
-`luaossl` has no Lua 5.5 build, so build cgit against 5.1 to 5.4 if you use the
+luaossl has no Lua 5.5 build, so build cgit against 5.1 to 5.4 if you use the
 auth or email filters.
 
 
@@ -115,7 +108,7 @@ one, where a value of all marks the few not tied to particular pages.
 | id2      | diff patch rawdiff   | second object of a diff, paired with id    |
 | ofs      | index log refs stats | offset into a paged listing                |
 | path     | all                  | restrict the page to one path              |
-| q        | log                  | the search term                            |
+| q        | log                  | the search term, matched literally         |
 | qt       | log                  | one of grep, author, committer or range    |
 | s        | index                | sort key for the listing                   |
 | showmsg  | log                  | show full commit messages                  |