 
    -----------------------------------
    FNORDADEL 1.32 SOURCES DISTRIBUTION
    -----------------------------------

    This archive contains the full source code for the Fnordadel programs and
documentation.  Here is a list of what's what:

README.src	This file.
citalt/		(DIR) Peripheral programs; not part of the general distribution.
cith/		(DIR) Header files.
citlib/		(DIR) Library sources.
citmain/	(DIR) Sources for citadel.tos and configur.tos.
citutil/	(DIR) Sources for all distributed utilities.
ctdlcnfg.doc	Documented configuration file.
fnordbug	Current list of known bugs.
fnorddoc	Current list of suggestions for the documentation.
fnordsug	Current list of suggestions for improvements to Fnordadel.
increm		Current increm (incremental change documentation; IMPORTANT!).
increm.1	Old increm file.
increm.2	     -ditto-
increm.3	     -ditto-
increm.4	     -ditto-
makefile	The master makefile.
man/		(DIR) Nroff sources for the man pages.
ref-man/	(DIR) Texinfo sources for the Reference Manual.
scripts/	(DIR) Various shell scripts, for Unix shells and Gulam (ST).

citalt:
citpeek.c	Program to get down and dirty with system files; debugging aid.
dumpmsg.c	Dump pieces of message base to the screen.
runit.c		Old STadel prg to run the BBS; a kind of specialised mini-shell
spooledt.c	Old STadel prg for editing network spool files.
users.c		Old STadel prg to postprocess clog output.

cith:
*.h		C header files, included by all Fnordadel programs.

citlib:
*.c		C source files for the Fnordadel library.  The Makefile links
		all binaries against this library to pick up commonly used
		low-level code.

citmain:
*.c		C source files for citadel and configur.

citutil:
*.c		C source files for all distributed utility programs.

man:
Makefile	The Makefile (generates *.man from *.1)
manfilt.c	A quick hack to filter excess blank lines from formatted man
		pages.  You may not need this.
*.1		Nroff sources for man pages.

ref-man:
Makefile	A Makefile for the Reference Manual.
*.tex		Texinfo source files for the Manual.

scripts:
bbs.g		A Gulam script to run the BBS.
ldt*		Unix shellscript to make a file listing all sources.
makedist*	Unix shellscript to build a distribution; use after `setupdist'.
manbak*		Unix shellscript to make a quickie manual backup.
manbak.g	Gulam version of above.
setupdist*	Unix shellscript to set up a distribution directory.
srcbak*		Unix shellscript to make a quickie sources backup.
srcbak.g	Gulam version of above.


    How to build Fnordadel
    ----------------------

    This is the scary bit. (-:  Firstly, some requirements.  Fnordadel is
written in ANSI C.  We use the GCC compiler, but there are other ANSI
compilers for the ST (Turbo C, to name one).  We use Eric Smith's MiNT library
with it, although bammi's GCC libs should work fine.  We make no guarantee
that things will work using different libs under GCC or another compiler,
but we don't think we've done anything gross to make it lib-specific or
anything.
 
    Assuming that the first paragraph didn't get you, here's how to build
Fnordadel:

    1) Unpack the rest of this archive, if you haven't already.  You'll find
       the directory structure as listed above.
    2) Edit the makefile to point make at the binaries for your compiler.  We
       compile Fnordadel on a NeXT running a GCC cross-compiler, but we also
       compile on the ST.  Take your pick, or if you're using another compiler,
       try it.
    3) Take a look at the various targets defined in the makefile.  Among the
       more popular options are `make minimum' to build citadel and configur,
       and `make remake' to build the whole bloody thing.  We suggest the
       first one, for starters.

    If you tried a make in step 3 and it worked, you should have binaries in
citmain called citadel.tos and configur.tos.  Try running them.  If all works,
run a make remake to build the whole lot.
 
    If you tried a make and it didn't work, you're out of luck. (-:  No,
seriously... 

    o If make cannot find the compiler binaries, you'll find out pretty
quick.  If you're using GCC, make sure you have the GCCEXEC environment
variable set correctly (using a command like `SETENV GCCEXEC c:\bin\gcc-').

    o If the gcc archiver (gcc-ar) dies while make is trying to build
libfnord.olb, you might have one of the buggy versions.  Make will crap out,
and you can manually rename a temporary file you'll find lying about in
citlib to `libfnord.olb' and restart the make.  This is annoying, so get a
fresh copy of the gcc-ar.

    o If make craps out on you at a random point with `out of memory' errors,
just restart it.  ST versions of GNU-Make have some sort of memory leak which
causes harmless but annoying sudden stops.

    o If something else craps out, you're on your own.  If you have the same
setup as we do, things should go smoothly.  If you have a different setup,
we can try to help, but no guarantees.  Send some mail.


    What to do with it once it's built
    ----------------------------------

    There are a few things you can do with the Fnordadel sources once you've
