From b01604c3b96fbdf165d8cabab97de9f2f584f555 Mon Sep 17 00:00:00 2001 From: Bryce Kwon Date: Sat, 31 Oct 2026 13:13:18 -0700 Subject: Leave the filter contracts to the Filter API Each global filter entry restated the arguments and the stdin and stdout contract that "Filter API" gives in full. commit-filter and email-filter now name their shipped filters, as the others do. --- MANUAL.txt | 61 ++++++++++++++++++++++++++----------------------------------- 1 file changed, 26 insertions(+), 35 deletions(-) diff --git a/MANUAL.txt b/MANUAL.txt index b00b42a..6cb68ae 100644 --- a/MANUAL.txt +++ b/MANUAL.txt @@ -18,15 +18,11 @@ Global settings about-filter:: Specifies a command which will be invoked to format the content of about - pages (both top-level and for each repository). The command will get the - content of the about-file on its stdin and the name of the file, with - the tree url its links resolve against, as arguments, and the stdout - from the command will be included verbatim on the about page. Default - value: none. When no about-filter is set, a repository's readme is - escaped and served as plain text, while root-readme is included - verbatim. A bundled Lua filter, about-render.lua, renders markdown, man - pages and plain text when about-filter points at it. See also: "Filter - API". + pages (both top-level and for each repository). When no about-filter is + set, a repository's readme is escaped and served as plain text. A + bundled Lua filter, about-render.lua, renders markdown, man pages and + plain text when about-filter points at it. Default value: none. See + also: "Filter API". age-file:: Specifies a path, relative to each repository path, which can be used to @@ -37,9 +33,8 @@ age-file:: auth-filter:: Specifies a command that will be invoked for authenticating repository - access. Receives 12 arguments, with request data on stdin and its answer - on stdout, as described under "Filter API". If no auth-filter is - specified, no authentication is performed. Default value: none. + access. If no auth-filter is specified, no authentication is performed. + Default value: none. See also: "Filter API". branch-sort:: Flag which, when set to "age", enables date ordering in the branch ref @@ -113,10 +108,11 @@ clone-url:: "Macro expansion", "Filter API". commit-filter:: - Specifies a command which will be invoked to format commit messages. The - command will get the message on its stdin, and the stdout from the - command will be included verbatim as the commit message, which is one - way to link a bug tracker. Default value: none. See also: "Filter API". + Specifies a command which will be invoked to format commit messages, for + example to link a bug tracker. A ready filter linking object names and + configurable text references ships as + custom/extensions/link-commits.lua. Default value: none. See also: + "Filter API". commit-sort:: Flag which, when set to "date", enables strict date ordering in the @@ -147,10 +143,10 @@ date-format:: email-filter:: Specifies a command which will be invoked to format names and email address of committers, authors, and taggers, as represented in various - places throughout the cgit interface. This command will receive an email - address and an origin page string as its command line arguments, and the - text to format on stdin. It is to write the formatted text back out onto - stdout. Default value: none. See also: "Filter API". + places throughout the cgit interface. Ready filters adding a Gravatar or + Libravatar icon ship as custom/extensions/email-gravatar.lua and + custom/extensions/email-libravatar.lua. Default value: none. See also: + "Filter API". embedded:: Flag which, when set to "1", makes cgit generate a html fragment @@ -522,12 +518,9 @@ snapshots:: source-filter:: Specifies a command which will be invoked to format plaintext blobs in - the tree and blame pages. The command will get the blob content on its - stdin and the name of the blob as its only command line argument. The - stdout from the command will be included verbatim as the blob contents, - which is how syntax highlighting is done. When no source-filter is - configured, cgit serves the text plain. A ready syntax highlighter using - the Scintillua lexer collection ships as + the tree and blame pages, which is how syntax highlighting is done. When + no source-filter is configured, cgit serves the text plain. A ready + syntax highlighter using the Scintillua lexer collection ships as custom/extensions/syntax-highlight.lua, see the comments in that file for its dependencies. Default value: none. See also: "Filter API". @@ -552,15 +545,13 @@ summary-tags:: trailer-filter:: Specifies a command which will be invoked to format the value of a - commit trailer when "enable-commit-trailers" is set. The command will - get the trailer key and an origin page string as its command line - arguments and the value on its stdin, and the stdout from the command - will be included verbatim as the value. Trailers whose value is a name - and email address, such as Signed-off-by, go through the email-filter - instead, and when no trailer-filter is configured the remaining values - go through the commit-filter. A ready filter linking Fixes, Reverts, - Closes, Bug and URL values ships as custom/extensions/link-trailers.lua. - Default value: none. See also: "Filter API". + commit trailer when "enable-commit-trailers" is set. Trailers whose + value is a name and email address, such as Signed-off-by, go through + the email-filter instead, and when no trailer-filter is configured the + remaining values go through the commit-filter. A ready filter linking + Fixes, Reverts, Closes, Bug and URL values ships as + custom/extensions/link-trailers.lua. Default value: none. See also: + "Filter API". trust-scan-config:: Flag which, when set to "1", honours every setting in a repository's own -- cgit