CEDET

>>> David Ponce <david.ponce@...> seems to think that:
>Hi All,
>
>I checked an updated version of the Wisent's manual in.
>
>I took into account latest changes in both Wisent and Semantic, and
>cleaned up the texinfo code to follow what I saw in Emacs manuals ;-)
>
>Free free to proofread it, and maybe use better English ;-)
  [ ... ]

Hi,

  It looks good.  I tried to read the new sections but am not sure I
  read everything.

  Anyway, I have some doc for extending semanticdb I need to write
  also, and was thinking it would be good to move it all into a
  subdirectory such as "semantic/info".  It would also be good to
  split up the existing manual, as it is somewhat hard to edit at
  3000+ lines.  As many functions it refers too are now obsolete, I
  really need to go through and update it.

  Perhaps Richard has some suggestions on this topic.

Eric

ps.  Here is a short diff

*** wisent.texi.~1.18.~	Sun Feb 23 13:09:09 2003
--- wisent.texi	Sun Feb 23 13:40:20 2003
***************
*** 134,140 ****
  Wisent can generate compilers compatible with the Semantic tool set.
  See the @ref{Top, Semantic Manual, , semantic}.
  
! It benefits of the main Bison's features:
  
  @itemize @bullet
  @item 
--- 134,140 ----
  Wisent can generate compilers compatible with the Semantic tool set.
  See the @ref{Top, Semantic Manual, , semantic}.
  
! It benefits from these Bison features:
  
  @itemize @bullet
  @item 
***************
*** 383,389 ****
  @item $nterm
  This variable is initialized with the nonterminal symbol
  (@var{nonterm}) the rule belongs to.  It could be useful to improve
! error reporting or debugging.  It is used too, to automatically
  provide the @code{reparse-symbol} property of a Semantic token
  generated by the function @code{wisent-cooked-token}.  See
  @ref{Wisent Semantic}, for details.
--- 383,389 ----
  @item $nterm
  This variable is initialized with the nonterminal symbol
  (@var{nonterm}) the rule belongs to.  It could be useful to improve
! error reporting or debugging.  It is also used to automatically
  provide the @code{reparse-symbol} property of a Semantic token
  generated by the function @code{wisent-cooked-token}.  See
  @ref{Wisent Semantic}, for details.
***************
*** 1116,1122 ****
  
  It is important to understand that the parser does not parse
  characters, but lexical tokens, and does not know anything about
! characters and streams!
  
  @cindex lexical analysis
  @cindex lexer
--- 1116,1122 ----
  
  It is important to understand that the parser does not parse
  characters, but lexical tokens, and does not know anything about
! characters in text streams!
  
  @cindex lexical analysis
  @cindex lexer

-- 
          Eric Ludlam:                 zappo@..., eric@...
   Home: http://www.ludlam.net            Siege: http://www.siege-engine.com
Emacs: http://cedet.sourceforge.net               GNU: http://www.gnu.org

>>>>> "EL" == Eric M Ludlam <eric@...> writes:
    EL> 
    >>>> David Ponce <david.ponce@...> seems to think that:
    >> Hi All,
    >> 
    >> I checked an updated version of the Wisent's manual in.
    >> 
    >> I took into account latest changes in both Wisent and Semantic, and
    >> cleaned up the texinfo code to follow what I saw in Emacs manuals ;-)
    >> 
    >> Free free to proofread it, and maybe use better English ;-)
    EL>   [ ... ]
    EL> 
    EL> Hi,
    EL> 
    EL>   It looks good.  I tried to read the new sections but am not sure I
    EL>   read everything.
    EL> 
    EL>   Anyway, I have some doc for extending semanticdb I need to write
    EL>   also, and was thinking it would be good to move it all into a
    EL>   subdirectory such as "semantic/info".  It would also be good to
    EL>   split up the existing manual, as it is somewhat hard to edit at
    EL>   3000+ lines.  As many functions it refers too are now obsolete, I
    EL>   really need to go through and update it.
    EL> 
    EL>   Perhaps Richard has some suggestions on this topic.

I would like to suggest that we merge all semantic
documentation info one manual.  Of course this doesn't mean
that we can't split the manual into several files.

I provide a very rough outline below.

If we agree on this approach, we can work on refining the
structure (chapters and sections) and brief summaries of
each chapters and sections.  Then we can merge existing
semantic/wisent documents first.  Refining I'm sure would
follow.  

I will be happy to act as the secretary in making pushing
things along so that we have semantic 2.0 manual to go along
with the first release.


\input texinfo  @c -*-texinfo-*-
@c %**start of header
@set TITLE  Semantic Manual
@set AUTHOR Semantic Developers
@setfilename semantic-manual.info
@settitle @value{TITLE}

@node top
@top @value{TITLE}

@menu
* Overview::                    
* Installation::                
* Semantic User's Guide::       
* Application Developer's Guide::  
* Parser Developer's Guide::    
* Semantic Internals::          
* Index::                       
@end menu

@node Overview
@chapter Overview

This chapter gives the overview of semantic and its goals.
Things to mention here could be:

@example
* regular expressions (and syntax tables) are the basis of identifying
  components of a buffer for purposes such as color highlighting
