.\" Automatically generated by Pandoc 3.7.0.1
.\"
.TH "CHA-MAILCAP" "5"
.SH Mailcap
By default, Chawan\(cqs buffers only handle HTML and plain text.
The \f[CR]mailcap\f[R] file can be used to view other file formats using
external commands, or to convert them to HTML/plain text before
displaying them in Chawan.
.PP
Note that Chawan\(cqs default mime.types file only recognizes a few file
extensions, which may result in your entries not being executed if your
system lacks an /etc/mime.types file.
Please consult the \f[B]cha\-mime.types\f[R](5) documentation for
details.
.PP
For an exact description of the mailcap format, see \c
.UR https://www.rfc-editor.org/rfc/rfc1524
RFC 1524
.UE \c
\&.
.SS Search path
The search path for mailcap files is set by the configuration variable
\f[CR]external.mailcap\f[R].
This matches the recommended path in the RFC:
.IP
.EX
$HOME/.mailcap:/etc/mailcap:/usr/etc/mailcap:/usr/local/etc/mailcap
.EE
.PP
By default, mailcap entries are only executed if the user types
\f[CR]r\f[R] (run) after the prompt.
Other options are to view the file with \f[CR]t\f[R] (text), or to save
the file with \f[CR]s\f[R].
.PP
If a capital letter is typed (e.g.\ press shift and type \f[CR]R\f[R]),
then a corresponding entry is appended to
\f[CR]external.auto\-mailcap\f[R] (default:
\f[CR]\(ti/.chawan/auto.mailcap\f[R], or
\f[CR]\(ti/.config/chawan/auto.mailcap\f[R] with XDG basedirs).
\f[CR](T)ext\f[R] and \f[CR](S)ave\f[R] may also be used to append
entries corresponding to the other display options.
.PP
Entries in auto\-mailcap are automatically executed, so it is
recommended to add your Chawan\-specific entries there (or just set it
to your personal mailcap file).
.SS Format
Chawan adheres to the format described in RFC 1524, with a few
extensions.
.PP
Note that text/html and text/plain entries are ignored.
.SS Templating
\f[CR]%s\f[R], \f[CR]%t\f[R], and named content type fields like
\f[CR]%{charset}\f[R] work as described in the standard.
.PP
If no quoting is applied, Chawan quotes the templates automatically.
(This works with $(command substitutions) as well.)
However, other software may misbehave on such templates, so it may be
better to assign them to a variable first.
.PP
The non\-standard template %u may be specified to get the original URL
of the resource.
This is a Netscape extension that may not be compatible with other
implementations.
As an alternative, the \f[CR]$MAILCAP_URL\f[R] environment variable is
set to the same value.
.SS Fields
The \f[CR]test\f[R], \f[CR]nametemplate\f[R], \f[CR]needsterminal\f[R]
and \f[CR]copiousoutput\f[R] fields are recognized.
The non\-standard \f[CR]x\-htmloutput\f[R], \f[CR]x\-ansioutput\f[R],
\f[CR]x\-saveoutput\f[R] and \f[CR]x\-needsstyle\f[R] extension fields
are also recognized.
.IP \(bu 2
When the \f[CR]test\f[R] named field is specified, the mailcap entry is
only used if the test command returns 0.
.RS 2
.PP
Warning: as of now, \f[CR]%s\f[R] does not work with \f[CR]test\f[R];
\f[CR]test\f[R] named fields with a \f[CR]%s\f[R] template are skipped,
and no data is piped into \f[CR]test\f[R] commands.
.RE
.IP \(bu 2
\f[CR]copiousoutput\f[R] makes Chawan redirect the output of the
external command\(cqs output into a new buffer.
If either x\-htmloutput or x\-ansioutput is defined too, then it is
ignored.
.IP \(bu 2
The \f[CR]x\-htmloutput\f[R] extension field behaves the same as
\f[CR]copiousoutput\f[R], but makes Chawan interpret the command\(cqs
output as HTML.
.IP \(bu 2
\f[CR]x\-ansioutput\f[R] pipes the output through the
\(lqtext/x\-ansi\(rq content type handler, so that ANSI colors,
formatting, etc.
are displayed correctly.
.IP \(bu 2
\f[CR]x\-saveoutput\f[R] prompts the user to save the entry\(cqs output
in a file.
.IP \(bu 2
\f[CR]x\-needsstyle\f[R] forces CSS to be processed for the specific
type, even if styling is disabled in the config.
Only useful when combined with \f[CR]x\-htmloutput\f[R].
.IP \(bu 2
\f[CR]x\-needsimage\f[R] forces images to be displayed in
\f[CR]x\-htmloutput\f[R], even if images are disabled.
.IP \(bu 2
\f[CR]needsterminal\f[R] hands over control of the terminal to the
command while it is running.
Note: as of now, \f[CR]needsterminal\f[R] does nothing if either
\f[CR]copiousoutput\f[R] or \f[CR]x\-htmloutput\f[R] is specified.
.IP \(bu 2
For a description of \f[CR]nametemplate\f[R], see the RFC.
.SS Examples
I recommend placing entries in \f[CR]\(ti/.chawan/auto.mailcap\f[R] (or
\f[CR]\(ti/.config/chawan/auto.mailcap\f[R] if you use XDG basedirs).
.IP
.EX
# 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 %u \-; 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

# 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

# epub \-> HTML using pandoc. (Again, don\(aqt forget to adjust mime.types.)
# We set http_proxy to keep it from downloading whatever through http/s.
application/epub+zip; http_proxy=localhost:0 pandoc \- \-f epub \(rs
\-\-embed\-resources \-\-standalone; x\-htmloutput

# Following entry will be ignored, as text/html is supported natively by Chawan.
text/html; cha \-dT text/html \-I %{charset}; copiousoutput
.EE
.SS See also
\f[B]cha\f[R](1)