Dear Gap Forum,
The documentation is getting so large that it it is hard to
comprehend. The online help is useful, but does not enable browsing.
I therefore wrote a conversion program from the tex files to EMACS
info format. It's the biggest info file I've ever seen (57 files)!
Directions:
0) Create a directory to hold the info files.
1) Save the shar portion of this message in a file INFO-GAP
in this directory
2) Type "unshar INFO-GAP" (or if you do not have unshar,
change INFO-GAP to executable, and type "INFO-GAP".
3) Read the file README, and make a few changes in "info.pl".
4) Type "info.pl", and wait 30 minutes (or so).
5) Fix up the index, and you're done!
I hope that you find this useful. It is easy to change this to
include new documentation. It's almost, but not quite, automatic.
--
Steve Fisk Department of Mathematics
207-725-3574 Bowdoin College
fisk@bowdoin.edu Brunswick, Me. 04011 USA
#!/bin/sh
# This is a shell archive (produced by shar 3.52.3)
# To extract the files from this archive, save it to a file, remove
# everything above the "!/bin/sh" line above, and type "sh file_name".
#
# made 08/18/1994 13:25 UTC by fisk@bruin.bowdoin.edu
# Source directory /people/faculty/math/fisk/tmp/GAP-texi
#
# existing files will NOT be overwritten unless -c is specified
#
# This shar contains:
# length mode name
# ------ ---------- ------------------------------------------
# 2093 -rw------- README
# 75 -rw-r--r-- GAP-INDEX.texi
# 104 -rw-r--r-- GAP-emacs.el
# 4366 -rw-r--r-- GAP.texi-orig
# 5885 -rwxr--r-- info.pl
#
touch -am 1231235999 $$.touch >/dev/null 2>&1
if test ! -f 1231235999 && test -f $$.touch; then
shar_touch=touch
else
shar_touch=:
echo 'WARNING: not restoring timestamps'
fi
rm -f 1231235999 $$.touch
#
# ============= README ==============
if test -f 'README' && test X"$1" != X"-c"; then
echo 'x - skipping README (File already exists)'
else
echo 'x - extracting README (Text)'
sed 's/^X//' << 'SHAR_EOF' > 'README' &&
Preliminary changes:
X
X I was amazed how well the documentation followed its rules. Creating
X the info file was not hard (although I had to learn perl to do it).
X I only found one syntactic mistake in the info files that needed
X changing: in install.tex, there are many references to |c:\|; these
X should be changed to |c:|. I think that there might also be one
X occurrence of |grp\| there (change it to |grp|, but my notes are
X not clear about that.
X
X
How to create the info files.
X
X 1) make a new directory to hold the info files
X
X 2) copy info.pl, GAP-emacs.el, and GAP-texi.orig to this directory.
X
X 3) edit info.pl - there are two directories that must be specified.
X Also, check if the pathname to perl (first line) is correct.
X
X 4) run info.pl - this takes a while (10 minutes to 30 minutes for me)
X it produces lots of messages!
X
X 5) If all goes well, at the very end you should get the message
X
X
Removing temp files and emacs backups
Making info file `GAP.info' from `GAP.texi'.
/people/faculty/math/fisk/tmp/GAP-texi/algebra.texi:1982:
X This `example' doesn't have a matching `@end example'.
X
X
X (I don't understand this error.)
X
X 6) The result of the computation is:
X
X GAP.info
X GAP.info-1 ... GAP.info-57
X algebra.texi algebra-menu.texi ... (two for each chapter)
X
X All the files except the files GAP.info* can be removed
X if you are satisfied with the outcome.
X
X 6) For some reason, the index file is not correct. For me,
X the index is located in GAP.info-57. Find the two lines
X
X
Command Index
*************
X
X All the menu items have several leading spaces. So, instead of
X
X * Menu:
X
X * AbelianGroup: The Basic Groups Library.
X * AbelianInvariantsNormalClosureFpGroup: Group Functions for Finitely Presented Groups.
X (etc)
X
X you should remove the leading spaces to create
X
X
* Menu:
X
* AbelianGroup: The Basic Groups Library.
* AbelianInvariantsNormalClosureFpGroup: Group Functions for Finitely Presented Groups.
X (etc)
X
X
X 7) With these changes, you should have an info file for GAP!
X
SHAR_EOF
$shar_touch -am 0818092294 'README' &&
chmod 0600 'README' ||
echo 'restore of README failed'
shar_count="`wc -c < 'README'`"
test 2093 -eq "$shar_count" ||
echo "README: original size 2093, current size $shar_count"
fi
# ============= GAP-INDEX.texi ==============
if test -f 'GAP-INDEX.texi' && test X"$1" != X"-c"; then
echo 'x - skipping GAP-INDEX.texi (File already exists)'
else
echo 'x - extracting GAP-INDEX.texi (Text)'
sed 's/^X//' << 'SHAR_EOF' > 'GAP-INDEX.texi' &&
@node Command Index, , weyl, Top
@chapter Command Index
X
@printindex cm
X
SHAR_EOF
$shar_touch -am 0818090894 'GAP-INDEX.texi' &&
chmod 0644 'GAP-INDEX.texi' ||
echo 'restore of GAP-INDEX.texi failed'
shar_count="`wc -c < 'GAP-INDEX.texi'`"
test 75 -eq "$shar_count" ||
echo "GAP-INDEX.texi: original size 75, current size $shar_count"
fi
# ============= GAP-emacs.el ==============
if test -f 'GAP-emacs.el' && test X"$1" != X"-c"; then
echo 'x - skipping GAP-emacs.el (File already exists)'
else
echo 'x - extracting GAP-emacs.el (Text)'
sed 's/^X//' << 'SHAR_EOF' > 'GAP-emacs.el' &&
(load-library "texnfo-upd")
(texinfo-multiple-files-update "GAP.texi" t t)
(save-buffers-kill-emacs t)
SHAR_EOF
$shar_touch -am 0729104094 'GAP-emacs.el' &&
chmod 0644 'GAP-emacs.el' ||
echo 'restore of GAP-emacs.el failed'
shar_count="`wc -c < 'GAP-emacs.el'`"
test 104 -eq "$shar_count" ||
echo "GAP-emacs.el: original size 104, current size $shar_count"
fi
# ============= GAP.texi-orig ==============
if test -f 'GAP.texi-orig' && test X"$1" != X"-c"; then
echo 'x - skipping GAP.texi-orig (File already exists)'
else
echo 'x - extracting GAP.texi-orig (Text)'
sed 's/^X//' << 'SHAR_EOF' > 'GAP.texi-orig' &&
\input texinfo @c -*- texinfo -*-
@c %**start of header
@setfilename GAP.info
@settitle GAP @value{version}
@c make a command index:
@defcodeindex cm
@c %**end of header
X
@set version 1.5
@set update-date 2 Feb 1994
@set update-month Feb 1994
X
@clear smallbook
X
@c Play with some whitespace settings:
@tex
\global\chapheadingskip = 15pt plus 4pt minus 2pt
\global\secheadingskip = 12pt plus 3pt minus 2pt
\global\subsecheadingskip = 9pt plus 2pt minus 2pt
@end tex
X
@c Use smaller whitespace between paragraphs in the 8.5x11 format:
@ifclear smallbook
@tex
\global\parskip 6pt plus 1pt
@end tex
@end ifclear
X
@finalout
X
@ifinfo
X
@end ifinfo
X
@setchapternewpage odd
@titlepage
@title GAP
X
X
@c The following two commands start the copyright page.
@c Put it inside the titlepage to turn off headings:
@page
@vskip 0pt plus 1filll
X
@end titlepage
X
@node Top, aboutgap, (dir), (dir)
@top GAP
X
@menu
* aboutgap::About GAP
* language::The Programming Language
* environm::Environment
* domain::Domains
* ring::Rings
* field::Fields
* group::Groups
* operatio::Operations of Groups
* vecspace::Vector Spaces
* integer::Integers
* numtheor::Number Theory
* rational::Rationals
* cyclotom::Cyclotomics
* gaussian::Gaussians
* numfield::Subfields of Cyclotomic Fields
* unknown::Unknowns
* finfield::Finite Fields
* polynom::Polynomials
* permutat::Permutations
* permgrp::Permutation Groups
* word::Words in Abstract Generators
* fpgrp::Finitely Presented Groups
* agwords::Words in Finite Polycyclic Groups
* aggroup::Finite Polycyclic Groups
* saggroup::Special Ag Groups
* list::Lists
* set::Sets
* blister::Boolean Lists
* string::Strings and Characters
* range::Ranges
* vector::Vectors
* rowspace::Row Spaces
* matrix::Matrices
* matring::Matrix Rings
* matgrp::Matrix Groups
* grplib::Group Libraries
* algebra::Algebras
* algfp::Finitely Presented Algebras
* algmat::Matrix Algebras
* module::Modules
* mapping::Mappings
* homomorp::Homomorphisms
* boolean::Booleans
* record::Records
* combinat::Combinatorics
* tom::Tables of Marks
* chartabl::Character Tables
* gentable::Generic Character Tables
* characte::Characters
* paramaps::Maps and Parametrized Maps
* gettable::Character Table Libraries
* classfun::Class Functions
* monomial::Monomiality Questions
* install::Getting and Installing GAP
* share::Share Libraries
* anupq::ANU Pq
* grape::Grape
* mtx::The MeatAxe
* sisyphos::Sisyphos
* smash::Smash, Matrix Groups and $G$-Modules
* ve::Vector Enumeration
* weyl::Weyl Groups and Hecke Algebras
* aboutgap::About GAP
* language::The Programming Language
* environm::Environment
* domain::Domains
* ring::Rings
* field::Fields
* group::Groups
* operatio::Operations of Groups
* vecspace::Vector Spaces
* integer::Integers
* numtheor::Number Theory
* rational::Rationals
* cyclotom::Cyclotomics
* gaussian::Gaussians
* numfield::Subfields of Cyclotomic Fields
* unknown::Unknowns
* finfield::Finite Fields
* polynom::Polynomials
* permutat::Permutations
* permgrp::Permutation Groups
* word::Words in Abstract Generators
* fpgrp::Finitely Presented Groups
* agwords::Words in Finite Polycyclic Groups
* aggroup::Finite Polycyclic Groups
* saggroup::Special Ag Groups
* list::Lists
* set::Sets
* blister::Boolean Lists
* string::Strings and Characters
* range::Ranges
* vector::Vectors
* rowspace::Row Spaces
* matrix::Matrices
* matring::Matrix Rings
* matgrp::Matrix Groups
* grplib::Group Libraries
* algebra::Algebras
* algfp::Finitely Presented Algebras
* algmat::Matrix Algebras
* module::Modules
* mapping::Mappings
* homomorp::Homomorphisms
* boolean::Booleans
* record::Records
* combinat::Combinatorics
* tom::Tables of Marks
* chartabl::Character Tables
* gentable::Generic Character Tables
* characte::Characters
* paramaps::Maps and Parametrized Maps
* gettable::Character Table Libraries
* classfun::Class Functions
* monomial::Monomiality Questions
* install::Getting and Installing GAP
* share::Share Libraries
* anupq::ANU Pq
* grape::Grape
* mtx::The MeatAxe
* sisyphos::Sisyphos
* smash::Smash, Matrix Groups and $G$-Modules
* ve::Vector Enumeration
* weyl::Weyl Groups and Hecke Algebras
* Comamnd Index::Index of Commands
@end menu
X
XXXXXXinclude-hereXXXXX
X
@page
X
@include GAP-INDEX.texi
X
@contents
@bye
X
X
X
SHAR_EOF
$shar_touch -am 0817154294 'GAP.texi-orig' &&
chmod 0644 'GAP.texi-orig' ||
echo 'restore of GAP.texi-orig failed'
shar_count="`wc -c < 'GAP.texi-orig'`"
test 4366 -eq "$shar_count" ||
echo "GAP.texi-orig: original size 4366, current size $shar_count"
fi
# ============= info.pl ==============
if test -f 'info.pl' && test X"$1" != X"-c"; then
echo 'x - skipping info.pl (File already exists)'
else
echo 'x - extracting info.pl (Text)'
sed 's/^X//' << 'SHAR_EOF' > 'info.pl' &&
#!/usr/local/bin/perl
X
# An overview of the files
X
# Original Files
X
# GAP-emacs.el Used to update all the nodes in the texinfo file
# GAP.texi-orig Skeleton used to create main texinfo file
# GAP-INDEX.texi Read in to input the index
X
# Created Files
X
# GAPinclude.texi List of texinfo files to be included; it is
# inserted into GAP.texi-orig to make GAP.texi
# GAP.texi main texinfo file
# ?.texi one file for each chapter
# GAPmainmenu.texi If you want, you could replace (by hand!) the
# menu in GAP.texi by this one -
# it has the section names
X
#
# Set the following to the GAP home directory
#
X
$GAPdir = "/people/faculty/math/fisk/usr/local/src/gap3r4p0";
X
#
# Where the info files should be (and the file GAP.info is)
#
X
$GAPinfodir = "/people/faculty/math/fisk/tmp/GAP-texi";
X
###############################################################
#
# Nothing more to change
#
###############################################################
X
#
# test to see that the files and directories are there
#
X
chdir($GAPinfodir) || die("please make the info directory\n");
$tmpfile = $GAPinfodir . "/TEMP";
X
if (!(-e "GAP.texi-orig")) {die("file GAP.texi-orig not found")};
if (!(-e "GAP-emacs.el")) {die("file GAP-emacs.el not found")};
if (!(-w $GAPdir)) {die("directory for GAP not writable")};
X
X
#
# files included in top info file
#
X
open(GAPinclude, ">GAPinclude.texi");
open(GAPmainmenu, ">GAPmainmenu.texi");
open(GAPtexinfo, ">GAP.texi");
open(GAPtexinfoXX, "GAP.texi-orig");
X
#
# the list of all chapters, in order from manual.tex
#
X
@GAPlist = ("aboutgap","language","environm", "domain", "ring", "field",
"group","operatio","vecspace","integer","numtheor","rational","cyclotom",
"gaussian","numfield","unknown","finfield","polynom","permutat","permgrp",
"word","fpgrp","agwords","aggroup","saggroup","list","set","blister","string",
"range","vector","rowspace","matrix","matring","matgrp","grplib","algebra",
"algfp","algmat","module","mapping","homomorp","boolean","record","combinat",
"tom","chartabl","gentable","characte","paramaps","gettable","classfun",
"monomial","install","share","anupq","grape","mtx","sisyphos","smash","ve",
"weyl");
X
#@GAPlist = ("aboutgap","language");
#@GAPlist = ("install");
X
#
# convert each chapter
#
X
foreach $GAPchapter (@GAPlist) {
X
X
X $current = $GAPdir . "/doc/" . $GAPchapter . ".tex";
X $texinfo = $GAPinfodir . "/" . $GAPchapter . ".texi";
X $texmenu = $GAPinfodir . "/" . $GAPchapter . "-menu.texi";
X
X $parity_of_bar = 0; # reset at beginning of each chapter
X
X print "Processing $current\n";
X print GAPinclude "@include $texinfo\n";
X
X open(GAPfile,$current) || die "can't open $current";
X open(GAPtexi, ">" . $texinfo) || die("can't open $texinfo\n");
X open(GAPmenu, ">" . $texmenu) || die("can't open $texmenu\n");
X
X
X
X Main:
X while(<GAPfile>) {
X chop($_);
X $name = $_;
#
# skip comments
#
X if(substr($_,0,1) eq "%") {
X next Main;
X }
X
X s/@/@@/g; # fix @'s
X s/\\\\{}/@*/g; # break lines
X s/\\\\/@*/g;
X s/\\vspace{[\d\w]*}//g; # no vspace
X s/\\index{(\w*)}/\n@cmindex \1 \n/g; # fix index
X s/\\index{(\w*!\w*)}/\n@cmindex \1 \n/g;
X s/{/ @{/g; # protect { and }
X s/}/ @}/g;
X
#
# worry about literals
#
X s/\|\\\|/BARSLASHBAR/g;
X s/\\\|/BBAARR/g; # temporarily change literal bars
X $number_of_bars=0; # count bars (page 155, perl book)
X $pos = 0;
X while (( $pos = index($_,"|",$pos)) >= 0) {
X $pos++;
X $number_of_bars++;
X }
#
# skip if an even number of bars
#
X if( ($number_of_bars % 2) == 1) {
X $parity_of_bar = 1 - $parity_of_bar;
X if($parity_of_bar == 1)
X {s/\|/\n@example\n/;}
X else
X {s/\|/\n@end example\n/;}
X };
X s/BBAARR/\\\|/g; # restore literal bars
X s/BARSLASHBAR/\|\\\|/g;
#
# Write
#
X $writeout = 1;
X if(/\\Chapter|\\Section/) {
X $writeout = 0;
X $name =~ s/\\Chapter{//g;
X $name =~ s/\\Section{//g;
X $name =~ s/}//g;
X $name =~ s/}//g;
X $name =~ s/%//g;
X $name =~ s/\\index.*//g;
X };
X if(/\\Chapter/) {
X print GAPmenu "@node $GAPchapter,Top,Top,Top\n";
X print GAPmenu "@chapter $name\n";
X print GAPmenu "@menu \n";
X print GAPmainmenu "* $GAPchapter::$name \n";
X };
X if(/\\Section/){
X print GAPtexi "@node $name\n";
X print GAPtexi "@section $name\n";
X print GAPmenu "* $name:: \n";
X };
X if($writeout == 1) { # write out
X print GAPtexi "$_\n";
X };
X }
X
#
# Close files
#
X print GAPmenu "@end menu \n";
X close(GAPfile);
X close(GAPtexi);
X close(GAPmenu);
X
#
# copy the menu to the beginning of the file, and then remove it
#
X system("mv $texinfo $tmpfile");
X system("cat $texmenu $tmpfile > $texinfo");
# unlink($texmenu);
}
X
X
X
X
X
#
# copy the include files to the main texinfo file
#
X
close(GAPinclude);
open(GAPinclude, "GAPinclude.texi");
X
while(<GAPtexinfoXX>) {
X if(index($_,"XXXXXinclude-hereXXXXX") == -1){
X print GAPtexinfo;
} else {
X while(<GAPinclude>) {
X print GAPtexinfo;
X }
}}
X
close(GAPtexinfo);
X
X
#
# update the new texinfo file
#
X
X print " updating nodes - this takes a long time \n";
X system("emacs -batch -q -l GAP-emacs.el ");
X
X
#
# all done - remove temp file and backups created by emacs
#
X
print "\nRemoving temp files and emacs backups\n";
close(GAPmainmenu);
unlink($tmpfile);
X
foreach $GAPchapter (@GAPlist) {
X $texinfo_back = $GAPinfodir . "/" . $GAPchapter . ".texi~";
X unlink($texinfo_back);
}
X
X
#
# run makeinfo and create the info files
#
X
X
system("makeinfo GAP.texi");
X
X
X
X
SHAR_EOF
$shar_touch -am 0817145794 'info.pl' &&
chmod 0744 'info.pl' ||
echo 'restore of info.pl failed'
shar_count="`wc -c < 'info.pl'`"
test 5885 -eq "$shar_count" ||
echo "info.pl: original size 5885, current size $shar_count"
fi
exit 0