>>> David PONCE <david.ponce@...> seems to think that:
>Hi Eric, [Richard?]
>
>I am currently [slowly(*)] working on a new manual that documents the
>semantic grammar framework, that is how to write semantic grammars ;-)
[ ... ]
David,
You have started a very nice piece of documentation. In this case,
I think it was wise starting over instead of modifying the existing
documentation from bovine.texi. The organization is much better here.
I even learned a few things in reading it. Thanks.
Here is a diff. Many of my changes are just in comment sections.
Your English is very good.
Eric
-----------------
cd /home/zappo/cedet/semantic/doc/
diff -c /tmp/daviddoc.texi.orig /home/zappo/cedet/semantic/doc/grammar-fw.texi
*** /tmp/daviddoc.texi.orig 2004-01-30 22:46:04.000000000 -0500
--- /home/zappo/cedet/semantic/doc/grammar-fw.texi 2004-01-31 12:11:21.000000000 -0500
***************
*** 29,34 ****
--- 29,37 ----
Copyright @copyright{} 2004 David Ponce
Copyright @copyright{} 2004 Richard Y. Kim
+ @c If this document includes aspects of previous documents, we need
+ @c the dates to go back in time to include when those were written.
+
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
***************
*** 84,90 ****
@node top
@top @value{TITLE}
!
@menu
* Overview::
--- 87,96 ----
@node top
@top @value{TITLE}
! The Semantic Grammar Framework provides a consistent way to write
! rule based grammars for use in Emacs. This document describes how to
! use the grammar writing environment, and how to write in the rule
! based language.
@menu
* Overview::
***************
*** 109,126 ****
@item
The C-like syntax is replaced by Emacs Lisp syntax.
@item
! Percent declarations suit the specific @semantic{} needs.
@end itemize
! Nevertheless, for those who are a little familiar with Bison grammar
syntax, and have some knowledge of Emacs Lisp, writing @semantic{}
! grammars shouldn't be too hard. Moreover, the grammar framework
! provides Emacs goodies (indenter, syntax coloring, etc.) to help
! editing grammars.
! On a second step, grammars written in the common rule based language
must be translated into Emacs Lisp code so a @semantic{} parser can
! handle it. The framework defines a reusable and flexible
@acronym{API} that simplifies the implementation of grammar-to-lisp
translators.
--- 115,132 ----
@item
The C-like syntax is replaced by Emacs Lisp syntax.
@item
! Percent declarations are specific to @semantic{}.
@end itemize
! Nevertheless, for those who are a familiar with Bison grammar
syntax, and have some knowledge of Emacs Lisp, writing @semantic{}
! grammars won't hard. Moreover, the grammar framework
! provides Emacs goodies (indentation, syntax coloring, etc.) to help
! edit grammars.
! Grammars written in the common rule based language
must be translated into Emacs Lisp code so a @semantic{} parser can
! use it. The framework defines a reusable and flexible
@acronym{API} that simplifies the implementation of grammar-to-lisp
translators.
***************
*** 134,140 ****
associates input grammars to a @emph{concrete} grammar mode, that is
to a particular translator and parser.
! These @emph{concrete} grammar modes exist:
@table @code
@item bovine-grammar-mode
--- 140,146 ----
associates input grammars to a @emph{concrete} grammar mode, that is
to a particular translator and parser.
! @semantic{} defines these @emph{concrete} grammar modes:
@table @code
@item bovine-grammar-mode
***************
*** 186,191 ****
--- 192,199 ----
@node Grammar File
@chapter Grammar File
+ @c If there is only one subsection, perhaps it should be promoted?
+
@menu
* Grammar outline::
@end menu
***************
*** 229,235 ****
These are copied to the beginning of the generated parser file so that
they precede the definition of the grammar rules actions. You can use
! `require' to get the declarations from another library. If you don't
need any Emacs Lisp declarations, you may omit this section.
You may have more than one @var{prologue} section, intermixed with
--- 237,243 ----
These are copied to the beginning of the generated parser file so that
they precede the definition of the grammar rules actions. You can use
! `require' to get the declarations from other libraries. If you don't
need any Emacs Lisp declarations, you may omit this section.
You may have more than one @var{prologue} section, intermixed with
***************
*** 243,255 ****
terminal symbols, specify precedence, and so on. In some simple
grammars you may not need any declarations.
! Declarations of terminal symbols defines the symbols (tokens) used in
formulating the grammar and the type associated to categories of
tokens.
All token names (but not single-character literal tokens such as
@code{'+'} and @code{'*'}) must be declared.
@menu
* package Decl::
* languagemode Decl::
--- 251,266 ----
terminal symbols, specify precedence, and so on. In some simple
grammars you may not need any declarations.
! Declarations of terminal symbols defines the symbols (lexical tokens) used in
formulating the grammar and the type associated to categories of
tokens.
All token names (but not single-character literal tokens such as
@code{'+'} and @code{'*'}) must be declared.
+ For more on lexical analysis,
+ see @inforef{Writing Lexers, ,semantic-langdev}.
+
@menu
* package Decl::
* languagemode Decl::
***************
*** 268,276 ****
@node package Decl
@subsubsection package Decl
! @example
! %package @var{library-name}
! @end example
Declare the Emacs Lisp library created from the grammar.
--- 279,294 ----
@node package Decl
@subsubsection package Decl
! @c Perhaps the declaration below could be
! @c %package @var{package-name}
! @c or
! @c %library @var{library-name}
! @c ??
!
! @c Perhaps we can use @deffn to declare them so they are automatically
! @c indexed?
!
! @deffn DECLARATION %package library-name
Declare the Emacs Lisp library created from the grammar.
***************
*** 282,291 ****
(provide '@var{library-name})
@end lisp
! Excepted the code in the @var{prologue} and @var{epilogue} sections,
! which is copied verbatim, every generated variable and function names
! will be prefixed by @code{@var{library-name}-}, following Emacs
! standard coding conventions.
If there is no @code{%package} statement, a default @var{library-name}
is used, of the form:
--- 300,308 ----
(provide '@var{library-name})
@end lisp
! All variable and function names generated from the @var{declarations}
! section will be prefixed by @code{@var{library-name}-}, following
! Emacs standard coding conventions.
If there is no @code{%package} statement, a default @var{library-name}
is used, of the form:
***************
*** 296,301 ****
--- 313,319 ----
For instance, the default library name for the grammar in the
@file{foo.wy} file is @code{foo-wy}.
+ @end deffn
@node languagemode Decl
@subsubsection languagemode Decl
***************
*** 307,315 ****
Declare in which major modes Emacs edits the sources that @semantic{}
parses using this grammar.
! For instance, the following tells that the grammar will be used to
! parse C or C++ files, edited in @code{c-mode} or @code{c++-mode} by
! Emacs.
@example
%languagemode c-mode c++-mode
--- 325,332 ----
Declare in which major modes Emacs edits the sources that @semantic{}
parses using this grammar.
! For instance, the following declares that the grammar will be used to
! parse files edited in @code{c-mode} or @code{c++-mode} by Emacs.
@example
%languagemode c-mode c++-mode
***************
*** 354,361 ****
buffer, in the buffer local variable
@code{semantic-flex-keywords-obarray}.
However you shouldn't use that variable directly. @semantic{} provides
! the following @acronym{API} to play with language keywords at run
time.
@defun semantic-lex-keyword-symbol name
--- 371,380 ----
buffer, in the buffer local variable
@code{semantic-flex-keywords-obarray}.
+ @c Oh dear. Perhaps it's time to obsolete and rename that variable. ;)
+
However you shouldn't use that variable directly. @semantic{} provides
! the following @acronym{API} to use with language keywords at run
time.
@defun semantic-lex-keyword-symbol name
***************
*** 401,410 ****
@node put Decl
@subsubsection put Decl
! The @code{%put} statement permits to assign properties to keywords
(@pxref{keyword Decl}). For instance, the predefined @code{summary}
! property assign an on-the-fly help string to a keyword, displayed when
! the cursor is over that keyword.
@code{%put} statement can have the following forms:
--- 420,429 ----
@node put Decl
@subsubsection put Decl
! The @code{%put} statement assigns properties to keywords
(@pxref{keyword Decl}). For instance, the predefined @code{summary}
! property assigns a help string to a keyword. The help string is
! used by @code{semantic-idle-summary-mode} for on-the-fly help.
@code{%put} statement can have the following forms:
***************
*** 420,434 ****
@item
@example
@exdent
! %put @var{keyword-name} @{@var{property} @var{value} @dots{}@}
@end example
! Give to @var{keyword-name} a set of @var{property} with @var{value}.
@item
@example
@exdent
! %put @{@var{keyword-name} @dots{}@} @var{property} @var{value}
@end example
Give to several @var{keyword-name} a single @var{property} with @var{value}.
--- 439,453 ----
@item
@example
@exdent
! %put @var{keyword-name} @{@var{property1} @var{value1} @var{property2} @var{value2} @dots{}@}
@end example
! Give to @var{keyword-name} a set of @var{properties} with @var{values}.
@item
@example
@exdent
! %put @{@var{keyword-name1} @var{keyword-name2} @dots{}@} @var{property} @var{value}
@end example
Give to several @var{keyword-name} a single @var{property} with @var{value}.
***************
*** 447,453 ****
@item keyword-name
Is a terminal symbol defined as a keyword.
@item property
! Is a property name, a valid Emacs Lisp symbol.
@item value
Is a property value, a valid Emacs Lisp constant expression.
@end table
--- 466,472 ----
@item keyword-name
Is a terminal symbol defined as a keyword.
@item property
! Is a property name, which is a valid Emacs Lisp symbol.
@item value
Is a property value, a valid Emacs Lisp constant expression.
@end table
***************
*** 483,489 ****
%token [<@var{type-name}>] @var{token-name} @var{token-value}
@end example
! Which declare one token with an optional type, and a value.
@item
@example
--- 502,510 ----
%token [<@var{type-name}>] @var{token-name} @var{token-value}
@end example
! @c Perhaps token-match instead of token-value?
!
! Which declares one token with an optional type, and a value.
@item
@example
***************
*** 531,536 ****
--- 552,561 ----
%type <@var{type-name}> [@var{property} @var{value} @dots{}]
@end example
+ @c ``type'' has a lot of different meanings in semantic, so you may
+ @c want to define ``token type'' here. In tags, we had changed the
+ @c name to ``class'' for a similar feature.
+
Explicitly declare a token type, and optionally give it properties.
@table @var
***************
*** 579,584 ****
--- 604,613 ----
See also @code{%prec} in @ref{Grammar Rules}.
+ @c is this true?
+ Defining precidence in a grammar that provides tagging information
+ for @semantic does not usually necessary.
+
@node default-prec Decl
@subsubsection default-prec Decl
***************
*** 590,595 ****
--- 619,627 ----
%no-default-prec
@end example
+ Defining precidence in a grammar that provides tagging information
+ for @semantic does not usually necessary.
+
@node quotemode Decl
@subsubsection quotemode Decl
***************
*** 597,602 ****
--- 629,638 ----
%quotemode @var{symbol}
@end example
+ This is a mechanism used to specify how quoting worked in optional
+ lambda expressions.
+ @inforef{Optional Lambda Expression, , bovine}
+
@node scopestart Decl
@subsubsection scopestart Decl
***************
*** 604,609 ****
--- 640,649 ----
%scopestart @var{nonterminal}
@end example
+ The @code{scopestart} declaration specifies the name of a nonterminal
+ that is used for parsing the body of functional code. This is used
+ in the local context parser to find locally defined variables.
+
@node start Decl
@subsubsection start Decl
***************
*** 782,787 ****
--- 822,828 ----
@item sexp
@item keyword
@end table
+
@end table
@node Predefined well-known types
***************
*** 805,827 ****
@node Macros
@subsection Macros
@node BY grammars
@section BY grammars
@c Document here specificities of BY grammars. Particularly how to
@c write semantic actions, and the generated Elisp code.
@node WY grammars
@section WY grammars
@c Document here specificities of WY grammars. Particularly how to
@c write semantic actions, and the generated Elisp code.
@node Adding a new grammar mode
@chapter Adding a new grammar mode
Each specialized grammar mode is responsible for implementing the
! following @acronym{API} to provide:
@itemize @minus
@item A keyword table builder.
--- 846,876 ----
@node Macros
@subsection Macros
+ @c This refers to ASSOC, EXPANDFULL, and TAG?
+
@node BY grammars
@section BY grammars
@c Document here specificities of BY grammars. Particularly how to
@c write semantic actions, and the generated Elisp code.
+ @c This is in bovine.texi
+
@node WY grammars
@section WY grammars
@c Document here specificities of WY grammars. Particularly how to
@c write semantic actions, and the generated Elisp code.
+ @c This is in wisent.texi
+
@node Adding a new grammar mode
@chapter Adding a new grammar mode
Each specialized grammar mode is responsible for implementing the
! following @acronym{API}. Implementations are done with
! @emph{overload methods}.
! @inforef{Semantic Overload Mechanism, , semantic-langdev}.
@itemize @minus
@item A keyword table builder.
***************
*** 884,887 ****
@c Following comments are for the benefit of ispell.
! @c LocalWords: bovinator wisent LALR Elisp automagically
--- 933,936 ----
@c Following comments are for the benefit of ispell.
! @c LocalWords: bovinator wisent LALR Elisp automagically Decl
Diff finished at Sat Jan 31 12:14:32
|