ICU-601 added manual pages for convrtrs.txt and cnvalias.dat, cleaned up page for gencnval.

X-SVN-Rev: 2536

.gitignore

@@ -113,6 +113,7 @@ icu4c/source/tools/gencnval/*.pdb
 icu4c/source/tools/gencnval/Debug
 icu4c/source/tools/gencnval/Makefile
 icu4c/source/tools/gencnval/Release
+icu4c/source/tools/gencnval/convrtrs.txt.[0-9]
 icu4c/source/tools/gencnval/gencnval
 icu4c/source/tools/gencnval/gencnval.[0-9]
 icu4c/source/tools/gencnval/tmp

icu4c/source/tools/gencnval/.cvsignore

@@ -6,4 +6,5 @@ Makefile
 *.pdb
 gencnval
 gencnval.[0-9]
+convrtrs.txt.[0-9]
 

icu4c/source/tools/gencnval/Makefile.in

@@ -10,6 +10,10 @@ VERSION = @VERSION@
 SECTION = 8
 MAN_FILES = $(TARGET).$(SECTION)
 
+MAN5_FILES = convrtrs.txt.5 cnvalias.dat.5
+
+ALL_MAN_FILES = $(MAN_FILES) $(MAN5_FILES)
+
 ICUDATADIR=$(top_builddir)/data/
 CONVRTRSFILE=$(top_srcdir)/../data/convrtrs.txt
 
@@ -51,7 +55,7 @@ top_builddir = ../..
 subdir = tools/gencnval
 
 ## Extra files to remove for 'make clean'
-CLEANFILES = *~ $(TARGET).$(SECTION)
+CLEANFILES = *~ $(ALL_MAN_FILES)
 
 ## Target information
 TARGET = gencnval
@@ -72,7 +76,7 @@ DEPS = $(OBJECTS:.o=.d)
 ## List of phony targets
 .PHONY : all all-local install install-local clean clean-local		\
 distclean distclean-local dist dist-local check	\
-check-local build-data install-man
+check-local build-data install-man install-man-files install-man5-files
 
 ## Clear suffix list
 .SUFFIXES :
@@ -85,7 +89,7 @@ distclean : distclean-local
 dist: dist-local
 check: all check-local
 
-all-local: $(TARGET) $(MAN_FILES) build-data
+all-local: $(TARGET) $(ALL_MAN_FILES) build-data
 
 install-local: all-local build-data install-man
 	$(mkinstalldirs) $(DESTDIR)$(sbindir)
@@ -117,11 +121,19 @@ $(TARGET) : $(OBJECTS)
 	$(LINK.cc) -o $@ $^ $(LIBS) 
 
 # man page
-install-man: $(MAN_FILES)
-	$(mkinstalldirs) $(DESTDIR)$(mandir)/man$(SECTION)
-	$(INSTALL_DATA) $< $(DESTDIR)$(mandir)/man$(SECTION)
+install-man: install-man-files install-man5-files
 
-$(TARGET).$(SECTION): $(srcdir)/$(TARGET).$(SECTION).in
+install-man-files: $(MAN_FILES)
+	$(mkinstalldirs) $(DESTDIR)$(mandir)/man$(SECTION)
+	$(INSTALL_DATA) $? $(DESTDIR)$(mandir)/man$(SECTION)
+install-man5-files: $(MAN5_FILES)
+	$(mkinstalldirs) $(DESTDIR)$(mandir)/man5
+	$(INSTALL_DATA) $? $(DESTDIR)$(mandir)/man5
+
+%.$(SECTION): $(srcdir)/%.$(SECTION).in
+	cd $(top_builddir) \
+	 && CONFIG_FILES=$(subdir)/$@ CONFIG_HEADERS= $(SHELL) ./config.status
+%.5: $(srcdir)/%.5.in
 	cd $(top_builddir) \
 	 && CONFIG_FILES=$(subdir)/$@ CONFIG_HEADERS= $(SHELL) ./config.status
 
@@ -139,3 +151,4 @@ ifneq ($(patsubst %clean,,$(MAKECMDGOALS)),)
 -include $(DEPS)
 endif
 endif
+

icu4c/source/tools/gencnval/cnvalias.dat.5

@@ -0,0 +1,2 @@
+.so man5/convrtrs.txt.5
+

icu4c/source/tools/gencnval/convrtrs.txt.5.in

@@ -0,0 +1,116 @@
+.\" Hey, Emacs! This is -*-nroff-*- you know...
+.\"
+.\" convrtrs.txt.5: manual page for the convrtrs.txt file
+.\"
+.\" Copyright (C) 2000 IBM, Inc. and others.
+.\"
+.TH CONVRTRS.TXT 5 "29 September 2000" "ICU @VERSION@"
+.SH NAME
+.B convrtrs.txt
+\- ICU converters aliases file
+.br
+.B cnvalias.dat
+\- binary ICU converters aliases file
+.SH DESCRIPTION
+The file
+.B convrtrs.txt
+lists the names of the converters that ICU can handle, along with
+their known aliases. ICU can open a converter given either its real name or
+any of its aliases.
+.B convrtrs.txt
+is read by
+.BR gencnval (8)
+in order to generate the binary data that ICU uses to represent the converters
+aliases information.
+.PP
+Each converter and its aliases are described on a separate lines; fields
+on each line are separated by white space. The order of records in
+.B convrtrs.txt
+is important: if a given name appears multiple times, the last one prevails.
+Names of converters and aliases are compared without considering case; the
+dash, underscore, and space characters are also ignored during comparison
+(even though spaces cannot be used in
+.B convrtrs.txt
+since white space is significant as a field delimiter).
+Thus the names
+.BR UTF-8 ,
+.BR utf_8 ,
+and
+.BR "Utf 8"
+are equivalent converters names.
+.PP
+The format of
+.B convrtrs.txt
+can be described by the following BNF grammar:
+.PP
+.RS
+.nf
+converters ::= { converter | comment }
+converter ::= name [ tags ] { alias } [ comment ]
+alias ::= name [ tags ]
+tags ::= '{' { name } '}'
+comment ::= '#' \fIanything\fP
+.fi
+.RE
+.PP
+A
+.I name
+can use any character other than white space and the '{' and '#' delimiters.
+In practice, names are usually restricted to the set of uppercase and
+lowercase latin letters plus arabic digits, the dash, the underscore,
+and the colon characters. It is recommended to follow this convention
+when naming new converters or their aliases.
+.PP
+A
+.I comment
+starts with the pound character '#' and ends with the current
+line. Comments are ignored.
+.PP
+The
+.I name
+of a given
+.I converter
+must match its algorithmic name if the converter is algorithmic, or
+its file name if the converter is table-driven. The table for the
+converter
+.B ibm-912
+for example, is expected to be in the
+.B ibm-912.cnv
+file.
+An
+.I alias
+has no such restriction, as aliases are just arbitrary names
+associated to a given converter.
+.PP
+The presence of a
+.I tag
+after a converter or alias name means that this name is associated to
+a given standard set of names. Two well-known such standards are the
+.B MIME
+and
+.B IANA
+registries of names. The default ICU
+.B convrtrs.txt
+file already uses these tags.
+Note that tags do not need to be declared, they are collected as they
+appear.
+Names appropriate for a given standard can be retrieved
+programmatically by using the
+.BR ucnv_getStandardName (3)
+function.
+.SH CAVEATS
+The
+.B convrtrs.txt
+file is not directly read by ICU. It must be transformed into a binary
+file by
+.BR gencnval (5)
+first. Also, depending on the way ICU was packaged, even the resulting
+.B cnvalias.dat
+file may not be read by ICU. Please refer to the ICU manual for more
+information on which files are effectively read by ICU at runtime, and
+how to produce them.
+.SH COPYRIGHT
+Copyright (C) 2000 IBM, Inc. and others.
+.SH SEE ALSO
+.BR gencnval (8),
+.BR pkgdata (8)

icu4c/source/tools/gencnval/gencnval.8.in

@@ -1,50 +1,82 @@
-.TH GENCNVAL 1 @VERSION@ "ICU" \" -*-nroff-*-   $Revision: 1.1 $ 
+.\" Hey, Emacs! This is -*-nroff-*- you know...
+.\"
+.\" gencnval.8: manual page for the gencnval utility
+.\"
+.\" Copyright (C) 2000 IBM, Inc. and others.
+.\"
+.TH GENCNVAL 8 "29 September 2000" "ICU @VERSION@"
 .SH NAME
-gencnval \- Compile the converter alias file
+.B gencnval
+\- compile the converters aliases file
 .SH SYNOPSIS
-.ta 6n
-\fBgencnval\fP  	[-\fIoptions\fP ...] [ \fIconvrtrs.txt\fP ]
+.B gencnval
+[
+.BR "\-h\fP, \fB\-?\fP, \fB\-\-help"
+]
+[
+.BR "\-c\fP, \fB\-\-copyright"
+]
+[
+.BI "\-s\fP, \fB\-\-sourcedir" " source"
+]
+[
+.BI "\-d\fP, \fB\-\-destdir" " destination"
+]
+[
+.I converterfile
+]
 .SH DESCRIPTION
-The 
-.I gencnval
-program converts the ICU alias file
-.I convrtrs.txt
+.B gencnval
+converts the ICU alias file
+.I converterfile
 into the binary file
-.I cnvalias.dat
+.BR cnvalias.dat .
+This binary file can then be read directly by ICU, or used by
+.BR pkgdata (8)
+for incorporation into a larger archive or library.
+.PP
+If
+.I converterfile
+is not provided, the default ICU
+.B convrtrs.txt
+file is used.
 .SH OPTIONS
-.PP
-.TP 8
-.B \-\-help\fP or \fB \-h \fP or \fB \-?
-Display a short help text
-.TP 8
-.B \-\-copyright \fP or \fB \-c
-Include a copyright notice in the binary data
-.TP 8
-.B \-\-destdir=\fIpath\fP\fR \fP or \fB \-d=\fIpath\fP
-Change the output destination directory. Default is ICU_DATA directory.
-See
-.B ENVIRONMENT
-below.
-.TP 8
-.B \-\-sourcedir=\fIpath\fP\fR \fP or \fB \-s=\fIpath\fP
-Change the default source directory. Default is ICU_DATA directory.
-See
-.B ENVIRONMENT
-below.
-.TP 8
-.I convrtrs.txt
-Specify an alternate file to read for the alias source. Default: convrtrs.txt
-.fi
-.sp
+.TP
+.BR \-h\fP, \fB\-?\fP, \fB\-\-help
+Print help about usage and exit.
+.TP
+.BR \-c\fP, \fB\-\-copyright
+Include a copyright notice in the binary data.
+.TP
+.BI "\-s\fP, \fB\-\-sourcedir" " source"
+Set the source directory to
+.IR source .
+The default source directory is specified by the environment variable
+.BR ICU_DATA .
+.TP
+.BI "\-d\fP, \fB\-\-destdir" " destination"
+Set the destination directory to
+.IR destination .
+The default destination directory is specified by the environment variable
+.BR ICU_DATA .
 .SH ENVIRONMENT
-.PP
-.TP 8
+.TP 10
 .B ICU_DATA
-Specifies the directory containing ICU data.  Default is \fI@prefix@share/icu/@VERSION@/\fP
-- Make sure there is a trailing slash.
+Specifies the directory containing ICU data. Defaults to
+.BR @thedatadir@/icu/@VERSION@/ .
+Some tools in ICU depend on the presence of the trailing slash. It is thus
+important to make sure that it is present if
+.B ICU_DATA
+is set.
 .SH FILES
-convrtrs.txt - specifies alias source file
-\".SH SEE ALSO
-\" blah(1)
+.TP \w'\fB@thedatadir@/icu/@VERSION@/convrtrs.txt'u+3n
+.B @thedatadir@/icu/@VERSION@/convrtrs.txt
+Description of ICU's converters and their aliases.
+.SH VERSION
+@VERSION@
 .SH COPYRIGHT
-Copyright (c) 2000 IBM, Inc. and others.
+Copyright (C) 2000 IBM, Inc. and others.
+.SH SEE ALSO
+.BR convrtrs.txt (5) 
+.br
+.BR pkgdata (8)