This is a collection of various programming-related documentations from 
the GNU project.  If you aren't a programmer the thing won't be too
exciting for you (no images, just computing hubba bubba).

All sources were converted from GNU texinfo format into ST-Guide
format using info2stg by Martin Osieka <Martin_Osieka@of2.maus.de>.
The converter is very good but not perfect.  So please expect some
broken links, and some fancy formatting every here and there.  However,
the hypertexts should be generally alright.

All texinfo sources can be found at ftp://prep.ai.mit.edu/pub/gnu
in the corresponding archives (i.e. if you look for the texinfo sources
for the gcc documentation, download the gcc package).  

You should know that I never intended to publish these hypertexts,
I've created them solely for private use.  I considered the info2stg
output (i.e. the ST-Guide sources .stg) as intermediate and have 
deleted them.  So if you think the results are unsatisfying and you
want to do a revision on them, you can't help but download the GNU
stuff and redo the whole thing.

If you feel that this archive is too big feel free to split it up
into distinct pieces.  Please make sure to include the file COPYING
in your distribution.  You should also consider to leave this file
intact and write a new README.1st instead.

General
=======

On a MiNT system with gcc and MiNTLib installed you have all opportunities
to write modern, platform-independent, not only Unix-programs.  Gcc
is an ANSI-compliant C compiler, the MiNTLib offers the most important
features of a standard libc as found on most Unix machines.  Yet
many people are looking for a comprehensive introduction into the
software development in a Unix environment.  The hypertexts included
here can serve both as an introduction and as a reference manual
but in an easy-to-access way, the way Atari users are used to.

What's inside?
==============

1. library.hyp

The documentation of the GNU libc 1.97.  The GNU libc is a very
powerful implementation of a standard, POSIX-compliant libc.  The
MiNTLib is also a very powerful implementation of a standard, POSIX-
compliant libc but not as powerful and not as POSIX-compliant as
the GNU libc is.  However you can still use the GNU documentation
as a documentation to MiNTlib.  At least it's better than nothing
and in fact there's no other documentation for the MiNTlib available.

However you should bear in mind that the MiNTlib suffers from various
deficiencies:  Some functions are completely missing (most of
the internationalization stuff for instance), some functions are
mal-implemented (you shouldn't rely too much on the documented values
of `errno' after a failed function call, in the MiNTLib it's often
pure fantasy), and some functions described in the hypertext are
GNU extensions (e.g. getline).  The latter are generally indicated
as such.  But if you find the GNU extensions useful it's often
no problem to get a standalone version of the particular function.
You can then either compile them directly into your mintlib (remember
that you can add modules to any library) or you just add them
to your sources.

The hypertext is really very, very big.  You should get familiar
with its structure first.  If you want a step-by-step introduction
I would recommend to simply click on the right-arrow icon.  This
will visit all chapter headings.  In every chapter you can
choose the first link and then use the right-arrow again and so on.
If you then manage to remember everything you've read you should
really be an expert in using the standard libc.

If you're already familiar with the libc you might rather want
to use the documentation as a quick reference to look up the
behaviour of a certain function, to refresh your knowledge.  On 
the front page you will find a paragraph `indices'.  These 
5 indices listed there will give you really quick access to 
the particular node you look for.  I mostly use the `Function
index'.  A typical session:  I look up the function `geteuid'.
I read the text and want to understand more about the context
that `geteuid' is embedded in.  So I simply click the `Node-Up'
icon and find myself in the chapter `Users and Groups'.  I
see the various aspects of users and groups database including
a somewhat exhaustive example of the programming interface.
Show me a book that explains it better/faster! ;-)

One last note:  The GNU libc includes some modules that are
placed in separate libraries for MiNT.  E.g. the socket
interface is found in Kay Roemer's libsocket.  The math
stuff can be found in the portable math library.  Some of
the internationalization stuff can be found in libintl
(download the gettext package from prep.ai.mit.edu, libintl
is included there).

libg++.hyp
==========

The documentation of the GNU libg++ 2.7.1.  Note that this hypertext
does /not/ give an introduction to the C++ programming language.
You can access the description of the various classes directly
from the front page so the doc doesn't need any further description.

iostream.hyp
============

Actually the stream classes are the `heart' of a C++ library.  They
are covered in a separate module however.

gcc.hyp
=======

The documentation of the GNU C compiler gcc.  Note that large parts of
the file describes how to build the compiler resp. how to port the
compiler to a new platform.  This is probably of little use for
most folks.  However it explains the many special features and
language extensions of the GNU C compiler, so it shouldn't be missing
here.

g++.hyp
=======

The C++ compiler is now included in gcc.  For traditional reasons
the C++ stuff is explained in a separate documentation.

cpp.hyp
=======

The C preprocessor.  

make.hyp
========

Maybe a little off topic.  This hypertext documents GNU make.  If
you plan to realize complex projects you can't do without the help
of make.  


I hope the files will be useful for you.  Typos and other mistakes
are property of the finder.  Have fun!

Guido Flohr
-- 
http://stud.uni-sb.de/~gufl0000/
mailto:gufl0000@stud.uni-sb.de
