\input texinfo.tex    @c -*-texinfo-*-

@c %**start of header
@setfilename asn1-mode.info
@settitle Emacs Mode for ASN.1
@syncodeindex vr cp
@syncodeindex fn cp
@syncodeindex ky cp
@finalout
@c %**end of header

@set edition 2.0
@set year 1999
@set month August
@set copyright-owner-1 France Télécom - R&D Division
@set copyright-owner-2 Cnet, National Center for Telecommunications Studies

@set update-month @value{month} @value{year}
@c ------------

@tex
\gdef\putwordChapter{Section}
@end tex

@ifinfo
This file documents @dots{}

Copyright @value{year} @value{copyright-owner}
@end ifinfo
@c ------------

@titlepage
@title Emacs Mode for ASN.1
@subtitle User's Manual
@subtitle @value{update-month}
@author Guillaume LATU
@author Stéphane LEVANT
@author Olivier DUBUISSON
Email: @ @ @ @t{asn1@@cnet.francetelecom.fr}@*
Serveur: @ @ @t{http://asn1.elibel.tm.fr/en/tools/emacs/}@*
France Télécom - Cnet DTL/MSV - F-22307 Lannion Cedex
@page
@vskip 0pt plus 1filll

@multitable @columnfractions .23 .77
@item
Copyright @copyright{} @value{year} 
@tab @value{copyright-owner-1} 
@item
@tab @value{copyright-owner-2}
@end multitable

@sp 3

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.@*
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.@*
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by France Télécom.
@page
@end titlepage
@c ------------

@c @headings off
@c @everyfooting @| @thispage @|
@headings on

@ifinfo

@c This document describes @dots{} 

@c This document applies to version @dots{} 
@c of the program named @dots{}

@c ------------
@node Top, Presentation of the ASN.1 mode, (dir), (dir)
@top Emacs Mode for ASN.1

@c ------------

@end ifinfo

@c head
@c title ASN.1 Site - Tools - Emacs mode - User manual
@c description ASN.1 is an internationally standardized notation for the communication between heterogeneous system. This page will contain the english user manual for the ASN.1 (X)Emacs mode.
@c body

@c menu Emacs Mode for ASN.1
@menu
* Presentation of the ASN.1 mode::  
* Syntax editor::               
* Compilation::                 
* Customization::                   
* Advanced configuration::      
@end menu 


@c ------------


@c @iftex
@c @hyphenation{réa-li-sée ma-ni-pu-la-tion cons-truc-tion mo-di-fi-er}
@c @end iftex


@node Presentation of the ASN.1 mode, Syntax editor, Top, Top
@chapter Presentation of the ASN.1 mode

The ASN.1 mode for Emacs and XEmacs is a user-friendly tool for writing
and editing ASN.1 specifications. It allows text highlighting, automatic
indentation, completion, direct compiling in Emacs@dots{}

It is a complete emacs mode. It is built in order to be as user-friendly
as possible. 

Moreover, this mode contains the ASN.1 grammar. It allows
to built ASN.1 modules using syntax menus, by clicking on the items.

@c ec
@node  Syntax editor, Compilation, Presentation of the ASN.1 mode, Top
@chapter Syntax editor

The mode provides:
@itemize @minus
@item help constructing ASN.1 modules by inserting parts of the grammar
@item detection of syntax errors, by calling in Emacs an ASN.1
compiler or a parser
@end itemize

@section Introduction

A little example is the best way to introduce the syntax editor.
@itemize @minus
@item open a new ASN.1 file (with extension ".asn" or ".asn1")
@item if the "ASN.1-syntax" is not loaded at startup (i.e. if it doesn't
appear in the menubar), build it: select the menu item "Build Syntax Menu"
in the ASN.1 menu.
@item in the menu "ASN.1-Syntax", select the sub-menu "ModuleDefinition"
and in this menu, select the item "insert". The text 
@code{"--(ModuleDefinition)--"} appears in the buffer. This text is
mouse-sensitive: it is highlighted
when the mouse is on it. It can be clicked on
with the button-2 of the mouse (right button the two buttons mice).
@item click on this text. This text is erased and the body of a module
definition is inserted:
@example
--$modulereference$-- --[DefinitiveIdentifer]--
DEFINITIONS --[TagDefault]-- --[ExtensionDefault]-- ::=
   BEGIN
     --[Modulebody]--
   END
@end example
@item by clicking on the element which have appeared, it is possible to
develop it and finally to build a complete ASN.1 module.
@end itemize

@section The menu ASN.1-Syntax 

The sections "Built Syntax Menu" and "Fast Customization" explain how
to build the syntax menu and how to build it at startup.
To build the syntax menu, select the item "Build Syntax Menu"
in the ASN.1 menu.

The menu "ASN.1-Syntax" allows the user to insert elements of the ASN.1
grammar in the buffer. The menu contains some non-terminals. 
A sub-menu is associated to each non-terminal. The first line of a
sub-menu contains the 
word "insert". This command inserts the non-terminal associated with
the sub-menu.
The rest of the sub-menu gives the different productions of the
non-terminal.
The following notation is used:
@itemize @minus
@item a word surrounded by "(" and ")" is a non-terminal: @*
"(non-terminal)"
@item a word surrounded by "[" and "]" is an optional non-terminal;
it can be removed by: $*
"[non-terminal]"
@item a word surrounded by "$" and "$" is a terminal:
"$terminal$"
@end itemize

By clicking on a non-terminal of the menu, a sub-menu representing the
different productions of the non-terminal appears. If the grammar rule allows
several productions, each production begins by the symbol "->".
 @w{Ex.:} the sub-menu issued of "TaggedType" @w{is:}
@example
        "
        insert
        ------------
        -> <Tag>
           <Type>
        -> <Tag>
           IMPLICIT 
           <Type>
        -> <Tag>
           EXPLICIT
           <Type>
        "
@end example

The arrow indicates the beginning of each production.

By clicking on a terminal or a string in a sub-menu, this terminal is
inserted in the current buffer.

Note: terminals and non-terminals are nested in comments. Therefore, it is
possible to compile a module which contains both terminals and non-terminals.


@section Developing ASN.1 modules

Clicking in a non-terminal has the following effect:
@itemize @minus
@item if the rule associated to this non-terminal allows only one
production, this production is inserted in the buffer in place of the
non-terminal.
@item if the rule associated to this non-terminal allows several
productions, a popup menu appears. It is then possible to select a
production. This production is inserted in the buffer in place of the
non-terminal.
@end itemize

Clicking on a terminal displays the name of the terminal and prompts
a value in the minibuffer. Some corrections are automatically done.

@w{Example 1:}@*
Click on @w{@code{--$modulereference$--}} and type
@w{@code{"module1"}}
 in the minibuffer. The string 
@w{@code{"Module1"}} is inserted. 
The first letter has automatically been capitalized.

@w{Example 2:} @*
Click on @w{@code{--$number$--}} (you can insert this terminal using
"Syntax Element Completion" in the syntax menu). Then, enter @w{@code{10.0}}.
The following message appears:
@t{"The number you typed is not a correct number"} @*
It is because @code{number} should be an integer (with no ".").
Type then @w{@code{10}}. The number is accepted and inserted in the
buffer.

The last two items of the "ASN.1-Syntax" menu are:
@table @kbd
@kindex M-n
@item M-n
"Delete syntax element": erase the terminal or the non-terminal
under the cursor.

@kindex M-[
@item M-[
"Syntax Element Completion": complete the terminal or the non-terminal.
Thus, you can insert all the ASN.1 terminals, everytime they are not
accessible from the syntax menu.@*

 @w{Example:}@*
@itemize @minus
@item type  @kbd{M-[},
@item  you want to introduce the non-terminal @w{@code{ModuleDefinition}},
type @* @w{@code{"ModuleDef"}},
@item type @kbd{TAB} and @w{@code{"ModuleDef"}} is completed in
@w{@code{"ModuleDefinition"}},
@item type @kbd{ENTER}, @w{@code{"--(ModuleDefinition)--"}} is
inserting in the buffer.
@end itemize
@end table

@w{Note:} the part of the ASN.1 grammar accessible in the
"ASN.1-Syntax" menu is not exactly the grammar of the standard.
This grammar has been reorganized and some non-terminals labels
have sometimes been rennamed to be self-explicit.
Only part of the grammar is accessible from the syntax menu. To access
the whole grammar, use "Syntax Element Completion" (@w{@kbd{M-[}}), for
inserting a non-terminal or a terminal.
To insert an ASN.1 keyword, use "ASN.1 Completion" (@w{@kbd{M-TAB}}).


@c ec
@node  Compilation, Customization, Syntax editor, Top
@chapter Compilation

The item "Compile" of the ASN.1 menu allows to run an ASN.1 compiler or a
parser under Emacs. The user can then move to the
position of an error by clicking or typing @w{@kbd{ENTER}} on the error
message.

This mode is built to work with Asnp,
a parser for ASN.1:1997 developed by France Telecom Cnet
(@t{http://asn1.elibel.tm.fr/en/tools/asnp}).


@table @kbd
@kindex C-c C-c
@item "Compile" (C-c C-c)
Start the compilation.

@item "Compile Command" of the sub-menu "Fast Customization"
@kindex C-c C-p
Change the "Compile" command.

@item "Compile Switches" of the sub-menu "Fast Customization"
@kindex C-c C-o
Change the switches of the commande used by "Compile".
By default, no option is used.

@item Save settings
The compile command and switches can be saved using the sub-menu
"Fast Customization".

@item 
@end table


@c ec
@node  Customization, Advanced configuration, Compilation, Top
@chapter Customization

@section Fast Customization

The sub-menu "Fast Customization" allows to easily change some options of
the ASN.1 mode:

@itemize @minus
@item Change language
@item Modify compile command
@item Modify compile switches
@item Build syntax menu at startup
@item Save compile command and switches
@end itemize

@section General options

The options are:

@itemize @minus
@item Language (French or English)
@item Show a presentation page at startup
@item Compile command
@item Compile switches
@item Syntax menu at startup
@item button of the mouse to use
@item Use of a standard "customize" buffer to change the colors
@end itemize

@section Modification of indentation

A customize buffer allows to change the value of indentation variables of
the ASN.1 structures.

@section Modification des couleurs

A buffer similar to a "customize" buffer allows to modify all the colors
used in the mode:

@itemize @minus
@item @strong{module skeleton}: @*
@w{@sc{"begin"}} 
@w{@sc{"definitions"}} 
@w{@sc{"end"}} 
@w{@sc{"exports"}} 
@w{@sc{"extensibility implied"}} @*
@w{@sc{"from"}} 
@w{@sc{"imports"}},
@item @strong{class keywords}: @*
@w{@sc{"abstract-syntax"}} 
@w{@sc{"by"}} 
@w{@sc{"class"}} 
@w{@sc{"constrained"}} 
@w{@sc{"instance of"}} @*
@w{@sc{"type-identifier"}} 
@w{@sc{"with syntax"}} 
@w{@sc{"unique"}},
@item @strong{subtyping expressions}
@item @strong{tags}: @*
@w{@sc{"automatic"}} 
@w{@sc{"explicit"}} 
@w{@sc{"implicit"}}
@w{@sc{"tags"}} 
  and tags @* (@w{ex.:} @code{[UNIVERSAL 22]}),
@item @strong{keywords OPTIONAL/DEFAULT}
@item @strong{subtyping keywords}: @*
@w{@sc{"all"}} 
@w{@sc{"present"}} 
@w{@sc{"absent"}} 
@w{@sc{"optional"}} 
@w{@sc{"except"}} 
@w{@sc{"components of"}} 
@w{@sc{"except"}} 
@w{@sc{"includes"}} 
@w{@sc{"intersection"}} 
@w{@sc{"max"}} 
@w{@sc{"min"}} 
@w{@sc{"size"}} 
@w{@sc{"union"}}
@w{@sc{"with component"}} 
@w{@sc{"with components"}},
@item @strong{structured types}: @*
@w{@sc{"choice"}} 
@w{@sc{"sequence"}} 
@w{@sc{"set"}} 
@w{@sc{"of"}},
@item @strong{basic types}: @*
@w{@sc{"bit string"}} 
@w{"BMPString"} 
@w{@sc{"boolean"}} 
@w{@sc{"character"}} 
@w{@sc{"embedded"}} 
@w{@sc{"pdv"}} @*
@w{@sc{"enumerated"}} 
@w{@sc{"external"}} 
@w{"GeneralizedTime"} 
@w{"GeneralString"} 
@w{"GraphicString"} @*
@w{"IA5String"} 
@w{@sc{"integer"}} 
@w{"ISO646String"} 
@w{"NumericString"} 
@w{"ObjectDescriptor"} @* 
@w{@sc{"object identifier"}}
@w{@sc{"octet string"}} 
@w{"PrintableString"} 
@w{@sc{"RELATIVE-OID"}}  @*
@w{"T61String"}
@w{"TeletexString"}
@w{@sc{"real"}} 
@w{"UniversalString"} 
@w{"UTCTime"}  @*
@w{"UTF8String"}
@w{"VideotexString"}
@w{"VisibleString"}
@w{@sc{"null"}},
@item @strong{values}: @*
@w{@sc{"false"}} 
@w{@sc{"minus-infinity"}} 
@w{@sc{"plus-infinity"}} 
@w{@sc{"null"}} 
@w{@sc{"true"}}.
@item @strong{information object class}: @*
user friendly syntax introduced by @w{@sc{WITH SYNTAX}}
@end itemize

@c ec
@node  Advanced configuration,  , Customization, Top
@chapter Advanced configuration

It is possible to modify directly the mode's options by writing
emacs-lisp code in the @file{.emacs} file

Example:
@w{@code{(setq asn1-language 'en)}} sets the value of
@code{asn1-language} to @code{'en}, which means the language used is English.

NB:
all the configuration options can be modified with the
"customize" buffers.

This is the list of all variables which can be modified:

@itemize @minus
@item asn1-language
@item asn1-data-presentation 
@item asn1-compile-command 
@item asn1-compile-switches 
@item asn1-data-syntax-menu-autoload 
@item asn1-data-use-colors 
@item asn1-data-change-modeline 
@item asn1-data-use-standard-custom

@item asn1-data-faces

@item asn1-data-bracket-indent-text 
@item asn1-data-indent-of-DEFINITIONS 
@item asn1-data-indent-in-DEFINITIONS-bloc
@item asn1-data-indent-of-BEGIN 
@item asn1-data-indent-in-BEGIN-bloc 
@item asn1-data-indent-of-END 
@item asn1-data-indent-of-IMPORTS 
@item asn1-data-indent-in-IMPORTS-bloc 
@item asn1-data-indent-of-EXPORTS 
@item asn1-data-indent-in-EXPORTS-bloc 
@item asn1-data-indent-of-FROM 
@item asn1-data-indent-of-\; 
@item asn1-data-indent-of-\@{

@item asn1-data-indent-of-\( 
@item asn1-data-indent-of-\[ 
@item asn1-data-indent-of-::= 
@item asn1-data-indent-WITH-SYNTAX

@item asn1-mode-hook 
@item asn1-add-syntax-menu-hook
@end itemize

@page


@section Bibliography

Emacs:

@itemize @minus
@item GNU Emacs Manual @*
@t{http://asn1.elibel.tm.fr/en/tools/emacs/emacs.ps.gz} @*
@w{[ps.gz - 456 p. - 1064 Ko]}

@item GNU Emacs Lisp Introduction (version 1.05)@*
@t{http://asn1.elibel.tm.fr/en/tools/emacs/emacs-lisp-intro.ps.gz} @*
@w{[ps.gz - 258 p. - 731 Ko]}

@item GNU Emacs Lisp Reference Manual (version 20-2.5)@*
@t{http://asn1.elibel.tm.fr/en/tools/emacs/elisp.ps.gz} @*
@w{[ps.gz - 888 p. - 1643 Ko]}
@end itemize

XEmacs:

@itemize @minus
@item GNU XEmacs Introduction (version 20-2.5)@*
@t{ftp://ftp.lip6.fr/pub/emacs/xemacs/docs/a4/new-users-guide-a4.ps.gz} @*
@w{[ps.gz - 58 p. - 131 Ko]}

@item GNU XEmacs Manual @*
@t{ftp://ftp.lip6.fr/pub/emacs/xemacs/docs/a4/xemacs-a4.ps.gz} @*
@w{[ps.gz - 336 p. - 488 Ko]}

@item GNU XEmacs Lisp Reference Manual (version 3.1)@*
@t{ftp://ftp.lip6.fr/pub/emacs/xemacs/docs/a4/lispref-a4.ps.gz} @*
@w{[ps.gz - 828 p. - 1025 Ko]}
@end itemize

@c ec

@c end-html
@bye
