* libbfd-in.h, bfd-in.h: Eliminate all PROTO calls, replace with

[deliverable/binutils-gdb.git] / sol-intro.texi

\input texinfo
@c $Id$
@setfilename intro.info
@settitle Introduction
@iftex
@c The include file "texiplus.tex" is in the texinfo/cygnus dir, and
@c implements Cygnus modifications to the texinfo manual style.
@input texiplus
@c The include file "smpklug.texi" is a kluge to deal with local
@c document production issues at Cygnus; it's safe to comment out this
@c line if you don't have (or don't want) the file.
@input smpklug.texi
@smallbook
@cropmarks
@finalout
@end iftex
@titlepage
@title Introduction
@sp 3
@subtitle Cygnus Support Developer's Kit for Solaris 2.0
@author Cygnus Support
@page

@tex
\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
\xdef\manvers{\$Revision$} % for use in headers, footers
{\parskip=0pt \hfill Cygnus Support\par \hfill {\it Introduction (Solaris-2)}, \manvers\par \hfill
\TeX{}info \texinfoversion\par }
@end tex

@vskip 0pt plus 1filll
Copyright @copyright{} 1991, 1992 Cygnus Support

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.

@end titlepage

@node Top
@unnumbered Introduction

This Developer's Kit puts at your disposal, in a single coordinated
and tested release, some of the best software development tools
available:

@table @t
@item gcc
C compiler (and its supporting programs and libraries)

@item gdb
Debugger

@item gprof
Performance analyzer

@item byacc
Parser generator

@item flex
Fast lexical analyzer generator

@item send_pr
Cygnus problem-reporting utillity

@item patch
Source-code update utility

@item info
@itemx makeinfo
Online documentation tools

@item texinfo.tex
@itemx texindex
Documentation printing tools
@end table

