.\""Copyright (c) 2004 Apple Computer, Inc. All Rights Reserved.
.Dd September 9, 2004
.Dt TEXTUTIL 1
.Os "macOS"
.Sh NAME
.Nm textutil
.Nd text utility
.Sh SYNOPSIS
.Nm
.Op command_option
.Op other_options
.Ar file ...
.Sh DESCRIPTION
.Nm
can be used to manipulate text files of various formats, using the mechanisms provided by the Cocoa text system.
.Pp
The first argument indicates the operation to perform, one of:
.Bl -tag -width "-convert fmt"
.It Fl help
Show the usage information for the command and exit.
This is the default command option if none is specified.
.It Fl info
Display information about the specified files.
.It Fl convert Ar fmt
Convert the specified files to the indicated format and write each one back to the file system. 
.It Fl cat Ar fmt
Read the specified files, concatenate them, and write the result out as a single file in the indicated format.
.Bl -tag -width "fmt is one of:"
.It \fIfmt\fR is one of: 
.Sy txt ,
.Sy html ,
.Sy rtf ,
.Sy rtfd ,
.Sy doc ,
.Sy docx ,
.Sy wordml ,
.Sy odt ,
or
.Sy webarchive
.El
.El
.Pp
There are some additional options for general use:
.Bl -tag -width "-extension ext"
.It Fl extension Ar ext
Specify an extension to be used for output files (by default, the extension will be determined from the format).
.It Fl output Ar path
Specify the file name to be used for the first output file.
.It Fl stdin
Specify that input should be read from stdin rather than from files.
.It Fl stdout
Specify that the first output file should go to stdout.
.It Fl encoding Ar IANA_name | Ar NSStringEncoding
Specify the encoding to be used for plain text or HTML output files (by default, the output encoding will be UTF-8).  NSStringEncoding refers to one of the numeric values recognized by NSString.  IANA_name refers to an IANA character set name as understood by CFString.  The operation will fail if the file cannot be converted to the specified encoding.
.It Fl inputencoding Ar IANA_name | Ar NSStringEncoding
Force all plain text input files to be interpreted using the specified encoding (by default, a file's encoding will be determined from its BOM).  The operation will fail if the file cannot be interpreted using the specified encoding.
.It Fl format Ar fmt
Force all input files to be interpreted using the indicated format (by default, a file's format will be determined from its contents).
.It Fl font Ar font
Specify the name of the font to be used for converting plain to rich text.
.It Fl fontsize Ar size
Specify the size in points of the font to be used for converting plain to rich text.
.It Fl -
Specify that all further arguments are file names.
.El
.Pp
There are some additional options for HTML and WebArchive files:
.Bl -tag -width "-prefixspaces n"
.It Fl noload
Do not load subsidiary resources.
.It Fl nostore
Do not write out subsidiary resources.
.It Fl baseurl Ar url
Specify a base URL to be used for relative URLs.
.It Fl timeout Ar t
Specify the time in seconds to wait for resources to load.
.It Fl textsizemultiplier Ar x
Specify a numeric factor by which to multiply font sizes.
.It Fl excludedelements Ar (tag1, tag2, ...)
Specify which HTML elements should not be used in generated HTML (the list should be a single argument, and so will usually need to be quoted in a shell context).
.It Fl prefixspaces Ar n
Specify the number of spaces by which to indent nested elements in generated HTML (default is 2).
.El
.Pp
There are some additional options for treating metadata:
.Bl -tag -width "-company val"
.It Fl strip
Do not copy metadata from input files to output files.
.It Fl title Ar val
Specify the title metadata attribute for output files.
.It Fl author Ar val
Specify the author metadata attribute for output files.
.It Fl subject Ar val
Specify the subject metadata attribute for output files.
.It Fl keywords Ar (val1, val2, ...)
Specify the keywords metadata attribute for output files (the list should be a single argument, and so will usually need to be quoted in a shell context).
.It Fl comment Ar val
Specify the comment metadata attribute for output files.
.It Fl editor Ar val
Specify the editor metadata attribute for output files.
.It Fl company Ar val
Specify the company metadata attribute for output files.
.It Fl creationtime Ar yyyy-mm-ddThh:mm:ssZ
Specify the creation time metadata attribute for output files.
.It Fl modificationtime Ar yyyy-mm-ddThh:mm:ssZ
Specify the modification time metadata attribute for output files.
.El
.Pp
.Sh EXAMPLES
    textutil -info foo.rtf
.Pp
displays information about foo.rtf.
.Pp
    textutil -convert html foo.rtf
.Pp
converts foo.rtf into foo.html.  
.Pp
    textutil -convert rtf -font Times -fontsize 10 foo.txt
.Pp
converts foo.txt into foo.rtf, using Times 10 for the font.
.Pp
    textutil -cat html -title "Several Files" -output index.html *.rtf
.Pp
loads all RTF files in the current directory, concatenates their contents, and writes the result out as index.html with the HTML title set to "Several Files".
.Pp
.Sh DIAGNOSTICS
The
.Nm
command exits 0 on success, and 1 on failure.
.Sh CAUTIONS
Some options may require a connection to the window server.
.Sh HISTORY
The
.Nm
command first appeared in Mac OS X 10.4.