preconv.1

   1 .\"     $Id: preconv.1,v 1.2 2011/05/26 12:14:46 kristaps Exp $
   2 .\"
   3 .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .Dd $Mdocdate: May 26 2011 $
  18 .Dt PRECONV 1
  19 .Os
  20 .Sh NAME
  21 .Nm preconv
  22 .Nd recode multibyte UNIX manuals
  23 .Sh SYNOPSIS
  24 .Nm preconv
  25 .Op Fl D Ar enc
  26 .Op Fl e Ar enc
  27 .Op Ar file
  28 .Sh DESCRIPTION
  29 The
  30 .Nm
  31 utility recodes multibyte
  32 .Ux
  33 manual files into
  34 .Xr mandoc 1
  35 .Po
  36 or other troff system supporting the
  37 .Sq \e[uNNNN]
  38 escape sequence
  39 .Pc
  40 input.
  41 Its arguments are as follows:
  42 .Bl -tag -width Ds
  43 .It Fl D Ar enc
  44 The default encoding.
  45 This is case-insensitive.
  46 See
  47 .Sx Algorithm
  48 and
  49 .Sx Encodings .
  50 .It Fl e Ar enc
  51 The document's encoding.
  52 This is case-insensitive.
  53 See
  54 .Sx Algorithm
  55 and
  56 .Sx Encodings .
  57 .It Ar file
  58 The input file.
  59 .El
  60 .Pp
  61 If
  62 .Ar file
  63 is not provided,
  64 .Nm
  65 accepts standard input.
  66 Output is written to standard output.
  67 Unicode characters in the ASCII range are printed as regular ASCII
  68 characters; those above this range are printed using the
  69 .Sq \e[uNNNN]
  70 format documented in
  71 .Xr mandoc_char 7 .
  72 .Pp
  73 If input bytes are improperly formed in the current encoding, they're
  74 passed unmodified to standard output.
  75 .Ss Encodings
  76 The
  77 .Nm
  78 utility accepts the
  79 .Ar utf\-8 ,
  80 .Ar us\-ascii ,
  81 and
  82 .Ar latin\-1
  83 encodings as arguments to
  84 .Fl D Ar enc
  85 or
  86 .Fl e Ar enc .
  87 .Ss Algorithm
  88 An encoding is chosen according to the following steps:
  89 .Bl -enum
  90 .It
  91 From the argument passed to
  92 .Fl e Ar enc .
  93 .It
  94 If a BOM exists, utf\-8 encoding is selected.
  95 .It
  96 From the argument passed to
  97 .Fl D Ar enc .
  98 .It
  99 If all else fails, Latin\-1 is used.
 100 .El
 101 .\" .Sh IMPLEMENTATION NOTES
 102 .\" Not used in OpenBSD.
 103 .\" .Sh RETURN VALUES
 104 .\" For sections 2, 3, & 9 only.
 105 .\" .Sh ENVIRONMENT
 106 .\" For sections 1, 6, 7, & 8 only.
 107 .\" .Sh FILES
 108 .Sh EXIT STATUS
 109 .Ex -std
 110 .\" .Sh EXAMPLES
 111 .\" .Sh DIAGNOSTICS
 112 .\" For sections 1, 4, 6, 7, & 8 only.
 113 .\" .Sh ERRORS
 114 .\" For sections 2, 3, & 9 only.
 115 .Sh SEE ALSO
 116 .Xr mandoc 1 ,
 117 .Xr mandoc_char 7
 118 .Sh STANDARDS
 119 The
 120 .Nm
 121 utility references the US-ASCII character set standard, ANSI_X3.4\-1968;
 122 the Latin\-1 character set standard, ISO/IEC 8859\-1:1998; the UTF\-8
 123 character set standard; and UCS (Unicode), ISO/IEC 10646.
 124 .Sh HISTORY
 125 The
 126 .Nm
 127 utility first appeared in the GNU troff
 128 .Pq Dq groff
 129 system in December 2005, authored by Tomohiro Kubota and Werner
 130 Lemberg.
 131 The implementation that is part of the
 132 .Xr mandoc 1
 133 utility appeared in May 2011.
 134 .Sh AUTHORS
 135 The
 136 .Nm
 137 utility was written by
 138 .An Kristaps Dzonsons Aq kristaps@bsd.lv .
 139 .\" .Sh CAVEATS
 140 .\" .Sh BUGS
 141 .\" .Sh SECURITY CONSIDERATIONS
 142 .\" Not used in OpenBSD.