
writer(1)                    Khoros                     writer(1)

PROGRAM
     writer - The purpose of Ghostwriter is to create C source
     code and man pages for the application program.  The SOURCE
     of information for ghostwriter are the *.pane file (User
     Interface Specification File), and the *.prog file (Program
     Specification file).  The DESTINATION of extracted informa-
     tion is one or more of five files:  a *.c file, a *.h file,
     an l*.c file, a *.1 file, and a *.3 file, where '*' is the
     name of the program being generated.

SYNTAX
     writer

     -name          name of program to be generated

     [-config]      use configuration file?

     [-lib]         generate lib file?

     [-man3]        generate man3 file?

     [-install]     install output?

     [-format]      formatting (0 = none, 1 = nroff)

     [-debug]       generate debug statements in main?

     [-tag]         append tags on variable names?

     [-force]       force output?

     [-cp]          alternate copyright file (*.prog style)

     [-tb]          toolbox name

     [-type]        type of program:
                     'prog' (vroutine),
                     'xprog' (xvroutine),
                     'fprog' (vroutine w/ calls to FORTRAN),
                      or 'fxprog' (xvroutine w/ calls to FORTRAN)
                       [default = prog]

     [-V]           Gives the version for writer

     [-U]           Gives the usage for writer

     [-P]           Prompts for command line options

     [-A [file1]]   Creates the answer file called writer.ans or
                    file1

     [-a [file1]]   Uses writer.ans or file1 as the answer file

DESCRIPTION
     Ghostwriter is explained in detail in Chapter 5 of the
     Khoros Programmer's Manual; the information given there will
     not be repeated here, so you are referred to that document.
     For reference purposes, a detailed explanation of each argu-
     ment to ghostwriter is as follows:

     name:     The name of the program to be generated, as well
               as the base name "*" in all files used by ghos-
               treader and ghostwriter: *.c, *.h, l*.c, *.1, *.3,
               *.pane, *.prog, and *.conf.  This name may be a
               maximum of 9 characters long, so that the length
               of generated files with postfixes will meet the 14
               character limit of filenames on System V machines.
               This is the one argument required by both ghos-
               treader and ghostwriter.

     config:   Provide a value of True (1) if a configuration
               file, *.conf, is to be used with ghostwriter.
               Configuration files will be explained in detail in
               a later section.  Note that if a configuration
               file is to be used, it MUST exist in the local "."
               directory where ghostwriter is executed.

     lib:      Provide a value of False (0) if no library file is
               to be generated.  Note that not all programs need
               a library file.

     man3:     Provide a value of False (0) if [-lib] is also
               specified as False (0).  Any program that does not
               have a library file has no need for a man3 file.

     install:  Provide a value of True (1) if output files of
               ghostwriter are to be installed at the locations
               specified by the configuration file.  The install
               flag will be discussed further in a later section,
               along with configuration files.  Note that a value
               of True (1) should ONLY be provided for [-install]
               when a value of True (1) is also provided for [-
               config].

     format:   Provide a value of 0 ONLY if nroff is not avail-
               able on your system. The default value of 1 (indi-
               cating use of nroff) should otherwise be used.  No
               other values for [-format] are available at this
               time.

     debug:    Generally used only by members of the Khoros pro-
               gramming staff, providing a value of True (1) for
               [-debug] will cause ghostwriter to put fprintf()
               statements in the main() of the generated program,
               so that values returned from the gw_get_args()
               routine are printed out.

     tag:      If [-tag] is specified as False (0), the variable
               tags (_int, _float, _string, etc) are NOT tacked
               onto the end of the command line argument struc-
               ture that is generated in the *.h  file.  This is
               a question of programming style.  In general, only
               Khoros xvroutines use [-tag 0].

     force:    If [-force] is specified as True (1), output from
               ghostwriter will automatically over-write any
               existing files by the same name;  the user will
               not be prompted before files are clobbered.

     cp:       You may provide an alternative copyright file
               using the [-cp] option.  This will allow you to
               specify your own short copyright to appear in man
               pages that are automatically generated by ghost-
               writer, and your own long copyright to appear in
               automatically generated code.  This file may also
               be used if you want no copyright to appear in your
               man pages or code.  This copyright file must be in
               the same format as the *.prog file.  That is, the
               short copyright must have the begin key "-
               copyright_short" on a line by itself above it, and
               the end key "-copyright_short_end" on a line by
               itself following it.  The long copyright must have
               the begin key "-copyright_long" on a line by
               itself above it, and the end key "-
               copyright_short_end" on a line by itself following
               it.  We recommend that users copy
               $KHOROS_HOME/repos/utils/cpright.ghost, and modify
               it as desired.  If you don't want any copyrights
               in your program, you may copy this file and delete
               both copyrights from within the begin and end
               keys.  When ghostwriter sees a pair of keys with
               no text between them, it will leave the text block
               in question out completely.

     tb:       The [-tb] flag is for use exclusively with
               "imkmf", which is called automatically by ghost-
               writer when the current directory does not have an
               Imakefile.  It specifies the name of the toolbox
               in which the program is to be installed.  If you
               forget the [-type tb] argument when you do not
               have an Imakefile in your current directory,
               remove the Imakefile and Makefile created by
               ghostwriter in this situation. Create the correct
               Imakefile & Makefile by executing:

               % imkmf -name xvroutine -type xprog -toolbox
               {toolbox name}

               % makemake

     type:     The [-type] flag is optional, and defaults to
               'prog', implying that the program being written is
               a vroutine.  If you are writing an xvroutine, it
               is very important that you remember to provide the
               [-type xprog] argument to ghostwriter.  The dis-
               tinction between Khoros vroutines and Khoros
               xvroutines is made clearly in Chapter 1 of the
               Khoros Programmer's Manual.  If you do not under-
               stand the difference, you should review the first
               section of that chapter now.  If you are writing
               an xvroutine and you forget to provide the [-type
               xprog] flag to ghostwriter, the *.c file and l*.c
               file will incorrectly include "vinclude.h", when
               they should in fact be including "xvinclude.h".
               In addition, the Imakefile that is generated (when
               there is no existing Imakefile in your current
               directory) will not include links to the XLib, Xt,
               and Xaw libraries, and your code will not compile.
               If you forget the [-type xprog] argument when
               writing an xvroutine, simply remember to change
               references to "vinclude.h" to "xvinclude.h".
               Then, remove the Imakefile and Makefile created by
               ghostwriter.  Create the correct Imakefile &
               Makefile by executing:

               % imkmf -name xvroutine -type xprog -toolbox
               {toolbox name}

               % makemake

