From 6f47d5d104edf2b53c86db897e85b7b364ff93e6 Mon Sep 17 00:00:00 2001 From: Yves Arrouye Date: Fri, 29 Sep 2000 22:03:55 +0000 Subject: [PATCH] ICU-601 added manual pages for convrtrs.txt and cnvalias.dat, cleaned up page for gencnval. X-SVN-Rev: 2536 --- .gitignore | 1 + icu4c/source/tools/gencnval/.cvsignore | 1 + icu4c/source/tools/gencnval/Makefile.in | 27 ++-- icu4c/source/tools/gencnval/cnvalias.dat.5 | 2 + icu4c/source/tools/gencnval/convrtrs.txt.5.in | 116 ++++++++++++++++++ icu4c/source/tools/gencnval/gencnval.8.in | 114 ++++++++++------- 6 files changed, 213 insertions(+), 48 deletions(-) create mode 100644 icu4c/source/tools/gencnval/cnvalias.dat.5 create mode 100644 icu4c/source/tools/gencnval/convrtrs.txt.5.in diff --git a/.gitignore b/.gitignore index 65ab58d349a..b3a26db2d06 100644 --- a/.gitignore +++ b/.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 diff --git a/icu4c/source/tools/gencnval/.cvsignore b/icu4c/source/tools/gencnval/.cvsignore index 0aef3164e9a..ecfa341a953 100644 --- a/icu4c/source/tools/gencnval/.cvsignore +++ b/icu4c/source/tools/gencnval/.cvsignore @@ -6,4 +6,5 @@ Makefile *.pdb gencnval gencnval.[0-9] +convrtrs.txt.[0-9] diff --git a/icu4c/source/tools/gencnval/Makefile.in b/icu4c/source/tools/gencnval/Makefile.in index 8afbe6aa48b..34823beb700 100644 --- a/icu4c/source/tools/gencnval/Makefile.in +++ b/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 + diff --git a/icu4c/source/tools/gencnval/cnvalias.dat.5 b/icu4c/source/tools/gencnval/cnvalias.dat.5 new file mode 100644 index 00000000000..2c258775576 --- /dev/null +++ b/icu4c/source/tools/gencnval/cnvalias.dat.5 @@ -0,0 +1,2 @@ +.so man5/convrtrs.txt.5 + diff --git a/icu4c/source/tools/gencnval/convrtrs.txt.5.in b/icu4c/source/tools/gencnval/convrtrs.txt.5.in new file mode 100644 index 00000000000..68f2fef329a --- /dev/null +++ b/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) diff --git a/icu4c/source/tools/gencnval/gencnval.8.in b/icu4c/source/tools/gencnval/gencnval.8.in index d31508247ae..a5a2e059cfd 100644 --- a/icu4c/source/tools/gencnval/gencnval.8.in +++ b/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)