contrib/mdocml/preconv.1

   1 .\"     $Id: preconv.1,v 1.7 2013/07/13 19:41:16 schwarze 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: July 13 2013 $
  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 .Pp
  42 By default, it parses from standard output, determining encoding as
  43 described in
  44 .Sx Algorithm .
  45 .Pp
  46 Its arguments are as follows:
  47 .Bl -tag -width Ds
  48 .It Fl D Ar enc
  49 The default encoding.
  50 .It Fl e Ar enc
  51 The document's encoding.
  52 .It Ar file
  53 The input file.
  54 .El
  55 .Pp
  56 The recoded input is written to standard output: Unicode characters in
  57 the ASCII range are printed as regular ASCII characters, while those
  58 above this range are printed using the
  59 .Sq \e[uNNNN]
  60 format documented in
  61 .Xr mandoc_char 7 .
  62 .Pp
  63 If input bytes are improperly formed in the current encoding, they're
  64 passed unmodified to standard output.
  65 For some encodings, such as UTF-8, unrecoverable input sequences will
  66 cause
  67 .Nm
  68 to stop processing and exit.
  69 .Ss Algorithm
  70 An encoding is chosen according to the following steps:
  71 .Bl -enum
  72 .It
  73 From the argument passed to
  74 .Fl e Ar enc .
  75 .It
  76 If a BOM exists, UTF\-8 encoding is selected.
  77 .It
  78 From the coding tags parsed from
  79 .Qq File Variables
  80 on the first two lines of input.
  81 A file variable is an input line of the form
  82 .Pp
  83 .Dl \%.\e\(dq -*- key: val [; key: val ]* -*-
  84 .Pp
  85 A coding tag variable is where
  86 .Cm key
  87 is
  88 .Qq coding
  89 and
  90 .Cm val
  91 is the name of the encoding.
  92 A typical file variable with a coding tag is
  93 .Pp
  94 .Dl \%.\e\(dq -*- mode: troff; coding: utf-8 -*-
  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 .Pp
 102 The
 103 .Nm
 104 utility recognises the UTF\-8, us\-ascii, and latin\-1 encodings as
 105 passed to the
 106 .Fl e
 107 and
 108 .Fl D
 109 arguments, or as coding tags.
 110 Encodings are matched case-insensitively.
 111 .\" .Sh IMPLEMENTATION NOTES
 112 .\" Not used in OpenBSD.
 113 .\" .Sh RETURN VALUES
 114 .\" For sections 2, 3, & 9 only.
 115 .\" .Sh ENVIRONMENT
 116 .\" For sections 1, 6, 7, & 8 only.
 117 .\" .Sh FILES
 118 .Sh EXIT STATUS
 119 .Ex -std
 120 .Sh EXAMPLES
 121 Explicitly page a UTF\-8 manual
 122 .Pa foo.1
 123 in the current locale:
 124 .Pp
 125 .Dl $ preconv \-e utf\-8 foo.1 | mandoc -Tlocale | less
 126 .\" .Sh DIAGNOSTICS
 127 .\" For sections 1, 4, 6, 7, & 8 only.
 128 .\" .Sh ERRORS
 129 .\" For sections 2, 3, & 9 only.
 130 .Sh SEE ALSO
 131 .Xr mandoc 1 ,
 132 .Xr mandoc_char 7
 133 .Sh STANDARDS
 134 The
 135 .Nm
 136 utility references the US-ASCII character set standard, ANSI_X3.4\-1968;
 137 the Latin\-1 character set standard, ISO/IEC 8859\-1:1998; the UTF\-8
 138 character set standard; and UCS (Unicode), ISO/IEC 10646.
 139 .Sh HISTORY
 140 The
 141 .Nm
 142 utility first appeared in the GNU troff
 143 .Pq Dq groff
 144 system in December 2005, authored by Tomohiro Kubota and Werner
 145 Lemberg.
 146 The implementation that is part of the
 147 .Xr mandoc 1
 148 utility appeared in May 2011.
 149 .Sh AUTHORS
 150 The
 151 .Nm
 152 utility was written by
 153 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
 154 .\" .Sh CAVEATS
 155 .\" .Sh BUGS
 156 .\" .Sh SECURITY CONSIDERATIONS
 157 .\" Not used in OpenBSD.