From b11b2209abf05efb76dfcf935a9c3855c4b440b1 Mon Sep 17 00:00:00 2001 From: Lev Walkin Date: Sun, 12 Oct 2014 17:51:12 -0700 Subject: docs updated; use markdown --- Makefile.am | 2 +- README | 79 --------------------------------------------------------- README.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ asn1c.spec.in | 2 +- doc/Makefile.am | 4 +-- 5 files changed, 81 insertions(+), 83 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/Makefile.am b/Makefile.am index c190f151..290adee6 100644 --- a/Makefile.am +++ b/Makefile.am @@ -9,7 +9,7 @@ SUBDIRS = \ docsdir = $(datadir)/doc/asn1c -docs_DATA = README FAQ COPYING ChangeLog BUGS TODO +docs_DATA = README.md FAQ COPYING ChangeLog BUGS TODO EXTRA_DIST = asn1c.spec.in FAQ BUGS MANIFEST tests/ CLEANFILES = asn1c.spec diff --git a/README b/README deleted file mode 100644 index 9dc8a217..00000000 --- a/README +++ /dev/null @@ -1,79 +0,0 @@ -WHAT TO READ? -============= - -If you haven't installed the asn1c yet, read the INSTALL file for -a short installation guide. - -For the list of asn1c command line options, see `asn1c -h` or `man asn1c`. - -For more complete documentation on this compiler and on using the -results of compilation phase, please look into asn1c-quick.pdf and -asn1c-usage.{pdf,html}. -If you are building the compiler from the sources, these documents reside -in the ./doc directory, otherwise they lie nearby the README file you're -reading right now. - -Please also read the FAQ file. - -An excellent book on ASN.1 is written by Olivier Dubuisson: -"ASN.1 Communication between heterogeneous systems", ISBN:0-12-6333361-0. - -QUICK START (also check out asn1c-quick.pdf) -============================================ - -After building [and installing] the compiler (see INSTALL), you may use -the asn1c command to compile the ASN.1 specification: - - asn1c # Compile module - -If several specifications contain interdependencies, all of them must be -specified: - - asn1c ... # Compile interdependent modules - -If you are building the asn1c from the sources, the ./examples directory -contains several ASN.1 modules and a script to extract the ASN.1 modules -from RFC documents. Refer to the README file in that directory. -To compile the X.509 PKI module: - - ./asn1c/asn1c -P ./examples/rfc3280-*.asn1 # Compile-n-print - -In this example, -P option is used to instruct the compiler to print the -compiled text on the standard output instead of creating multiple .c -and .h files for every ASN.1 type found inside the specified ASN.1 modules. -This is useful for debugging and test automation. - -The compiler -E and -EF options are used for testing the parser and -the semantic fixer, respectively. These options will instruct the compiler -to dump out the parsed (and fixed) ASN.1 specification as it was -"understood" by the compiler. It might be useful for checking -whether a particular syntactic construction is properly supported -by the compiler. - - asn1c -EF # Check semantic validity - - -MODEL OF OPERATION -================== - -The asn1c compiler works by processing the ASN.1 module specification -in several stages: -1. In the first stage, the ASN.1 file is parsed. - (Parsing produces an ASN.1 syntax tree for the subsequent levels) -2. In the second stage, the syntax tree is "fixed". - (Fixing is a process of checking the tree for semantic errors, - accompanied by the tree transformation into the canonical form) -3. In the third stage, the syntax tree is compiled into the target language. - -There are several command-line options reserved for printing the results -after each stage of operation: - - => print (-E) - => => print (-E -F) - => => => print (-P) - => => => save-compiled [default] - - --- -Lev Walkin -vlm@lionet.info diff --git a/README.md b/README.md new file mode 100644 index 00000000..59d9c967 --- /dev/null +++ b/README.md @@ -0,0 +1,77 @@ +# WHAT TO READ? + +If you haven't installed the asn1c yet, read the INSTALL file for a +short installation guide. + +For the list of asn1c command line options, see `asn1c -h` or `man asn1c`. + +The comprehensive documentation on this compiler is in asn1c-usage.pdf. + +If you are building the compiler from the sources, the PDFs reside +in the ./doc directory. Normally the file is installed together with the +README.md file you're reading right now. + +Please also read the FAQ file. + +An excellent book on ASN.1 is written by Olivier Dubuisson: +"ASN.1 Communication between heterogeneous systems", ISBN:0-12-6333361-0. + +# QUICK START + +(also check out ./doc/asn1c-quick.pdf) + +After building [and installing] the compiler (see INSTALL), you may use +the asn1c command to compile the ASN.1 specification: + + asn1c # Compile module + +If several specifications contain interdependencies, all of them must be +specified: + + asn1c ... # Compile interdependent modules + +If you are building the asn1c from the sources, the ./examples directory +contains several ASN.1 modules and a script to extract the ASN.1 modules +from RFC documents. Refer to the README file in that directory. +To compile the X.509 PKI module: + + ./asn1c/asn1c -P ./examples/rfc3280-*.asn1 # Compile-n-print + +In this example, -P option is used to instruct the compiler to print the +compiled text on the standard output instead of creating multiple .c +and .h files for every ASN.1 type found inside the specified ASN.1 modules. +This is useful for debugging and test automation. + +The compiler -E and -EF options are used for testing the parser and +the semantic fixer, respectively. These options will instruct the compiler +to dump out the parsed (and fixed) ASN.1 specification as it was +"understood" by the compiler. It might be useful for checking +whether a particular syntactic construction is properly supported +by the compiler. + + asn1c -EF # Check semantic validity + +# MODEL OF OPERATION + +The asn1c compiler works by processing the ASN.1 module specifications +in several stages: + +1. In the first stage, the ASN.1 file is parsed. + (Parsing produces an ASN.1 syntax tree for the subsequent levels) +2. In the second stage, the syntax tree is "fixed". + (Fixing is a process of checking the tree for semantic errors, + accompanied by the tree transformation into the canonical form) +3. In the third stage, the syntax tree is compiled into the target language. + +There are several command-line options reserved for printing the results +after each stage of operation: + + => print (-E) + => => print (-E -F) + => => => print (-P) + => => => save-compiled [default] + + +-- +Lev Walkin +vlm@lionet.info diff --git a/asn1c.spec.in b/asn1c.spec.in index 8a1d08fa..85368010 100644 --- a/asn1c.spec.in +++ b/asn1c.spec.in @@ -37,7 +37,7 @@ rm -rf $RPM_BUILD_ROOT rm -rf $RPM_BUILD_ROOT %files -%doc README FAQ COPYING ChangeLog BUGS TODO +%doc README.md FAQ COPYING ChangeLog BUGS TODO %doc doc/asn1c-usage.pdf doc/asn1c-usage.html %attr(755,root,root) %{_bindir} %attr(644,root,root) %{_datadir}/asn1c diff --git a/doc/Makefile.am b/doc/Makefile.am index a714512c..9582917c 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -3,7 +3,7 @@ SUBDIRS = docsrc docsdir = $(datadir)/doc/asn1c -docs_DATA = $(srcdir)/*.pdf +docs_DATA = $(srcdir)/asn1c-*.pdf -EXTRA_DIST = $(srcdir)/*.pdf +EXTRA_DIST = $(srcdir)/asn1c-*.pdf -- cgit v1.2.3