REQUIRED ARGUMENTS
     -name  type: string
            desc: name of program to be generated

OPTIONAL ARGUMENTS
     -config
            type: boolean
            desc: use configuration file?
            default: false

     -lib   type: boolean
            desc: generate lib file?
            default: true

     -man3  type: boolean
            desc: generate man3 file?
            default: true

     -install
            type: boolean
            desc: install output?
            default: false

     -format
            type: integer
            desc: formatting (0 = none, 1 = nroff)
            default: 1
            bounds: 0 < [-format] < 1

     -debug type: boolean
            desc: generate debug statements in main?
            default: false

     -tag   type: boolean
            desc: append tags on variable names?
            default: true

     -force type: boolean
            desc: force output?
            default: false

     -cp    type: string
            desc: alternate copyright file (*.prog style)
            default: null

     -tb    type: string
            desc: toolbox name
            default: null

     -type  type: string
            desc: type of program
            allowed values:
             'prog' (vroutine),
             'xprog' (xvroutine),
             'fprog' (vroutine w/ calls to FORTRAN),
              or 'fxprog' (xvroutine w/ calls to FORTRAN)

EXAMPLES
     % ghostwriter -name vadd -config 1 -lib 1 -man3 1 -install 1

SEE ALSO
     intro(1), verror(3), vgparms(3), vutils(3)
     ghostreader(1) and Chapter 5 of the Khoros User's Manual

RESTRICTIONS
COPYRIGHT
     Copyright 1991, University of New Mexico.  All rights
     reserved.

Khoros                    Release: 1.0                          1

