<HTML>
<HEAD>
<TITLE> natstar2HTML: the natstar NCL documentation generator </TITLE>
<META name="keywords" content="NatStar, C++, C, HTML, SGML, XML, documentation, siliconbrain">
<META name="description" content="siliconbrain project: programming in ISO ANSI C++ wehave created
a programm converting a natstar project into a collection of HTML pages.">
</HEAD>
<BODY>
<H1> natstar2HTML: the natstar NCL documentation generator </H1>
<pre>
$Header: /repository/documentation/natstar2.htm,v 1.2 2006/04/29 00:24:44 joerg Exp $
</pre>
<H2> summary </H2>
<!-- the following summary is also the short description sended via mail -->
<!-- to interested people. it ends with the next H2 tag. -->
<P> natstar to HTML (natstar2HTML) converts your <STRONG> natstar projects </STRONG> into a complete
collection of <STRONG>HTML pages</STRONG> for documentation purposes.</P>
<P> the main focus is laid on the <STRONG>NCL</STRONG> part. using extensivly the technique of
<STRONG>HTML links</STRONG>, you can surf thru your code. whenever in your NCL code or in
Natstar Variable definitions, library uses and so on, another object is used,
there is put a link in the code, so that you directly can jump to the documentation
of that object. with just a single mouse click! </P>
<P> Natstars NCL code is <STRONG>syntax highlighted</STRONG>, so that reading it is easy. embedded
c-code is displayed in a different colour, so that it imediatly is visible as
such. </P>
<P> a great bulk of <STRONG>analisys and cross reference data</STRONG> is added. the usage of objects,
all constants sorted by definition value, all events and their implementations and
much more. the appendix includes a list of all global variables, a list of not used
resources, a list of all long descriptions (which are realy hard to find in the
natstar development environment), a list of all embedded C-code and more. </P>
<P> the programm is written in <STRONG>ISO-C++</STRONG> and is developed on Macintosh and windows. ports
to other operating systems, where an ISO-C++ compiler is available will be possible
at low cost. </P>
<P> keep your documentation <STRONG>up to date</STRONG>! you no longer have to worry about your programmers
keeping their documentation fitting to the actual implementation of the natstar
objects. they just have to put their additional explanations in the description
(the long form). this text is put formatted and containing hyperlinks into the
HTML documentation. if you do, your documentation is automatically administered by
<STRONG>NSA-config</STRONG>. </P>
<P> natstar2HTML keeps your documentation up to date, provides a bulk of analisys data
for quality assurance and reengineering, helps to handle documentation with NSA-config,
helps your programmers to understand existing natstar implementations. </P>
<P> natstar2HTML gives a productivity boost to your natstar projects. </P>
<P> you can use a searche engine (like altavista) to provide a fulltext search
on your natstar projects. </P>
<HR>
<H2> test </H2>
<P> <STRONG>test it!</STRONG> </P>
<P> just send an export of your complete natstar project to <STRONG>siliconbrain</STRONG>, and you get back
the complete output as an HTML documentation. </P>
<HR>
<H2> description </H2>
<UL>
<LI> <A HREF = #usage > usage </A> </LI>
<LI> <A HREF = #index > index </A> </LI>
<LI> <A HREF = #description > description </A> </LI>
<LI> <A HREF = #NCL > NCL </A> </LI>
<LI> <A HREF = #classes > classes </A> </LI>
<LI> <A HREF = #process_model> process model </A> </LI>
<LI> <A HREF = #library > library </A> </LI>
<UL>
<LI> <A HREF = #function > function </A> </LI>
<LI> <A HREF = #method_definition > method definition </A> </LI>
<LI> <A HREF = #instruction > instruction </A> </LI>
<LI> <A HREF = #constant > constant </A> </LI>
<LI> <A HREF = #process > process </A> </LI>
<LI> <A HREF = #window > window </A> </LI>
<LI> <A HREF = #trigger > trigger </A> </LI>
<LI> <A HREF = #template > template </A> </LI>
<LI> <A HREF = #segment > segment </A> </LI>
<LI> <A HREF = #text > text </A> </LI>
<LI> <A HREF = #global > global </A> </LI>
<LI> <A HREF = #typedef > typedef </A> </LI>
</UL> </LI>
<LI> <A HREF = #window_model> window model </A> </LI>
<LI> <A HREF = #target > target </A> </LI>
<LI> <A HREF = #appendix > appendix </A> </LI>
<UL>
<LI> <A HREF = #strings > all strings </A> </LI>
<LI> <A HREF = #constants_content > constants (by content) </A> </LI>
<LI> <A HREF = #constants_name > Constants (by name) </A> </LI>
<LI> <A HREF = #members > members of libraries and classes</A> </LI>
<LI> <A HREF = #not_used > NOT USED members of libraries and classes</A> </LI>
<LI> <A HREF = #globals > Global variables </A> </LI>
<LI> <A HREF = #events > Events </A> </LI>
<LI> <A HREF = #triggers > Trigger </A> </LI>
<LI> <A HREF = #documents > Documents </A> </LI>
<LI> <A HREF = #c-codes > c-codes </A> </LI>
<LI> <A HREF = #hint > hint for NSA-Config users: </A> </LI>
</UL> </LI>
</UL>
<A NAME = "usage" ></A>
<H3> usage </H3>
<P> call:
<CODE><PRE>
natstar2HTML <export_file> <output_dir>
</PRE></CODE>
the <output_dir> must end in a \ in the actual version. </P>
<A NAME = "index" ></A>
<H3> index </H3>
<P> the index is the start page. it lists all classes, libraries, window models,
process models and a collection of appendices. you can start with a certain
class, library, ... which you now, or you imediatly go to some appendix if
you investigate special questions, for example: what is the name of the
constant with the value "ERROR-42". </P>
<P> the apendix is made out off:
<UL>
<LI> all string constants used in NCL code </LI>
<LI> all constants sorted by name (not by library) </LI>
<LI> all constants sorted by value</LI>
<LI> all resources sorted alphabetically independend of library </LI>
<LI> all not used resources </LI>
<LI> all global variables </LI>
<LI> all events including their usage and implementations </LI>
<LI> all library and class triggers and their implementations </LI>
<LI> all long descriptions </LI>
<LI> all embedded C-code </LI>
</UL>
</P>
<A NAME = "description" ></A>
<H3> description </H3>
<P> in the natstar developement environment, every library, class, method, function,
variable, virtually everything can have a long description. this description
has to be distinguished from the description line, which is displayed in the lists
of these resources. the later is easyly seen, but for the long form you have to open
a special natstar textprocessing editor. </P>
<P> so it is very hard work to find pieces of information. in projects, where documentation
of this kind is seldom, the programmers will usually not open this description. </P>
<P> in the generated HTML documentation, the long description is put at the beginning
of every resource or lib or class (except for class variables in this version). part
of the formating is converted to HTML formating. (to be exact: font, size, italic
and bold.) </P>
<P> inside the generated long description each word, which is a known lib, class or
resource name, is converted to a hyperlink to its definition. so it is very easy
to create HTML linked documentation. </P>
<P> because nsa config saves also this descriptions, you combine the advantage
of documentation synchronized automatically with the version of your software,
with the advantage of modern hyper linked information presentation. </P>
<P> of course the short description, the single line associated to each resource,
is displayed at the beginning of each defining location
all the time without mentioning in this document. </P>
<A NAME = "NCL" ></A>
<H3> NCL </H3>
<P> before strolling thru the other parts first some words on the NCL code. </P>
<P> in natstar, everything which cannot be implemented by point and click is
written in natstars own programming language NCL. NCL is a normal programming
language like C or COBOL. </P>
<P> each pice of NCL code is displayed with syntax highlighting. strings are green,
NCL key words are blue, comments are red (for documentation purposses, comments
are the most importand). embedded C-code is displayed in gray. </P>
<P> the later is especially usefull, if complete blocks of NCL code is inactivated by </P>
<CODE><PRE>
%
/*
...
*/
%
</PRE></CODE>
<P> if you scroll in the code its easy not to see the % and /*. but because its
gray, you immediatly see that this code is not real NCL. </P>
<P> in the NCL code each usage of a method, function, constant, typedef, ... is
placed as a hyperlink to the definition of that resource. so when you read NCL
and you want to know the value of a constant, just click on it. </P>
<P> each usage of these resources is collected. in the definition part of them, you see
a list of all usages in NCL code. so its easy to know all places where for example
a certain typedef is used. <P>
<A NAME = "classes" ></A>
<H3> classes </H3>
<P> first you see an alphabetical list of all mehtods implemented in this class. each
entry is a hyperlink, so you quickly can jump to the method. </P>
<P> next is the superclass, which is again a link, followed by the list of
variables, including the description and again as link the typedef or the
ref-class. </P>
<P> each method has a hyperlink to its method definition, the definition of the
parameters (with the typedefs again as hyperlinks) followed by the NCL code full of
hyperlinks and HREF anchors (the targets of links from else where). </P>
<P> syntactically a trigger is a method without a method definition or better with
a natstar supplied method definiton. </P>
<P> a trigger is documented by its NCL code plus a link to the
trigger implementation and usage analysis, wich is the substitution to the missing
method definition. the natstar defined parameter definition is not shown. </P>
<P> at the end of every method you find a list of all places where this method
is used (called) again as a link. so you can very quickly investigate the
method calling NCL codes. </P>
<P> here only a syntactical analysis is perfomed. if there is a call like
<CODE><PRE>
!(hAddress%).create
</PRE></CODE>
potentially <CODE>hAddress%</CODE> could hold a handle to any class implementing
the method definition "CREATE". if program flow forces hAddress to be a handle
to a specific class (e.g. a <CODE> THINGS_NEW "ADDRESS", hAddress%</CODE> imediatly before
the call), this information is not used. in other words: there is no semantical
analysis.
<P> <A NAME="usage"></A> at the very end of the class page you find a list of all
libraries which are
part of the usage list. this list is displayed in three forms: 1. an alphabetically
list of all directly used libs. this is what you see in the natstars usage section. 2.
an alphabetical list of all used libs including the idirectly used ones (libs, which are used
by used libs). 3. the second list is displayed as a tree, so you can see which
lib is responsible for the indirectly used ones. </P>
<A NAME = "process_model" ></A>
<H3> process model </H3>
<P> in the current version only the export code is shown. normaly its not very
useful. </P>
<A NAME = "library" ></A>
<H3> library </H3>
<P> first is as it is for classes, an index of all resources implemented in this
lib. after a eventaully existing long description folloows a section for
each resource implemented in this lib. at the very end you find a
<A HREF="#usage" >usage
analysis</A> equal to that of classes </P>
<A NAME = "function" ></A>
<H4> function </H4>
<P> after the return type and the list of parameters follows the syntax
highlighted hyperlinked NCL code. after the NCL part you find the list
of all calls to that function. </P>
<A NAME = "method_definition" ></A>
<H4> method definition </H4>
<P> a method definition can be used by many methods. the classes of these methods
even need not to stay in some inheritance relations. a method definition is
a pure interface definition and a method of a class is an interface implementation.
the same interface can be implemented by many classes. </P>
<P> the first part of the method definition documentation is is hyperlinked list
of all implementation of this menthod definition. in other words, a list of all
methods with same name. <P>
<P> this is followed by the parameterdefiniton (typedefs are again hyperlinked) and
by a list of usages (calls to that method-definiton). </P>
<A NAME = "instruction" ></A>
<H4> instruction </H4>
<P> after the list of parameters follows the syntax
highlighted hyperlinked NCL code. after the NCL part you find the list
of all calls to that instruction. </P>
<P> the usage of an instruction in process models is not recognized in this
version </P>
<A NAME = "constant" ></A>
<H4> constant </H4>
<P> its value followed by its usage list. </P>
<A NAME = "process" ></A>
<H4> process </H4>
<P> currently only for FUNCTION processes. only the syntax highlighted hyperlinked NCL
code is shown. no usage analysis </P>
<A NAME = "window" ></A>
<H4> window </H4>
<P> after a link to the window model follows all events controls and their events. </P>
<P> for each event there is a link to the event implementation and usage analysis.
the reason is, that events behave similar to methods. if you have a code like
<CODE><PRE>
send EXECUTED to hMyWindow%
</PRE></CODE>
you know the real event only, when you know the contents of <CODE>hMyWindow%</CODE>.
in the event implementation and usage analysis you find a list of all implementations
and all usages, like in the documentation of method definitions. </P>
<A NAME = "trigger" ></A>
<H4> trigger </H4>
<P> syntactically a trigger is a method without a method definition or better with
a natstar supplied method definiton. </P>
<P> a trigger is documented by its NCL code plus a link to the
trigger implementation and usage analysis, wich is the substitution to the missing
method definition. </P>
<A NAME = "template" ></A>
<H4> template </H4>
<P> syntactically a template is much the same as a window. so afer a link to
the underlying template model you find all events controls and their events like
in the documentaqtion of windows. </P>
<A NAME = "segment" ></A>
<H4> segment </H4>
<P> each segment is documented by a table of its elements. if the type of an entry
is a sub-segment it is a hyperlink to the documentation of the sub-segment. </P>
<P> at the end there is a list of usages in NCL code. </P>
<A NAME = "text" ></A>
<H4> text </H4>
<P> it i displayed as is, where words equal to known resources are represented
by links to their definition. </P>
<A NAME = "global" ></A>
<H4> global </H4>
<P> the definition followed by a list of usages in natstar NCL code. </P>
<A NAME = "typedef" ></A>
<H4> typedef </H4>
<P> the type is displayed. following is the list of external definitions for
several databases. </P>
<P> at the end there is the usual usage list. the typedef is usd in NCL code, parameter definitions,
variable types. </P>
<A NAME = "window_model" ></A>
<H3> window model </H3>
<P> a window model is exactly equal documented as a window. see there. </P>
<A NAME = "target" ></A>
<H3> target </H3>
<P> a target has little information. this is displayed here. </P>
<A NAME = "appendix" ></A>
<H3> appendix </H3>
<P> in the appendix there are several lists: </P>
<A NAME = "strings" ></A>
<H4> all strings</H4>
<P> all string constants used in natstars NCL code are listed by their value. so
when in the code there is something like:
<CODE><PRE>
move 'DAT-0004' to RCODE2
</PRE></CODE>
you will find an entry DAT-0004 in this list. </P>
<A NAME = "constants_content" ></A>
<H4> constants (by content)</H4>
<P> a list of all constants sorted by their contents. so if there is a constant
with the value "ERROR-42", you will find it in the list. if you click on it,
you get the definition including the usage list. </P>
<A NAME = "constants_name" ></A>
<H4> Constants (by name)</H4>
<P> the same list but sorted by the name of the constant, but independent of the
library implementing this constant. <(P>
<A NAME = "members" ></A>
<H4> members of libraries and classes</H4>
<P> all resources listed alphabeticaly. so if you look for a function, method,
typedef, ... and you don't know the lib, look up here via name. </P>
<A NAME = "not_used" ></A>
<H4> NOT USED members of libraries and classes</H4>
<P> it is intendet to provide a list of resources that can be deleted. unfortunatly
"not used" means not detected by natstar2HTML. it is often used by natstar but
not detected. so an entry in the "not used" list is just a hint to investigate,
if it is perhaps realy not used. </P>
<A NAME = "globals" ></A>
<H4> Global variables</H4>
<P> a list of hyperlinked definitions of global variables. </P>
<A NAME = "events" ></A>
<H4> Events</H4>
<P> a list of all events sorted by name. you find a link to each implementation
of an event of that name, plus a list of usages in send statments. </P>
<A NAME = "triggers" ></A>
<H4> Trigger</H4>
<P> a list off all library or class triggers. because triggers have the same name
in different classes and libraries, the idea is the same as for method definitions.
there is a list of implementations plus a list of usages. </P>
<A NAME = "documents" ></A>
<H4> Documents</H4>
<P> because the long desriptions are hard to fin but perhaps contain valuable
information, here is a list of all those documentations. </P>
<A NAME = "c-codes" ></A>
<H4> c-codes</H4>
<P> C-code can be used to comment out blocks of code, use C-defined values (e.g.
NS_UNIX) or to do very speciall things. a list of all C-code usages
is provided here. </P>
<A NAME = "hint" ></A>
<H4> hint for NSA-Config users:</H4>
<P> natstar2HTML only supports single input file. so first create a complete
workspace, containig all resources of your natstar project, then export everything
then convert it to HTML. </P>
<HR>
<P> <A HREF="index.htm">the silicon brain home page</A> </P>
<P> <A HREF="mailto:info@siliconbrain.com">contact
SiliconBrain</A></P>
<ADDRESS>
<A HREF="mailto:info@siliconbrain.com">info@siliconbrain.com</A>
</ADDRESS>
<P> this web page was designed by joerg kunze.</P>
<P> copyright; 1999, 2006 joerg kunze </P>
<P> this web page is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the license or (at your opinion) any later version.</P>
<P> this web page is distributed in the hope that it is useful, but
<STRONG>without any warranty</STRONG>; without even the implied warranty of
<STRONG>merchantability</STRONG> or <STRONG>fitness for a particular
purpose</STRONG>. see the GNU General Public License for details.</P>
<P> you should have received a <A HREF="gpl.html">copy of the GNU
General Public License</A>
along with these web page; if not, write to the
<A HREF="http://www.fsf.org/">Free Software Foundation</A>, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.</P>
<hr>
<pre>
$Log: natstar2.htm,v $
Revision 1.2 2006/04/29 00:24:44 joerg
add Header and Log cvs keywords
</pre>
</BODY>
</HTML>