summaryrefslogtreecommitdiff
path: root/web/noweb/src/INSTALL
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /web/noweb/src/INSTALL
Initial commit
Diffstat (limited to 'web/noweb/src/INSTALL')
-rw-r--r--web/noweb/src/INSTALL92
1 files changed, 92 insertions, 0 deletions
diff --git a/web/noweb/src/INSTALL b/web/noweb/src/INSTALL
new file mode 100644
index 0000000000..a56b88aedc
--- /dev/null
+++ b/web/noweb/src/INSTALL
@@ -0,0 +1,92 @@
+These installation instructions are for Unix systems.
+For Plan 9 systems, Russ Cox has kindly provided scripts in the contrib
+directory, but for installation instructions, you are on your own.
+If you use Microsoft Windows, Jim Pettigrew has written installation
+instructions for Windows 7 at http://www.jim-pettigrew.com/noweb/install/.
+
+Crucial parts of noweb are written in both Icon and Awk. You can use
+either Icon or Awk, but Icon is better:
+
+ - If you have Icon, use the Icon version of the noweb library; this
+ code speeds up noweave by a factor of 3. The Icon versions have
+ fewer bugs and provide more filters (e.g., convert LaTeX to HTML
+ in documentation chunks). Not all of the examples will work with
+ the awk library. If you have an Icon compiler and believe it
+ works, set `ICONC=iconc -f l' in the Makefile. (Icon is freely
+ available from the University of Arizona, but the compiler is no
+ longer maintained.)
+
+ - As of version 2.12, the Awk code for noweb's indexing and
+ cross-reference relies on the bit-manipulation primitives found
+ in GNU Awk. If you have neither Icon nor GNU Awk, you will not
+ be able to index or cross-reference literate programs.
+ (This breaking change was put in to enable the Awk and Icon codes
+ to generate *identical* outputs, for regression testing.)
+
+
+To build noweb:
+
+ 1) First point to compilers to be used to built the tools and
+ library by setting these variables in the Makefile:
+ CC the name of an ANSI C compiler
+ LIBSRC 'awk' or 'icon', depending on which library you want
+
+ Now choose locations for the noweb files, and set the appropriate
+ variables in the Makefile:
+ BIN on $PATH, will hold notangle, noweave, noroots, ...
+ LIB a directory to store markup, nt, noxref, ...
+ MAN man pages will go in $MAN/man1
+ TEXINPUTS a directory TeX will look for nwmac.tex and noweb.sty
+ ELISP a directory for noweb-mode.el, for emacs 19 and up
+ All of these files are *output* files, where noweb will place
+ binaries and man pages that are customized for your installation.
+ Therefore you should:
+ - make sure you have permission to write to these directories
+ - refrain from making them point into the noweb source distribution
+ - arrange for BIN to be on your $PATH and MAN to be on your $MANPATH
+ If you don't use emacs, just leave ELISP set to /dev/null.
+
+ 2) If your modern awk is called something other than `nawk', run the
+ `awkname' script to change all references to nawk. For example,
+ `awkname gawk'. You need to do this even if you have chosen
+ LIBSRC=icon, because there are a few scripts here and there that
+ are only written in awk. If you have an HPUX system and you're
+ using the vendor-supplied awk, you have a problem---see file HPUX
+ for details.
+
+ Note: the `awkname' script relies on mktemp(1) to create
+ temporary files. If your system lacks this program, you'll need
+ to substitute tempfile(1) or some other means of creating a
+ temporary file.
+
+ 3) Type `make boot'. This command updates timestamps so that noweb
+ does not try to build itself using noweb.
+
+ 4) Fasten your seat belt and type `make all install'. If you want a
+ nonstandard noweave, you can use the WEAVE variable in the
+ Makefile; for example, `make WEAVE=noweave.simple'. In contrast
+ with previous versions, the standard noweave should work with
+ HPUX and SGI Irix.
+
+ 5) If you want to install contributed software, you need the
+ `contrib' hierarchy. Get it, set the LIB variable in the
+ Makefile, and type 'make all install'. If you just want the
+ nuweb parser, try
+ (cd ../contrib/norman; make LIB=$LIB all install)
+ where $LIB is the noweb LIB directory.
+
+ 6) On some installations, (e.g., Unix teTeX), you may have to run
+ texhash(1) before TeX or latex will see files added to TEXINPUTS.
+
+ 7) You can clean up by typing `make clean'. If you wish, you can
+ remove the pre-built sources by typing `make clobber', but then
+ you will be unable to build noweb unless you already have noweb.
+
+Instead of editing the Makefile, you can create a shell script that
+invokes make with the proper variables. `nwmake' is an example of
+such a script; I use it to install noweb at Princeton using the Icon
+cross-referencer and our local C compiler. If you make your own
+script, call it something else so it won't get overwritten by the
+default nwmake when you unbundle a new distribution.
+
+If you encounter a problem building noweb, try the FAQ file.