Changeset 354f3b in git for doc

Timestamp:

Nov 29, 1999, 1:56:11 PM (24 years ago)

Author:

Olaf Bachmann <obachman@…>

Branches:

(u'spielwiese', '2a584933abf2a2d3082034c7586d38bb6de1a30a')

Children:

6429844b12e9748d6a461099af9e807e552d8950

Parents:

7736c5c981277530fc20586946850a0fe14b5348

Message:

 Changes to docu and install


git-svn-id: file:///usr/local/Singular/svn/trunk@3933 2c84dea3-7e68-4137-9b89-c4e89433aadc

Location:

doc

Files:

• INSTALL_unix.texi (modified) (10 diffs)
• Makefile.in (modified) (5 diffs)
• doc2tex.pl (modified) (6 diffs)
• general.doc (modified) (previous)
• platform.doc (modified) (previous)
• reference.doc (modified) (previous)
• singular.doc (modified) (previous)

doc/INSTALL_unix.texi

@@ -1 +1 @@
 @comment -*-texinfo-*-
-@comment $Id: INSTALL_unix.texi,v 1.2 1999-11-26 18:03:25 obachman Exp $
+@comment $Id: INSTALL_unix.texi,v 1.3 1999-11-29 12:56:06 obachman Exp $
 @comment this file contains the installation instruction for Singular on 
 @comment Unix
+@ifclear VERSION
 @include version.texi
+@end ifclear
 
 @ifclear singularmanual
@@ -14 +16 @@
 
 @ifset UNAME
-@set _UNAME @value{UNAME}
+@include uname.texi
 @end ifset
 
@@ -27 +29 @@
 archives: 
 @table @code
-@item Singular-@value{VERSION}-share.tar.gz 
+@item Singular-@value{VERSION}-share.tgz 
 contains architecture independent data like documentation and libraries
