Read Me

                     IvmaiAsn ASN1/ECN/XDR Tools
                     ---------------------------

Copyright (C) 2002-2005 Ivan Maidanski <ivmai@mail.ru> All rights reserved.


Project site
------------

http://ivmaiasn.sourceforge.net


Preface
-------

A collection of the ASN.1/ECN parser, XDR-to-ASN.1 converter and
pretty-printer scripts for ASN.1/ECN specifications. Contains also
a formal definition of the ASN.1 built-in types, ECN encoding classes
and XDR encoding rules.

Includes a comprehensive list of the ASN.1 normative documents and
a collection of the web resources (on the site).


Disclaimer/License
------------------

This is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

This collection is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this collection; if not, write to the Free Software Foundation,
Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.


General
-------

The major goals of this project are:
- develop an editor syntax highlighter for ASN.1 and ECN
specifications;
- develop a pretty-printer (HTML generator) for ASN.1 and ECN
specifications;
- develop an LL(1) parser for ASN.1:2002 and ECN (EDM/ELM)
specifications;
- formally describe the ASN.1 built-in types in terms of ASN.1 itself
(to simplify the development of an ASN.1 compiler);
- formally describe the ECN built-in encoding classes in terms of ECN
itself and ASN.1 (to simplify the development of an ECN compiler);
- develop an LL(1) parser for XDR specifications;
- develop a specification converter from XDR notation to ASN.1 one;
- using the ECN notation, formally describe the XDR encoding rules
(which could be applied to the converted XDR specifications).


Usage guidelines
----------------

The pretty-printer for ASN.1 and ECN:
- get and install the Colorer Library;
- install asn1.hrc add-on script into the Colorer Library (as explained
in asn1.hrc) if not there;
- optionally install htmlcss.hrd into the Colorer Library (as explained
in htmlcss.hrd) if not there;
- use "colorer" executable to generate an HTML file for a given ASN.1
or ECN specification (the input file name must have .asn, .asn1, .ecn,
.edm or .elm extension);
- if "htmlcss" schema is used then place "hrdstyle.css" file (either
the original one or your "customized" variant of it) along with the
generated HTML files (in the same folder).

The editor syntax highlighting support for ASN.1 and ECN:
- get and install the Colorer plugin (only FAR, Eclipse and Midnight
Commander have support for the Colorer at present);
- install asn1.hrc add-on script into the Colorer plugin (if not
already there) as explained in asn1.hrc.

Notes for the pretty-printer and syntax highlighter support:
- the syntax highlighter script supports both the new (2002) and the
old versions of ASN.1 (including the old MACRO notation);
- the syntax highlighter script supports only the new "take5" version
of the Colorer Library (or plugin);
- "htmlcss" Colorer HRD script (together with the accompanying
"hrdstyle" HTML style sheet) is not related to ASN.1/ECN technologies
and has been developed for pretty-printing convenience (as an
alternative to the Colorer "-ht" option);
- the latest version of the Colorer Library (available from its public
SVN) might already have ASN.1 support (as well as "htmlcss" hrd/text
schema).

Guidelines for building the ASN.1/ECN parser manually (that is, without
running the supplied build.xml file):
- get and unpack Coco/R for Java V1.15 (the previous or later versions
may not fit);
- apply the required bug-fixes to the original Coco/R for Java V1.15
as described in "asn2002s.atg" file and rebuild the Coco/R;
- run the modified Coco/R against "asn2002s.atg";
- modify the generated Scanner and Parser java files as described
in "asn2002s.atg";
- compile the modified generated Scanner, Parser and ErrorStream java
files.

Notes for the XDR-to-ASN1 converter:
- the converter, for a given XDR specification, produces the equivalent
legacy ASN.1 specification (preserving the identifiers);
- to preserve the binary protocol format for a converted XDR
specification, "IvmaiAsn-XDR-Encoding" encoding module should
be applied to it (this requires an ECN compiler);
- all the comments present in an input XDR specification are preserved
in the output ASN.1 specification;
- if xdr2asn1 is invoked without "-d" command-line option then xdr2asn1
only checks the validity (syntax) of the input XDR specification file
(the resulting equivalent ASN.1 specification file is not written);
- xdr2asn1 also checks and translates the RPC notation;
- there is no definition of the #REAL encoding class in the current
version of ECN (2002), so the XDR floating-point types (in
a specification generated by "xdr2asn1" converter) should be manually
re-defined as ASN.1 "OCTET STRING" (with the corresponding fixed size
constraint) to make an ECN compiler apply "IvmaiAsn-XDR-Encoding" rules
correctly;
- "IvmaiAsn-XDR-Encoding" rules set has not been tested thoroughly.

Notes for "IvmaiAsn-ECN-CLASS" and "IvmaiAsn-USEFUL" ASN.1 modules:
- some of the ASN.1 built-in types cannot be precisely described
in terms of ASN.1 itself;
- some of the ECN built-in encoding classes have no special encoding
class yet (and, thus, cannot be precisely described in terms of ASN.1).


asn2002s information and usage
------------------------------

This program is developed for quick syntax checking of data
specifications written in the ASN.1 and/or ECN descriptive languages
(strictly the version of year 2002 with Amendment 1). To learn about
the ASN.1 (Abstract Syntax Notation One), see ITU-T X.680 .. X.683
documents. To learn about the ECN (Encoding Control Notation), see
ITU-T X.692 document.

To do syntax checking, You should run this program with one or more
arguments specifying the names of the input files containing the
data specifications You need to check (You may also use wildcards
to specify a group of files). If no syntax error is found (in every
of the specified files supplied for checking) then the program just
prints 'Ok' message and exits. Otherwise, the program stops at the
first file containing one or more errors, and shows the list of
these found errors together with their line numbers.

