doc: include auto-generated manpages in repository

The 100kb or so doesn't hurt as much as not having manual pages at all
without pandoc (+ not auto-updating them through make all) does.

1 files changed, 160 insertions, 0 deletions

diff --git a/doc/cha-mailcap.5 b/doc/cha-mailcap.5
new file mode 100644
index 00000000..9972b63a
--- /dev/null
+++ b/doc/cha-mailcap.5
@@ -0,0 +1,160 @@
+.\" Automatically generated by Pandoc 2.17.1.1
+.\"
+.\" Define V font for inline verbatim, using C font in formats
+.\" that render this, and otherwise B font.
+.ie "\f[CB]x\f[]"x" \{\
+. ftr V B
+. ftr VI BI
+. ftr VB B
+. ftr VBI BI
+.\}
+.el \{\
+. ftr V CR
+. ftr VI CI
+. ftr VB CB
+. ftr VBI CBI
+.\}
+.TH "cha-mailcap" "5" "" "" "Mailcap support in Chawan"
+.hy
+.SH Mailcap
+.PP
+Chawan\[cq]s buffers can only handle HTML and plain text.
+To make Chawan recognize other file formats, the mailcap file format can
+be used.
+.PP
+Note that Chawan\[cq]s default mime.types file only recognizes a few
+file extensions, which may result in your entries not being executed.
+Please consult the \f[B]cha-mime.types\f[R](5) documentation for
+details.
+.PP
+For an exact description of the mailcap format, see RFC
+1524 (https://www.rfc-editor.org/rfc/rfc1524).
+.SS Search path
+.PP
+The search path for mailcap files can be overridden using the
+configuration variable \f[V]external.mailcap\f[R].
+.PP
+By default, the only file checked by Chawan is \f[V]$HOME/.mailcap\f[R].
+.PP
+In the past, the full path from the specification was used.
+This was changed because mailcap files shipped with various systems are
+usually incompatible with the assumptions Chawan makes about mailcap
+file contents.
+You can restore the old/standard-recommended behavior by adding this to
+your config.toml:
+.IP
+.nf
+\f[C]
+mailcap = [
+\[dq]\[ti]/.mailcap\[dq],
+\[dq]/etc/mailcap\[dq],
+\[dq]/usr/etc/mailcap\[dq],
+\[dq]/usr/local/etc/mailcap\[dq]
+]
+\f[R]
+.fi
+.SS Format
+.PP
+Chawan tries to adhere to the format described in RFC 1524, with a few
+extensions.
+.SS Templating
+.PP
+%s, %t works as described in the standard.
+However, named content type fields (%{\&...}) only work with %{charset}
+as of now.
+(TODO: fix this.)
+.PP
+If no quoting is applied, Chawan will quote the templates automatically.
+(This works with $(command substitutions) as well.)
+.PP
+DEPRECATED:
+.PP
+Also, the non-standard template %u may be specified to get the original
+URL of the resource.
+Note that this is no longer recommended; instead, use the $MAILCAP_URL
+environment variable which is set to the same value before the execution
+of every mailcap command.
+.SS Fields
+.PP
+The \f[V]test\f[R], \f[V]nametemplate\f[R], \f[V]needsterminal\f[R] and
+\f[V]copiousoutput\f[R] fields are recognized.
+Additionally, the non-standard \f[V]x-htmloutput\f[R] and
+\f[V]x-ansioutput\f[R] extension fields are recognized too.
+.IP \[bu] 2
+When the \f[V]test\f[R] named field is specified, the mailcap entry is
+only used if the test command returns 0.
+Warning: as of now, \f[V]%s\f[R] does not work with \f[V]test\f[R];
+\f[V]test\f[R] named fields with a \f[V]%s\f[R] template are skipped.
+Additionally, no data is piped into \f[V]test\f[R] either.
+.IP \[bu] 2
+\f[V]copiousoutput\f[R] makes Chawan redirect the output of the external
+command into a new buffer.
+If either x-htmloutput or x-ansioutput is defined too, then it is
+ignored.
+.IP \[bu] 2
+The \f[V]x-htmloutput\f[R] extension field behaves the same as
+\f[V]copiousoutput\f[R], but makes Chawan interpret the command\[cq]s
+output as HTML.
+.IP \[bu] 2
+\f[V]x-ansioutput\f[R] makes Chawan pipe the output through the default
+\[lq]text/x-ansi\[rq] content type handler.
+This means that you get colors, formatting, etc.
+displayed with ANSI escape sequences.
+.IP \[bu] 2
+\f[V]needsterminal\f[R] hands over control of the terminal to the
+command while it is running.
+Note: as of now, \f[V]needsterminal\f[R] does nothing if either
+\f[V]copiousoutput\f[R] or \f[V]x-htmloutput\f[R] is specified.
+.IP \[bu] 2
+For a description of \f[V]nametemplate\f[R], see the RFC.
+Note however, that it does not work with test (since %s is not supported
+there).
+.SS Environment variables
+.PP
+As noted above, the $MAILCAP_URL variable is set to the URL of the
+target resource before the execution of the mailcap command.
+Backwards compatibility with mailcap agents that do not support this
+variable can be achieved through shell substitution,
+e.g.\ ${MAILCAP_URL:-string for when it is unsupported}.
+.PP
+Note that it is not recommended to set %s as the fallback, because it
+will force Chawan to download the entire file before displaying it even
+if it could have been piped into the command.
+.SS Note
+.PP
+Entries with a content type of text/html or text/plain are ignored.
+.SS Examples
+.IP
+.nf
+\f[C]
+# Note: these examples require an entry in mime.types that sets e.g. md as
+# the markdown content type.
+
+# Handle markdown files using pandoc.
+text/markdown; pandoc - -f markdown -t html -o -; x-htmloutput
+
+# Show syntax highlighting for JavaScript source files using bat.
+text/javascript; bat -f -l es6 --file-name ${MAILCAP_URL:-STDIN} -; x-ansioutput
+
+# Play music using mpv, and hand over control of the terminal until mpv exits.
+audio/*; mpv -; needsterminal
+
+# Play videos using mpv in the background, redirecting its standard output
+# and standard error to /dev/null.
+video/*; mpv -
+
+# Open docx files using LibreOffice Writer.
+application/vnd.openxmlformats-officedocument.wordprocessingml.document;lowriter %s
+# (Wow that was ugly.)
+
+# Display manpages using pandoc. (Make sure the mime type matches the one
+# set in your mime.types file for extensions .1, .2, .3, ...)
+application/x-troff-man;pandoc - -f man -t html -o -; x-htmloutput
+
+# Following entry will be ignored, as text/html is supported natively by Chawan.
+text/html; cha -dT text/html -I %{charset}; copiousoutput
+\f[R]
+.fi
+.SS See also
+.PP
+\f[B]cha\f[R](1)