* regexp is useful but has limitations
* semantic provides new intrastructure that goes far beyond regexp
  based text analysis by
  - parse each buffer based on the grammar of the language
  - define a uniform structure of the parse tree mostly independent of
    any one language
  - define an API so that programmers can develop applications that
    work for all languages
  - provide bison-like parser generator so that new languages can be
    supported easily
  - provide a set of applications that demonstrate the usefulness
    of semantic.

The following diagram illustrates the benefits of using semantic:

* Semantic parses a language (for which a parser is available) and
  produces a common parse tree regardless of the original source
  language.

* Semantic provides a common API based on which applications can be
  written in a language independent way.  This means that the
  application will work for ALL languages for which a semantic parser
  can be witten.

* Semantic provids good set of tools and examples for the appplication
  writers.

* Semantic also provies extensive tools for the parser developers as well.
  For many languages, those that can be described using a context-free
  grammer, all that one needs to do is write a grammar file along with
  appropriate semantic rules.


The words in all-capital are those that semantic itself provides.
Others are current or future languages or applications that are not
distributed along with semantic.


                                                             Applications
                                                                 and
                                                              Utilities
                                                                -------
                                                               /       \
               +---------------+    +--------+    +--------+
         C --->| C      PARSER |--->|        |    |        |
               +---------------+    |        |    |        |
               +---------------+    | COMMON |    | COMMON |<--- SPEEDBAR
      Java --->| JAVA   PARSER |--->|        |    |        |
               +---------------+    | PARSE  |    | PARSE  |<--- SENATOR
               +---------------+    |        |    |        |
    Python --->| PYTHON PARSER |--->| TREE   |    | TREE   |<--- DOCUMENT
               +---------------+    |        |    |        |
               +---------------+    | FORMAT |    | API    |<--- SEMANTICDB
    Scheme --->| SCHEME PARSER |--->|        |    |        |
               +---------------+    |        |    |        |<--- jdee
               +---------------+    |        |    |        |
   Texinfo --->| TEXI.  PARSER |--->|        |    |        |<--- ecb
               +---------------+    |        |    |        |

                    ...                ...           ...         ...

               +---------------+    |        |    |        |<--- app. 1
   Lang. A --->| A      Parser |--->|        |    |        |
               +---------------+    |        |    |        |<--- app. 2
               +---------------+    |        |    |        |
   Lang. B --->| B      Parser |--->|        |    |        |<--- app. 3
               +---------------+    |        |    |        |

                     ...        ...     ...          ...       ...

               +---------------+    |        |    |        |
   Lang. Y --->| Y      Parser |--->|        |    |        |<--- app. ?
               +---------------+    |        |    |        |
               +---------------+    |        |    |        |<--- app. ?
   Lang. Z --->| Z      Parser |--->|        |    |        |
               +---------------+    +--------+    +--------+
@end example

@node Installation
@chapter Installation

@node Semantic User's Guide
@chapter Semantic User's Guide

This chapter describes how to use semantic for the end user.
Hopefully not much elisp knowledge is required for the
target audience of this chapter.

Also describe each of the applications that come with semantic
as well as mention third party applications such as jdee and ecb.

@menu
* semanticdb::                  
* speedbar::                    
* senator::                     
* analyzer::                    
* class browser::               
* document::                    
* charts::                      
@end menu

@node semanticdb
@section semanticdb
@cindex semanticdb

Describe what this is and how the user can control its behavior.

@node speedbar
@section speedbar
@cindex speedbar

Give brief overview and refer to the speedbar documentation.

@node senator
@section senator
@cindex senator

@node analyzer
@section analyzer
@cindex analyzer

@node class browser
@section class browser
@cindex class browser

@node document
@section document
@cindex document

@node charts
@section charts
@cindex charts

@node Application Developer's Guide
@chapter Application Developer's Guide

This chapter is for developers of semantic applications
such as JDEE and ECB.
Describe all things that such developers would need to know
such as semantic token structures and API.

Most of the stuff from @ref{Programming,,,semantic}
would go here.

@node Parser Developer's Guide
@chapter Parser Developer's Guide

This chapter is for those who would like to add a new parser to the
growing family of parsers.
This chapter should
@example
* describe wisent LALR parser, bovine LL parser, and give examples of
  custom parsers.
* describe grammar file formats, semantic actions.
* describe how to write lexers
* give examples such as wisent-awk, wisent-calc, etc
@end example    

@menu
* Parser Overview::             
* Writing Grammars::            
* Writing Lexers::              
* Parser Error Handling::       
@end menu

@node Parser Overview
@section Parser Overview
@cindex Parser Overview

@example
wisent parsers
bovine parsers
custom parsers
@end example

@node Writing Grammars
@section Writing Grammars
@cindex Writing Grammars

@node Writing Lexers
@section Writing Lexers
@cindex Writing Lexers

@example
semantic-flex?
new lexer based on macros
@end example

@node Parser Error Handling
@section Parser Error Handling
@cindex Parser Error Handling

@node Semantic Internals
@chapter Semantic Internals

This chapter explains the internals of semantic.
This information would not be needed by neither applicatioan developers
nor grammar developers.

It would be useful mostly for the hackers who would like to learn
more about how semantic works.

@node Index
@unnumbered Index
@printindex cp

@iftex
@contents
@summarycontents
@end iftex

@bye