Annotation of mandoc/preconv.1, Revision 1.1
1.1 ! kristaps 1: .\" $Id: mandoc.1,v 1.88 2011/05/20 15:51:18 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$
! 18: .Dt PRECONV 1
! 19: .Os
! 20: .Sh NAME
! 21: .Nm preconv
! 22: .Nd recodes multibyte UNIX manuals as mandoc input
! 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: input.
! 36: Its arguments are as follows:
! 37: .Bl -tag -width Ds
! 38: .It Fl D Ar enc
! 39: The default encoding.
! 40: This is case-insensitive.
! 41: See
! 42: .Sx Algorithm
! 43: and
! 44: .Sx Encodings .
! 45: .It Fl e Ar enc
! 46: The document's encoding.
! 47: This is case-insensitive.
! 48: See
! 49: .Sx Algorithm
! 50: and
! 51: .Sx Encodings .
! 52: .It Ar file
! 53: The input file.
! 54: .El
! 55: .Pp
! 56: If
! 57: .Ar file
! 58: is not provided,
! 59: .Nm
! 60: accepts standard input.
! 61: Output is written to standard output.
! 62: Unicode characters in the ASCII range are printed as regular ASCII
! 63: characters; those above this range are printed using the
! 64: .Sq \e[uNNNN]
! 65: format documented in
! 66: .Xr mandoc_char 7 .
! 67: .Pp
! 68: If input bytes are improperly formed in the current encoding, they're
! 69: passed unmodified to standard output.
! 70: .Ss Encodings
! 71: The
! 72: .Nm
! 73: utility accepts the
! 74: .Ar utf\-8 ,
! 75: .Ar us\-ascii ,
! 76: and
! 77: .Ar latin\-1
! 78: encodings as arguments to
! 79: .Fl D Ar enc
! 80: or
! 81: .Fl e Ar enc .
! 82: .Ss Algorithm
! 83: An encoding is chosen according to the following steps:
! 84: .Bl -enum
! 85: .It
! 86: From the argument passed to
! 87: .Fl e Ar enc .
! 88: .It
! 89: If a BOM exists, utf\-8 encoding is selected.
! 90: .It
! 91: From the argument passed to
! 92: .Fl D Ar enc .
! 93: .It
! 94: If all else fails, Latin\-1 is used.
! 95: .El
! 96: .\" .Sh IMPLEMENTATION NOTES
! 97: .\" Not used in OpenBSD.
! 98: .\" .Sh RETURN VALUES
! 99: .\" For sections 2, 3, & 9 only.
! 100: .\" .Sh ENVIRONMENT
! 101: .\" For sections 1, 6, 7, & 8 only.
! 102: .\" .Sh FILES
! 103: .Sh EXIT STATUS
! 104: .Ex -std
! 105: .\" .Sh EXAMPLES
! 106: .\" .Sh DIAGNOSTICS
! 107: .\" For sections 1, 4, 6, 7, & 8 only.
! 108: .\" .Sh ERRORS
! 109: .\" For sections 2, 3, & 9 only.
! 110: .Sh SEE ALSO
! 111: .Xr mandoc 1 ,
! 112: .Xr mandoc_char 7
! 113: .Sh STANDARDS
! 114: The
! 115: .Nm
! 116: utility references the US-ASCII character set standard, ANSI_X3.4\-1968;
! 117: the Latin\-1 character set standard, ISO/IEC 8859\-1:1998; the UTF\-8
! 118: character set standard; and UCS (Unicode), ISO/IEC 10646.
! 119: .Sh HISTORY
! 120: The
! 121: .Nm
! 122: utility first appeared in the GNU troff
! 123: .Pq Dq groff
! 124: system in December 2005, authored by Tomohiro Kubota and Werner
! 125: Lemberg.
! 126: The implementation that is part of the
! 127: .Xr mandoc 1
! 128: utility appeared in May 2011.
! 129: .Sh AUTHORS
! 130: The
! 131: .Nm
! 132: utility was written by
! 133: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
! 134: .\" .Sh CAVEATS
! 135: .\" .Sh BUGS
! 136: .\" .Sh SECURITY CONSIDERATIONS
! 137: .\" Not used in OpenBSD.
CVSweb