|
Re[1]: [CEDET-devel] Updated Wisent's manual
From: <ryk@ds...> - 2003-02-24 02:13
|
>>>>> "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
|
| Thread | Author | Date | |
|---|---|---|---|
| [CEDET-devel] Updated Wisent's manual | David Ponce <david.ponce@wa...> |
|
|