>>> "David PONCE" <David.Ponce@...> seems to think that:
[ ... ]
>> 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.
>[...]
>
>GNU Emacs uses emacs/man for manual sources (.texi) and emacs/info for
>manual in info format.
>
>Maybe we could use a such organization? However I would prefer
>"semantic/doc" to "semantic/man" because "man" is already reserved for
>Un*x manuals ;-)
I think semantic/doc makes sense.
[ ... ]
>> 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.
[ ... ]
>
>Thanks Richard, I love that idea! I found your outline very good.
>Maybe could you check it in in a new semantic/doc (or what we decide
>to use) directory. It would be an excellent starting point.
>
>Eric, what do you think?
I agree. I certainly think that getting things started is a good
idea.
>Could you suggest me where I could split the wisent manual up, and
>where to insert parts in the global outline? I would really
>appreciate it :-)
Your outline so far is great. I have the follow suggestions, most of
which are just enhancements on things you probably didn't get to.
It would be great if the outline contained the include statements
where you suggest sections of the manual could be written. This
would answer David's question most succinctly.
For the parser developer, I can think of two extra sections. One for
semanticdb extensions, (If a system database is needed.) A second
for the `semantic-ctxt' extensions. Many of the most interesting
tools will completely fail to work without local context parsing
support.
Perhaps even a section on foreign tokens. For example, putting a
Java token into a C++ file could auto-gen a native method, just as
putting a token into a Texinfo file converts it into documentation.
In addition, in the "writing grammars" section should have
subsections as listed in the examples of the overview section. It
might be useful to have a fourth section describing the similarities
between the two file types (by and wy) and how to use the grammar
mode. (I'm not sure if that should be covered elsewhere.)
With those sections, perhaps instead of "Parser Developer", a better
term is "Language Support Developer" where the parser is one subset
of a greater whole of completely abstracting the language so that it
can be used by generic tools.
An application developer section needs to know how to get token lists,
get details from tokens, extract and search those lists with and
without the database, and convert tokens into displayable text
strings in one of the many different formats.
Thanks!
Eric
--
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
|