-(alternativly, you may also download 
+(alternatively, you may also download 
 @code{Singular-@value{VERSION}-share.zip}).
-@item Singular-@value{VERSION}-@value{_UNAME}.tar.gz
+@item Singular-@value{VERSION}-@value{_UNAME}.tgz
 contains architecture dependent executables, like the @sc{Singular}
-program
+program.
 @ifclear UNAME
- where @code{@value{_UNAME}} is a description of the processor and operating system
+@code{@value{_UNAME}} is a description of the processor and operating system
 for which @sc{Singular} is compiled (e.g, @code{ix86-Linux}). Please contact us if
-you can not find an appropriate architecture dependent archive
-@end ifclear
-.
+you can not find an appropriate architecture dependent archive.
+@end ifclear
 @end table
 
-You can obtain these files from
-@url{ftp://www.mathematik.uni-kl.de/pub/Math/Singular/}. 
+You can obtain these (and other) archives from
+@display
+@uref{ftp://www.mathematik.uni-kl.de/pub/Math/Singular/}. 
+@end display
 
 @ifclear singularmanual
@@ -82 +85 @@
 Unpack the archives:
 @smallexample
-gzip -dc Singular-@value{VERSION}-@value{_UNAME}.tar.gz | tar -pxf -
-gzip -dc Singular-@value{VERSION}-share.tar.gz | tar -pxf -
+gzip -dc Singular-@value{VERSION}-@value{_UNAME}.tgz | tar -pxf -
+gzip -dc Singular-@value{VERSION}-share.tgz | tar -pxf -
 @end smallexample
 If you have downloaded @code{Singular-@value{VERSION}-share.zip},
@@ -113 +116 @@
 to figure out where its @sc{Singular} libraries and on-line 
 documentation files are.  These constraints on the local directory layout
-are necessary to avoid having to hardcode pathnames into the
+are necessary to avoid having to hard-code pathnames into the
 executables, or require that environment variables be set before
 running the executable. In particular, you should not move or copy
@@ -147 +150 @@
 
 You also might want to adjust your personal start-up files
-(@code{~/.cshrc} for @code{csh}, @code{.tcshrc} for @code{tcsh},
-@code{.profile} for @code{bash}) accordingly, 
+(@code{~/.cshrc} for @code{csh}, @code{~/.tcshrc} for @code{tcsh}, or
+@code{~/.profile} for @code{bash}) accordingly, 
 so that the @code{$PATH} variable is set automatically each time you login.
 
 @strong{IMPORTANT:} Do @emph{never} move or copy the file 
-@code{Singular/@value{VERSION}/@value{_UNAME}/Singular} to another place, but use
-soft-links instead. 
+@code{Singular/@value{VERSION}/@value{_UNAME}/Singular} to another
+place, but use soft-links instead. 
 
 @item
@@ -162 +165 @@
 @item @strong{Feature} @tab @strong{Requires}
 @item running @code{ESingular}, or @code{Singular} within Emacs
-@tab @uref{http://www.fsf.org/software/emacs/emacs.html,Emacs} version
-20 or higher, or, @uref{http://www.xemacs.org,Xemacs} version 20 or
+@tab @uref{http://www.fsf.org/software/emacs/emacs.html,,Emacs} version
+20 or higher, or, @uref{http://www.xemacs.org,,Xemacs} version 20 or
 higher
+
 @item on-line @code{html} help
-@tab @uref{http://www.netscape.com, netscape} browser
+@tab @uref{http://www.netscape.com,,netscape} browser
 @item on-line @code{info} help
-@tab @uref{http://www.texinfo.org, info}, or
-@uref{http://math-www.uni-paderborn.de/~axel/tkinfo/, tkinfo} texinfo browser programs
+@tab @uref{http://www.texinfo.org,,info}, or
+@uref{http://math-www.uni-paderborn.de/~axel/tkinfo/,,tkinfo} texinfo browser programs
 @item TAB completion and history mechanism of ASCII-terminal interface
-@tab shared @uref{ftp://ftp.de.uu.net/pub/gnu/readline/, readline}
+@tab shared @uref{ftp://ftp.de.uu.net/pub/gnu/readline/,,readline}
 library, i.e. @code{/usr/lib/libreadline.so}
-@item visulization of curves and surfaces with @code{surf} (i.e., usage of @sc{Singular} library @code{surf.lib})
+@item visualization of curves and surfaces 
 @tab
-@uref{http://www.mathematik.uni-mainz.de/AlgebraischeGeometrie/surf/surf.shtml,surf}
+@uref{http://www.mathematik.uni-mainz.de/AlgebraischeGeometrie/surf/surf.shtml,,surf}
 version 0.9 or higher (only available for Linux and Solaris).
 @end multitable
 
-Notice that you may also download most of these programs from
+You may download most of these programs from
+@display
 @uref{ftp://www.mathematik.uni-kl.de/pub/Math/Singular/utils/}.
+@end display
 
 @item Customize the on-line help system:
@@ -187 +193 @@
 the @code{netscape} program.
 
-However, this behaviour can be customized in several ways
-using the @sc{Singular} commands @code{system("--allow-net", 1)} and
-@code{system("--browser",<browser>")} (or, by starting up @sc{Singular}
+However, this behavior can be customized in several ways
+using the @sc{Singular} commands @code{system("--browser",<browser>")}
+and @code{system("--allow-net", 1)} (or, by starting up @sc{Singular}
 with the respective command line options).
 
 In particular, creating the file
-@code{Singular/@value{VERSION}/LIB/.singularrc/} and putting the
+@code{Singular/@value{VERSION}/LIB/.singularrc} and putting the
 @sc{Singular} command
 @smallexample
@@ -199 +205 @@
 @end smallexample
 in it, allows the on-line help system to fetch its @code{html} pages
-from @uref{www.mathemtaik.uni-kl.de/~zca/Singular, Singular's WWW home site}
+from @uref{http://www.mathemtaik.uni-kl.de/~zca/Singular, Singular's WWW
+home site} 
 in case its local html pages are not found. That is, you may delete your
 local html pages, after setting this option. 
@@ -230 +237 @@
 @heading Troubleshooting
 
-
-
+@itemize
+@item General: @sc{Singular} can not find its libraries or on-line help
+@enumerate
+@item
+Start up @sc{Singular}, and issue the command @code{system("Singular");}.
+If this does not return the correct and expanded location of the
+@sc{Singular} executable, then you found a bug in @sc{Singular}, which we
+ask you to report (see below).
+@item
+Check whether the directories containing the libraries and on-line help
+files can be found by @sc{Singular}: If @code{$bindir} denotes the
+directory where the @sc{Singular} executable resides, then @sc{Singular}
+looks for library files as follows:    
+@* (0) the current directory     
+@* (1) all dirs of the environment variable SINGULARPATH
+@* (2) @code{$bindir/LIB}
+@* (3) @code{$bindir/../LIB}
+@* (4) @code{/usr/local/Singular/@value{VERSION}/LIB}
+@* (4) @code{/usr/local/Singular/LIB}
+@* The on-line @code{info} files need to be at  @code{$bindir/../info} and the
+@code{html} pages at @code{$bindir/../html}.
+@end enumerate
+
+You can inspect the found library and @code{info}/@code{html}
+directories by starting up @sc{Singular} with the
+@code{--version} option, or by issuing the @sc{Singular} command
+@code{system("--version");}.
+
+@item For @code{HPUX} systems:
+@*The /etc/termcap files which are pre-installed on these systems are
+broken which leads to messages like
+@example
+Name collision between 9826 9836
+@end example
+when @sc{Singular} is started. To fix this, you can get fixed termcap
+files from @uref{ftp://www.mathematik.uni-kl.de/pub/Math/Singular/utils} 
+by downloading the files termcap-<uname-description> and either
+replace your /etc/termcap file by the file found there, or view, and
+redo the respective changes by @code{diff}'ing the downloaded and the
+original file.
+
+@item For @code{ix86-Linux} systems:
+@*Due to some incompatibilities of shared libraries, the start-up of
+@sc{Singular} might fail with messages like
+@example
+  Can not find shared library ...
+@end example
+To fix this, download and install
+@code{Singular-@value{VERSION}-ix86-Linux-static.tgz}.
+
+@item For @code{AIX} systems:
+@*The default @code{info} program of the system is not GNU's texinfo 
+browser which is used to display the on-line documentation in the
+@code{info} format. Therefore, the distribution of the AIX executable
+already contains the @code{info} browser program. 
+If you remove this program, make sure that the GNU
+@code{info} program is executed if you call '@code{info}' from your shell.
+
+@item For any other troubles: 
+@*Please send an email to @email{singular@@mathematik.uni-kl.de}
+and include the header which is displayed by starting up @sc{Singular}
+with the @code{-v} option, and a description of your machine (issue the
+command @code{uname -a} on your shell) in your report.
+@end itemize
+
+
+@heading More information about @sc{Singular}: Comments, Questions, Bug Reports
+More and up-to-date information about @sc{Singular} is always available
+from
+@display
+@uref{http://www.mathematik.uni-kl.de/~zca/Singular}
+@end display
+We very much welcome any comments, questions, and bug reports. Please
+contact us at
+@display
+@email{singular@@mathematik.uni-kl.de}
+@end display
+
+@ifclear singularmanual
+GOOD LUCK and ENJOY!                         
+Your @sc{Singular} team.
+@end ifclear
+

doc/Makefile.in

@@ -2 +2 @@
 ### 
 ### Makefile for Singular documentation 
-### $Id: Makefile.in,v 1.43 1999-11-26 17:45:49 obachman Exp $
+### $Id: Makefile.in,v 1.44 1999-11-29 12:56:07 obachman Exp $
 #####################################################################
 SHELL=/bin/sh
@@ -38 +38 @@
 TEXI2HTML       = @TEXI2HTML@
 DVIPS           = dvips
+
 VERBOSE         = 1 # override this with make VERBOSE=2
-
+SINGUNAME       = @SINGUNAME@
 # d2t stuff
 SINGULAR        = @SINGULAR@
@@ -173 +174 @@
 
 # targets which produce stand-alone documents
+%.${SINGUNAME}.txt : %.texi
+        ${MAKEINFO} -D UNAME --no-header --paragraph-indent none  -o $@ $<
+
 %.txt :  %.texi
         ${MAKEINFO} --no-header --paragraph-indent none -o $@ $<
+
+%.${SINGUNAME}.html : %.texi
+        ${TEXI2HTML} -D UNAME -init_file t2h_standalone.init -verbose -split none -o $@ $<
 
 %.html : %.texi
@@ -242 +249 @@
         ${MKINSTALLDIRS} ${install_docdir}
         ${INSTALL_DATA} singular.idx ${install_docdir}
+
+install-bindist: INSTALL_unix.${SINGUNAME}.txt INSTALL_unix.${SINGUNAME}.html
+        ${MKINSTALLDIRS} ${install_prefix}
+        ${INSTALL_DATA} INSTALL_unix.${SINGUNAME}.txt ${install_prefix}/INSTALL
+        ${INSTALL_DATA} INSTALL_unix.${SINGUNAME}.html ${install_prefix}/INSTALL.html
 
 texi2html = $(TEXI2HTML:%.pl=%)
@@ -266 +278 @@
         /bin/rm -f ${HTML_SUBDIR}/${HTML_MANUAL_TOP} ${HTML_SUBDIR}/${HTML_TUTOR_TOP}
         /bin/rm -rf ${STANDALONE_HTML_FILES} ${STANDALONE_FILES} ${STANDALONE_TXT_FILES}
+        /bin/rm -f INSTALL_unix.${SINGUNAME}.txt INSTALL_unix.${SINGUNAME}.html
 
 distclean: clean

doc/doc2tex.pl

@@ -1 +1 @@
 #!/usr/local/bin/perl
-# $Id: doc2tex.pl,v 1.19 1999-11-24 18:50:40 obachman Exp $
+# $Id: doc2tex.pl,v 1.20 1999-11-29 12:56:07 obachman Exp $
 ###################################################################
 #  Computer Algebra System SINGULAR
@@ -163 +163 @@
 {
   $line++;
-  
   if (/^\@c\s*example/)     {&HandleExample; next;}
   if (/^\@c\s*include\s+/)  {&HandleInclude; next;}
@@ -177 +176 @@
   print TEX $_;
 
+  if (! $printed_header && /^\@c/) 
+  {
+    $printed_header = 1;
+    print TEX <<EOT;
+\@comment This file was generated by doc2tex.pl from $doc_file
+\@comment DO NOT EDIT DIRECTLY, BUT EDIT $doc_file INSTEAD
+EOT
+  }
+
   if (/^\@bye$/)            {last;}
 }
@@ -189 +197 @@
 ######################################################################
 # @c example [error] [no_comp]
-#    -> the text till the next @c example is feed into Singular,
+#    -> the text till the next @c example is fed into Singular,
 #       the text is then substituted by
 #       @c computed example $ex_prefix $doc_file:$line
@@ -265 +273 @@
   if ($reuse && $cache)
   {
+    my $ok = 1;
     print "<$ex_prefix>" if ($verbose);
     print TEX "\@c reused example $ex_prefix $doc_file:$lline \n";
     open(INC, "<$inc_file") || Error("can't open $inc_file for reading: $!\n");
-    while (<INC>){ print TEX $_;}
+    while (<INC>)
+    {
+      if (/error occurred/ && $ok && !error_ok)
+      {
+        Warn("Result file $inc_file contains errors. Force re-computation by removing $inc_file");
+        $ok = 0;
+      }
+      print TEX $_;
+    }
     close(INC);
   }
@@ -580 +597 @@
 }
 
+sub Warn
+{
+  print "$WARNING $_[0]\n";
+}
 #
 # leave this here --otherwise fontification in my emacs gets screwd up