Mon Apr 27 13:46:40 1998 John Metzler <jmetzler@cygnus.com>

[platform/upstream/binutils.git] / 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
@c We don't actually want a titlepage; HEADINGSon is usually called by
@c @end titlepage to turn on footers and headers.
@setchapternewpage odd
@HEADINGSon
@end iftex

@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

@item g++
C++ compiler

@item gdb
Debugger

@item make
Automates building and installing your programs

@item gprof
Performance analyzer

@item byacc
Parser generator

@item flex
Fast lexical analyzer generator

@item libg++.a
Class library for C++

@item send_pr
Script to send structured problem reports to Cygnus

@item diff
Compares source files

@item patch
Installs source fixes

@item info
@itemx makeinfo
Online documentation tools

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

On most host systems, the following are also included (to see if
they are available on your host, @pxref{Contents, Release Contents,
Release Contents, README.info, Installation Notes}).

@table @t
@item gas
Assembler

@item ld
Linker

@item ar
Manages object code archives

@item nm
Lists object file symbol tables

@item objdump
Displays object file information

@item ranlib
Generates archive index

@item size
Lists section and total sizes

@item strip
Discards symbols
@end table

These tools are free software; most of them are from the GNU project,
produced by the Free Software Foundation (FSF).  ``GNU'' is the name of
the FSF's evolving system (in speech, the `G' is sounded).  Cygnus
Support collaborates with the FSF in developing these tools.  In this,
our @dfn{Progressive} product, we've assembled the most recent forms of
the development tools, tested them, made sure they work well together,
made them easy to install---the installation tape comes with binaries
already compiled for your system---and made them easy to reconfigure and
recompile from source.

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.

@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}

@cite{Using @code{as}: The @sc{gnu} Assembler}

@cite{The @sc{gnu} Binary Utilities}

@cite{@code{gld}, the @sc{gnu} Linker}

@cite{@sc{gnu} Make: A Program for Directing Recompilation}

@cite{User's Guide to the @sc{GNU} C++ Class Library}

@end display

The manuals are designed for easy online browsing (@pxref{Info,,Online
Documentation}).  For online use, the accompanying software distribution
tape 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 on the tape.

@node Info,,,
@section Using Online Documentation

You can browse through the online documentation using either @sc{gnu} Emacs,
or the program @code{info} included on the accompanying tape.
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 bugreport (if you've marked your report as high priority, we respond
with an analysis of the problem in less than one business day).  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 does not 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