From ae7a4c5db89851b34ef90352d0ce7463f8e66365 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Tue, 25 Mar 2014 08:14:59 +0100 Subject: Shorten the Introduction section, keeping only the essential details We can assume that anyone that reads the documentation for the Asn1 documentation already knows about ASN.1, so we don't need three paragraphs of introductory. Keep one short paragraph explaining what ASN.1 is in case a reader unfamiliar with ASN.1 stumbles upon the manual. While we are at it, reformat the paragraphs in Introduction to shorter lines that don't wrap. --- lib/asn1/doc/src/asn1_ug.xml | 104 ++++++++++++++++--------------------------- 1 file changed, 38 insertions(+), 66 deletions(-) (limited to 'lib/asn1/doc/src/asn1_ug.xml') diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml index 18aa0b1d87..e39b47ff20 100644 --- a/lib/asn1/doc/src/asn1_ug.xml +++ b/lib/asn1/doc/src/asn1_ug.xml @@ -34,23 +34,25 @@
Features -

The Asn1 application provides: -

+

The Asn1 application provides:

An ASN.1 compiler for Erlang, which generates encode and decode functions to be used by Erlang programs sending and receiving ASN.1 specified data. Run-time functions used by the generated code. - The supported encoding rules are: + Support for the following encoding rules: Basic Encoding Rules (BER) - Distinguished Encoding Rules (DER), a specialized form of BER that is used in security-conscious applications. + Distinguished Encoding Rules (DER), a specialized + form of BER that is used in security-conscious + applications. - Packed Encoding Rules (PER) both the aligned and unaligned variant. + Packed Encoding Rules (PER); both the aligned and + unaligned variant. @@ -59,71 +61,41 @@
Overview -

ASN.1 (Abstract Syntax Notation 1) is a formal language for describing data structures to be exchanged between distributed computer systems. - The purpose of ASN.1 is to have - a platform and programming language independent notation to express - types using a - standardized set of rules for the transformation of values of - a defined type, into a stream of bytes. This stream of bytes - can then be sent on a communication channel set up by the - lower layers in the stack of communication protocols e.g. - TCP/IP or encapsulated within UDP packets. This way, two - different applications written in two completely different - programming languages running on different computers with - different internal representation of data can exchange - instances of structured data types (instead of exchanging - bytes or bits). This makes programming faster and easier since no code - has to be written to process the transport format of the - data. -

-

To write a network application which processes ASN.1 encoded - messages, it is prudent and sometimes essential to have a set - of off-line development tools such as an ASN.1 compiler which - can generate the encode and decode logic for the specific ASN.1 - data types. It is also necessary to combine this with some - general language-specific runtime support for ASN.1 encoding and - decoding. -

-

The ASN.1 compiler must be directed towards a target language - or a set of closely related languages. This manual describes a - compiler which is directed towards the functional language - Erlang. In order to use this compiler, familiarity with the - language Erlang is essential. Therefore, the runtime support for ASN.1 is - also closely related to the language Erlang and - consist of a number of functions, which the - compiler uses. The types in ASN.1 and how to represent - values of those types in Erlang are described in this manual. -

-

The following document is structured so that the first part describes - how to use ASN.1 compiler, and then there are descriptions of all - the primitive and constructed ASN.1 types and their representation - in Erlang, -

+

ASN.1 (Abstract Syntax Notation One) is a formal language for + describing data structures to be exchanged between distributed + computer systems. The purpose of ASN.1 is to have a platform + and programming language independent notation to express types + using a standardized set of rules for the transformation of + values of a defined type into a stream of bytes. This stream of + bytes can then be sent on any type of communication + channel. This way, two applications written in different + programming languages running on different computers with + different internal representation of data can exchange instances + of structured data types.

Prerequisites -

It is assumed that the reader is familiar with the ASN.1 notation - as documented in the standard definition [] which is - the primary text. It may also be helpful, but not necessary, - to read the standard definitions - [] [] [] - [] [].

-

A very good book explaining those reference texts is - [], free to download at - http://www.oss.com/asn1/dubuisson.html . +

It is assumed that the reader is familiar with the ASN.1 + notation as documented in the standard definition [] which is the primary text. It may also be + helpful, but not necessary, to read the standard definitions + [] [] [] [] [].

+

A good book explaining those reference texts is + [], which is free to download at + http://www.oss.com/asn1/dubuisson.html.

- Capability + Capabilities

This application covers all features of ASN.1 up to the 1997 - edition of the specification. In the 2002 edition of ASN.1 a number of - new features where introduced of which some are supported while - others are not. For example the - ECN (Encoding Control Notation) and XML notation are still - unsupported. Though, the other features of the 2002 edition are - fully or partly supported as shown below:

+ edition of the specification. In the 2002 edition of ASN.1 a + number of new features were introduced. The following features + of the 2002 edition are fully or partly supported as shown + below:

Decimal notation (e.g., "1.5e3") for REAL values. The @@ -131,7 +103,7 @@ supported.

 -

The RELATIVE-OID type for relative object identifiers are +

The RELATIVE-OID type for relative object identifiers is fully supported.

 @@ -141,16 +113,16 @@ constraint is not a PER-visible constraint.

 -

The subtype constraint by regular expressions (PATTERN) for character string types is parsed when compiling, but no further action is taken. This constraint is not a PER-visible constraint.

+

The subtype constraint by regular expressions (PATTERN) + for character string types is parsed when compiling, but no + further action is taken. This constraint is not a + PER-visible constraint.

Multiple-line comments as in C, /* ... */, are supported.

 -

It should also be added here that the encoding formats - supported are BER, DER, PER aligned - basic variant and PER unaligned basic variant.

-- cgit v1.2.3