Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
cha-mailcap(5)		   Mailcap support in Chawan		cha-mailcap(5)

Mailcap
       By  default,  Chawan's  buffers	only  handle HTML and plain text.  The
       mailcap file can	be used	to view	other file formats using external com-
       mands, or to convert them to HTML/plain text before displaying them  in
       Chawan.

       Note  that  Chawan's 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
       cha-mime.types(5) documentation for details.

       For   an	 exact	description  of	 the  mailcap  format,	see  RFC  1524
       <https://www.rfc-editor.org/rfc/rfc1524>.

   Search path
       The search path for mailcap files is set	by the configuration  variable
       external.mailcap.  This matches the recommended path in the RFC:

	      $HOME/.mailcap:/etc/mailcap:/usr/etc/mailcap:/usr/local/etc/mailcap

       By default, mailcap entries are only executed if	the user types r (run)
       after the prompt.  Other	options	are to view the	file with t (text), or
       to save the file	with s.

       If a capital letter is typed (e.g. press	shift and type R), then	a cor-
       responding   entry   is	appended  to  external.auto-mailcap  (default:
       ~/.chawan/auto.mailcap,	or   ~/.config/chawan/config.toml   with   XDG
       basedirs).  (T)ext and (S)ave may also be used to append	entries	corre-
       sponding	to the other display options.

       Entries	in  auto-mailcap  are  automatically executed, so it is	recom-
       mended to add your Chawan-specific entries there	(or  just  set	it  to
       your personal mailcap file).

   Format
       Chawan  adheres	to the format described	in RFC 1524, with a few	exten-
       sions.

       Note that text/html and text/plain entries are ignored.

   Templating
       %s, %t, and named content type fields like %{charset} work as described
       in the standard.

       If no quoting is	applied, Chawan	quotes	the  templates	automatically.
       (This works with	$(command substitutions) as well.)

       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 compati-
       ble with	other implementations.	As an  alternative,  the  $MAILCAP_URL
       environment variable is set to the same value.

   Fields
       The test, nametemplate, needsterminal and copiousoutput fields are rec-
       ognized.	 The non-standard x-htmloutput,	x-ansioutput, x-saveoutput and
       x-needsstyle extension fields are also recognized.

       • When  the  test  named	 field is specified, the mailcap entry is only
	 used if the test command returns 0.
       Warning:	as of now, %s does not work with test; test named fields  with
       a %s template are skipped, and no data is piped into test commands.

       • copiousoutput	makes  Chawan redirect the output of the external com-
	 mand's	output into a new buffer.  If  either  x-htmloutput  or	 x-an-
	 sioutput is defined too, then it is ignored.

       • The  x-htmloutput  extension field behaves the	same as	copiousoutput,
	 but makes Chawan interpret the	command's output as HTML.

       • x-ansioutput pipes the	output through the "text/x-ansi" content  type
	 handler,  so  that  ANSI colors, formatting, etc.  are	displayed cor-
	 rectly.

       • x-saveoutput prompts the user to save the entry's output in a file.

       • x-needsstyle forces CSS to be processed for the specific  type,  even
	 if styling is disabled	in the config.	Only useful when combined with
	 x-htmloutput.

       • needsterminal hands over control of the terminal to the command while
	 it is running.	 Note: as of now, needsterminal	does nothing if	either
	 copiousoutput or x-htmloutput is specified.

       • For a description of nametemplate, see	the RFC.

   Examples
       I  recommend  placing  entries  in  ~/.chawan/auto.mailcap  (or ~/.con-
       fig/chawan/auto.mailcap if you use XDG basedirs).

	      #	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

	      #	epub ->	HTML using pandoc. (Again, don't 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 \
	      --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

   See also
       cha(1)

								cha-mailcap(5)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=cha-mailcap&sektion=5&manpath=FreeBSD+Ports+15.0>

home | help