$Header: /usr/home/web681a3/repository/documentation/natstar2.htm,v 1.2 2006/04/29 00:24:44 joerg Exp $
natstar to HTML (natstar2HTML) converts your natstar projects into a complete collection of HTML pages for documentation purposes.
the main focus is laid on the NCL part. using extensivly the technique of HTML links, 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!
Natstars NCL code is syntax highlighted, so that reading it is easy. embedded c-code is displayed in a different colour, so that it imediatly is visible as such.
a great bulk of analisys and cross reference data 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.
the programm is written in ISO-C++ 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.
keep your documentation up to date! 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 NSA-config.
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.
natstar2HTML gives a productivity boost to your natstar projects.
you can use a searche engine (like altavista) to provide a fulltext search on your natstar projects.
test it!
just send an export of your complete natstar project to siliconbrain, and you get back the complete output as an HTML documentation.
call:
natstar2HTML <export_file> <output_dir>
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".
the apendix is made out off:
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.
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.
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.)
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.
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.
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.
before strolling thru the other parts first some words on the NCL code.
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.
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.
the later is especially usefull, if complete blocks of NCL code is inactivated by
%
/*
...
*/
%
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.
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.
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.
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.
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.
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).
syntactically a trigger is a method without a method definition or better with a natstar supplied method definiton.
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.
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.
here only a syntactical analysis is perfomed. if there is a call like
!(hAddress%).create
hAddress% 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 THINGS_NEW "ADDRESS", hAddress% imediatly before
the call), this information is not used. in other words: there is no semantical
analysis.
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.
in the current version only the export code is shown. normaly its not very useful.
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 usage analysis equal to that of classes
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.
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.
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.
this is followed by the parameterdefiniton (typedefs are again hyperlinked) and by a list of usages (calls to that method-definiton).
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.
the usage of an instruction in process models is not recognized in this version
its value followed by its usage list.
currently only for FUNCTION processes. only the syntax highlighted hyperlinked NCL code is shown. no usage analysis
after a link to the window model follows all events controls and their events.
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
send EXECUTED to hMyWindow%
hMyWindow%.
in the event implementation and usage analysis you find a list of all implementations
and all usages, like in the documentation of method definitions.
syntactically a trigger is a method without a method definition or better with a natstar supplied method definiton.
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.
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.
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.
at the end there is a list of usages in NCL code.
it i displayed as is, where words equal to known resources are represented by links to their definition.
the definition followed by a list of usages in natstar NCL code.
the type is displayed. following is the list of external definitions for several databases.
at the end there is the usual usage list. the typedef is usd in NCL code, parameter definitions, variable types.
a window model is exactly equal documented as a window. see there.
a target has little information. this is displayed here.
in the appendix there are several lists:
all string constants used in natstars NCL code are listed by their value. so
when in the code there is something like:
move 'DAT-0004' to RCODE2
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.
the same list but sorted by the name of the constant, but independent of the library implementing this constant. <(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.
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.
a list of hyperlinked definitions of global variables.
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.
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.
because the long desriptions are hard to fin but perhaps contain valuable information, here is a list of all those documentations.
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.
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.
this web page was designed by joerg kunze.
copyright; 1999, 2006 joerg kunze
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.
this web page is distributed in the hope that it is useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. see the GNU General Public License for details.
you should have received a copy of the GNU General Public License along with these web page; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
$Log: natstar2.htm,v $
Revision 1.2 2006/04/29 00:24:44 joerg
add Header and Log cvs keywords