got them built.

    1) Erase them, since it was all just an academic exercise. (-:
 
    2) Use them to keep up with new Fnordadel releases.  We will be releasing
       updates to Fnordadel in source and binary form; getting the source
       patches and building your own binaries will probably be cheaper in
       terms of the amount of stuff you'll have to download or transfer to
       get the new versions.

    3) Hack on it yourself.  We don't discourage this, but we would like to
       emphasize that we'd really like to keep Fnordadel a relatively stable
       system.  You are perfectly entitled to take Fnordadel, change a few
       things, change the name and release a new system, but please don't
       unless it's really radical stuff.  A much better approach is to hack
       in the things you want and then send us diffs; chances are good that
       we'll merge them with the official version.

       If you do plan to hack on Fnordadel, best to ask us before you start --
       we may already have hacked in the thing you want and just not told
       anyone yet, or we might know of someone else who's doing the same
       thing already.  Duplicated effort benefits no-one.


    Fnordadel development conventions
    ---------------------------------

    We maintain a few files to help the development process.  We list them
here:

    o fnordbug -- this is a list of all known bugs.  Bug reports are
      logged in here, preferably with an attribution (i.e., who reported it).
      When a bug is fixed, the version in which the fix went in is added
      beside the bug.  When we're confident that the fix works, we remove
      the bug from the list.
    o fnordsug -- same sort of thing as fnordbug, only for suggestions instead
      of bugs.  We put the version number where a suggestion was implemented,
      and leave it around until we're sure it works.
    o fnorddoc -- same thing again, only this time for documention glitches
      and/or suggestions.

    o increm -- Anything done to Fnordadel is logged in increm.  Each change
      is logged under a header listing the date, the version number and files
      affected.  Every so often when a new public or beta release goes out,
      it is renamed to increm.X where X is a number, and a new one is started.
      These increm files are transcribed by us into increm.doc, which is a
      version of increm written in English rather than hackerese for the
      benefit of the sysops.

    Another thing you should know about: the version numbering scheme.  The
version number of citadel.tos is comprised of a version string, VERSION, and
a patch number, PATCHNUM.  The former is defined in citlib/version.c, and is
changed rarely; changing the version number indicates a major change to
system files or something like that.  The patch number, on the other hand,
changes every single time a change or batch of changes is made, no matter how
minute.  The idea is that no incompatible system file changes are made
within a given version; i.e., utility binaries compiled under some revision
of version x.yz will work with any citadel/configur binaries from the
same version; if an incompatibility is introduced (like a change to the log
file, net file or similar), we must bump the version number.  Simple, huh?
In actual practice, sometimes we make changes that are tiny and don't seem
to warrant upping the version number, but which nonetheless render utility
binaries incompatible due to a change in ctdltabl.sys format.  This is a
weakness whcih must be addressed.


    How to build the Reference Manual
    ---------------------------------

    To build the Manual you need a few things that aren't included here.  You
will first off need a working TeX system.  TeX is available for the ST,
and it's a standard piece of software on most Unix sites, so if you have
access to a Unix box (especially one with a laser printer) you may be in
luck.  Once you've found a TeX system, or got the TeX stuff for your ST and
installed it and figured out how it works (no easy thing), you then have to
get ahold of the GNU Texinfo system.  It's available at secret and RT, and
at many sites on the Internet.  It consists of a file of TeX macros called
texinfo.tex, and a bunch of other stuff (like macros for the Emacs text
editor) that you don't have to worry about.

    In order to process the Manual and get the nice typeset output for a
laser printer, simply put texinfo.tex in the search path of TeX and say
`make fnord.dvi'.  Make will run TeX three times (this is slow as molasses,
we know, but it's necessary) and produce fnord.dvi, which is the
device-independent file of TeX output which can then be printed on any
sort of high-res output device.

    In order to get the ASCII version of the manual (the one that comes in
the fnXXXman.zoo archive), you'll need even more stuff.  Adrian (elim@secret)
has hacked the Texinfo macros to work in conjunction with a program called
`dvidoc', which takes a TeX DVI file and produces an ASCII approximation of
it.  The hacked texinfo.tex adjusts all the fonts to one boring font, and
changes a bunch of other things.  The modified texinfo.tex is called
`docinfo.tex', and is available at secret and RT.  You also need the dvidoc
program, available at the same places.  When you have these things, you
can say `make fnord.doc' and out will come a file of plain ASCII text
called fnord.doc.  (You will notice that the pagination is different between
the nice typeset version and the ASCII version; this is because of the
different fonts and page size set in docinfo.tex as opposed to texinfo.tex.
Notice that all the index entries and cross-references are properly
adjusted...neat, huh?)


    Formatting the man pages
    ------------------------

    In the man directory is a set of nroff source files (*.1), a Makefile and
a small C program called manfilt.c.  Manfilt was hacked together because the
nroff on our NeXT likes to put large numbers of spurious blank lines in the
output; this program filters them out.  If you're on a Unix box, you should
have no problem with these things (just type `make').  If you're on an ST,
you'll have to get ahold of some version of nroff.  Try Bill Rosencranz's
version.

    If you have problems
    --------------------

    If you have trouble getting any of this stuff to work, you can drop us
a line and we'll try to help.  Good luck.

    --Adrian Ashley (elim@secret)
      Royce Howland (Mr. Neutron@RT)

      September, 1991
