527 lines
19 KiB
Groff
527 lines
19 KiB
Groff
.\" $XConsortium: dtbuilder.1 /main/2 1995/07/17 14:26:53 drk $
|
|
.de LI
|
|
.\" simulate -mm .LIs by turning them into .TPs
|
|
.TP \\n()Jn
|
|
\\$1
|
|
..
|
|
.\" *************************************************************************
|
|
.\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company
|
|
.\" ** (c) Copyright 1993, 1994 International Business Machines Corp.
|
|
.\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc.
|
|
.\" ** (c) Copyright 1993, 1994 Novell, Inc.
|
|
.\" *************************************************************************
|
|
.\"--- The above copyrights must appear at the top of each man page.
|
|
.\"---
|
|
.\"--- @(#)dtbuilder.1 1.1 14 Sep 1994
|
|
.\"---
|
|
.\"--- -------------------------------------------------------------------------
|
|
.\"--- .TH Macro
|
|
.\"--- The .TH macro specifies information that applies to the man page as
|
|
.\"--- a whole.
|
|
.\"--- _title_ is the name of the man page. This should correspond to the
|
|
.\"--- first word under the NAME heading. _#_ specifies the manual section in
|
|
.\"--- which the page appears, where # is the number of the section.
|
|
.\"---
|
|
.\"--- .TH _title _#_
|
|
.TH dtbuilder 1
|
|
.TH dtbuilder 1
|
|
.\"---
|
|
.\"----------------------------------------------------------------------------
|
|
.\"--- NAME
|
|
.\"--- Give the name of the entry and briefly state its purpose.
|
|
.\"--- This section is used by cross-referencing programs. Hence, do not
|
|
.\"--- use any font changes or troff escape sequences in this section.
|
|
.\"--- After the name, use one space, a backslash minus \(mi, and then another space
|
|
.\"-- before the summary.
|
|
.\"--- Do not start the summary sentence with a capital letter or use
|
|
.\"--- any punctuation at the end.
|
|
.\"--- The summary line must be on one line (it can wrap). The reason for this
|
|
.\"--- is that some man page implementations build an index of man page values
|
|
.\"--- by reading through and getting the single line that follows the .SH NAME
|
|
.\"--- line. The line doesn't have to fit on a terminal screen, but there
|
|
.\"--- can be only one physical new line on the line.
|
|
.\"--- Make the summary a simple declarative sentence.
|
|
.\"---
|
|
.\"--- NAME example:
|
|
.\"---
|
|
.\"--- ttsession \(mi the ToolTalk message server
|
|
.\"--- or:
|
|
.\"--- dtgather \(mi gather application files for presentation by the Application Manager
|
|
.\"---
|
|
.SH Name
|
|
dtbuilder \(mi the \s-1CDE\s+1 Application Builder
|
|
.\"---
|
|
.\"----------------------------------------------------------------------------
|
|
.\"--- SYNOPSIS
|
|
.\"--- This section summarizes the syntax of the calling sequence for the
|
|
.\"--- utility, including options, option-arguments and operands.
|
|
.\"---
|
|
.\"--- Begin the synopsis with the .yS macro and end the synopsis with the
|
|
.\"--- .yE macro.
|
|
.\"---
|
|
.\"--- Use backslash minus \(mi for minus.
|
|
.\"---
|
|
.\"--- List single letters first in a group.
|
|
.\"---
|
|
.\"--- Code as in the following example; the conversion scripts do the rest.
|
|
.\"---
|
|
.\"--- Utility options in SYNOPSIS example:
|
|
.\"---
|
|
.\"--- .SH SYNOPSIS
|
|
.\"--- .yS
|
|
.\"--- ttsession
|
|
.\"--- [\(mihNpsStv]
|
|
.\"--- [\(miE|\(miX]
|
|
.\"--- [\(mia\ \f2level\fP]
|
|
.\"--- [\(mid\ \f2display\fP]
|
|
.\"--- [\(mic\ [\f2command\fP]]
|
|
.\"--- .yE
|
|
.\"---
|
|
.\"--- Utility options in TEXT example (bold for X/Open; use \(mi for minus):
|
|
.\"--- .B \(mix
|
|
.\"--- .BR \(miy ;
|
|
.\"--- .BI \(mif " makefile" [note space]
|
|
.\"--- \f3\(mif\ \fPmakefile\fP [version of previous if you're breaking
|
|
.\"--- across two lines]
|
|
.\"--- .LI \f3\(mia\0\f2level\f1 [.VL version; note usage of \0 as an internal
|
|
.\"--- space and the return to font 1]
|
|
.\"---
|
|
.SH SYNOPSIS
|
|
.ft 3
|
|
.fi
|
|
.na
|
|
dtbuilder
|
|
[projectfile]
|
|
.PP
|
|
.fi
|
|
.\"---
|
|
.\"----------------------------------------------------------------------------
|
|
.\"--- DESCRIPTION
|
|
.\"--- This section describes the actions of the utility. If the utility
|
|
.\"--- has a very complex set of subcommands or its own procedural language,
|
|
.\"--- an EXTENDED DESCRIPTION heading is provided. Most explanations of
|
|
.\"--- optional functionality are omitted here, as they are usually explained
|
|
.\"--- under the OPTIONS heading.
|
|
.\"--- When specific functions are cited, the underlying operating system
|
|
.\"--- provides equivalent functionality and all side effects associated
|
|
.\"--- with successful execution of the function. The treatment of erors and
|
|
.\"--- intermediate results from the individual functions cited are generally
|
|
.\"--- not specified by this document. See the utility's EXIT STATUS and
|
|
.\"--- CONSEQUENCES OF ERRORS section for all actions associated with errors
|
|
.\"--- encountered with by the utility.
|
|
.\"---
|
|
.\"--- When writing, use active voice, never use 2nd person, and make it
|
|
.\"--- clear who or what the requirements are placed on.
|
|
.\"---
|
|
.\"--- DESCRIPTION example:
|
|
.\"---
|
|
.\"--- Do not say: When you are done with this
|
|
.\"--- implementation object, it should be freed. (Who frees
|
|
.\"--- it, the programmer or the implementation?)
|
|
.\"--- Do use active voice and say: When you are done with this implementation
|
|
.\"--- object, you must free it. Or: When you are done with this
|
|
.\"--- implementation object, the implementation will free it.
|
|
.\"---
|
|
.\"--- Make the utility the grammatical subject
|
|
.\"--- of the first sentence; use a present tense verb to describe the utility;
|
|
.\"--- note that whenever you use the utility name, use the
|
|
.\"--- .Fn request and put it on a single line.
|
|
.\"--- .Fn gets the correct font and puts in the trailing
|
|
.\"--- "( )" with the correct spacing.
|
|
.\"---
|
|
.\"--- DESCRIPTION example:
|
|
.\"---
|
|
.\"--- The
|
|
.\"--- .Fn tt_session
|
|
.\"--- utility is the ToolTalk message server.
|
|
.\"---
|
|
.SH DESCRIPTION
|
|
The
|
|
.BR dtbuilder
|
|
utility is an interactive application development tool and user
|
|
interface management system for \s-1CDE\s+1.
|
|
Known more fully as the \s-1CDE\s+1 Application Builder,
|
|
.BR dtbuilder
|
|
is designed to make it easier for developers to construct applications that
|
|
integrate well into the Common Desktop Environment.
|
|
It provides two basic services - aid in assembling Motif objects into the
|
|
desired application user interface and generation of appropriate calls
|
|
to the routines that support \s-1CDE\s+1 desktop services (e.g. ToolTalk, sessioning,
|
|
Help).
|
|
.\"---
|
|
.\"----------------------------------------------------------------------------
|
|
.\"--- OPTIONS
|
|
.\"--- This section describes the utility options and option-arguments, and how
|
|
.\"--- they modify the actions of the utility.
|
|
.\"--- Default behavior: When this section is listed as "None", it means that
|
|
.\"--- the implementation need not support any options.
|
|
.\"---
|
|
.\"--- OPTIONS example:
|
|
.\"---
|
|
.\"--- .SH OPTIONS
|
|
.\"--- need something here as an example
|
|
.\"---
|
|
.SH OPTIONS
|
|
None.
|
|
.\"---
|
|
.\"----------------------------------------------------------------------------
|
|
.\"--- OPERANDS
|
|
.\"--- This section describes the utility operands, and how they affect the
|
|
.\"--- actions of the utility.
|
|
.\"--- Default behavior: When this section is listed as "None", it means that
|
|
.\"--- the implementation need not support any operands.
|
|
.\"---
|
|
.\"--- OPERANDS example:
|
|
.\"---
|
|
.\"--- .SH OPERANDS
|
|
.\"--- need some sort of example here
|
|
.\"---
|
|
.SH OPERANDS
|
|
The
|
|
.BR dtbuilder
|
|
utility accepts an optional filename operand
|
|
that is interpreted as the name of an application project file
|
|
that should be loaded for editing.
|
|
This file should be in the BIL format defined for use by the
|
|
Application Builder.
|
|
.PP
|
|
If no project file is specified, then
|
|
.BR dtbuilder
|
|
comes up "empty", ready for a new
|
|
application to be developed interactively by the user.
|
|
.\"---
|
|
.\"----------------------------------------------------------------------------
|
|
.\"--- RESOURCES
|
|
.\"--- This section, which has no corresponding section in the X/Open CAE
|
|
.\"--- Specification, Commands and Utilities, Issue 4, lists the X Window
|
|
.\"--- System resources that affect the utility operation.
|
|
.\"---
|
|
.\"--- RESOURCES example:
|
|
.\"---
|
|
.\"--- .SH RESOURCES
|
|
.\"--- need some sort of example here.
|
|
.\"---
|
|
.SH RESOURCES
|
|
None.
|
|
.\"----------------------------------------------------------------------------
|
|
.\"--- CAPABILITIES
|
|
.\"--- TBD
|
|
.\"---
|
|
.\"---
|
|
.\"----------------------------------------------------------------------------
|
|
.\"--- STDIN
|
|
.\"--- This section describes the standard input of the utility. This section
|
|
.\"--- is frequently a reference to the following section, as many utilties
|
|
.\"--- treat standard input and input files in the same manner. Unless
|
|
.\"--- otherwise stated, all restrictions described under the INPUT FILES
|
|
.\"--- heading apply to this section as well.
|
|
.\"--- Default behavior: When this section is listed as "Not used", it means
|
|
.\"--- that the standard input will not be read when the utility is used as
|
|
.\"--- described by this document.
|
|
.\"---
|
|
.\"---STDIN example:
|
|
.\"---
|
|
.\"--- .SH STDIN
|
|
.\"--- need some example here
|
|
.\"---
|
|
.SH STDIN
|
|
Not used.
|
|
.\"---
|
|
.\"----------------------------------------------------------------------------
|
|
.\"--- "INPUT FILES"
|
|
.\"--- This section describes the files, other than the standard input, used
|
|
.\"--- as input by the utility. It includes files named as operands
|
|
.\"--- and option-arguments as well as other files that are referred to, such
|
|
.\"--- as startup and initialization files, databases, etc. Commonly-used
|
|
.\"--- files are generally described in one place and cross-referenced by other
|
|
.\"--- utilities.
|
|
.\"--- Default Behavior: When this section is listed as "None", it means that
|
|
.\"--- no input files are required to be supplied when the utility is used as d
|
|
.\"--- described om this document.
|
|
.\"---
|
|
.\"--- INPUT FILES example:
|
|
.\"---
|
|
.\"--- "INPUT FILES"
|
|
.\"--- need an example here
|
|
.\"---
|
|
.SH "INPUT FILES"
|
|
A project file to be processed by the
|
|
.BR dtbuilder
|
|
utility must to be in the BIL format defined for the \s-1CDE\s+1 Application
|
|
Builder.
|
|
.PP
|
|
Interactively, the Application Builder provides facilities for loading
|
|
additional project files, as well as application module files
|
|
(which also must be in the BIL format) and interface files that use
|
|
Motif's UIL format.
|
|
.\"----------------------------------------------------------------------------
|
|
.\"--- "ENVIRONMENT VARIABLES"
|
|
.\"--- This section lists what variables affect the utility's execution.
|
|
.\"--- Default Behavior: When this section is listed as "None", it means that the
|
|
.\"--- behavior of the utility is not directly affected by environment variables
|
|
.\"--- described by this document when the utility is used as described in this
|
|
.\"--- document.
|
|
.\"---
|
|
.\"--- ENVIRONMENT VARIABLES example:
|
|
.\"---
|
|
.\"--- .SH "ENVIRONMENT VARIABLES"
|
|
.\"--- need example here
|
|
.\"---
|
|
.SH "ENVIRONMENT VARIABLES"
|
|
None.
|
|
.\"---
|
|
.\"----------------------------------------------------------------------------
|
|
.\"--- "ASYNCHRONOUS EVENTS"
|
|
.\"--- This section lists how the utility reacts to such events as signals
|
|
.\"--- and what signals are caught.
|
|
.\"---
|
|
.\"--- ASYNCHRONOUS EVENTS example:
|
|
.\"---
|
|
.\"--- .SH "ASYCHRONOUS EVENTS"
|
|
.\"--- The
|
|
.\"--- .Cm ttsession
|
|
.\"--- utility reacts to two signals.
|
|
.\"--- If it receives the
|
|
.\"--- .Cn SIGUSR1
|
|
.\"--- signal, it toggles trace mode on or off (see the
|
|
.\"--- .B \(mit
|
|
.\"--- option).
|
|
.\"--- If it receives the
|
|
.\"--- .Cn SIGUSR2
|
|
.\"--- signal, it rereads the types file.
|
|
.\"--- The
|
|
.\"---.Cm ttsession
|
|
.\"--- utility takes the standard action for all other signals.
|
|
.\"---
|
|
.SH "ASYNCHRONOUS EVENTS"
|
|
The
|
|
.BR dtbuilder
|
|
utility takes the standard action for all signals.
|
|
.\"---
|
|
.\"----------------------------------------------------------------------------
|
|
.\"--- "STDOUT"
|
|
.\"--- This section describes the standard output of the utility.
|
|
.\"--- Default Behavior: When this section is listed as "Not Used", it means
|
|
.\"--- that the standard output will not be written when the utility is used as
|
|
.\"--- described in this document.
|
|
.\"---
|
|
.\"--- STDOUT example:
|
|
.\"---
|
|
.\"--- .SH STDOUT
|
|
.\"--- When the
|
|
.\"--- .B \(miv
|
|
.\"--- option is used,
|
|
.\"--- .Cm ttsession
|
|
.\"--- writes the version number in an unspecified format.
|
|
.\"--- When
|
|
.\"--- .B \(mip
|
|
.\"--- is used,
|
|
.\"--- .Cm ttsession
|
|
.\"--- writes the name of a new process tree session.
|
|
.\"---
|
|
.SH STDOUT
|
|
Not used.
|
|
.\"---
|
|
.\"----------------------------------------------------------------------------
|
|
.\"--- STDERR
|
|
.\"--- This section describes the standard error output of the utility.
|
|
.\"--- Only those messages that are purposely sent by the utility are
|
|
.\"--- described.
|
|
.\"--- Default Behavior: When this section is listed as "Used only for dagnostic
|
|
.\"--- messages", it means that, unless otherwise stated, the diagnostic messages
|
|
.\"--- are sent to the standard error only when the exit status is non-zero
|
|
.\"--- and the utility is used as described by this document.
|
|
.\"--- When this section is listed as "Not used", it means that the standard
|
|
.\"--- output will not be written when the utility is used as
|
|
.\"--- described in this document.
|
|
.\"---
|
|
.\"--- STDERR example:
|
|
.\"---
|
|
.\"--- .SH STDERR
|
|
.\"--- need example here
|
|
.\"---
|
|
.SH STDERR
|
|
Used only for diagnostic messages.
|
|
.\"---
|
|
.\"----------------------------------------------------------------------------
|
|
.\"--- "OUTPUT FILES"
|
|
.\"--- This section describes the files created or modified by the utility.
|
|
.\"--- Default Behavior: When this section is listed as "None", it means that no
|
|
.\"--- files are created or modified as a consequence of direct action on the
|
|
.\"--- part of the utility when the utility is used as described by this
|
|
.\"--- document. However, the utility may create or modify system files, such
|
|
.\"--- as log files, that are outside the utility's normal execution environment.
|
|
.\"---
|
|
.\"--- OUTPUT FILES example:
|
|
.\"---
|
|
.\"--- .SH "OUTPUT FILES"
|
|
.\"--- need example
|
|
.\"---
|
|
.SH "OUTPUT FILES"
|
|
None by default.
|
|
.PP
|
|
Interactively, the Application Builder provides facilities for writing
|
|
("saving") application project and module files, both of which must be
|
|
in the BIL format, and also for writing ("exporting") interface files that use
|
|
Motif's UIL format.
|
|
.\"---
|
|
.\"----------------------------------------------------------------------------
|
|
.\"--- "EXTENDED DESCRIPTION"
|
|
.\"--- This section provides a place for describing the actions of very complicated
|
|
.\"--- utilities, such as text editors or language processors, which typically
|
|
.\"--- have elaborate command languages.
|
|
.\"--- Default behavior: When this section is listed as "None", no further
|
|
.\"--- description is necessary.
|
|
.\"---
|
|
.\"--- EXTENDED DESCRIPTION example:
|
|
.\"---
|
|
.\"--- .SH "EXTENDED DESCRIPTION"
|
|
.\"--- need example
|
|
.\"---
|
|
.SH "EXTENDED DESCRIPTION"
|
|
None.
|
|
.\"---
|
|
.\"----------------------------------------------------------------------------
|
|
.\"--- "EXIT STATUS"
|
|
.\"--- This section describes the values the utility returns to the calling
|
|
.\"--- program, or shell, and the conditions that cause these
|
|
.\"--- values to be returned. Usually, utilities return zero for successful
|
|
.\"--- completion and values greater than zero for various error conditions.
|
|
.\"--- If specific numeric values are listed in this section, the system
|
|
.\"--- uses those values for the errors described. In some cases, status
|
|
.\"--- values are listed more loosely, such as ">0". A portable application
|
|
.\"--- cannot rely on any specific value in the range shown and must be
|
|
.\"--- prepared to receive any value in the range. For example,
|
|
.\"--- a utility may list zero as a successful return, 1 as a failure for a
|
|
.\"--- specific reason, and >1 as "an error occurred". In this case,
|
|
.\"--- unspecified conditions may cause a 2 or 3, or other value, to be
|
|
.\"--- returned. A portable application should be written
|
|
.\"--- so that it tests for successful exit status values (zero in this case),
|
|
.\"--- rather than relying on the single specific error value listed
|
|
.\"--- in this document. In that way, it will have maximum portability,
|
|
.\"--- even on implementations with extensions. Unspecified error
|
|
.\"--- conditions may be represented by specific values not listed
|
|
.\"--- in this document.
|
|
.\"---
|
|
.\"--- EXIT STATUS example:
|
|
.\"---
|
|
.\"--- .SH "EXIT STATUS"
|
|
.\"--- When the
|
|
.\"--- .B \(mic
|
|
.\"--- child process exits,
|
|
.\"--- .Cm ttsession
|
|
.\"--- exits with the status of the exited child.
|
|
.\"--- Otherwise, the following exit values are returned:
|
|
.\"--- .VL 4
|
|
.\"--- .LI 0
|
|
.\"--- Normal termination.
|
|
.\"--- Without the
|
|
.\"--- .B \(mic
|
|
.\"--- or
|
|
.\"--- .B \(miS
|
|
.\"--- options, a zero exit status means
|
|
.\"--- .Cm ttsession
|
|
.\"--- has successfully forked an instance of itself that has begun
|
|
.\"--- serving the session.
|
|
.\"--- .LI 1
|
|
.\"--- Abnormal termination.
|
|
.\"--- The
|
|
.\"--- .Cm ttsession
|
|
.\"--- utility was given invalid command line options, was interrupted by
|
|
.\"--- .Cn SIGINT ,
|
|
.\"--- or encountered some internal error.
|
|
.\"--- .LI 2
|
|
.\"--- Collision.
|
|
.\"--- Another
|
|
.\"--- .Cm ttsession
|
|
.\"--- was found to be serving the session already.
|
|
.\"--- .LE
|
|
.\"---
|
|
.SH "EXIT STATUS"
|
|
The following exit values are returned:
|
|
.PP
|
|
.RS 3
|
|
.nr )J 4
|
|
.LI 0
|
|
Normal termination.
|
|
.LI 1
|
|
Abnormal termination.
|
|
The
|
|
.BR dtbuilder
|
|
utility was unable to allocate necessary memory or spawn the code generator.
|
|
.PP
|
|
.RE
|
|
.nr )J 0
|
|
.\"---
|
|
.\"----------------------------------------------------------------------------
|
|
.\"--- "CONSEQUENCES OF ERRORS"
|
|
.\"--- This section describes the effects on the environment, files systems, and
|
|
.\"--- so on, when error conditions occur. It does not describe error messages
|
|
.\"--- produced or exit status values used.
|
|
.\"--- When a utility encounters an error condition, several actions are possible,
|
|
.\"--- depending on the severity of the error and the state of the utility.
|
|
.\"--- Included in the possible actions of various utilities are: deletion of
|
|
.\"--- temporary intermediate work files; deletion of incomplete files; validity
|
|
.\"--- checking of the file system or directory.
|
|
.\"--- Default behavior: When this section is listed as "Default", it means that
|
|
.\"--- any changes to the environment are unspecified.
|
|
.\"---
|
|
.\"--- CONSEQUENCES OF ERRORS example:
|
|
.\"---
|
|
.\"--- .SH "CONSEQUENCES OF ERRORS"
|
|
.\"--- need example here.
|
|
.\"---
|
|
.SH "CONSEQUENCES OF ERRORS"
|
|
Default.
|
|
.\"---
|
|
.\"----------------------------------------------------------------------------
|
|
.\"--- "APPLICATION USAGE"
|
|
.\"--- This section gives advice to the application programmer or user about the
|
|
.\"--- way the utility should be used.
|
|
.\"---
|
|
.SH "APPLICATION USAGE"
|
|
Because the
|
|
.BR dtbuilder
|
|
is a complex, highly-interactive tool, users
|
|
typically consider the command line interface as little more than the way
|
|
to start up the Application Builder.
|
|
.PP
|
|
\s-1CDE\s+1 provides an "AppBuilder" action so the Application Builder can be
|
|
invoked through the standard action interface, including through
|
|
the Application Manager.
|
|
.\"---
|
|
.\"----------------------------------------------------------------------------
|
|
.\"--- EXAMPLES
|
|
.\"--- This section gives one or more examples of usage, where appropriate.
|
|
.\"---
|
|
.SH EXAMPLES
|
|
.TP
|
|
.B "dtbuilder"
|
|
This runs the \s-1CDE\s+1 Application Builder, presuming that the user will either
|
|
be creating a new project or will load one interactively through the
|
|
Application Builder's "File" menu.
|
|
.TP
|
|
.B "dtbuilder myproject.bip"
|
|
Starts the \s-1CDE\s+1 Application Builder and instructs it to load the project
|
|
defined in the file
|
|
.BR myproject.bip .
|
|
.\"---
|
|
.\"----------------------------------------------------------------------------
|
|
.\"--- "SEE ALSO"
|
|
.na
|
|
.\"--- This section lists related entries
|
|
.\"---
|
|
.\"--- for example:
|
|
.\"---
|
|
.\"--- .SH "SEE ALSO"
|
|
.na
|
|
.\"--- .Hd <header_file.h> 5, if needed
|
|
.\"--- .Fn utility_name section number,
|
|
.\"--- .Fn utility_name section number,
|
|
.\"--- .Fn utility_name section number.
|
|
.\"---
|
|
.SH "SEE ALSO"
|
|
.na
|
|
.BR dtcodegen (1)
|
|
.BR BIL (4)
|