Short:        KeepPrivate - header/autodocs strip
Author:       John Haubrich
Uploader:     amigasourcecodepreservation gmail com
Type:         dev/misc
Version:      1.1
Architecture: m68k-amigaos

KeepPrivate will strip private methods and attributes from autodocs and
header files, generating a public output file.

Uploaded to aminet for historical preservation.


NOTES
=======
KeepPrivate 1.1
(C) 1999  John M Haubrich Jr
          All Rights Under Copyright Reserved

PURPOSE
   KeepPrivate will strip private methods and attributes from autodocs and
   header files, generating a public output file.


ASSUMPTIONS
   KeepPrivate assumes that a MUI autodocs file is split into two sections:
      * A HEADER section that declares the list of attrs/methods.
      * A DETAIL section that itemizes the attrs/methods with corresponding
      full description.

   The two sections are delimeted by a FORMFEED character (ASCII 12).

   For example:

   ------------------------- START: MCC_TreeList.doc -----------------------
   TABLE OF CONTENTS

   TreeList.mcc/TreeList.mcc
   TreeList.mcc/MUIA_TreeList_Active
   TreeList.mcc/MUIA_TreeList_CollapseHook
   TreeList.mcc/MUIM_TreeList_EmbezzleFunds     //private
   TreeList.mcc/MUIM_TreeList_EvadeAuthorities     //private
   TreeList.mcc/MUIM_TreeList_RetireInNevis


   TreeList.mcc/TreeList.mcc

      Author: John Haubrich
      E-Mail: johnh@kc.net
      Web   : www.kc.net/~johnhkc/

      TreeList.mcc is a subclass of list class that provides easy access
      to tree data-structure.  TreeList class handles multi-select logic.

   TreeList.mcc/MUIA_TreeList_Active

      NAME
        MUIA_TreeList_Active -- [.SG], APTR

      SPECIAL INPUTS
        MUIV_TreeList_Position_Root
         MUIV_TreeList_Active_Off

      FUNCTION
        Set active node.

   TreeList.mcc/MUIA_TreeList_CollapseHook

      NAME
        MUIA_TreeList_CollapseHook -- [IS.], struct Hook *

      FUNCTION
        The collapse hook is called after a list node is closed, then you can
         change the list.  The collapse hook will be called with the hook
        in A0, the TreeList object in A2 and the tree node in register A1.

      SEE ALSO
        MUIA_TreeList_Expand, MUIA_TreeList_ExpandHook

   TreeList.mcc/MUIM_TreeList_EmbezzleFunds

      NAME
        MUIM_TreeList_EmbezzleFunds

   file continues...
   -------------------------- END: MCC_TreeList.doc ------------------------

   The HEADER section contains a list of all attrs/methods that are defined
   below in the DETAIL section.  Each attr or method definition is preceded
   by a FORMFEED character (ASCII 12).  The first FORMFEED character detected
   by the program signals the start of the DETAIL section.  (You may also have
   a FORMFEED character on the class name line, TreeList.mcc/TreeList.mcc.


USAGE

   For an AUTODOCS file:
      Add the "//PRIVATE" keyword to the attr or method declaration line in
      the header only.  The header declaration and the detail definition of
      this "entity" will be excluded from the public output file.  In the
      above example, the _EmbezzleFunds and _EvadeAuthorities methods will
      be excluded from the public output file.

   For a HEADER file:
      Add the "//PRIVATE" keyword to every line of the file to be excluded
      from the public file.


LAUNCHING THE PROGRAM

   From the Shell or CLI:
      KeepPrivate infile outfile [HEADER]
   where
      infile  is the master header file with '//private' keywords inserted.
      outfile is the public header output file.
      HEADER   keyword is specified when parsing a header input file.
            Otherwise, the program parses an autodocs file.


RESULTS

   For an autodocs file, a statistics line will appear after processing with
   totals for the number of private methods detected in the header and
   excluded in the detail section.  If these numbers do not match,
   a warning will appear.  Return Code 2.

   For a header file, a generic success message will print after parsing
   is completed.


RETURN CODES

   DOS return codes are as follows:
      20 Cannot open input or output file.
      10 Program arguments are incorrect.
       5 Buffer overflow (non-deadend).
       2 Exclusion count mismatch between header and detail sections.


LIMITATIONS

   * Input file must have formfeed after header section.
   * Input file must have formfeed immediately preceding method/attribute
     name in detail section.
   * Program is limited to tracking 2048 attr/method names per file.  If this
     is insufficient, you may run the program again with the output from the
     first iteration as the input to the second iteration.  A warning message
     will appear if this condition occurs.  Return Code 5.
   * If the documentation for a public attr or method references a private
     attr or method, this tool will not exclude that information.
   * The "//PRIVATE" keyword must be specified on every excludable line of a
     header file.
   * The FORMFEED character should immediately precede the attr/method name
     in the detail section.  The program will still parse correctly but it
     will display incorrect information during processing (to stdout).


Cheers!
https://twitter.com/AmigaSourcePres

  _____ ___   _   __  __     _   __  __ ___ ___   _   
 |_   _| __| /_ |  /  |   /_ |  /  |_ _/ __| /_  
   | | | _| / _ | |/| |  / _ | |/| || | (_ |/ _  
  _|_| |___/_/ __|_ |_|_/_/___|__|_|______/_/__
 / __|/ _ | | | | _ / __| __|  / __/ _ |   | __|  
 __  (_) | |_| |   / (__| _|  | (_| (_) | |) | _|   
 |___/___/____/|_|_\___|___|________/|___/|___|_ 
 | _  _  __/ __| __| _   / /__   _|_ _/ _ | | |
 |  _/   / _|__  _||   / V / _ | |  | | (_) | .` |
 |_| |_|____|___/___|_|_ _/_/ __| |______/|_|_|