These tools are free software; many of them are from the Free Software
Foundation (FSF) GNU project (in speech, the `G' in GNU is sounded).
Others were developed by the University of California, Berkeley and its
contributors.

Cygnus Support collaborates with the FSF in developing these tools.  In
this product, we've ported recent forms of the development tools to
Solaris 2, tested them, made sure they work well together, and made them
easy to install---the installation package comes with binaries already
compiled for your system.

Cygnus Support exists to help our clients exploit their freedom in
using, adapting, or enhancing this software.  @xref{Cygnus,,About Cygnus
Support}, for more information.

@menu
* Copying::     Free Software
* Manuals::     Printed and Online Manuals
* Info::        Using Online Documentation
* Bugs::        Reporting Trouble
* Cygnus::      About Cygnus Support
@end menu

@page
@node Copying
@section Free Software
If you find our Developer's Kit useful, please feel free to give or sell
copies of the software and documentation to anyone you like.

Cygnus products are @dfn{free software}, protected by the @sc{gnu} General
Public License (GPL).  The GPL gives you the freedom to copy or adapt any
program it licenses---but every person getting a copy also gets with it the
freedom to modify that copy (which means that they must get access to
the source code), and the freedom to distribute further copies.  Typical
software companies use copyrights to limit your freedoms; the GPL is
designed to preserve your freedoms.

Fundamentally, the General Public License is a license which grants you
these freedoms, and only imposes restrictions to ensure that no one can
take these freedoms away from anyone else.

For full details, see the @strong{LICENSE} section in this manual
set.

@page
@node Manuals
@section Manuals
@noindent
These printed manuals are included in your Cygnus Progressive Release:
@display

@cite{Using the @sc{gnu} C Compiler}

@cite{The C Preprocessor}

@cite{GDB: The @sc{gnu} Source-Level Debugger}

@end display

The manuals are also designed for easy online browsing (@pxref{Info,,Online
Documentation}).  For online use, the accompanying software distribution
includes all the printed manuals, and also the following documents:

@table @emph
@item FLEX: A Fast Lexical Analyzer Generator
Generates lexical analyzers suitable for GCC and other compilers.

@item Info: Documentation Browsing System
Full details on the @code{info} browser.

@item Texinfo: The @sc{gnu} Documentation Format
How you can use @TeX{} to print these manuals, and how to write your own
manuals in this style.

@item Using and Porting @sc{gnu cc}
Detailed information about what's needed to put @sc{gnu cc} on different
platforms, or to modify @sc{gnu cc}.  Also includes all the
information in the printed manual @cite{Using the @sc{gnu} C Compiler}.
@end table

@noindent
Finally, @code{man} pages are included for all the programs in the release.

You have the freedom to copy the manuals, like the software they cover;
each manual's copyright statement includes the necessary permissions.
The manuals themselves are also free software, and the source for them
is also available in the installation package.

@node Info
@section Using Online Documentation

You can browse through the online documentation using either @sc{gnu} Emacs,
or the (included) program @code{info}.
Online, the manuals are organized into @dfn{nodes}, which correspond to
the chapters and sections of a printed book.  You can follow them in
sequence, if you wish, just like in the printed book---but there are
also other choices.  The documents have menus that let you go quickly to
the node that has the information you need.  @code{info} has ``hot''
references; if one section refers to another, you can tell @code{info}
to take you immediately to that other section---and you can get back
again easily to take up your reading where you left off.  Naturally, you
can also search for particular words or phrases.

The best way to get started with the online documentation system is to
run the browser @code{info}.  After the Progressive Release is installed on
your system, you can get into @code{info} by just typing its name---no
options or arguments are necessary---at your shell's prompt (shown as
@samp{eg%} here):
@example
eg% info
@end example

@noindent
@code{info} will display its first screen, a menu of the documentation
available, and will await your input.  Typing the single letter
@example
h
@end example
@noindent
requests a tutorial, designed to teach you how to use @code{info}.

If you already use Emacs, you may want to get into the documentation
browsing mode, instead, by typing @kbd{C-h i} inside Emacs.

You can get out of @code{info} at any time by typing the single letter
@kbd{q}.  

@page
Here is a summary of all the @code{info} commands; @code{info} itself
can display a summary like this at any time, when you type the single
character @kbd{?}.

@smallexample
@cartouche
h       @r{Invoke the Info tutorial.}
q       @r{Quit Info}

@i{Selecting other nodes:}
n       @r{Move to the ``next'' node of this node.}
p       @r{Move to the ``previous'' node of this node.}
u       @r{Move ``up'' from this node.}
m       @r{Pick menu item specified by name (or abbreviation).}
        @r{Picking a menu item moves to the corresponding node.}
f       @r{Follow a cross reference.  Reads name of reference.}
l       @r{Move to the last node you were looking at.}

@i{Moving within a node:}
Space   @r{scroll forward a page.}
DEL     @r{scroll backward a page.}
b       @r{Go to beginning of this node.}

@i{Advanced commands:}
1       @r{Pick first item in node's menu.}
2 - 5   @r{Pick second ... fifth item in node's menu.}
g       @r{Move to node specified by name.}
        @r{You may include a filename as well, as @code{(@var{FILENAME})@var{NODENAME}}.}
s       @r{Search through this Info file for a specified string,}
        @r{and select the node in which the next occurrence is found.}
Ctl-p   @r{Print the contents of this node using @samp{lpr}.}
@end cartouche
@end smallexample

@page
@node Bugs
@section Reporting Trouble
We've tried to make the programs in your Progressive Release as
trouble-free as possible.  If you do encounter trouble, however, we'd
like to be able to diagnose and fix the problem as quickly as possible.
You can help us do that by using the script @code{send_pr} to send us your
problem reports.

@code{send_pr} invokes an editor on a problem report form (after
trying to fill in some fields with reasonable default values). After
you exit the editor, @code{send_pr} sends the filled out form to the
problem report management system (PRMS) at Cygnus Support.  You can
use the environment variable @code{EDITOR} to specify what editor to
use (the default is @code{vi}).

@code{send_pr} attempts to send your problem report to Cygnus via
electronic mail.  If your site cannot support this, you can still use
the problem report form: use @samp{send_pr -p} to capture a copy of the
blank problem-report form and fill it in.  (You can also photocopy the
blank form at the end of this section to fill in.)  In either case you
can FAX the problem report to Cygnus at @w{+1 415 322 3270}.

At Cygnus Support, the problem report is assigned a unique number and is
stored in the PRMS database according to its category and your
customer ID.  PRMS automatically replies with an acknowledgement, citing
the category and the PR number.  As the next step, Cygnus staff inspects
the bug report (if you've marked your report as high priority, we respond
with an analysis of the problem in less than five business days).  We'll
offer a solution as soon as possible, and await your feedback.  As a
matter of policy, we do not consider your problem report closed until
you've agreed with a solution we offer.

To ensure that a problem report is handled promptly, it must contain
your (unique) customer ID and one of the available categories, shown as
comments in the problem report form, to identify the problem area. As a
Cygnus Support customer, you can obtain your customer ID by invoking
@code{send_pr} with the @samp{-request-id} option.

@page
@subsection Filling out a problem report
Problem reports are structured so that a program can manage them. When
filling out the form, please remember the following guidelines:

@itemize @bullet
@item
Each PR needs a valid customer ID and category.

@item
Describe only one problem with one PR.

@item
For follow-up mail, use the same subject line as the one in the
automatic acknowledgent. It shows the category, the PR number and the
original synopsis line.  This allows Cygnus Support to make sure mail on
the same problem report stays together.

@item 
Please try to make the subject or synopsis line as informative
as possible.  For misbehaving software, you might use a sentence of
the form ``with input foo, component xyz produces bar''.

@item
You don't need to delete the comment lines while editing the PR form;
this is done by @code{send_pr}.  Put your information before or
after the comment.
@end itemize

@page
For full details on @code{send_pr} and the supporting form, see the man
page @code{send_pr}(1).  Here is a sample blank problem-report form; if
electronic mail from your site cannot reach Cygnus, you can send us
problem reports by photocopying this sample, filling it out, and sending
it by FAX to @w{+1 415 322 3270}.

@iftex
@widen{28pt}
@end iftex

@smallexample
SEND_PR: Choose from the following categories:
SEND_PR:
SEND_PR: bfd       binutils  bison     clib      config    cvs
SEND_PR: diff      doc       emacs     g++       gas       gcc       
SEND_PR: gdb       grep      ispell    ld        libg++    libiberty
SEND_PR: libiberty make      rcs       readline  send_pr   texinfo
SEND_PR: other
SEND_PR:

To: cygnus-bugs@@cygnus.com 

Subject: 

From: 

Reply-To: 

X-send-pr-version: send_pr: 1.15


>Customer-Id:

>Originator:    <name of the PR author (one line)>

>Organization:  <organization of PR author (multiple lines)>



>Confidential:  <[ yes | no ] (one line)>

>Synopsis:	<synopsis of the problem (one line)>

>Severity:	<[ non-critical | serious | critical ] (one line)>

>Priority:	<[ low | medium | high ] (one line)>

>Category: 	<name of the product (one line)>

>Class:		<[ sw-bug | doc-bug | change-request | support ] (one line)>

>Release:	<release number or tag (one line)>

>Environment:
        <machine, os, target, libraries (multiple lines)>



>Description:	 
        <precise description of the problem (multiple lines)>






>How-To-Repeat:	 
        <code/input/activities to reproduce the problem (multiple lines)>
@end smallexample

@iftex
@widen{-28pt}
@end iftex

@page
@node Cygnus
@section About Cygnus Support
Cygnus Support was founded in 1989 to provide commercial support for
free software.  Cygnus supplies products and services that benefit
advanced development groups by allowing them to use state-of-the-art
tools without having to maintain them.  With Cygnus Support, sites that
once were forced to do their own tool support can recover that valuable
staff time.  Former users of proprietary software now may choose
supported free software, combining the advantages of both worlds.

Free software is faster, more powerful, and more portable than its
proprietary counterparts.  It evolves faster because users who want to
make improvements are free to do so.  Cygnus tracks these
improvements and integrates them into tested, stable versions ready
for commercial use, then backs this software with comprehensive
support.

With Cygnus Support as your partner, you will have the software and
the support you need to meet your business objectives.  Cygnus
is intimately familiar with this software from extensive experience
using, debugging, and implementing it.  You get direct access to the
most qualified support people: the authors of that software.

We provide up-to-the minute ``progressive'' releases, for those who need
the very latest version---or ``vintage'' releases: stable versions which
have been through extensive use and testing.

Because all our improvements are also free software, you can
distribute them widely within your organization, or to your customers,
without extra cost.

@sp 4

@display
Cygnus Support
814 University Avenue
Palo Alto, CA 94301, USA

+1 415 322 3811

email: @code{info@@cygnus.com}
fax: +1 415 322 3270
@end display

@bye