"Fossies" - the Fresh Open Source Software Archive

Member "ivtools-ivtools-2.0.4/src/html/README" (9 Oct 2020, 3848 Bytes) of package /linux/misc/ivtools-ivtools-2.0.4.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 Instructions for auto-generating ivtools html documentation.
    2 ------------------------------------------------------------
    3 
    4 1. Background
    5 
    6 ivtools header files (.h files) include comments that can be extracted
    7 by PERCEPS, an automatic documentation generator for C++ written in
    8 Perl (http://starship.python.net/crew/tbryan/PERCEPS/).
    9 
   10 ivtools uses three techniques supported by PERCEPS for embedding
   11 extractable comments:
   12 
   13 	1. one-line class definition -- comments that proceed a class
   14 	definition (or any free-standing function, global, or typedef)
   15 	that start with a "//:"
   16 
   17 	2. multi-line class description -- comments that follow a
   18 	"//:" comment that start with "//", and still proceed the
   19 	class definition.
   20 
   21 	3. class member descriptions -- comments inside a class
   22 	definition that begin with a "//" that immediately follow any
   23 	particular item.
   24 
   25 Normal C comments, of the "/* */" style are not extracted.
   26 
   27 PERCEPS first extracts the class information, then uses a directory of
   28 templates (PERL plugins) to generate documentation of arbitrary
   29 format.  The "templates" directory within this directory generates
   30 HTML documentation for each individual class, plus two global indexes,
   31 and one page of miscellaneous information.
   32 
   33 
   34 2. Generating HTML Documentation for C++ Classes
   35 
   36 To generate the HTML documentation for each C++ class defined in
   37 ivtools, do the following:
   38 
   39 	2.1 Acquire and install a copy of PERCEPS, Version 3.4.1 or
   40 	greater.  Get it from the maintainers's website:
   41 
   42 		http://starship.python.net/crew/tbryan/PERCEPS/
   43 
   44 	or from here:
   45 
   46 		http://www.ivtools.org/pub/src/perceps341.tgz
   47 
   48 	2.2 Verify your version of Perl is >= 5.003 with:
   49 
   50 		perl --version
   51 
   52 	
   53 	2.3 Verify your copy of Perl is installed at /usr/bin/perl:
   54 
   55 		which perl
   56 
   57 	    If it is not at that location, edit the first line of the 
   58 	    perceps script in this directory to reflect the actual
   59 	location, or make a symbol link for.
   60 
   61 
   62 	2.4 Run the following commands to generate the html:
   63 
   64 		mkdir classes
   65 		cd ..
   66 		html/perceps.pl -t html/templates -d html/classes `cat ../MANIFEST.perceps`
   67 	        cd html
   68 
   69 	    The whole process takes some time, especially the generation of the
   70 	    global html/classes/index.html.	
   71 
   72 
   73 3. Generating Derived Class HTML
   74 
   75 Two more web pages are needed in the classes sub-directory to make it
   76 complete: derivedclasses.html, a list of links to class web pages
   77 immediately followed by links to each of their immediate derived (or
   78 children) classes; and derivedtree.html, a tree structured web page of
   79 all classes without parents followed by their complete tree of derived
   80 classes.
   81 
   82 iclass has been modified to generate these automatically.
   83 
   84 	3.1 Generating classes/derivedclasses.html
   85 
   86 	cd ..;iclass -r -c -d . >html/classes/derivedclasses.html;cd html
   87 
   88 	3.2 Generating classes/derivedtree.html
   89 
   90 	cd ..;iclass -r -c -t . >html/classes/derivedtree.html;cd html
   91 
   92 4. Acquiring HTML Documentation related to InterViews 3.1
   93 
   94 Some of the HTML documentation generated for the ivtools classes
   95 contains embedded links to HTML versions of the original InterViews
   96 3.1 man pages and reference manual.  Two scripts are included in this
   97 directory to facilitate downloading these directories from the online
   98 directory of ivtools documentation.  These web pages are available
   99 under the same COPYRIGHT and license of ivtools.
  100 
  101 	4.1 HTML versions of InterViews 3.1 man pages
  102 
  103 	Run the shell script getman31.sh from this directory.
  104 	Requires an installed and working copy of the ivtools utility
  105 	ivdl.  The script can be edited to use w3c or curl or any other
  106 	command line URL grabber.
  107 
  108 	4.2 HTML versions of InterViews 3.1 reference manual
  109 
  110 	Run the shell script getrefman31.sh from this directory.
  111 	Requires an installed and working copy of the ivtools utility
  112 	ivdl.  The script can be edited to use w3c or curl or any other
  113 	command line URL grabber.
  114