Liren Large Software Subsidy 5/05.iso/a/a060/2.ddi/FOXDOC.HLP

Text File | 1988-06-14 | 27.8 KB | 605 lines

1.1    General Help
This is some general help.
!
2.1    System Name
Enter the name of the system you wish to document.  This name is used
in the program file heading and on the source code listings. If you do
not choose to write file headings or print source code, you may omit
this field.
!
2.2    Author
Enter the name of the system author.  This name is used in the program
file heading and on the source code listings.  If you do not choose
to write file headings or print source code, you may omit this field.
!
2.3    Copyright Holder
Enter the name of the copyright holder, or leave blank if the author
holds the copyright.  This name is used in the program file heading
and on the source code listings.  If you do not choose to write file
headings or print source code, you may omit this field.
!
2.4    Copyright Date
Enter the copyright date.  This date is used in the program file
heading and the source code listing.  If you choose not to write file
headings or print source code, you may omit this field.
!
2.5    Top File Name
Input the first filename you wish to document.  Do not enter a drive
designation or a path.  File extensions are optional (.PRG assumed if
no extension entered).  If you wish to document an entire FoxBASE+
system, this file should be the "top" file in the system.

If this field is blank or if the filename you enter does not exist, in
the source directory, FoxDoc will reposition the cursor on this field.
You cannot begin documentation until this file is found.
!
2.6   Path for Source Code Files
Enter the path for your system's source code files.   Your entry
should begin with a backslash ('\') but should not end with one.  For
example, if your programs are in a directory called FOX\SOURCE,
you would enter the following:
   Path to source code files: \FOX\SOURCE
FoxDoc will execute a CHDIR command to make this directory the default
directory.  All files except databases and indexes MUST be in this
subdirectory for FoxDoc to find them.
!
2.7   Path for Data Files
Enter the path for your system's database and index files.   Your
entry should begin with a backslash ('\') but should not end with one.
For example, if your data files are in a directory called
FOX\SOURCE, you would enter the following:
   Path to data files: \FOX\SOURCE
FoxDoc also searches the program directory for these files if they are
not in the data directory.
!
2.8   Path for Output Files
Enter the path for FoxDoc documentation.   Your entry should begin
with a backslash ('\') but should not end with one.  For example, if
you want output routed to a directory called C:\FOX\OUTPUT, you
would enter the following:

   Path for output files: C:\FOX\OUTPUT
!
2.9   Path for FoxDoc Files
Enter the path for FoxDoc help files and keywords.  If FoxDoc is in
the current directory, simply press the enter key.  Otherwise, enter
the path to the directory in which FoxDoc resides.  Your entry should
begin with a backslash ('\') but should not end with one.  For
example, if FoxDoc is in a directory called FOX\FOXDOC, you would
enter the following:

   Path to FoxDoc Files: \FOX\FOXDOC
!
3.1    Write Program Tree Structure?
Choose "Y" to display and echo to a file a diagram of the system tree
structure, showing which programs call which other programs, and
which programs use which databases.  The diagram also indicates which
"programs" are FoxBASE+ procedures.
!
3.2    Write List of Files Used in System
Choose "Y" to display and echo to a file a list of all files used in
the system.  This report shows programs, databases, index files,
report forms, format files, memory files, and procedures.  You might
use such a report to identify all the files in a subdirectory that
your application uses.
!
3.3    Write Index File Summary?
Choose "Y" to display and echo to a file a summary of index files
used in the system.  FoxDoc watches for references to indexes
within your programs and will prepare a report showing the index file
name, the fields on which it is indexed, and the program files that
use it.
!
3.4    Write Database Summary and Data Dictionary?
Choose "Y" to display and echo to a file a database summary and data
dictionary, showing each field in the system and the databases
containing it.  The data dictionary also highlights the links among
your databases.  In addition to the data dictionary, this option
displays a list of each database used in the system, the database
structure, and a list of program files which use the database.
!
3.5    Write Format File Summary?
Choose "Y" to display and echo to a file a summary of format files
used in the system.  FoxDoc watches for references to format files
within your programs and will prepare a report showing the format
file name and the program files that use it.
!
3.6    Write Report Form Summary?
Choose "Y" to display and echo to a file a summary of report forms
used in the system.  FoxDoc watches for references to report forms
within your programs and will prepare a report showing the report
form name and the program files that use it.
!
3.7   Write Procedure Summary?
Choose "Y" to display and echo to a file a summary of procedures used
in the system.  FoxDoc watches for references to procedures within
your programs and will prepare a report showing the procedure name,
the individual procedures it contains and the program files that use
it.
!
3.8   Write Label Summary?
Choose "Y" to display and echo to a file a summary of label forms
used in the system.  FoxDoc watches for references to label forms
within your programs and will prepare a report showing the label
form name and the program files that use it.
!
3.9    Write Variable Cross Reference?
Choose "Y" to display and echo to a file a cross reference of all
words in the system that are not key words, quoted strings or numeric
constants.  This report provides system-wide documentation of each
program and program line that references a memory variable, file name,
field, and so forth.  You can also 1) include selected key words in
this report by prefacing them with an at sign (@) in the key word
file, or 2) exclude memory variables by adding them temporarily to the
key word file.  FoxDoc is limited to 1000 individual variables.
!
3.10        Prepare batch files?
Choose "Y" to prepare three batch files for backing up programs,
databases and other files.  If you select this option, the following
files will be created in the output directory:
   UPDATE.BAT  -- Copies the new output files to the source directory
   BACKDBF.BAT -- Copies databases and index and memory files
   BACKPRG.BAT -- Copies programs, format files and report forms
If you choose "N" these files will not be created.  Note that UPDATE
will write over your original source code files.  Use it only after
you have backed them up and verified that the output files are good.
!
3.11    Tree Structure File Name
Input the filename for the tree diagram to be written to.  If you
choose not to display the tree, this field is ignored.
!
3.12    File List File Name
Input the filename for the file list to be written to.  If you
choose not to display the file list, this field is ignored.
!
3.13    Index Summary File Name
Input the filename for the index summary to be written to.  If you
choose not to display the index summary, this field is ignored.

Do not enter a path here.  The output path you entered on the previous
screen determines the subdirectory in which this file will be written.
!
3.14    Data Dictionary File Name
Input the filename for the data dictionary to be written to.  If you
choose not to display the data dictionary, this field is ignored.

Do not enter a path here.  The output path you entered on the previous
screen determines the subdirectory in which this file will be written.
!
3.15    Format Summary File Name
Input the filename for the format file summary to be written to.  If
you choose not to display the format file summary, this field is
ignored.

Do not enter a path here.  The output path you entered on the previous
screen determines the subdirectory in which this file will be written.
!
3.16    Report Form Summary File Name
Input the filename for the report form summary to be written to.  If
you choose not to display the report form summary, this field is
ignored.

Do not enter a path here.  The output path you entered on the previous
screen determines the subdirectory in which this file will be written.
!
3.17    Procedure Summary File Name
Input the filename for the procedure summary to be written to.  If
you choose not to display the procedure summary, this field is
ignored.

Do not enter a path here.  The output path you entered on the previous
screen determines the subdirectory in which this file will be written.
!
3.18    Label Summary File Name
Input the filename for the label summary to be written to.  If
you choose not to display the label summary, this field is
ignored.

Do not enter a path here.  The output path you entered on the previous
screen determines the subdirectory in which this file will be written.
!
3.19    Cross Reference File Name
Input the filename for the cross reference to be written to.  If you
choose not to display the cross reference, this field is ignored.

Do not enter a path here.  The output path you entered on the previous
screen determines the subdirectory in which this file will be written.
!
4.1    Create Formatted Source Code Files?
Answer "Y" if you would like FoxDoc to produce output formatted source
code files.  Since this is the main purpose of FoxDoc, you will
usually want to have this option in effect.  If you choose this
option, FoxDoc will output a copy of each of your source code files
formatted as you specify below.
!
4.2    Preserve Original Date and Time
When FoxDoc formats source code files and produces new output files,
the new files will have the same date and time as the original input
files if this option is 'Y'.  Otherwise, the new files will have the
current DOS date and time.  You might want to preserve the original
date for MAKE reasons or simply to have the file date represent the
last time you (as opposed to FoxDoc) changed the file.
!
4.3    Write Headings for Source Code Files?
Answer "Y" or "N" depending on whether you want to write file headings
on each program file and action file.  The file heading is a series of
comments documenting the filename, system name, and copyright notice,
in addition to a list of files that call the program, files the
program calls, and databases, index files, format files, report forms
and memory files used.  FoxDoc writes the file heading directly onto
your program file (but backs up your original file if your source and
output paths are the same).
!
4.4   Echo Headings to a File?
Enter 'Y' to echo headings to a separate file.  This file will just
contain copies of all of the headings written to source code files.
FoxDoc puts a formfeed character between each pair of headings.
!
4.5   Heading File Name
Enter the filename to contain a copy of the headings that are written
to each source code file.  If you do not choose to echo headings to a
file, this field is ignored.
!
4.6   Capitalize Tokens (Upper/Lower/First/None)?
Choose "U" to capitalize all occurrences of tokens--words not found in
the FXPWORDS.FXD or FX2WORDS.FXD file, the original version of which
contains all FoxBASE key words.  Choose "L" to convert all of them to
lower case (default).  Choose "F" to capitalize only the first letter
of the token.  Also, FoxDoc will recognize valid 4-character
abbreviations of key words (e.g., PICT will be recognized as an
abbreviation of PICTURE and treated as a key word).   Choose "N" to
leave the case unchanged.
!
4.7   Capitalize FoxBASE+ Key Words (Upper/Lower/First/None)?
Choose "U" to capitalize all occurrences of key words found in the
FXPWORDS.FXD or FX2WORDS.FXD file, the original version of which
contains all FoxBASE key words.  Choose "L" to convert all keywords to
lower case.  Choose "F" to capitalize only the first letter of the
token.  You may add extra words to be capitalized to this file, or
temporarily "comment out" key words from the file by prefacing them
with an asterisk.  Also, FoxDoc will recognize valid 4-character
abbreviations of key words (e.g., PICT will be recognized as an
abbreviation of PICTURE).  Choose "N" to leave the case unchanged.
!
4.8   Key Word File Name
Input the filename containing a list of keywords to be capitalized
(and not included in the cross-reference listing).  This file should
contain one keyword per line.  This file allows you to customize the
words that will be capitalized, cross-referenced, expanded, etc.
There are many options--see the manual for details.
!
4.9   Tabs, spaces or no indenting?
Choose "T" (for tabs) or "S" (for spaces) to indent code underneath
control structures (DO WHILE, IF, CASE, FOR etc.). If you choose to
indent your code, one tab character (or the number of spaces you
specify) will be inserted for each control statement nesting level.
Choose "N" for no indentation.

This option also scans your source code for unmatched control
structures (e.g., IFs not matched with ENDIFs) and reports any
discrepancies.
!
4.10   No. of Spaces
Enter the number of spaces to be used for each level of indentation.
This field is ignored if you choose tabs or no indenting.
!
4.11   Eliminate blank lines?
Choose 'Y' to eliminate blank lines in the input file from the output
file.  Please only use this option if you have a backup of your source
code.  It's also a good idea to send output to a directory other
than the input directory if you choose this option.

This is a one-way street--you can't put the blank lines back in again.
!
4.12    Eliminate comments?
Choose 'Y' to eliminate comments in the input file from the output
file.  Please only choose this option if you have a backup of your
source code.  It's also a good idea to send output to a directory
other than the input directory if you choose this option.

This is a one-way street--you can't put the comments back in again.
!
4.13    Keyword Conversion?
Use with caution!  See the manual for some examples of how this option
can screw up your code.  Choose "E" to expand keywords to their full
length.  FoxBASE+ allows four character abbreviations, which makes the
code faster to type in, but harder to read.  This option expands them
back. Choose "C" to compress them to four characters.  Choose "N" to do
nothing. Note that a "keyword" is anything in the keyword file.  If
you put variables, etc. there,  FoxDoc will not be able to tell the
difference. Also, if you use key words as variable names, they will be
changed along with all other key words.
!
4.14    Create Action Diagrams?
Choose "Y" to prepare action diagram files.  Action diagrams are just
like program files, except that they use the IBM extended ASCII
characters to diagram the structure of a program like this:
                   ┌─IF foo
                   │    DO bar
                   └─ENDIF
These files are useful for documentation purposes but are not
directly executable or compilable. If you choose to generate action
diagrams, they will be written to the output directory.
!
4.15    File Extension for Action Diagrams
Input the extension for the files containing the action diagrams. If
the output directory and the input directory are the same, these files
will be written to the input directory and will overwrite any existing
files with the same name.  The extension may contain the ? character
as a wildcard meaning, "the character in the same position in the
original program file extension."  Thus, if you specify "??T" as the
action file extension and one of your input files is named "FOO.BAR",
the final action file will be named "FOO.BAT".  The default extension
is "ACT".  Extensions of 'PRG' and '???' are invalid.
!
4.16  Add Line Numbers to Action Diagrams?
Respond "Y" to put line numbers at the beginning of each line in the
action diagrams.  If you answer "N", no line numbers will be
inserted.
!
4.17   Graphics, ASCII, or Other Characters?
Respond "G" to use the IBM line-drawing characters in the action
diagrams.  These resulting diagrams are visually appealing but may
not print well on some printers.  Choose "A" to use only standard
ASCII characters.  Alternatively, you can define your own set of
action diagram characters by replying "O" here.  The field below
(User-defined Characters) is where you specify which characters to
use.
!
4.18   User-defined Characters
If you are happy with the predefined graphics or ASCII characters for
action diagrams, you can ignore this field.  It is only used if you
answer "O" to the question immediately above this one.

Enter the characters to use for the action diagram.  Read the manual
or you will spoil the whole wretched mess.  Note:  I said it was
possible--I didn't say it was easy.  If you think it is hard to ENTER
user-defined characters, you should see what it was like to PROGRAM
them.
!
5.1   Cross-reference Public Variables
Your response here determines whether FoxBASE+ public variables
will be included in the cross-reference report.  If you answer this
question 'Y' and the other questions 'N', then only public variables
will appear on the cross-reference report.
!
5.2   Cross-reference Other Variables and Tokens
The cross-reference report normally includes all "things" in your
source code that are not either:
   Comments                     Numeric constants
   Key words                    Punctuation
   Quoted strings
Accordingly, file names, field names, and so on will appear in the
cross-reference listing.  If you wish to restrict the report to
public variables only, you can respond 'N' to this and subsequent
questions.
!
5.3   Cross-reference Key Words
Your response determines whether key words will be included in the
cross-reference report.  If you respond 'Y' then all words in the key
words file will be referenced on the report.  For example, you might
select this option to see where you used the REPLACE verb. For large
FoxBASE+ systems, you will probably exceed the number of allowable
references to such commonly-used key words as SAY, STORE, TO, and
perhaps others. If so, FoxDoc will display a warning message ("Too
many references to SAY") and continue processing your files.  Any
excess references are discarded and do not appear on the report.
!
5.4   Cross-reference Numeric Constants
Your response determines whether numbers used in your system will
appear on the cross-reference report.  Under normal circumstances,
they will probably only get in the way, but you may occasionally want
to see where you used a particular constant, especially if you later
need to change it.
!
6.1    Write Program Tree Structure?
Choose "Y" to display and echo to a file a diagram of the system tree
structure, showing which programs call which other programs, and
which programs use which databases.  The diagram also indicates which
"programs" are FoxBASE+ procedures.
!
6.2    Tree Structure File Name
Input the filename for the tree diagram to be written to.  If you
choose not to display the tree, this field is ignored.
!
6.3    Include Procedures in the Tree Diagram?
Type 'N' to exclude procedure files from the tree diagram.  While you
would ordinarily not want to do this, you might want to exclude
procedure files if you had a lot of procedures that just cluttered up
the diagram.  If you exclude procedures, you cannot use graphics or
ASCII characters to depict the tree hierarchy (I couldn't figure out
how to make it all work).
!
6.4    Include Functions in the Tree Diagram?
Type 'N' to exclude functions from the tree diagram.  While you would
ordinarily not want to do this, you might want to exclude functions if
you had a lot of functions that just cluttered up the diagram.  If you
exclude functions, you cannot use graphics or ASCII characters to
depict the tree hierarchy (I couldn't figure out how to make it all
work).
!
6.5    Include Format Files in the Tree Diagram?
Type 'N' to exclude format files from the tree diagram.  While you
would ordinarily not want to do this, you might want to exclude format
files if you had a lot of format files that just cluttered up the
diagram.  If you exclude format files, you cannot use graphics or
ASCII characters to depict the tree hierarchy (I couldn't figure out
how to make it all work).
!
6.6    Include Databases in the Tree Diagram?
Type 'Y' to include databases in the tree diagram underneath the
program that USEs them.  Alias names are also shown.
!
6.7    Include Index Files in the Tree Diagram?
Type 'Y' to include indexes in the tree diagram underneath the program
that references them.
!
6.8    Include Report Forms in the Tree Diagram?
Type 'Y' to include report forms in the tree diagram underneath the
program that references them.
!
6.9    Include Label Forms in the Tree Diagram?
Type 'Y' to include label forms in the tree diagram underneath the
program that references them.
!
6.10   Include Memory Files in the Tree Diagram?
Type 'Y' to include memory files in the tree diagram underneath the
program that references them.
!
6.11   Characters for Tree Diagram
Enter 'G' for IBM box-graphics characters, such as the following:
            TopFile
            ├────OneFile
            │    └────YetAnotherFile
            └────AnotherFile
Enter 'A' for ASCII characters only--no graphics characters used. The
plus character is used for joining lines, while hyphens and pipe
symbols are used for horizontal and vertical lines. Some printers
cannot print the graphics characters.  Select 'N' to omit the
characters entirely.
!
7.1    Print Source Code Files?
Answer 'Y' to print the new source code files you just created.
FoxDoc expects to see these files in the output directory you
specified before you began documentation.  This program can only
print source code files produced during the current documentation
session.
!
7.2    Print Action Diagrams?
Answer 'Y' to print the new action diagrams you just created.
FoxDoc expects to see these files in the output directory you
specified before you began documentation.  FoxDoc can only print
action diagrams created during the current documentation session.
!
7.3   Line Width
Input a line width between 40 and 255.  The standard line width of
most printers using 8.5 x 11 inch paper is 80, but you can change it
by using wide paper and entering the appropriate setup codes for your
printer.  The line width you enter should be the total number of
characters your printer can print across a line.  The actual length
of printed source code lines will be reduced by the left and right
margins you set below.  Source code lines longer than the line width
you specify will be wrapped to the next line.
!
7.4   Page Length
Input a page length greater than or equal to 0.  If you enter 0, the
program assumes continuous form paper and will not write page
headings except on the first page.  Page length must also be larger
than your top and bottom margins.
!
7.5   Top Margin
Enter a number greater than 3 and smaller than your page length.
The first three lines are used to print a heading on each page.
!
7.6   Bottom Margin
Enter a number greater than or equal to 0.  This many lines will be
left blank at the bottom of each page.
!
7.7   Left Margin
Enter a number greater than 0 and less than your line width.  Line
numbers (or source code if you elect not to print line numbers) will
begin this many spaces from the left edge of the paper.  A left
margin of 12 usually leaves room for 3-hole binder punches.
!
7.8   Right Margin
Enter a number greater than 0 and less than your line width.  This
many spaces will remain between your source code and the right
edge of the paper.
!
7.9   Spaces per Tab
Enter a number between 1 and 12.  Each tab character in your source
code will be converted to this many spaces as the source code is
printed.  The source code file will be unaffected--the expansion is
done for printing purposes only.  Tab expansions of 3 or 4 make the
code easy to follow without causing it to march off the right side of
the page.
!
7.10   Print Line Numbers?
Choose "Y" to print line numbers next to each line of source code or
"N" to suppress them.  Line numbers are useful references for
following up on error messages or for using the variable
cross-reference report.

Line numbers are not added to action diagrams.  If you want action
diagrams with line numbers on them, you must put them there when the
diagrams are created.
!
7.11   Form Feed Before Printing
Enter a 'Y' to send a form feed before printing the first source code
file.
!
7.12   Form Feed After Printing
Enter a 'Y' to send a form feed after printing the last source code
file.
!
7.13   Printer Setup Codes
Enter setup codes for your printer.  The default codes shift an Epson
(and many other printers) into compressed print.  The format for setup
codes is three-digit decimal numbers separated by backslashes (\),
along with other characters.  For example, the code to put an
Epson-compatible printer into compressed print is \015.  This string
works well on an HP LaserJet II:
   \027E\027&l0o8D\027(10U\027(s16.6H
This field is always optional.
!
7.14   Printer Reset Codes
Enter reset codes for your printer.  These are sent to yor printer
after FoxDoc finishes printing. The default codes shift an Epson (and
many other printers) into regular print.  The format for reset codes
is three-digit decimal numbers separated by backslashes (\).  For
example, the code to put an Epson-compatible printer into regular
print is:
   \018
This field is always optional.
!
8.1   Ignore Drive Designations?
Choose "Y" to ignore drive designations when looking for program
files. This option is useful if your program tests for the existence
of files on various drives and makes a decision based on the results.
If you choose not to ignore drive designations, FoxDoc will attempt
to find the program files on the specified drive.  Depending on the
equipment you have installed, DOS may prompt you to insert a disk in
drive B.  This DOS message usually messes up the FoxDoc screen.
!
8.2    Search Tree?
Enter a "Y" here to search all programs in the tree below the
top filename.  If you enter a "N", FoxDoc will only document the
specific file you enter.
!
8.3   FoxBASE+ Format?
Enter a "Y" if your system is written in FoxBASE+, or another
FoxBASE+-compatible system.  Otherwise, enter a "N".  FoxBASE and
FoxBASE+ use different syntax and different formats for database
and index files.
!
8.4  Associate Databases and Other Files?
Enter 'Y' here if you would like FoxDoc to try to figure out how your
databases, indexes, report forms, etc. are related.  FoxDoc cannot
always tell, but it takes its best shot.
!
9.1   Configuration File Name
Enter the complete file name for the configuration.  You may include a
drive and path designation if you wish.  If you do not specify the
path, the file will be read from or written to the current directory
when you invoked FoxDoc
!
10.1   File Containing List of Filenames
Enter the name of the file that contains the filenames to print.
FoxDoc will print each of the files listed in this file, except for
files with the following extensions: DBF, IDX, NDX, NTX, MDX, MEM,
FRM, LBL and VUE.  FoxDoc will recognize a FILELIST.DOC file and
appropriately eliminate blank lines and other extraneous information
before printing the files.
!
10.2  Path for Files to be Printed
Enter the path where the files to be printed are located.  Your entry
should begin with a backslash ('\') but should not end with one.  For
example, if your data files are in a directory called FOX\SOURCE,
you would enter the following:

   Path for filenames: C:\FOX\SOURCE

If this path is not blank, FoxDoc removes any paths from the filenames
in the file list and adds this path instead.
!