Program features: strict syntax checking for conformance with the
ASN.1 and ECN standards; extremely fast (since it is built on LL(1)
parser); every file (every ASN.1 or EDM, or ELM module) is checked
independently on the others; the program is free for use.
Disadvantage: the semantic errors are not checked by this program.


Abbreviations
-------------

The following acronyms are in use:
- ASN.1 - Abstract Syntax Notation One (defined in ITU-T X.680-683);
- ASN.1:2002 - the modern version of ASN.1 (draft published in year
2002);
- ATG - Attributed-Type Grammar (the Coco/R parser generators
notation);
- Coco/R - an LL(1) compiler generator;
- ECN - Encoding Control Notation (defined in ITU-T X.692);
- EDM - Encoding Definition Module (part of ECN);
- ELM - Encoding Link Module (part of ECN);
- FAR - console File and Archive Manager program (for Windows);
- IETF - Internet Engineering Task Force (open international
community);
- ITU-T - International Telecommunication Union (formerly known
as CCITT);
- JRE - Java Runtime Environment (includes a Java Virtual Machine);
- LL(1) - a top-down parser (with one lookahead token) for a subset
of the context-free grammars;
- RPC - Remote Procedure Call protocol and specification language
(defined in IETF RFC 1831);
- XDR - External Data Representation protocol and specification
language (defined in IETF RFC 1832).


List of files
-------------

The official binary distributive files contain:
- GNU_GPL.txt - the GNU License;
- README.txt - this file;
- asn2002s.jar (or asn2002s.exe) - IvmaiAsn ASN.1/ECN:2002 Syntax-only
Checker;
- xdr2asn1.jar (or xdr2asn1.exe) - IvmaiAsn XDR-to-ASN1 specification
converter.

The source collection consists of:
- ChangeLog - the standard changes log file;
- GNU_GPL.txt - the GNU License;
- README.txt - this file;
- asn1prod.txt - the ASN.1:2002 "original" syntax productions (as
specified in ITU-T Recommendation X.680 - X.683);
- build-colored-docs.bat - the Windows script generating 'colored'
HTML documents for IvmaiAsn-ECN-CLASS.asn, IvmaiAsn-ECN-USEFUL.edm,
IvmaiAsn-USEFUL.asn, IvmaiAsn-XDR-Encoding.edm, asn1_hrc_demo.asn and
hrdstyle.css files;
- build-win32-x86-jcgo.bat - building script for Win32 target (builds
asn2002s and xdr2asn1 tools);
- build.xml - the Apache Ant script for building the binary release
(for JRE) containing asn2002s and xdr2asn1 tools (the script requires
the original Coco/R for Java V1.15 tar-ball to be unpacked into the
newly-created "jcoco115" folder);
- ecnprod.txt - the ECN:2002 "original" syntax productions (as
specified in ITU-T Recommendation X.692);
- asnmods/IvmaiAsn-ECN-CLASS.asn - the ECN built-in primary encoding
classes definition expressed as a valid ASN.1 module (could be used
as a user formal reference for ECN notation, or as a part of an ECN
compiler);
- asnmods/IvmaiAsn-ECN-USEFUL.edm - the ECN built-in derivable encoding
classes definition expressed as a valid ECN (EDM) module (could be used
as a user formal reference for ECN encoding classes, or as a part of an
ECN compiler);
- asnmods/IvmaiAsn-USEFUL.asn - the ASN.1 built-in and "useful" types
definition expressed as a valid ASN.1 module (expressed as precisely
as possible, could be used as a user formal reference for ASN.1
built-in types, or as a part of an ASN.1 compiler);
- asnmods/IvmaiAsn-XDR-Encoding.edm - XDR encoding rules expressed as
a valid ECN (EDM) module (this EDM module could be applied to ASN.1
specifications generated by "xdr2asn1" converter tool);
- color/asn1.hrc - the Colorer Library add-on script ("colorizing"
scheme) for ASN.1/ECN specifications syntax highlighting (in editors)
and pretty-printing;
- color/asn1_hrc_demo.asn - Syntax highlighting demo for ASN.1 (the
purpose of this file is to show how various ASN.1 lexical elements are
colorized in the editor or pretty-printer);
- color/hrdstyle.css - the customizable style sheet for HTML files
produced by the Colorer HTML generator (pretty-printer) with "htmlcss"
HRD schema;
- color/htmlcss.hrd - a convenient Colorer add-on HRD schema (script)
to produce "colorized" HTML documents having syntax highlighting style
fully governed by the customizable "hrdstyle" cascading style sheet
file;
- src/asn2002s-jcoco.diff - the required patch for the files produced
by the modified Coco/R for asn2002s.atg (the same as described in the
file);
- src/asn2002s.atg - ASN.1/ECN:2002 syntax checker source (written
in Coco/R for Java ATG);
- src/jcoco115.diff - the patch for "Coco/R for Java" V1.15 (jcoco115)
required, at least, for building asn2002s (the same as described
in asn2002s.atg);
- src/xdr2asn1-jcoco.diff - the required patch for the files produced
by Coco/R for xdr2asn1.atg (the same as described in the file);
- src/xdr2asn1.atg - XDR/RPC syntax checker and XDR-to-ASN1
specification converter (written in Coco/R for Java ATG).


Bibliography
------------

(See this information on the site.)


Web resources
-------------

(See this information on the site.)


User's feedback
---------------

Any questions, suggestions, bug reports and patches are welcomed at the
IvmaiAsn site tracker (hosted at SourceForge.net).

                          --- [ End of File ] ---