Trim README and fold in the author credits

1 file changed, 52 insertions, 122 deletions

diff --git a/README.txt b/README.txtindex 5b5d2dd..bba4a46 100644--- a/README.txt+++ b/README.txt@@ -33,85 +33,43 @@ 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). -Lua is optional and only powers the lua: filter extensions (authentication,-email and commit-message 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. Acceptable values are generally "luajit",-"lua", "lua5.4", "lua5.3", "lua5.2" and "lua5.1".+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:      $ 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:      $ make NO_LUA=1  -Previewing locally---------------------cgit is a CGI program, so trying it out normally means configuring a web server.-For development there is a small dependency-free preview server at-`tools/serve.py` that runs the built binary and serves the static assets. It-needs only Python 3.--    $ python3 tools/serve.py --config /path/to/cgitrc --port 8080--It is a development aid and is not meant to face the internet.---Tests+Setup ----- -The suite in tests/ is built on the test library in the bundled Git tree, the-same harness Git uses for its own suite, one self-contained tNNNN-*.sh script-per area. Run it from the top level, which builds cgit and the bundled Git-tree before anything runs.--    $ make test--Once those are built, a single script runs directly from tests/, where -v-shows each check and -i stops at the first failure. The full option list-lives in vendor/git/t/README, and options for a run through make go in-CGIT_TEST_OPTS, where --valgrind runs every cgit invocation under valgrind.--    $ cd tests && ./t0104-tree.sh -v--The numbering walks outward, t000x for the ground the suite stands on, t01xx-for page content, t02xx for features that cut across pages, t03xx for-security regressions, t04xx for the helper tools under tools/ and t05xx for-the extensions under custom/extensions, each pairing unit checks under a-standalone Lua with a run through cgit itself. A failing script leaves its-trash directory behind under tests/trash/ with the pages it was looking at, and-scripts skip rather than fail when a helper program or Lua module is missing,-saying so in their output.--A new script takes the next free number, needs the executable bit and is-picked up with no further wiring. Three traps are worth knowing. The cgitrc-that tests/setup.sh writes enables the cache, so a test rendering one URL-under two configs needs a config of its own with cache-size=0. A bare plus in-a cgit_url argument decodes to a space, so the foo+bar fixture repository is-written foo%2bbar. And a log page echoes the search query back inside an-input value, so an assertion that a commit is absent should match the subject-link, written as ">commit 2</a>", rather than the bare text.---Dependencies---------------* zlib-* optional: luajit or lua, most reliably used when pkg-config is available+cgit is a CGI program. Complete, commented configurations for nginx, Apache and+lighttpd live in `custom/servers/`, each explaining how that server routes+requests to the binary and serves the static assets off disk. -cgit builds without OpenSSL or libcurl, so no development packages for those are-needed.+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.   Filter extensions ----------------- -The optional Lua filters in `custom/extensions/` need extra Lua modules. Each-script's header lists the exact install commands for its own dependencies.+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`.@@ -119,20 +77,12 @@ script's header lists the exact install commands for its own dependencies.   `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 pages. Plain text needs only Lua.+* The about-page renderer (`about-render.lua`) needs `lpeg` for markdown and man+  pages. Plain text needs only Lua.+* `link-commits.lua` needs nothing beyond Lua itself. -These filters target Lua 5.1 through 5.4 and LuaJIT. `luaossl` has no Lua 5.5-build, so build cgit against 5.1 to 5.4 if you use the auth or email filters.-`link-commits.lua` needs nothing beyond Lua itself.---Web server configuration---------------------------cgit is a CGI program. Complete, commented configurations for nginx, Apache and-lighttpd live in `custom/servers/`, each explaining how that server routes-requests to the binary and serves the static assets off disk.+`luaossl` has no Lua 5.5 build, so build cgit against 5.1 to 5.4 if you use the+auth or email filters.   URLs and query parameters@@ -142,11 +92,7 @@ cgit serves every page from one CGI program, so a url names the repository, the page and a path inside that page. There are two forms and they carry the same information. With virtual-root set, a request is a path, written as /<repo>/<page>/<path> with anything else as a query string. Without it, the-whole request lives in the query string as ?url=<repo>/<page>/<path>, which is-the form the test suite uses. In the path form the first extra argument opens-the query string with a question mark, and in the url= form it continues the-existing one with an ampersand, which is why links in the two forms are spelled-differently.+whole request lives in the query string as ?url=<repo>/<page>/<path>.  The page name is the second element and is one of about, atom, blame, blob, commit, diff, log, patch, plain, rawdiff, refs, snapshot, stats, summary, tag or@@ -160,27 +106,27 @@ plus decodes to a space. Every parameter is optional. The pages column names the pages that read each one, where a value of all marks the few not tied to particular pages. -+----------+----------------------+---------------------------------------------+-| param    | pages                | description                                 |-+----------+----------------------+---------------------------------------------+-| url      | all                  | repository, page and path in one value      |-| h        | all                  | the branch or ref to read                   |-| id       | all                  | pin the page to one commit or object        |-| id2      | diff patch rawdiff   | the 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                             |-| qt       | log                  | one of grep, author, committer or range     |-| s        | index                | sort key for the listing                    |-| showmsg  | log                  | show full commit messages                   |-| period   | stats                | the statistics window, one of w, m, q or y  |-| dt       | diff commit          | diff type, unified, side by side or raw     |-| ss       | diff commit          | shorthand for the side by side diff         |-| all      | atom                 | include every ref rather than one branch    |-| context  | diff commit          | lines of context around a diff hunk         |-| ignorews | diff commit          | ignore whitespace when diffing              |-| follow   | log                  | follow a single path across renames         |-+----------+----------------------+---------------------------------------------+++----------+----------------------+--------------------------------------------++| param    | pages                | description                                |++----------+----------------------+--------------------------------------------++| url      | all                  | repository, page and path in one value     |+| h        | all                  | the branch or ref to read                  |+| id       | all                  | pin the page to one commit or object       |+| 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                            |+| qt       | log                  | one of grep, author, committer or range    |+| s        | index                | sort key for the listing                   |+| showmsg  | log                  | show full commit messages                  |+| period   | stats                | the statistics window, one of w, m, q or y |+| dt       | diff commit          | diff type, unified, side by side or raw    |+| ss       | diff commit          | shorthand for the side by side diff        |+| all      | atom                 | include every ref rather than one branch   |+| context  | diff commit          | lines of context around a diff hunk        |+| ignorews | diff commit          | ignore whitespace when diffing             |+| follow   | log                  | follow a single path across renames        |++----------+----------------------+--------------------------------------------+  A few endpoints are not ordinary pages. The snapshot page takes a filename rather than a ref, so /demo/snapshot/demo-1.0.tar.gz names both the ref and the@@ -209,26 +155,10 @@ Some worked examples, in the url= form.     ?url=demo/atom&h=main              the commit feed for a branch  -Runtime configuration------------------------The file `/etc/cgitrc` is read by cgit before handling a request. In addition to-runtime parameters, this file may also contain a list of repositories displayed-by cgit (see `MANUAL.txt` for further details). A fully commented starting point-with every option at its default is in `custom/cgitrc`.---The cache------------When cgit is invoked it looks for a cache file matching the request and returns-it to the client. If no such cache file exists (or if it has expired), the-content for the request is written into the proper cache file before the file is-returned.--If the cache file has expired but cgit is unable to obtain a lock for it, the-stale cache file is returned to the client. This is done to favour page-throughput over page freshness.+Credits+------- -The generated content contains the complete response to the client, including-the HTTP headers.+cgit was created by Lars Hjemli and maintained upstream for many years, most+recently by Jason A. Donenfeld. This repository is an independent fork that+builds on their work. They are not maintainers of this fork and are not+responsible for it.
diff --git a/README.txt b/README.txt
index 5b5d2dd..bba4a46 100644
--- a/README.txt
+++ b/README.txt
@@ -33,85 +33,43 @@ 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).
 
-Lua is optional and only powers the lua: filter extensions (authentication,
-email and commit-message 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. Acceptable values are generally "luajit",
-"lua", "lua5.4", "lua5.3", "lua5.2" and "lua5.1".
+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:
 
     $ 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:
 
     $ make NO_LUA=1
 
 
-Previewing locally
-------------------
-
-cgit is a CGI program, so trying it out normally means configuring a web server.
-For development there is a small dependency-free preview server at
-`tools/serve.py` that runs the built binary and serves the static assets. It
-needs only Python 3.
-
-    $ python3 tools/serve.py --config /path/to/cgitrc --port 8080
-
-It is a development aid and is not meant to face the internet.
-
-
-Tests
+Setup
 -----
 
-The suite in tests/ is built on the test library in the bundled Git tree, the
-same harness Git uses for its own suite, one self-contained tNNNN-*.sh script
-per area. Run it from the top level, which builds cgit and the bundled Git
-tree before anything runs.
-
-    $ make test
-
-Once those are built, a single script runs directly from tests/, where -v
-shows each check and -i stops at the first failure. The full option list
-lives in vendor/git/t/README, and options for a run through make go in
-CGIT_TEST_OPTS, where --valgrind runs every cgit invocation under valgrind.
-
-    $ cd tests && ./t0104-tree.sh -v
-
-The numbering walks outward, t000x for the ground the suite stands on, t01xx
-for page content, t02xx for features that cut across pages, t03xx for
-security regressions, t04xx for the helper tools under tools/ and t05xx for
-the extensions under custom/extensions, each pairing unit checks under a
-standalone Lua with a run through cgit itself. A failing script leaves its
-trash directory behind under tests/trash/ with the pages it was looking at, and
-scripts skip rather than fail when a helper program or Lua module is missing,
-saying so in their output.
-
-A new script takes the next free number, needs the executable bit and is
-picked up with no further wiring. Three traps are worth knowing. The cgitrc
-that tests/setup.sh writes enables the cache, so a test rendering one URL
-under two configs needs a config of its own with cache-size=0. A bare plus in
-a cgit_url argument decodes to a space, so the foo+bar fixture repository is
-written foo%2bbar. And a log page echoes the search query back inside an
-input value, so an assertion that a commit is absent should match the subject
-link, written as ">commit 2</a>", rather than the bare text.
-
-
-Dependencies
-------------
-
-* zlib
-* optional: luajit or lua, most reliably used when pkg-config is available
+cgit is a CGI program. Complete, commented configurations for nginx, Apache and
+lighttpd live in `custom/servers/`, each explaining how that server routes
+requests to the binary and serves the static assets off disk.
 
-cgit builds without OpenSSL or libcurl, so no development packages for those are
-needed.
+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.
 
 
 Filter extensions
 -----------------
 
-The optional Lua filters in `custom/extensions/` need extra Lua modules. Each
-script's header lists the exact install commands for its own dependencies.
+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`.
@@ -119,20 +77,12 @@ script's header lists the exact install commands for its own dependencies.
   `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 pages. Plain text needs only Lua.
+* The about-page renderer (`about-render.lua`) needs `lpeg` for markdown and man
+  pages. Plain text needs only Lua.
+* `link-commits.lua` needs nothing beyond Lua itself.
 
-These filters target Lua 5.1 through 5.4 and LuaJIT. `luaossl` has no Lua 5.5
-build, so build cgit against 5.1 to 5.4 if you use the auth or email filters.
-`link-commits.lua` needs nothing beyond Lua itself.
-
-
-Web server configuration
-------------------------
-
-cgit is a CGI program. Complete, commented configurations for nginx, Apache and
-lighttpd live in `custom/servers/`, each explaining how that server routes
-requests to the binary and serves the static assets off disk.
+`luaossl` has no Lua 5.5 build, so build cgit against 5.1 to 5.4 if you use the
+auth or email filters.
 
 
 URLs and query parameters
@@ -142,11 +92,7 @@ cgit serves every page from one CGI program, so a url names the repository, the
 page and a path inside that page. There are two forms and they carry the same
 information. With virtual-root set, a request is a path, written as
 /<repo>/<page>/<path> with anything else as a query string. Without it, the
-whole request lives in the query string as ?url=<repo>/<page>/<path>, which is
-the form the test suite uses. In the path form the first extra argument opens
-the query string with a question mark, and in the url= form it continues the
-existing one with an ampersand, which is why links in the two forms are spelled
-differently.
+whole request lives in the query string as ?url=<repo>/<page>/<path>.
 
 The page name is the second element and is one of about, atom, blame, blob,
 commit, diff, log, patch, plain, rawdiff, refs, snapshot, stats, summary, tag or
@@ -160,27 +106,27 @@ plus decodes to a space.
 Every parameter is optional. The pages column names the pages that read each
 one, where a value of all marks the few not tied to particular pages.
 
-+----------+----------------------+---------------------------------------------+
-| param    | pages                | description                                 |
-+----------+----------------------+---------------------------------------------+
-| url      | all                  | repository, page and path in one value      |
-| h        | all                  | the branch or ref to read                   |
-| id       | all                  | pin the page to one commit or object        |
-| id2      | diff patch rawdiff   | the 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                             |
-| qt       | log                  | one of grep, author, committer or range     |
-| s        | index                | sort key for the listing                    |
-| showmsg  | log                  | show full commit messages                   |
-| period   | stats                | the statistics window, one of w, m, q or y  |
-| dt       | diff commit          | diff type, unified, side by side or raw     |
-| ss       | diff commit          | shorthand for the side by side diff         |
-| all      | atom                 | include every ref rather than one branch    |
-| context  | diff commit          | lines of context around a diff hunk         |
-| ignorews | diff commit          | ignore whitespace when diffing              |
-| follow   | log                  | follow a single path across renames         |
-+----------+----------------------+---------------------------------------------+
++----------+----------------------+--------------------------------------------+
+| param    | pages                | description                                |
++----------+----------------------+--------------------------------------------+
+| url      | all                  | repository, page and path in one value     |
+| h        | all                  | the branch or ref to read                  |
+| id       | all                  | pin the page to one commit or object       |
+| 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                            |
+| qt       | log                  | one of grep, author, committer or range    |
+| s        | index                | sort key for the listing                   |
+| showmsg  | log                  | show full commit messages                  |
+| period   | stats                | the statistics window, one of w, m, q or y |
+| dt       | diff commit          | diff type, unified, side by side or raw    |
+| ss       | diff commit          | shorthand for the side by side diff        |
+| all      | atom                 | include every ref rather than one branch   |
+| context  | diff commit          | lines of context around a diff hunk        |
+| ignorews | diff commit          | ignore whitespace when diffing             |
+| follow   | log                  | follow a single path across renames        |
++----------+----------------------+--------------------------------------------+
 
 A few endpoints are not ordinary pages. The snapshot page takes a filename
 rather than a ref, so /demo/snapshot/demo-1.0.tar.gz names both the ref and the
@@ -209,26 +155,10 @@ Some worked examples, in the url= form.
     ?url=demo/atom&h=main              the commit feed for a branch
 
 
-Runtime configuration
----------------------
-
-The file `/etc/cgitrc` is read by cgit before handling a request. In addition to
-runtime parameters, this file may also contain a list of repositories displayed
-by cgit (see `MANUAL.txt` for further details). A fully commented starting point
-with every option at its default is in `custom/cgitrc`.
-
-
-The cache
----------
-
-When cgit is invoked it looks for a cache file matching the request and returns
-it to the client. If no such cache file exists (or if it has expired), the
-content for the request is written into the proper cache file before the file is
-returned.
-
-If the cache file has expired but cgit is unable to obtain a lock for it, the
-stale cache file is returned to the client. This is done to favour page
-throughput over page freshness.
+Credits
+-------
 
-The generated content contains the complete response to the client, including
-the HTTP headers.
+cgit was created by Lars Hjemli and maintained upstream for many years, most
+recently by Jason A. Donenfeld. This repository is an independent fork that
+builds on their work. They are not maintainers of this fork and are not
+responsible for it.