diff --git a/LDP/migration-2016/faqmigration.py b/LDP/migration-2016/faqmigration.py
new file mode 100644
index 00000000..ad68c0e5
--- /dev/null
+++ b/LDP/migration-2016/faqmigration.py
@@ -0,0 +1,173 @@
+#! /usr/bin/python
+#
+# -- migrate to the new naming scheme
+
+from __future__ import absolute_import, division, print_function
+
+import os
+import sys
+import time
+import errno
+import shutil
+import logging
+import functools
+
+logformat = '%(levelname)-9s %(name)s %(filename)s#%(lineno)s ' \
+ + '%(funcName)s %(message)s'
+logging.basicConfig(stream=sys.stderr, format=logformat, level=logging.DEBUG)
+logger = logging.getLogger(__name__)
+
+# -- short names
+#
+opa = os.path.abspath
+opb = os.path.basename
+opd = os.path.dirname
+opj = os.path.join
+opn = os.path.normpath
+opr = os.path.relpath
+ops = os.path.split
+
+faqdocs = '''Ftape-FAQ
+Linux-RAID-FAQ
+LDP-FAQ
+AfterStep-FAQ'''.split()
+
+
+def validate_args(argv):
+ if len(argv) == 4:
+ for d in argv[:3]:
+ if not os.path.isdir(d):
+ return False
+ return True
+ return False
+
+
+def collect_published_stems(dirbase):
+ d = dict()
+ for stem in os.listdir(dirbase):
+ if not os.path.isdir(opj(dirbase, stem)):
+ continue
+ d[stem] = stem
+ return d
+
+
+def make_refresh(target, title, delay=0):
+ text = '''
+
+ {1}: {0}
+
+
+
+
This page has moved permanently to
+ {0}.
+ Update your bookmarks if you wish. The compatibility
+ redirect will remain through, at least, early 2017.
+
+
+
+'''
+ return text.format(target, title, delay)
+
+def swapfiles(a, b):
+ '''use os.rename() to make "a" become "b"'''
+ if not os.path.isfile(a):
+ raise OSError(errno.ENOENT, os.strerror(errno.ENOENT), a)
+ tf = None
+ if os.path.exists(b):
+ _, tf = mkstemp(prefix='swapfile-', dir=opd(opa(a)))
+ logger.debug("Created tempfile %s.", tf)
+ logger.debug("About to rename %s to %s.", b, tf)
+ os.rename(b, tf)
+ logger.debug("About to rename %s to %s.", a, b)
+ os.rename(a, b)
+ if tf:
+ logger.debug("About to rename %s to %s.", tf, a)
+ os.rename(tf, a)
+ logger.debug("About to remove %s.", tf)
+ os.rmdir(tf)
+
+
+def create_symlink(source, target):
+ assert not os.path.exists(target)
+ targetdir = os.path.dirname(target)
+ if not os.path.isdir(targetdir):
+ logger.debug("Creating directory %s", targetdir)
+ os.makedirs(targetdir)
+ logger.debug("Creating symlink %s, pointing to %s", target, source)
+ os.symlink(os.path.relpath(source, start=targetdir), target)
+
+
+def create_refresh_meta_equiv(fname, url, stem, **kwargs):
+ assert not os.path.exists(fname)
+ targetdir = os.path.dirname(fname)
+ if not os.path.isdir(targetdir):
+ logger.debug("Creating directory %s", targetdir)
+ os.makedirs(targetdir)
+ logger.debug("Creating file %s, with redirect to %s", fname, url)
+ with open(fname, 'w') as f:
+ f.write(make_refresh(url, stem, **kwargs))
+
+
+def newhtmlfilename(pubdir, stem, fname):
+ sought = opj(pubdir, stem, fname)
+ if not os.path.isfile(sought):
+ return opj(pubdir, stem, 'index.html')
+ return sought
+
+
+def faqs(stems, faqpath, faqcompat, pubdir, urlbase):
+
+ for stem in faqdocs:
+ if stem not in stems:
+ logger.critical("Stem %s not found in %s.", stem, pubdir)
+ sys.exit(1)
+
+ # -- PDF handling
+ newpdf = opj(pubdir, stem, stem + '.pdf')
+ oldpdf = opj(faqcompat, 'pdf', stem + '.pdf')
+ if os.path.exists(oldpdf):
+ assert os.path.exists(oldpdf)
+ assert os.path.exists(newpdf)
+ os.rename(oldpdf, oldpdf + '.' + str(int(time.time())))
+ create_symlink(newpdf, oldpdf)
+
+ # -- HTML handling
+ htmldir = opj(faqcompat, stem)
+ if os.path.isdir(htmldir):
+ # -- LDP-FAQ and Linux-RAID-FAQ
+ for fn in os.listdir(htmldir):
+ if not fn.endswith('.html'):
+ continue
+ pubpath = newhtmlfilename(pubdir, stem, fn)
+ url = pubpath.replace(pubdir, urlbase)
+ fullname = opj(htmldir, fn)
+ os.rename(fullname, fullname + '.' + str(int(time.time())))
+ create_refresh_meta_equiv(fullname, url, stem, delay=2)
+ else:
+ # -- AfterStep-FAQ and Ftape-FAQ
+ htmldir = faqcompat
+ for fn in os.listdir(htmldir):
+ if not fn.startswith(stem):
+ continue
+ pubpath = newhtmlfilename(pubdir, stem, fn)
+ url = pubpath.replace(pubdir, urlbase)
+ fullname = opj(htmldir, fn)
+ os.rename(fullname, fullname + '.' + str(int(time.time())))
+ create_refresh_meta_equiv(fullname, url, stem, delay=2)
+
+
+def main(fin, fout, argv):
+ me = os.path.basename(sys.argv[0])
+ usage = "usage: %s " % (me,)
+ if not validate_args(argv):
+ return usage
+ faqpath, faqcompat, pubdir, urlbase = argv
+ stems = collect_published_stems(pubdir)
+ faqs(stems, faqpath, faqcompat, pubdir, urlbase)
+ return os.EX_OK
+
+
+if __name__ == '__main__':
+ sys.exit(main(sys.stdin, sys.stdout, sys.argv[1:]))
+
+# -- end of file
diff --git a/LDP/migration-2016/golive.sh b/LDP/migration-2016/golive.sh
new file mode 100644
index 00000000..87702c4a
--- /dev/null
+++ b/LDP/migration-2016/golive.sh
@@ -0,0 +1,52 @@
+#! /bin/bash
+
+set -e
+set -x
+
+squawk () { printf >&2 "%s\n" "$@"; }
+abort () { squawk "$@" ; exit 1; }
+
+SELFNAME="$( readlink --canonicalize ${0})"
+ME="${SELFNAME##*/}" # -- basename
+HERE="${SELFNAME%/*}" # -- dirname
+
+# -- SET THIS VARIABLE to the full path of the LDP content
+#
+CONTENTROOT=/home/mabrown/wip/tldp/website/html
+
+# -- trailing slash, atypically included on PUBDIR, here
+PUBDIR="${CONTENTROOT}/en/"
+
+cd "$CONTENTROOT"
+
+READY=yes
+for D in REF FAQ LDP HOWTO; do
+ if ! test -d "${D}"; then
+ squawk "Could not find directory ${D}."
+ READY=no
+ fi
+ if ! test -d "${D}.compat"; then
+ squawk "Could not find directory ${D}.compat."
+ READY=no
+ fi
+done
+
+if test "$READY" != "yes"; then
+ abort "Cowardly, refusing to throw the switch."
+fi
+
+for D in REF FAQ LDP HOWTO; do
+
+ squawk "Activating new ${D}."
+
+ mv -v "${D}" "old.${D}" && mv -v "${D}.compat" "${D}"
+
+ squawk "Activated new ${D}."
+
+done
+
+squawk "Done. Success."
+
+exit 0
+
+# -- end of file
diff --git a/LDP/migration-2016/guidemigration.py b/LDP/migration-2016/guidemigration.py
new file mode 100644
index 00000000..2dced884
--- /dev/null
+++ b/LDP/migration-2016/guidemigration.py
@@ -0,0 +1,213 @@
+#! /usr/bin/python
+#
+# -- migrate to the new naming scheme
+
+from __future__ import absolute_import, division, print_function
+
+import os
+import sys
+import time
+import errno
+import shutil
+import logging
+import functools
+
+logformat = '%(levelname)-9s %(name)s %(filename)s#%(lineno)s ' \
+ + '%(funcName)s %(message)s'
+logging.basicConfig(stream=sys.stderr, format=logformat, level=logging.DEBUG)
+logger = logging.getLogger(__name__)
+
+# -- short names
+#
+opa = os.path.abspath
+opb = os.path.basename
+opd = os.path.dirname
+opj = os.path.join
+opn = os.path.normpath
+opr = os.path.relpath
+ops = os.path.split
+
+
+# -- Stem handling for HTML
+
+predictably_named_guides = '''Bash-Beginners-Guide
+cpg
+espk-ug
+EVMSUG
+GNU-Linux-Tools-Summary
+LDP-Author-Guide
+Linux-Dictionary
+Linux-Filesystem-Hierarchy
+Linux-Media-Guide
+Mobile-Guide
+Pocket-Linux-Guide
+sag'''.split()
+
+stems = dict(zip(predictably_named_guides, predictably_named_guides))
+
+# -- no "html" subdirectory
+#
+stems['lki'] = 'lki'
+stems['nag2'] = 'nag2'
+
+# -- two kernel versions, same name (in days of yore)
+#
+stems['lkmpg/2.4'] = 'lkmpg-2.4'
+stems['lkmpg/2.6'] = 'lkmpg-2.6'
+
+# -- wacky path naming
+#
+stems['lame/LAME/linux-admin-made-easy'] = 'lame'
+stems['solrhe/Securing-Optimizing-Linux-RH-Edition-v1.3'] = 'solrhe'
+
+# -- name changers
+#
+stems['abs'] = 'abs-guide'
+stems['intro-linux'] = 'Intro-Linux'
+
+
+# -- PDF handling
+
+pdflist = '''Bash-Beginners-Guide/Bash-Beginners-Guide.pdf
+EVMSUG/EVMSUG.pdf
+GNU-Linux-Tools-Summary/GNU-Linux-Tools-Summary.pdf
+LDP-Author-Guide/LDP-Author-Guide.pdf
+Linux-Dictionary/Linux-Dictionary.pdf
+Linux-Filesystem-Hierarchy/Linux-Filesystem-Hierarchy.pdf
+Linux-Media-Guide/Linux-Media-Guide.pdf
+Mobile-Guide/Mobile-Guide.pdf
+Pocket-Linux-Guide/Pocket-Linux-Guide.pdf
+cpg/Custom-Porting-Guide.pdf
+espk-ug/espk-ug.pdf
+lame/lame.pdf
+lki/lki.pdf
+nag2/nag2.pdf
+sag/sag.pdf
+solrhe/Securing-Optimizing-Linux-RH-Edition-v1.3.pdf'''.split()
+
+extrapdfs = dict()
+extrapdfs['lkmpg/2.4/lkmpg.pdf'] = 'lkmpg-2.4'
+extrapdfs['lkmpg/2.6/lkmpg.pdf'] = 'lkmpg-2.6'
+extrapdfs['abs/abs-guide.pdf'] = 'abs-guide'
+extrapdfs['intro-linux/intro-linux.pdf'] = 'Intro-Linux'
+
+def validate_args(argv):
+ if len(argv) == 4:
+ for d in argv[:3]:
+ if not os.path.isdir(d):
+ return False
+ return True
+ return False
+
+
+def make_refresh(target, title, delay=0):
+ text = '''
+
+ {1}: {0}
+
+
+
+
This page has moved permanently to
+ {0}.
+ Update your bookmarks if you wish. The compatibility
+ redirect will remain through, at least, early 2017.
+
+
+
+'''
+ return text.format(target, title, delay)
+
+def swapfiles(a, b):
+ '''use os.rename() to make "a" become "b"'''
+ if not os.path.isfile(a):
+ raise OSError(errno.ENOENT, os.strerror(errno.ENOENT), a)
+ tf = None
+ if os.path.exists(b):
+ _, tf = mkstemp(prefix='swapfile-', dir=opd(opa(a)))
+ logger.debug("Created tempfile %s.", tf)
+ logger.debug("About to rename %s to %s.", b, tf)
+ os.rename(b, tf)
+ logger.debug("About to rename %s to %s.", a, b)
+ os.rename(a, b)
+ if tf:
+ logger.debug("About to rename %s to %s.", tf, a)
+ os.rename(tf, a)
+ logger.debug("About to remove %s.", tf)
+ os.rmdir(tf)
+
+
+def create_symlink(source, target):
+ assert not os.path.exists(target)
+ targetdir = os.path.dirname(target)
+ if not os.path.isdir(targetdir):
+ logger.debug("Creating directory %s", targetdir)
+ os.makedirs(targetdir)
+ logger.debug("Creating symlink %s, pointing to %s", target, source)
+ os.symlink(os.path.relpath(source, start=targetdir), target)
+
+
+def create_refresh_meta_equiv(fname, url, stem, **kwargs):
+ assert not os.path.exists(fname)
+ targetdir = os.path.dirname(fname)
+ if not os.path.isdir(targetdir):
+ logger.debug("Creating directory %s", targetdir)
+ os.makedirs(targetdir)
+ logger.debug("Creating file %s, with redirect to %s", fname, url)
+ with open(fname, 'w') as f:
+ f.write(make_refresh(url, stem, **kwargs))
+
+
+def newhtmlfilename(pubdir, stem, fname):
+ sought = opj(pubdir, stem, fname)
+ if not os.path.isfile(sought):
+ return opj(pubdir, stem, 'index.html')
+ return sought
+
+def guides(stems, guidepath, guidecompat, pubdir, urlbase):
+
+ for pdf in pdflist:
+ stem, _ = os.path.split(pdf)
+ oldpdf = opj(guidecompat, pdf)
+ newpdf = opj(pubdir, stem, stem + '.pdf')
+ assert os.path.exists(oldpdf)
+ assert os.path.exists(newpdf)
+ os.rename(oldpdf, oldpdf + '.' + str(int(time.time())))
+ create_symlink(newpdf, oldpdf)
+
+ for pdf, stem in extrapdfs.items():
+ oldpdf = opj(guidecompat, pdf)
+ newpdf = opj(pubdir, stem, stem + '.pdf')
+ assert os.path.exists(oldpdf)
+ assert os.path.exists(newpdf)
+ os.rename(oldpdf, oldpdf + '.' + str(int(time.time())))
+ create_symlink(newpdf, oldpdf)
+
+ for stem, newstem in sorted(stems.items(), key=lambda x: x[1].lower()):
+ htmldir = opj(guidecompat, stem, 'html')
+ if not os.path.isdir(htmldir):
+ htmldir, _ = os.path.split(htmldir)
+ assert os.path.exists(htmldir)
+ for fn in os.listdir(htmldir):
+ if not fn.endswith('.html'):
+ continue
+ pubpath = newhtmlfilename(pubdir, newstem, fn)
+ url = pubpath.replace(pubdir, urlbase)
+ fullname = opj(htmldir, fn)
+ os.rename(fullname, fullname + '.' + str(int(time.time())))
+ create_refresh_meta_equiv(fullname, url, newstem, delay=2)
+
+
+def main(fin, fout, argv):
+ me = os.path.basename(sys.argv[0])
+ usage = "usage: %s " % (me,)
+ if not validate_args(argv):
+ return usage
+ guidepath, guidecompat, pubdir, urlbase = argv
+ guides(stems, guidepath, guidecompat, pubdir, urlbase)
+ return os.EX_OK
+
+
+if __name__ == '__main__':
+ sys.exit(main(sys.stdin, sys.stdout, sys.argv[1:]))
+
+# -- end of file
diff --git a/LDP/migration-2016/howtomigration.py b/LDP/migration-2016/howtomigration.py
new file mode 100644
index 00000000..ab2a24d5
--- /dev/null
+++ b/LDP/migration-2016/howtomigration.py
@@ -0,0 +1,313 @@
+#! /usr/bin/python
+#
+# -- migrate to the new naming scheme
+
+from __future__ import absolute_import, division, print_function
+
+import os
+import sys
+import errno
+import shutil
+import logging
+import functools
+
+logformat = '%(levelname)-9s %(name)s %(filename)s#%(lineno)s ' \
+ + '%(funcName)s %(message)s'
+logging.basicConfig(stream=sys.stderr, format=logformat, level=logging.DEBUG)
+logger = logging.getLogger(__name__)
+
+# -- short names
+#
+opa = os.path.abspath
+opb = os.path.basename
+opd = os.path.dirname
+opj = os.path.join
+opn = os.path.normpath
+opr = os.path.relpath
+ops = os.path.split
+
+SKIP = object()
+
+
+def add_renamed_stems(stems):
+ stems['ppp-ssh'] = 'VPN-PPP-SSH-HOWTO'
+ stems['intro-linux'] = 'Intro-Linux'
+ stems['DPT-Hardware-RAID'] = 'DPT-Hardware-RAID-HOWTO'
+ stems['Loadlin+Win95'] = 'Loadlin+Win95-98-ME'
+ stems['Laptop-HOWTO'] = 'Mobile-Guide'
+ stems['IR-HOWTO'] = 'Infrared-HOWTO'
+ stems['Xnews-under-Linux-HOWTO'] = 'Windows-Newsreaders-under-Linux-HOWTO'
+ stems['Access-HOWTO'] = 'Accessibility-HOWTO'
+ stems['Adv-Bash-Scr-HOWTO'] = 'abs-guide'
+ stems['abs'] = 'abs-guide'
+ stems['Mosix-HOWTO'] = 'openMosix-HOWTO'
+ stems['Partition-Rescue-New'] = 'Partition-Rescue'
+ stems['Partition-Mass-Storage-Dummies-Linux-HOWTO'] = 'Partition-Mass-Storage-Definitions-Naming-HOWTO'
+
+
+def add_skipped_stems(stems):
+ stems['index.html'] = SKIP
+ stems['INDEX'] = SKIP
+ stems['README'] = SKIP
+ stems['COPYRIGHT'] = SKIP
+ stems['.htaccess'] = SKIP
+ stems['GCC-HOWTO'] = SKIP
+ stems['Netscape+Proxy'] = SKIP
+ stems['Sendmail+UUCP'] = SKIP
+ stems['GTEK-BBS-550'] = SKIP
+ stems['Consultants-HOWTO'] = SKIP
+ stems['Acer-Laptop-HOWTO'] = SKIP
+ stems['Linux-From-Scratch-HOWTO'] = SKIP
+ stems['Distributions-HOWTO'] = SKIP
+ stems['MIPS-HOWTO'] = SKIP
+ stems['3Dfx-HOWTO'] = SKIP
+ stems['PostgreSQL-HOWTO'] = SKIP
+ stems['Term-Firewall'] = SKIP
+ stems['WikiText-HOWTO'] = SKIP
+ stems['HOWTO-INDEX'] = SKIP
+ stems['HOWTO-HOWTO'] = SKIP
+ stems['Security-Quickstart-Redhat-HOWTO'] = SKIP
+
+
+def collect_published_stems(dirbase):
+ d = dict()
+ for stem in os.listdir(dirbase):
+ if not os.path.isdir(opj(dirbase, stem)):
+ continue
+ d[stem] = stem
+ add_renamed_stems(d)
+ add_skipped_stems(d)
+ return d
+
+
+def validate_args(argv):
+ if len(argv) == 4:
+ for d in argv[:3]:
+ if not os.path.isdir(d):
+ return False
+ return True
+ return False
+
+
+def walk_simple(stems, dirbase, root):
+ for name in os.listdir(dirbase):
+ if name.endswith('.pdf'):
+ stem, _ = os.path.splitext(name)
+ else:
+ stem = name
+ relpath = opr(opj(dirbase, name), start=root)
+ newstem = stems.get(stem, None)
+ if newstem is None:
+ logger.error("%s missing stem: %s", stem, relpath)
+ continue
+ elif newstem is SKIP:
+ logger.info("%s ignoring stem: %s", stem, relpath)
+ continue
+ yield newstem, relpath
+
+
+def walk_html_single(stems, dirbase, root):
+ for name in os.listdir(dirbase):
+ if name == 'images':
+ continue
+ dirname = opj(dirbase, name)
+ if not os.path.isdir(dirname):
+ continue
+ indexhtml = opj(dirname, 'index.html')
+ if not os.path.isfile(indexhtml):
+ logger.error("%s missing index.html: %s", stem, indexhtml)
+ stem = name
+ relpath = opr(indexhtml, start=root)
+ newstem = stems.get(stem, None)
+ if newstem is None:
+ logger.error("%s missing stem: %s", stem, relpath)
+ continue
+ elif newstem is SKIP:
+ logger.info("%s ignoring stem: %s", stem, relpath)
+ continue
+ yield newstem, relpath
+
+
+def walk_html_chunked_dirs(stems, dirbase, root):
+ for name in os.listdir(dirbase):
+ if name in ('images', 'pdf', 'text', 'html_single', 'archived'):
+ continue
+ dirname = opj(dirbase, name)
+ if not os.path.isdir(dirname):
+ continue
+ for subname in os.listdir(dirname):
+ fname = opj(dirname, subname)
+ if os.path.isdir(fname):
+ continue
+ stem = name
+ relpath = opr(fname, start=root)
+ newstem = stems.get(stem, None)
+ if newstem is None:
+ logger.error("%s missing stem: %s", stem, relpath)
+ continue
+ elif newstem is SKIP:
+ logger.info("%s ignoring stem: %s", stem, relpath)
+ continue
+ yield newstem, relpath
+
+
+def walk_html_chunked_files(stems, dirbase, root):
+ for name in os.listdir(dirbase):
+ fname = opj(dirbase, name)
+ if not os.path.isfile(fname):
+ continue
+ stem, ext = os.path.splitext(name)
+ if stem == 'index' or ext != '.html':
+ continue
+ if stem not in stems:
+ stem = '-'.join(stem.split('-')[:-1])
+ if stem not in stems:
+ logger.error("Could not determine stem for %s", fname)
+ continue
+ relpath = opr(fname, start=root)
+ newstem = stems.get(stem, None)
+ if newstem is None:
+ logger.error("%s missing stem: %s", stem, relpath)
+ continue
+ elif newstem is SKIP:
+ logger.info("%s ignoring stem: %s", stem, relpath)
+ continue
+ yield newstem, relpath
+
+
+def htmlf(stem, relpath, pubdir, newtree):
+ pubf = opj(pubdir, stem, relpath)
+ newf = opj(newtree, relpath)
+ if os.path.exists(pubf):
+ return stem, relpath, newf, pubf
+ else:
+ return stem, relpath, newf, opj(pubdir, stem, 'index.html')
+
+
+def htmld(stem, relpath, pubdir, newtree):
+ pubf = opj(pubdir, relpath)
+ newf = opj(newtree, relpath)
+ if os.path.exists(pubf):
+ return stem, relpath, newf, pubf
+ else:
+ return stem, relpath, newf, opj(pubdir, stem, 'index.html')
+
+
+def htmls(stem, relpath, pubdir, newtree):
+ pubf = opj(pubdir, stem, stem + '-single.html')
+ newf = opj(newtree, relpath)
+ if os.path.exists(pubf):
+ return stem, relpath, newf, pubf
+ else:
+ return stem, relpath, newf, opj(pubdir, stem, 'index.html')
+
+
+def txt(stem, relpath, pubdir, newtree):
+ pubf = opj(pubdir, stem, stem + '.txt')
+ newf = opj(newtree, relpath)
+ if os.path.exists(pubf):
+ return stem, relpath, newf, pubf
+ else:
+ return stem, relpath, newf, None
+
+
+def pdf(stem, relpath, pubdir, newtree):
+ pubf = opj(pubdir, stem, stem + '.pdf')
+ newf = opj(newtree, relpath)
+ if os.path.exists(pubf):
+ return stem, relpath, newf, pubf
+ else:
+ return stem, relpath, newf, None
+
+def make_refresh(target, title, delay=0):
+ text = '''
+
+ {1}: {0}
+
+
+
+
This page has moved permanently to
+ {0}.
+ Update your bookmarks if you wish. The compatibility
+ redirect will remain through, at least, early 2017.
+
This page has moved permanently to
+ {0}.
+ Update your bookmarks if you wish. The compatibility
+ redirect will remain through, at least, early 2017.
+
+
+
+'''
+ return text.format(target, title, delay)
+
+def swapfiles(a, b):
+ '''use os.rename() to make "a" become "b"'''
+ if not os.path.isfile(a):
+ raise OSError(errno.ENOENT, os.strerror(errno.ENOENT), a)
+ tf = None
+ if os.path.exists(b):
+ _, tf = mkstemp(prefix='swapfile-', dir=opd(opa(a)))
+ logger.debug("Created tempfile %s.", tf)
+ logger.debug("About to rename %s to %s.", b, tf)
+ os.rename(b, tf)
+ logger.debug("About to rename %s to %s.", a, b)
+ os.rename(a, b)
+ if tf:
+ logger.debug("About to rename %s to %s.", tf, a)
+ os.rename(tf, a)
+ logger.debug("About to remove %s.", tf)
+ os.rmdir(tf)
+
+
+def create_symlink(source, target):
+ assert not os.path.exists(target)
+ targetdir = os.path.dirname(target)
+ if not os.path.isdir(targetdir):
+ logger.debug("Creating directory %s", targetdir)
+ os.makedirs(targetdir)
+ logger.debug("Creating symlink %s, pointing to %s", target, source)
+ os.symlink(os.path.relpath(source, start=targetdir), target)
+
+
+def create_refresh_meta_equiv(fname, url, stem, **kwargs):
+ assert not os.path.exists(fname)
+ targetdir = os.path.dirname(fname)
+ if not os.path.isdir(targetdir):
+ logger.debug("Creating directory %s", targetdir)
+ os.makedirs(targetdir)
+ logger.debug("Creating file %s, with redirect to %s", fname, url)
+ with open(fname, 'w') as f:
+ f.write(make_refresh(url, stem, **kwargs))
+
+
+def newhtmlfilename(pubdir, stem, fname):
+ sought = opj(pubdir, stem, fname)
+ if not os.path.isfile(sought):
+ return opj(pubdir, stem, 'index.html')
+ return sought
+
+
+def refs(stems, refpath, refcompat, pubdir, urlbase):
+
+ for doc in refdocs:
+ stem = doc.replace('INTRO/', '')
+ if stem not in stems:
+ logger.critical("Stem %s not found in %s.", stem, pubdir)
+ sys.exit(1)
+
+ # -- PDF handling
+ newpdf = opj(pubdir, stem, stem + '.pdf')
+ oldpdf = opj(refcompat, doc + '.pdf')
+ if not os.path.exists(oldpdf):
+ oldpdf = opj(refcompat, stem, stem + '.pdf')
+ assert os.path.exists(oldpdf)
+ assert os.path.exists(newpdf)
+ os.rename(oldpdf, oldpdf + '.' + str(int(time.time())))
+ create_symlink(newpdf, oldpdf)
+
+ # -- HTML handling
+ htmldir = opj(refcompat, doc, 'html')
+ if not os.path.isdir(htmldir):
+ htmldir, _ = os.path.split(htmldir)
+ assert os.path.exists(htmldir)
+ for fn in os.listdir(htmldir):
+ if not fn.endswith('.html'):
+ continue
+ pubpath = newhtmlfilename(pubdir, stem, fn)
+ url = pubpath.replace(pubdir, urlbase)
+ fullname = opj(htmldir, fn)
+ os.rename(fullname, fullname + '.' + str(int(time.time())))
+ create_refresh_meta_equiv(fullname, url, stem, delay=2)
+
+
+def main(fin, fout, argv):
+ me = os.path.basename(sys.argv[0])
+ usage = "usage: %s " % (me,)
+ if not validate_args(argv):
+ return usage
+ refpath, refcompat, pubdir, urlbase = argv
+ stems = collect_published_stems(pubdir)
+ refs(stems, refpath, refcompat, pubdir, urlbase)
+ return os.EX_OK
+
+
+if __name__ == '__main__':
+ sys.exit(main(sys.stdin, sys.stdout, sys.argv[1:]))
+
+# -- end of file
diff --git a/LDP/migration-2016/run-whole-thing.sh b/LDP/migration-2016/run-whole-thing.sh
new file mode 100644
index 00000000..f85bba8d
--- /dev/null
+++ b/LDP/migration-2016/run-whole-thing.sh
@@ -0,0 +1,21 @@
+#! /bin/bash
+
+set -e
+set -x
+
+SELFNAME="$( readlink --canonicalize ${0})"
+ME="${SELFNAME##*/}" # -- basename
+HERE="${SELFNAME%/*}" # -- dirname
+
+{
+ exec 2>&1;
+
+ bash $HERE/migration-preparation.sh;
+
+ bash $HERE/migration-helper.sh;
+
+ bash $HERE/golive.sh;
+
+} | tee logfile-$( date +%F ).log
+
+# -- end of file
diff --git a/LDP/retired/3Dfx-HOWTO.sgml b/LDP/retired/3Dfx-HOWTO.sgml
new file mode 100644
index 00000000..f9f094a8
--- /dev/null
+++ b/LDP/retired/3Dfx-HOWTO.sgml
@@ -0,0 +1,2278 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ] >
+
+
+
+
+
+
+
+
+
+
+The Linux &c3Dfx; HOWTO
+<author>Bernd Kreimeier
+ (<htmlurl
+ url="mailto:bk@gamers.org"
+ name="bk@gamers.org">)
+<date>v1.16, 6 February 1998
+
+
+<abstract>
+The Linux &c3Dfx; HOWTO is not being maintained by the author,
+and is no longer relevant to the modern Linux system. It was removed
+from the collection May 6, 2004 by Emma Jane Hogbin (Technical Review
+Coordinator) based on the advice of the maintainer at the time, Michael
+Scherer. Comments should be sent to discuss@en.tldp.org
+<p>
+This document describes &c3Dfx; graphics accelerator chip
+support for Linux. It lists some supported hardware,
+describes how to configure the drivers, and answers
+frequently asked questions.
+</abstract>
+
+
+<!-- ====================================================== -->
+<!-- Indexing -->
+<!-- The index entries below might overlap with similar
+ entries from other HOWTO's e.g. on Mesa, GLint based
+ graphics, XFree86. Thus they are set as "idxentry"
+ style entries not meant to be tied to a particular
+ location. They could be anywhere in the file.
+ As the current backends maps invisible index entries
+ into the Index, that is, has no "idxentry" complement
+ to "idxref", I tried to put the index list in front
+ of the table of contents which was organized
+ in a way to remove the need for Index e.g. in HTML
+ backends, where indexing is currently not supported
+ anyway.
+ Keeping them in one spot should ease manual adjustment
+ of index entries from several documents into one
+ global index not using too many synonyms. -->
+
+
+
+<toc>
+
+
+<![ %Indexing
+ [
+
+<p>
+<nidx>Hardware accelerated 3D graphics with 3Dfx Voodoo</nidx>
+
+<nidx>XFree86 and 3Dfx Voodoo</nidx>
+<nidx>OpenGL and 3Dfx Voodoo</nidx>
+<nidx>Mesa and 3Dfx Voodoo</nidx>
+<nidx>GLUT and 3Dfx Voodoo</nidx>
+<nidx>GGI and 3Dfx Voodoo</nidx>
+
+<nidx>3Dfx</nidx>
+<nidx>Voodoo chipset</nidx>
+<nidx>Glide API for Linux</nidx>
+
+<nidx>Quantum 3D</nidx>
+<nidx>Obsidian graphics boards</nidx>
+
+<nidx>Orchid Righteous 3D</nidx>
+<nidx>Canopus Pure 3D</nidx>
+<nidx>Hercules Stealth 3D</nidx>
+<nidx>Diamond Monster 3D</nidx>
+
+<nidx>Quake for Linux</nidx>
+<nidx>GLQuake for Linux</nidx>
+<nidx>GLQuake and 3Dfx Voodoo</nidx>
+</p>
+
+ ]]>
+
+<!-- ====================================================== -->
+
+<sect>Introduction
+
+
+<p>
+This is the Linux &c3Dfx; HOWTO document. It is intended as a quick
+reference covering everything you need to know to install and
+configure &c3Dfx; support under Linux. Frequently asked questions
+regarding the &c3Dfx; support are answered, and references
+are given to some other sources of information on a variety of topics
+related to computer generated, hardware accelerated 3D graphics.
+<p>
+This information is only valid for Linux on the Intel platform. Some
+information may be applicable to other processor architectures, but I
+have no first hand experience or information on this. It is only
+applicable to boards based on &c3Dfx; technology, any other graphics
+accelerator hardware is beyond the scope of this document.
+
+
+<sect1>Contributors and Contacts
+<p>
+This document would not have been possible without all the
+information contributed by other people - those involved
+in the Linux &Glide; port and the beta testing process, in
+the development of &Mesa; and the &VooMesa; drivers, or
+rewieving the document on behalf of &c3Dfx; and Quantum3D.
+Some of them contributed entire sections to this document.
+<p>
+Daryll Strauss
+<htmlurl
+ url="mailto:Daryll Strauss <daryll@harlot.rb.ca.us>"
+ name="daryll@harlot.rb.ca.us"> did the port,
+Paul J. Metzger
+<htmlurl
+ url="mailto:Paul J. Metzger <pjm@rbd.com>"
+ name="pjm@rbd.com">
+modified the &VooMesa; driver (written by
+David Bucciarelli
+<htmlurl
+ url="mailto:David Bucciarelli <tech.hmw@plus.it>"
+ name="tech.hmw@plus.it">) for Linux,
+Brian Paul
+<htmlurl
+ url="mailto:Brian Paul <brianp@RA.AVID.COM>"
+ name="brianp@RA.AVID.COM">
+integrated it
+with his famous &Mesa; library. With respect to &VooDoo;
+accelerated Mesa, additional thanks has to go to Henri Fousse,
+Gary McTaggart, and the maintainer of the &c3Dfx; Mesa
+for DOS, Charlie Wallace
+<htmlurl
+ url="mailto:Charlie Wallace <Charlie.Wallace@unistudios.com>"
+ name="Charlie.Wallace@unistudios.com">.
+The folks at &c3Dfx;,
+notably Gary Sanders, Rod Hughes, and Marty Franz, provided
+valuable input, as did Ross Q. Smith of Quantum3D. The
+pages on the Voodoo Extreme and Operation 3Dfx websites
+provided useful info as well, and in some case I relied on
+the &c3Dfx; local Newsgroups. The Linux glQuake2 port
+that uses Linux &Glide; and &Mesa; is maintained by
+Dave Kirsch <htmlurl
+ url="mailto:Dave Kirsch <zoid@idsoftware.com>"
+ name="zoid@idsoftware.com">.
+Thanks to all those who sent
+e-mail regarding corrections and updates, and special
+thanks to Mark Atkinson for reminding me of the dual
+cable setup.
+<p>
+Thanks to the &SGMLT; package (formerly known as Linuxdoc-SGML),
+this HOWTO is available in several formats, all generated from a
+common source file. For information on &SGMLT; see its homepage
+at
+<htmlurl
+ url="http://pobox.com/~cg/sgmltools"
+ name="pobox.com/~cg/sgmltools">.
+
+
+<sect1>Acknowledgments
+<p>
+&c3Dfx;, the &c3Dfx; Interactive logo, &VooDoo;, and &VooRush;
+are registered trademarks of &c3Dfx; Interactive, Inc.
+&Glide;, &TexUs;, &Pixelfx; and &Texelfx; are trademarks of
+3Dfx Interactive, Inc. &OGL; is a registered trademark of
+Silicon Graphics. Obsidian is a trademark of Quantum3D.
+Other product names are trademarks of the respective holders,
+and are hereby considered properly acknowledged.
+
+<sect1>Revision History
+<p>
+<descrip>
+<tag>Version 1.03</tag>First version for public release.
+<tag>Version 1.16</tag>Current version &CurrentVer; &CurrentDate;.
+</descrip>
+
+<![ %Internal
+ [
+<sect2>Internal Revision History
+<p>
+The verbose revision history below is for internal use only,
+to provide assistance during the review/copy editing process.
+
+ <code>
+ Version 0.1i
+ First version; used for proof-reading purposes only.
+ Version 0.2i
+ Added Flash3D, added Orchid R3D to list of boards
+ known to work, minor fixes.
+ FAQ regarding grSstWinOpen() added, FAQ regarding
+ Glide demos with ATB. Trademark acknowdlegments.
+ Version 0.3i
+ Added Quantum3D statements about Linux support,
+ chipset definitions, Obsidian board. Added a
+ bit on Voodoo architecture.
+ Version 0.4i
+ Official Obsidian taxonomy from Ross Q. Smith.
+ Explanation on setuid from Daryll Strauss.
+ Comments on Voodoo GLUT by David Bucciarelli.
+ Version 0.5i
+ Upgraded to 2.3.1, added Intergraph Intense.
+ Version 1.0i
+ Fixed news.3dfx hierarchy, added bug report
+ group pointer, ready for release.
+ Version 1.01i
+ Corrections from Daryll, SST_DUALSCREEN, snapping
+ vertices, removed setuid/device/XAA discussion.
+ Version 1.02i
+ P5 added to requirements. Removed Banshee. No
+ Intergraph support. FAQ section overiew.
+ Version 1.03
+ Corrected typos, added Macintosh. Changed wording
+ on grSstOpen error - might be removed entirely.
+ Added a Mesa compilation problems section. More
+ trademarks from the Glide docs. TexUS. ATB doc
+ mentioned. Upp'ed to pending 2.4 release.
+
+ Version 1.10i
+ Internal revision, for long overdue update.
+ Removed some general accelerated 3D graphics
+ explanations. Stripped some vendor references,
+ as I am not going to keep track of that in
+ all detail. Added some Pixelfx, Texelfx,
+ SLI, AGP, and other 3Dfx specific technical
+ backgrounder. Removed the outdated commercial
+ Linux OpenGL details. Added some more URL's
+ of 3Dfx web and FTP site, ATB info, miniport
+ info. Added some details to the Rush support
+ issue (DirectDraw, SSST96). Added Mesa window
+ hack. Removed the deprecated mdw LDP URL.
+ LDP license link, copyright changed. Link to
+ Stingray FAQ. Added info@quantum3d. Added a
+ memory/board(s) configuration formula.
+ A few GGI changes, resolved SVGA duplicate.
+ Corrected GLUT version number.
+
+ Version 1.11i
+ Internal revision. Added www.opengl.org,
+ emphasized pointer to Gateway. Added Mark
+ Kilgard to beta mail alias. Added OpenGL
+ GameDev list and ListServ archive reference.
+ Hercules FAQ maintained by Kertis Henderson
+ (kertis@frozenwave.com) confirmed. Added TMU
+ alias to Texelfx entry. FAQ on support for
+ multi TMU in current release. Added mention
+ of seperate VR/VG distributions to current
+ version FAQ. No mention of any upcoming Glide
+ revisions. Added Mesa/Glide combo portability,
+ and Charlie Wallace' DOS port. Moved X vs. AT3D
+ into the X11 section, added technical details
+ on problem to pacify those bitching, mentioned
+ XFree86 3.3.3.2. Added Dirk Hohndel to beta mail
+ alias. Added assembly remark to Alpha
+ port question. Added texture size entry.
+ Replaced max res. 1280x960 for SLI with 1024x768.
+ Added overclocking/cooling comments. Removed
+ outdated Mesa-2.3.x and Glide 2.3 specifics
+ like grSstWinOpen/grSstOpen. Added glQuake in
+ window remark. Removed outdated VoodooGLUT in
+ Mesa remark.
+
+ Installed SGML-Tools v1.0.3. Added some minimal
+ indexing for RedHat LDP compilation. Switched to
+ Linuxdoc96 for release, as the nidx element has
+ not been added to strict DTD, while idx has.
+ Invisible indices cannot be created prior to
+ ToC - bugger.
+ Formatting: run into the familiar problem with
+ LaTeX styles not updated properly, and a duplicate
+ url.sty in a different location. Manual removal
+ and copy. Run texconfig rehash, fixed read permit
+ on style files. Formatting runs.
+ The url attribute rendering screws up underscores
+ and tilde character. OPP (other people's problem).
+ Strange, a misspelled &3Dfx; entity slips through
+ validation?
+
+ Version 1.12i
+ Rephrased multitexture in Mesa remark. Clarified
+ the 1024x768 issue, ruled out 1280x960. Reworked
+ info file for linux-3dfx@gamers.org proposal,
+ rephrased entry. Fixed Glide version 2.4.
+ ATB source hint, whatever it's worth. Fixed 3Dfx/
+ Quantum corporate entry. Added Linux Quake setuid,
+ an GL related bugs/workarounds from Dave Kirsch's
+ plan. Added LinuxQuake sites.
+
+ Version 1.13i
+ Added "Internal" marked section, moved revision
+ history out of comment. Have to take out <nidx>
+ indexing after submission to RedHat, because it
+ breaks HTML output. Added "Indexing" marked
+ section, might actually scatter some more indices
+ throughout the document that way. Memory speed
+ mentioned as overclocking issue, lot of typos
+ fixed there. Fixed outdated SGML-Tools URL. Mesa
+ 2.6b5 (current) and 3.0 (upcoming) mentioned.
+ Made separate Mesa multitexturing entry. Also made
+ LinuxQuake multitexturing entry.
+
+ Version 1.14i
+ Added blatant plug to "supported hardware" section,
+ for Voodoo2 board loans and DEC Alpha. Reworded
+ Glide multitexture section a bit, added Mesa
+ single pass trilinear filtering. Added "as of 2.6b5"
+ to Mesa statements.
+
+ Version 1.15i
+ Upped Mesa to 2.6b6. Feedback from Daryll, Paul, and
+ Brian so far. Created a Contributors and Contacts
+ section following Paul's suggestion, included all
+ e-mails of those publicly visible (no 3Dfx/Quantum3D
+ mailto). Added single screen dual cable as proposed
+ by Mark Atkinson. Typos. Slightly reworded Quantum3D
+ entry added to How do boards differ. Added two cross
+ references to Mesa window hack. Added single board
+ Obsidian SB SLI, added resetting dual and single
+ board SLI reset problem. Glide 3.0 is publicly talked
+ about, thus added a remark to current version. Keep
+ linux-3dfx mailing list entry. Disclaimer with Mark
+ Kilgards SGI address, GLUT mailing list.
+ Version 1.16
+ Switched Internal to IGNORE, upped current version,
+ notified LDP.
+
+ </code>
+
+ ]]>
+
+
+
+<!-- ====================================================== -->
+<sect1>New versions of this document
+<p>
+You will find the most recent version of this document at
+<htmlurl
+ url="http://www.gamers.org/dEngine/xf3D/"
+ name="www.gamers.org/dEngine/xf3D/">.
+<p>
+New versions of this document will be periodically posted to the
+<htmlurl
+url="news:comp.os.linux.answers"
+name="comp.os.linux.answers"> newsgroup. They will also be uploaded
+to various anonymous ftp sites that archive such information including
+<htmlurl
+url="ftp://sunsite.unc.edu/pub/Linux/docs/HOWTO/"
+name ="ftp://sunsite.unc.edu/pub/Linux/docs/HOWTO/">.
+<p>
+Hypertext versions of this and other Linux HOWTOs are available on
+many World-Wide-Web sites, including
+<htmlurl
+url="http://sunsite.unc.edu/LDP/"
+name="sunsite.unc.edu/LDP/">. Most Linux CD-ROM
+distributions include the HOWTOs, often under the
+<tt>/usr/doc/</tt>directory, and you can also buy printed copies from
+several vendors.
+<p>
+If you make a translation of this document into another language, let
+me know and I'll include a reference to it here.
+
+
+<sect1>Feedback
+<p>
+I rely on you, the reader, to make this HOWTO useful. If you have any
+suggestions, corrections, or comments, please send them to me (
+<htmlurl
+ url="mailto:bk@gamers.org"
+ name="bk@gamers.org">), and I will try to
+incorporate them in the next revision. Please add
+<tt>HOWTO 3Dfx</tt> to the Subject-line of the mail, so procmail
+will dump it in the appropriate folder.
+<p>
+Before sending bug reports or questions, <EM>please read all of the
+information in this HOWTO</EM>, and <EM>send detailed information
+about the problem</EM>.
+<p>
+If you publish this document on a CD-ROM or in hardcopy form, a
+complimentary copy would be appreciated. Mail me for my postal
+address. Also consider making a donation to the
+Linux Documentation Project to help support
+free documentation for Linux. Contact the
+Linux HOWTO coordinator, Tim Bynum
+(<htmlurl
+ url="mailto:linux-howto@sunsite.unc.edu"
+ name="linux-howto@sunsite.unc.edu">),
+for more information.
+
+
+<sect1>Distribution Policy
+<p>
+Copyright (c) 1997, 1998 by Bernd Kreimeier.
+This document may be
+ distributed under the terms set forth in the LDP license
+ at
+<htmlurl
+ url="http://sunsite.unc.edu/LDP/COPYRIGHT.html"
+ name="sunsite.unc.edu/LDP/COPYRIGHT.html">.
+<p>
+This HOWTO is free documentation; you can redistribute it and/or
+modify it under the terms of the LDP license.
+This document is distributed in the hope that it will be useful, but
+<bf>without any warranty</bf>; without even the implied warranty of
+<bf>merchantability</bf> or <bf>fitness for a particular purpose</bf>.
+See the LDP license for more details.
+
+
+
+
+<!-- ====================================================== -->
+<sect>Graphics Accelerator Technology
+
+<sect1>Basics
+<p>
+This section gives a <em>very</em> cursory overview of computer
+graphics accelerator technology, in order to help you understand
+the concepts used later in the document. You should consult e.g.
+a book on &OGL; in order to learn more.
+
+<sect1>Hardware configuration
+<p>
+Graphics accelerators come in different flavors: either
+as a separate PCI board that is able to pass through
+the video signal of a (possibly 2D or video accelerated)
+VGA board, or as a PCI board that does both VGA and
+3D graphics (effectively replacing older VGA controllers).
+The &c3Dfx; boards based on the &VooDoo; belong to the
+former category. We will get into this again later.
+<p>
+If there is no address conflict, any 3D accelerator
+board could be present under Linux without interfering,
+but in order to access the accelerator, you will need
+a driver. A combined 2D/3D accelerator might behave
+differently.
+
+<sect1>A bit of &VooDoo; architecture
+<p>
+Usually, accessing texture memory and frame/depth buffer is a
+major bottleneck. For each pixel on the screen, there are
+at least one (nearest), four (bi-linear), or eight (tri-linear
+mipmapped) read accesses to texture memory, plus a read/write
+to the depth buffer, and a read/write to frame buffer memory.
+<p>
+The &VooDoo; architecture separates texture memory from
+frame/depth buffer memory by introducing two separate
+rendering stages, with two corresponding units (&Pixelfx; and
+&Texelfx;), each having a separate memory interface to dedicated
+memory. This gives an above-average fill rate, paid for
+restrictions in memory management (e.g. unused framebuffer
+memory can not be used for texture caching).
+<p>
+Moreover, a &VooDoo; could use two TMU's (texture management
+or texelfx units), and finally, two &VooDoo; could be
+combined with a mechanism
+called Scan-Line Interleaving (SLI). SLI essentially
+means that each &Pixelfx; unit effectively provides only
+every other scanline, which decreases bandwidth impact
+on each &Pixelfx;' framebuffer memory.
+
+
+<sect>Installation
+<p>
+Configuring Linux to support &c3Dfx; accelerators involves the
+following steps:
+
+<enum>
+<item>Installing the board.
+<item>Installing the &Glide; distribution.
+<item>Compiling, linking and/or running the application.
+</enum>
+
+The next sections will cover each of these steps in detail.
+
+<sect1>Installing the board
+<p>
+Follow the manufacturer's instructions for installing the hardware or
+have your dealer perform the installation.
+It should not be necessary to select settings for IRQ, DMA channel,
+either Plug&Pray (tm) or factory defaults should work. The
+add-on boards described here are memory mapped devices and do
+not use IRQ's. The only kind of conflict to avoid
+is memory overlap with other devices.
+<p>
+As &c3Dfx; does not develop or sell any boards, do not contact
+them on any problems.
+
+<sect2>Troubleshooting the hardware installation
+<p>
+To check the installation and the memory mapping, do
+<tt>cat /proc/pci</tt>. The output should contain something like
+<code>
+ Bus 0, device 12, function 0:
+ VGA compatible controller: S3 Inc. Vision 968 (rev 0).
+ Medium devsel. IRQ 11.
+ Non-prefetchable 32 bit memory at 0xf4000000.
+
+ Bus 0, device 9, function 0:
+ Multimedia video controller: Unknown vendor Unknown device (rev 2).
+ Vendor id=121a. Device id=1.
+ Fast devsel. Fast back-to-back capable.
+ Prefetchable 32 bit memory at 0xfb000000.
+</code>
+for a Diamond Monster 3D used with a Diamond Stealth-64. Additionally
+a <tt>cat /proc/cpuinfo /proc/meminfo</tt> might be helpfull for
+tracking down conflicts and/or submitting a bug report.
+<p>
+With current kernels, you will probably get a boot warning
+like
+<code>
+Jun 12 12:31:52 hal kernel: Warning : Unknown PCI device (121a:1).
+Please read include/linux/pci.h
+</code>
+which could be safely ignored. If you happen to have a board
+not very common, or have encountered a new revision, you should
+take the time to follow the advice in <tt>/usr/include/linux/pci.h</tt>
+and send all necessary information
+to
+<htmlurl
+ url="mailto:linux-pcisupport@cao-vlsi.ibp.fr"
+ name="linux-pcisupport@cao-vlsi.ibp.fr">.
+<p>
+If you experience any problems with the board, you should
+try to verify that DOS and/or Win95 or NT support works. You
+will probably not receive any useful response from a
+board manufacturer on a bug report or request regarding
+Linux. Having dealt with the Diamond support e-mail
+system, I would not expect useful responses for other
+operating systems either.
+
+<sect2>Configuring the kernel
+<p>
+There is no kernel configuration necessary, as long as PCI
+support is enabled.
+The <url url="http://sunsite.unc.edu/mdw/HOWTO/Kernel-HOWTO.html"
+name="Linux Kernel HOWTO"> should be consulted for the details of
+building a kernel.
+
+
+<sect2>Configuring devices
+<p>
+The current drivers do not (yet) require any special devices.
+This is different from other driver developments
+(e.g. the sound drivers, where you will find
+a <tt>/dev/dsp</tt> and <tt>/dev/audio</tt>). The
+driver uses the <tt>/dev/mem</tt> device which should
+always be available. In consequence, you need to use
+<tt>setuid</tt> or root privileges to access the
+accelerator board.
+
+<sect1>Setting up the Displays
+<p>
+There are two possible setups with add-on boards. You
+could either pass-through the video signal from your
+regular VGA board via the accelerator board to the
+display, or you could use two displays at the same time.
+Rely to the manual provided by the board manufacturer
+for details. Both configurations have been tried with
+the Monster 3D board.
+
+<sect2>Single screen display solution
+<p>
+This configuration allows you to check basic operations
+of the accelerator board - if the video signal is not
+transmitted to the display, hardware failure is possible.
+<p>
+Beware that the video output signal might deteoriate
+significantly if passed through the video board. To
+a degree, this is inevitable. However, reviews have
+complained about below-average of the cables provided
+e.g. with the Monster 3D, and judging from the one I
+tested, this has not changed.
+<p>
+There are other pitfalls in single screen configurations.
+Switching from the VGA display mode to the accelerated
+display mode will change resolution and refresh rate as
+well, even if you are using 640x480 e.g. with X11, too.
+Moreover, if you are running X11, your application is
+responsible for demanding all keyboard and mouse events,
+or you might get stuck because of changed scope and exposure
+on the X11 display (that is effectively invisible when the
+accelerated mode is used) You could use SVGA console mode
+instead of X11.
+<p>
+If you are going to use a single screen configuration and
+switch modes often, remember that your monitor hardware
+might not enjoy this kind of use.
+
+
+<sect2>Single screen dual cable setup
+<p>
+Some high end monitors (e.g. the EIZO F-784-T)
+come with two connectors, one with 5 BNC connectors
+for RGB, HSync, VSync, the other e.g. a regular VGA
+or a 13W3 Sub-D VGA.
+These displays usually also feature a front panel
+input selector to safely switch from one to the
+other. It is thus possible to use e.g. a VGA-to-BNC
+cable with your high end 2D card, and a VGA-to-13W3
+Sub-D cable with your 3Dfx, and effectively run dual
+screen on one display.
+
+
+<sect2>Dual screen display solution
+<p>
+The accelerator board does not need the VGA input signal.
+Instead of routing the common video output through the
+accelerator board, you could attach a second monitor to
+its output, and use both at the same time. This solution
+is more expensive, but gives best results, as your main
+display will still be hires and without the signal
+quality losses involved in a pass-through solution. In
+addition, you could use X11 and the accelerated full
+screen display in parallel, for development and debugging.
+<p>
+A common problem is that the accelerator board will not
+provide any video signal when not used. In consequence,
+each time the graphics application terminates, the
+hardware screensave/powersave might kick in depending
+on your monitors configuration. Again, your hardware
+might not enjoy being treated like this. You should
+use
+<code>
+setenv SST_DUALSCREEN 1
+</code>
+to force continued video output in this setup.
+
+<sect1>Installing the &Glide; distribution
+<p>
+The &Glide; driver and library are provided as a single
+compressed archive. Use <tt>tar</tt> and <tt>gzip</tt>
+to unpack, and follow the instructions in the
+README and INSTALL accompanying the distribution.
+Read the install script and run it. Installation puts
+everything in /usr/local/glide/include,lib,bin and sets
+the ld.conf to look there. Where it installs and setting
+ld.conf are independent actions. If you skip the ld.conf
+step then you need the LD_LIBRARY_PATH.
+<p>
+You will need to install the header files in a location
+available at compile time, if you want to compile your own
+graphics applications. If you do not want to use the
+installation as above (i.e. you insist on a different
+location), make sure that any application could access
+the shared libary at runtime, or you will get a response
+like
+<tt>can't load library 'libglide.so'</tt>.
+
+
+
+<sect2>Using the detect program
+<p>
+There is a <tt>bin/detect</tt> program in the distribution
+(the source is not available). You have to run it as root,
+and you will get something like
+<code>
+slot vendorId devId baseAddr0 command description
+---- -------- ------ ---------- ------- -----------
+ 00 0x8086 0x122d 0x00000000 0x0006 Intel:430FX (Triton)
+ 07 0x8086 0x122e 0x00000000 0x0007 Intel:ISA bridge
+ 09 0x121a 0x0001 0xfb000008 0x0002 3Dfx:video multimedia adapter
+ 10 0x1000 0x0001 0x0000e401 0x0007 ???:SCSI bus controller
+ 11 0x9004 0x8178 0x0000e001 0x0017 Adaptec:SCSI bus controller
+ 12 0x5333 0x88f0 0xf4000000 0x0083 S3:VGA-compatible display co
+</code>
+as a result. If you do not have root privileges, the program will
+bail out with
+<code>
+Permission denied: Failed to change I/O privilege. Are you root?
+</code>
+output might come handy for a bug report as well.
+
+
+
+<sect2>Using the test programs
+<p>
+Within the &Glide; distribution, you will find a folder with
+test programs. Note that these test programs are under
+&c3Dfx; copyright, and are legally available for use only
+if you have purchased a board with a &c3Dfx; chipset. See
+the LICENSE file in the distribution, or
+their web site
+ <htmlurl
+ url="http://www.3dfx.com/"
+ name="www.3dfx.com"> for details.
+<p>
+It is recommend to compile and link the test programs even
+if there happen to be binaries in the distribution. Note
+that some of the programs will requires some files
+like <tt>alpha.3df</tt> from the distribution to be available
+in the same folder.
+All test programs use the 640x480 screen resolution. Some
+will request a veriety of single character inputs, others
+will just state <tt>Press A Key To Begin Test</tt>. Beware
+of loss of input scope if running X11 on the same screen
+at the same time.
+<p>
+See the README.test for a list of programs, and other details.
+
+
+
+
+
+<sect>Answers To Frequently Asked Questions
+<p>
+The following section answers some of the questions that
+(will) have been asked on the Usenet news groups and mailing
+lists. The FAQ has been subdivided into several parts for
+convenience, namely
+<itemize>
+<item>FAQ: Requirements?
+<item>FAQ: &VooDoo;? &c3Dfx;?
+<item>FAQ: &Glide;?
+<item>FAQ: &Glide; and SVGA?
+<item>FAQ: &Glide; and XFree86?
+<item>FAQ: &Glide; versus OpenGL/Mesa?
+<item>FAQ: But Quake?
+<item>FAQ: Troubleshooting?
+</itemize>
+Each section lists several questions and answers, which
+will hopefully address most problems.
+
+
+<sect>FAQ: Requirements?
+
+<sect1>What are the system requirements?
+<p>
+A Linux PC, PCI 2.1 compliant, a monitor capable
+of 640x480, and a 3D accelerator board based on
+the &c3Dfx; &VooDoo;. It will work on a P5 or P6,
+with or without MMX. The current version does not
+use MMX, but it has some optimized code paths for P6.
+<p>
+At one point, some &c3Dfx; statements seemed to
+imply that using Linux &Glide; required using a
+RedHat distribution. Note that while
+Linux &Glide; has originally been ported in a
+RedHat 4.1 environment, it has been used and
+tested with many other Linux distributions,
+including homebrew, Slackware, and Debian 1.3.1.
+
+<sect1>Does it work with Linux-Alpha?
+<p>
+There is currently no Linux &Glide; distribution available
+for any platform besides i586. As the &Glide; sources are
+not available for distribution, you will have to
+wait for the binary. Quantum3D has DEC Alpha support
+announced for 2H97. Please contact Daryll Strauss
+if you are interested in supporting this.
+<p>
+There is also the issue of porting the the assembly
+modules. While there are alternative C paths in the
+code, the assembly module in &Glide; (essentially
+triangle setup) offered significant performance gains
+depending on the P5 CPU used.
+
+
+<sect1>Which &c3Dfx; chipsets are supported?
+<p>
+Currently, the &c3Dfx; &VooDoo; chipset is supported
+under Linux. The &VooRush; chipset is not yet supported.
+
+<sect1>Is the &VooRush; supported?
+<p>
+The current port of &Glide; to Linux does not support
+the &VooRush;. An update is in the works.
+<p>
+The problem is that at one point the &VooRush; driver
+code in &Glide; depended on Direct Draw. There was
+an SST96 based DOS portion in the library that could
+theoretically be used for Linux, as soon as all
+portions residing in the 2D/Direct Draw/D3D combo
+driver are replaced.
+<p>
+Thus &VooRush; based boards like the
+<em>Hercules Stingray 128/3D</em>
+or <em>Intergraph Intense Rush</em> are not supported
+yet.
+
+
+<sect1>Which boards are supported?
+<p>
+There are no officially supported boards, as &c3Dfx; does
+not sell any boards. This section does not attempt to
+list all boards, it will just give an overview, and
+will list only boards that have been found to cause
+trouble.
+<p>
+It is important to recognize that Linux support for a given
+board does not only require a driver for the 3D accelerator
+component. If a board features its own VGA core as well,
+support by either Linux SVGA or XFree86 is required as well
+(see section about &VooRush; chipset).
+Currently, an add-on solution is recommended, as it allows
+you to choose a regular graphics board well supported for
+Linux. There are other aspects discussed below.
+<p>
+All Quantum3D Obsidian boards, independend of texture
+memory, frame buffer memory, number of Pixelfx and
+Texelfx units, and SLI should work. Same for all other
+ &VooDoo; based boards, like Orchid Righteous 3D, Canopus
+Pure 3D, Flash 3D, and Diamond Monster 3D.
+&VooRush; based boards are not yet supported.
+<p>
+Boards that are not based on &c3Dfx; chipsets (e.g. manufactured
+by S3, Matrox, 3Dlabs, Videologic) do <em>not</em> work with the &c3Dfx;
+drivers and are beyond the scope of this document.
+
+
+
+<sect1>How do boards differ?
+<p>
+As the board manufacturers are using the same chipset,
+any differences are due to board design. Examples are
+quality of the pass-through cable and connectors
+(reportedly, Orchid provided better quality than
+Diamond), availability of a TV-compliant video
+signal output (Canopus Pure 3D), and, most notably,
+memory size on board.
+<p>
+Most common were boards for games
+with 2MB texture cache and 2 MB framebuffer memory,
+however, the Canopus Pure3D comes with a maximal
+4 MB texture cache, which is an advantage e.g.
+with games using dynamically changed textures,
+and/or illumation textures (Quake, most notably).
+The memory architecture of a typical &VooDoo;
+board is described below, in a separate section.
+<p>
+Quantum 3D offers the widest selection of &c3Dfx;-based
+boards, and is probably the place to go if you are
+looking for a high end &VooDoo; based board configuration.
+Quantum 3D is addressing the visual simulation market,
+while most of the other vendors are only targetting the
+consumer-level PC-game market.
+
+
+<sect1>What about AGP?
+<p>
+There is no &VooDoo; or &VooRush; AGP board that I am
+aware of. I am not aware of AGP support under Linux,
+and I do not know whether upcmong AGP boards using
+&c3Dfx; technology might possibly be supported with
+Linux.
+
+
+
+<sect>FAQ: &VooDoo;? &c3Dfx;?
+
+<sect1>Who is &c3Dfx;?
+<p>
+&c3Dfx is a San Jose based manufacturer of 3D graphics
+accelerator hardware for arcade games, game consoles,
+and PC boards.
+Their official website is
+<htmlurl
+ url="http://www.3dfx.com/"
+ name="www.3dfx.com">. &c3Dfx; does not sell any boards,
+but other companies do, e.g. Quantum3D.
+
+
+<sect1>Who is Quantum3D?
+<p>
+Quantum3D started as a &c3Dfx; spin-off, manufacturing
+high end accelerator boards based on &c3Dfx; chip
+technology for consumer and business market, and
+supplying arcade game technology. See
+their home page at
+<htmlurl
+ url="http://www.quantum3d.com/"
+ name="www.quantum3d.com">
+for additional information. For general inquiries
+regarding Quantum3D,
+please send mail to
+<htmlurl
+ url="mailto:info@quantum3d"
+ name="info@quantum3d">.
+
+
+
+<sect1>What is the &VooDoo;?
+<p>
+The &VooDoo; is a chipset manufactured by &c3Dfx;. It
+is used in hardware acceleration boards for the PC.
+See the HOWTO section on supported hardware.
+
+<sect1>What is the &VooRush;?
+<p>
+The &VooRush; is a derivate of the &VooDoo; that
+has an interface to cooperate with a 2D VGA
+video accelerator, effectively supporting
+accelerated graphics in windows. This combo
+is currently not supported with Linux.
+
+<sect1>What is the &VooD2;?
+<p>
+The &VooD2; is the successor of the &VooDoo; chipset,
+featuring several improvements. It is announced
+for late March 1998, and annoucements of &VooD2;
+based boards have been published e.g. by Quantum 3D,
+by Creative Labs, Orchid Technologies, and
+Diamond Multimedia.
+<p>
+The &VooD2; is supposed to be backwards compatible.
+However, a new version of &Glide; will have to be
+ported to Linux.
+
+
+<sect1>What is VGA pass-though?
+<p>
+The &VooDoo; (but not the &VooRush;) boards are
+add-on boards, meant to be used with a regular
+2D VGA video accelerator board. In short, the
+video output of your regular VGA board is used
+as input for the &VooDoo; based add-on board,
+which by default passes it through to the display
+also connected to the &VooDoo; board. If the
+&VooDoo; is used (e.g. by a game), it will
+disconnect the VGA input signal, switch the
+display to a 640x480 fullscreen mode with the
+refresh rate configured by SST variables and
+the application/driver, and generate the video
+signal itself. The VGA doesn't need to be aware
+of this, and won't be.
+<p>
+This setup has several advantages: free choice
+of 2D VGA board, which is an issue with Linux,
+as XFree86 drivers aren't available for all
+chipsets and revisions, and a cost effective
+migration path to accelerated 3D graphics. It
+also has several disadvantages: an application
+using the &VooDoo; might not re-enable video
+output when crashing, and regular VGA video
+signal deteoriates in the the pass-through
+process.
+
+<sect1>What is &Texelfx; or TMU?
+<p>
+&VooDoo; chipsets have two units. The first one interfaces
+the texture memory on the board, does the texture mapping,
+and ultimately generates the input for the second unit
+that interfaces the framebuffer. This one is called
+&Texelfx;, aka Texture Management Unit, aka TMU. The neat
+thing about this is that a board can use two &Texelfx;
+instead of only one, like some of
+the Quantum3D Obsidian boards did, effectively doubling the
+processing power in some cases, depending on the application.
+<p>
+As each &Texelfx; can address 4MB texture memory, a dual
+&Texelfx; setup has an effective texture cache of up to 8MB.
+This can be true even if only one &Texelfx; is actually
+needed by a particular application, as textures can be
+distributed to both &Texelfx;, which are used depending
+on the requested texture. Both &Texelfx; are used together
+to perform certain operations as trilinear filtering and
+illumination texture/lightmap passes (e.g. in glQuake)
+in a single pass instead of the two passes that are
+required with only one &Texelfx;. To actually exploit the
+theoretically available speedup and cache size increase,
+a &Glide; application has to use both &Texelfx; properly.
+<p>
+The two &Texelfx; can not be used separately to
+each draw a textured triangle at the same time. A triangle
+is always drawn using whatever the current setup is,
+which can be to use both &Texelfx; for a single pass
+operation combining two textures, or one &Texelfx;
+for only a single texture. Each &Texelfx; can only
+access its own memory.
+
+
+<sect1>What is a &Pixelfx; unit?
+<p>
+&VooDoo; chipsets have two units. The second one interfaces
+the framebuffer and ultimately generates the depth buffer
+and pixel color updates. This one is called &Pixelfx;. The
+neat thing here is that two &Pixelfx; units can cooperate
+in SLI mode, like with some of the Quantum3D Obsidian boards,
+effectively doubling the frame rate.
+
+
+<sect1>What is SLI mode?
+<p>
+SLI means "Scanline Interleave". In this mode, two &Pixelfx;
+are connected and render in alternate turns, one handling
+odd, the other handling even scanlines of the actual output.
+Inthis mode, each &Pixelfx; stores only half of the image
+and half of the depth buffer data in its own local
+framebuffer, effectively doubling the number of pixels.
+<p>
+The &Pixelfx; in question can be on the same board,
+or on two boards properly connected. Some Quantum3D
+Obsidian boards support SLI with &VooDoo;.
+<p>
+As two cards can decode the same PCI addresses and receive
+the same data, there is not necessarily additional bus
+bandwidth required by SLI. On the other hand, texture
+data will have to be replicated on both boards, thus
+the amount of texture memory effectively stays the same.
+
+
+<sect1>Is there a single board SLI setup?
+<p>
+There are now two types of Quantum3D SLI boards.
+The intial setup used two boards, two PCI slots,
+and an interconnect (e.g. the Obsidian 100-4440).
+The later revision which performs identically is
+contained on one full-length PCI board (e.g.
+Obsidian 100-4440SB). Thus a single board SLI
+solution is possible, and has been done.
+
+
+<sect1>How much memory? How many buffers?
+<p>
+The most essential difference between different boards
+using the &VooDoo; chipset is the amount and
+organization of memory. Quantum3D used a three digit
+scheme to descibe boards. Here is a slightly modifed
+one (anticipating &VooD2;). Note that if you use
+more than one Texelfx, they need the same amount of
+texture cache memory each, and if you combine two
+Pixelfx, each needs the same amount of frame buffer
+memory.
+<code>
+ "SLI / Pixelfx / Texelfx1 / Texelfx2 "
+</code>
+It means that a common 2MB+2MB board would be a
+<tt>1/2/2/0</tt> solution, with the minimally
+required total 4Mb of memory. A Canopus Pure 3D
+would be <tt>1/2/4/0</tt>, or 6MB. An Obsidian-2220
+board with two Texelfx would be <tt>1/2/2/2</tt>,
+and an Obsidian SLI-2440 board would be <tt>2/2/4/4</tt>.
+A fully featured dual board solution (2 Pixelfx, each
+with 2 Texelfx and 4MB frame buffer, each Texelfx 4 MB
+texture cache) would be <tt>2/4/4/4</tt>, and the
+total amount of memory would be
+<tt>SLI*(Pixelfx+Texelfx1+Texelfx2)</tt>, or 24 MB.
+<p>
+So there.
+
+<sect1>Does the &VooDoo; do 24 or 32 bit color?
+<p>
+No. The &VooDoo; architecture uses 16bpp internally.
+This is true for &VooDoo;, &VooRush; and &VooD2;
+alike. Quantum3D claims to implement 22-bpp effective color depth
+with an enhanced 16-bpp frame buffer, though.
+
+<sect1>Does the &VooDoo; store 24 or 32 bit z-buffer per pixel?
+<p>
+No. The &VooDoo; architecture uses 16bpp internally
+for the depth buffer, too. This again is true for &VooDoo;,
+&VooRush; and &VooD2; alike. Again, Quantum3D claims
+that using the floating point 16-bits per pixel (bpp) depth
+buffering provides 22-bpp effective Z-buffer precision.
+
+<sect1>What resolutions does the &VooDoo; support?
+<p>
+The &VooDoo; chipset supports up to 4 MB frame buffer
+memory. Presuming double buffering and a depth buffer,
+a 2MB framebuffer will support a resolution of 640x480.
+With 4 MB frame buffer, 800x600 is possible.
+<p>
+Unfortunately 960x720 is not supported. The &VooDoo;
+chipset requires that the amount of memory for a particular
+resolution must be such that the vertical and horizontal
+resolutions must be evenly divisible by 32. The video
+refresh controller, though can output any particular
+resolution, but the "virtual" size required for the memory
+footprint must be in dimensions evenly divisible by 32.
+So, 960x720 actually requires 960x736 amount of memory,
+and 960x736x2x3 = 4.04MBytes.
+<p>
+However, using two boards with SLI, or a dual &Pixelfx;
+SLI board means that each framebuffer will only have
+to store half of the image. Thus 2 times 4 MB in SLI
+mode are good up to 1024x768, which is the maximum
+because of the overall hardware design. You will be
+able to do 1024x768 tripled buffered with Z, but you
+will not be able to do e.g. 1280x960 with double
+buffering.
+<p>
+Note that triple buffering (no VSync synchonization
+required by the application), stereo buffering (for
+interfacing LCD shutters) and other more demanding
+setups will severely decrease the available resolution.
+
+
+<sect1>What texture sizes are supported?
+<p>
+The maximum texture size for the &VooDoo; chipset
+is 256x256, and you have to use powers of two. Note
+that for really small textures (e.g. 16x16) you
+are better off merging them into a large texture,
+and adjusting your effective texture coordinates
+appropriately.
+
+<sect1>Does the &VooDoo; support paletted textures?
+<p>
+The &VooDoo; hardware and &Glide; support the palette
+extension to &OGL;. The most recent version of
+&Mesa; does support the
+<tt>GL_EXT_paletted_texture</tt>
+and
+<tt>GL_EXT_shared_texture_palette</tt> extensions.
+
+
+<sect1>What about overclocking?
+<p>
+If you want to put aside considerations about warranty
+and overheating, and want to do overclocking to boost
+up performance even further, there is related info out
+on the web. The basic mechanism is to use
+&Glide; environment variables to adjust the clock.
+<p>
+Note that the actual recommended clock is board
+dependend. While the default clock speed is 50 Mhz,
+the Diamond Monster 3D property sheet lets you set up
+a clock of 57 MHz. It all comes down to the design of
+a specific board, and which components are used with
+the &VooDoo; chipset - most notably access speed of
+the RAM in question. If you exceed the limits of your
+hardware, rendering artifacts will occur to say the
+least. Reportedly, 57 MHz usually works, while 60 MHz
+or more is already pushing it.
+<p>
+Increasing the clock frequency also means increasing
+the waste heat disposed in the chips, in a nonlinear
+dependency (10% increase in frequency means a lot
+larger increase in heating). In consequence, for permanent
+overclocking you might want to educate yourself about
+ways to add cooling fans to the board in a way that does
+not affect warranty. A very recommendable source is
+the "3Dfx Voodoo Heat Report" by Eric van Ballegoie,
+available on the web.
+
+
+<sect1>Where could I get additional info on &VooDoo;?
+<p>
+There is a FAQ by &c3Dfx;, which should be available
+at their
+<htmlurl
+ url="http://www.3dfx.com/voodoo/faq.html"
+ name="web site">.
+You will find retail information
+at the following locations:
+<htmlurl
+ url="http://www.3dfx.com/voodoo/sale/"
+ name="www.3dfx.com">
+and
+<htmlurl
+ url="http://www.quantum3d.com/"
+ name="www.quantum3d.com">.
+<p>
+Inofficial sites that have good info
+are "Voodoo Extreme" at
+<htmlurl
+ url="http://www.ve3d.com/"
+ name="www.ve3d.com">, and
+"Operation 3Dfx"
+at
+<htmlurl
+ url="http://www.ve3d.com/"
+ name="www.ve3d.com">.
+
+
+
+<sect>FAQ: &Glide;? &TexUs;?
+
+<sect1>What is &Glide; anyway?
+<p>
+&Glide; is a proprietary API plus drivers to access
+3D graphics accelerator hardware based on chipsets
+manufactured by &c3Dfx;. &Glide; has been developed
+and implemented for DOS, Windows, and Macintosh, and
+has been ported to Linux by Daryll Strauss.
+
+<sect1>What is &TexUs;?
+<p>
+In the distribution is a <tt>libtexus.so</tt>, which
+is the &c3Dfx; Interactive Texture Utility Software.
+It is an image processing libary and utility program
+for preparing images for use with the &c3Dfx;
+Interactive &Glide; library. Features of &TexUs; include
+file format conversion, MIPmap creation, and support for
+&c3Dfx; Interactive Narrow Channel Compression
+textures.
+<p>
+The &TexUs; utility program <tt>texus</tt>
+reads images in several popular formats (TGA, PPM,
+RGT), generates MIPmaps, and writes the
+images as &c3Dfx; Interactive textures files
+(see e.g. alpha.3df, as found in the distribution)
+or as an image file for inspection. For details
+on the parameters for <tt>texus</tt>, and the
+API, see the &TexUs; documentation.
+
+
+<sect1>Is &Glide; freeware?
+<p>
+Nope. &Glide; is neither GPL'ed nor subject to any other
+public license. See LICENSE in the distribution for any
+details. Effectively, by downloading and using it, you
+agree to the End User License Agreement (EULA) on the
+&c3Dfx; web site. &Glide; is provided as binary only,
+and you should
+neither use nor distribute any files but the ones released
+to the public, if you have not signed an NDA. The &Glide;
+distribution including the test program sources are
+copyrighted by &c3Dfx;.
+<p>
+The same is true for all the sources in the &Glide;
+distribution. In the words of &c3Dfx;: These are not public
+domain, but they can be freely distributed to
+owners of 3Dfx products only. No card, No code!
+
+<sect1>Where do I get &Glide;?
+<p>
+The entire &c3Dfx; SDK is available for download off their
+public web-site located at
+<htmlurl
+ url="http://www.3dfx.com/software/download_glide.html"
+ name="www.3dfx.com/software/download_glide.html">. Anything
+else &c3Dfx; publicly released by &c3Dfx; is nearby on
+their website, too.
+<p>
+There is also an FTP site,
+<htmlurl
+ url="ftp://ftp.3dfx.com/"
+ name="ftp.3dfx.com">. The FTP has a longer timeout, and some
+of the larger files have been broken into 3 files
+(approx. 3MB each).
+
+
+<sect1>Is the &Glide; source available?
+<p>
+Nope. The &Glide; source is made available only based
+on a special agreement and NDA with &c3Dfx;.
+
+<sect1>Is Linux &Glide; supported?
+<p>
+Currently, Linux &Glide; is unsupported. Basically,
+it is provided under the same disclaimers
+as the 3Dfx GL DLL (see below).
+<p>
+However, &c3Dfx; definitely wants to provide as much
+support as possible, and is in the process of
+setting up some prerequisites. For the time being,
+you will have to rely on the &c3Dfx; newsgroup (see
+below).
+<p>
+In addition, the Quantum3D web page claims that
+Linux support (for Obsidian) is planned for both Intel
+and AXP architecture systems in 2H97.
+
+<sect1>Where could I post &Glide; questions?
+<p>
+There are newsgroups currently available only on
+the NNTP server <htmlurl
+ url="news://news.3dfx.com/"
+ name="news.3dfx.com"> run by 3Dfx.
+This USENET groups are dedicated to
+&c3Dfx; and &Glide; in general, and will mainly provide
+assistance for DOS, Win95, and NT. The current
+list includes:
+<code>
+3dfx.events
+3dfx.games.glquake
+3dfx.glide
+3dfx.glide.linux
+3dfx.products
+3dfx.test
+</code>
+and the <tt>3dfx.oem.products.*</tt> group for
+specific boards, eg. <tt>3dfx.oem.products.quantum3d.obsidian</tt>.
+Please use
+<htmlurl
+ url="news://news.3dfx.com/3dfx.glide.linux"
+ name="news.3dfx.com/3dfx.glide.linux"> for all
+Lnux &Glide; related questions.
+<p>
+A mailing list dedicated to Linux &Glide; is in preparation
+for 1Q98. Send mail to
+<htmlurl
+ url="mailto:majordomo@gamers.org"
+ name="majordomo@gamers.org">, no subject,
+body of the message <tt>info linux-3dfx</tt> to get
+information about the posting guidelines, the
+hypermail archive and how
+to subscribe to the list or the digest.
+
+
+<sect1>Where to send bug reports?
+<p>
+Currently, you should rely on the newsgroup (see above),
+that is
+<htmlurl
+ url="news://news.3dfx.com/3dfx.glide.linux"
+ name="news.3dfx.com/3dfx.glide.linux">.
+There is no official support e-mail set up yet.
+For questions not specific to Linux Glide, make sure
+to use the other newsgroups.
+
+<sect1>Who is maintaining it?
+<p>
+&c3Dfx; will appoint an official maintainer soon.
+Currently, inofficial maintainer of the Linux
+&Glide; port is Daryll Strauss. Please post
+bug reports in the newsgroup (above). If you
+are confident that you found a bug not previously
+reported, please mail to Daryll at
+<htmlurl
+ url="mailto:daryll@harlot.rb.ca.us"
+ name="daryll@harlot.rb.ca.us">
+
+<sect1>How can I contribute to Linux &Glide;?
+<p>
+You could submit precise bug reports. Providing sample
+programs to be included in the distribution is another
+possibility. A major contribution would be adding
+code to the &Glide; based &VooMesa; driver source.
+See section on &VooMesa; below.
+
+
+<sect1>Do I have to use &Glide;?
+<p>
+Yes. As of now, there is no other &VooDoo; driver available
+for Linux. At the lowest level, &Glide; is the only interface
+that talks directly to the hardware. However, you
+can write &OGL; code without knowing anything about &Glide;,
+and use &Mesa; with the &Glide; based &VooMesa; driver.
+It helps to be aware of the involvement of &Glide; for
+recognizing driver limitations and bugs, though.
+<!-- p>
+For Win32 there is also OpenGVS, a cross platform high level
+graphics API (located somewhere between the level of
+&OGL; and IRIS Performer or OpenInventor). Quantum 3D is the
+sole distributor of OpenGVS, contact is
+John Archdeacon
+<htmlurl
+ url="mailto:John Archdeacon <jarch@gemtech.com>"
+ name="jarch@gemtech.com"> -->
+
+
+<sect1>Should I program using the Glide API?
+<p>
+That depends on the application you are heading for.
+&Glide; is a proprietary API that is partly similar
+to &OGL; or &Mesa;, partly contains features
+only available as EXTensions to some &OGL;
+implementations, and partly contains features not
+available anywhere but within &Glide;.
+<p>
+If you want to use the &OGL; API, you will need
+&Mesa; (see below).
+&Mesa;, namely the &VooMesa; driver, offers an
+API resembling the well documented and widely
+used OpenGL API. However, the &VooMesa; driver
+is in early alpha, and you will have to accept
+performance losses and lack of support for some
+features.
+<p>
+In summary, the decision is up to you - if you
+are heading for maximum performance while
+accepting potential problems with porting to
+non-&c3Dfx; hardware, &Glide; is not a bad
+choice. If you care about maintenance, &OGL;
+might be the best bet in the long run.
+
+
+<sect1>What is the &Glide; current version?
+<p>
+The current version of Linux &Glide; is &GlVer;.
+The next version will probably be identical to
+the current version for DOS/Windows, which is 2.4.3,
+which comes in two distributions. Right now, various
+parts of &Glide; are different for &VooRush; (VR)
+and &VooDoo; (VG) boards. Thus you have to pick up
+separate distributions (under Windows) for VR and VG.
+The same will be true for Linux. There will possibly
+be another chunk of code and another distribution for
+&VooD2; (V2) boards.
+<p>
+There is also a &Glide; 3.0 in preparation that
+will extend the API for use of triangle fans
+and triangle strips, and provide better state
+change optimization. Support for fans and strips
+will in some situations significantly reduce the
+amount of data sent ber triangle, and the
+&Mesa; driver will benefit from this, as
+the &OGL; API has separate modes for this. For
+a detailed explanation on this see e.g. the
+&OGL; documentation.
+
+
+<sect1>Does it support multiple &Texelfx; already?
+<p>
+Multiple &Texelfx;/TMU's can be used for single pass
+trilinear mipmapping for improvement image
+quality without performance penalty in current
+Linux &Glide; already. You will need a board
+with two &Texelfx; (that is, one of the appropriate
+Quantum3D Obsidian boards). The application needs
+to specify the use of both &Texelfx; accordingly,
+it does not happen automatically.
+<p>
+Note that because most applications are implemented for
+consumer boards with a single &Texelfx;, they might not
+query the presence of a second &Texelfx;, and thus not
+use it. This is not a flaw of &Glide; but of the
+application.
+
+
+
+<sect1>Is Linux &Glide; identical to DOS/Windows &Glide;?
+<p>
+The publicly available version of Linux &Glide; should
+be identical to the respective DOS/Windows versions.
+Delays in releasing the Linux port of newer DOS/Windows
+releases are possible.
+
+<sect1>Where to I get information on &Glide;?
+<p>
+There is exhaustive information available from
+&c3Dfx;. You could download it from their home
+page at
+<htmlurl
+ url="http://www.3dfx.com/software/download_glide.html"
+ name="www.3dfx.com/software/download_glide.html">.
+These are for free, presuming you bought a &c3Dfx;
+hardware based board. Please read the licensing regulations.
+<p>
+Basically, you should look for some of the following:
+<itemize>
+<item><em>Glide Release Notes</em>
+<item><em>Glide Programming Guide</em>
+<item><em>Glide Reference Manual</em>
+<item><em>Glide Porting Guide</em>
+<item><em>TexUs Texture Utility Software</em>
+<item><em>ATB Release Notes</em>
+<item><em>Installing and Using the Obsidian</em>
+</itemize>
+These are available as Microsoft Word documents, and
+part of the Windows Glide distribution, i.e.
+the self-extracting archive file. Postscript copies
+for separate download should be available at
+<htmlurl
+url="http://www.3dfx.com/software/download_glide.html"
+name="www.3dfx.com"> as well. Note that the release
+numbers are not always in sync with those of &Glide;.
+
+
+<sect1>Where to get some &Glide; demos?
+<p>
+You will find demo sources for &Glide; within the
+distribution (test programs), and on the &c3Dfx; home
+page. The problem with the latter is that some require
+ATB. To port these demos to Linux, the event handling
+has to be completely rewritten.
+<p>
+In addition, you might find useful some of the &OGL;
+demo sources accompanying Mesa and GLUT. While
+the &Glide; API is different from the &OGL; API,
+they target the same hardware rendering pipeline.
+
+
+<sect1>What is ATB?
+<p>
+Some of the &c3Dfx; demo programs for &Glide; depend
+not only on &Glide; but also on &c3Dfx;'s proprietary Arcade
+Toolbox (ATB), which is available for DOS and Win32,
+but has not been ported for Linux. If you are a devleoper,
+the sources are available within the Total Immersion
+program, so porting ATB to Linux would be possible.
+<p>
+
+<sect>FAQ: &Glide; and XFree86?
+<p>
+<sect1>Does it run with XFree86?
+<p>
+Basically, the &VooDoo; hardware does not care about X. The
+X server will not even notice that the video signal generated
+by the VGA hardware does not reach the display in single screen
+configurations. If your application is not written X aware,
+&Glide; switching to full screen mode might cause problems
+(see troubleshooting section). If you do not want the overhead
+of writing an X11-aware application, you might want to use
+SVGA console mode instead.
+<p>
+So yes, it does run with XFree86, but no, it is not cooperating
+if you don't write your application accordingly. You can use
+the &Mesa; "window hack", which will be significantly slower
+than fullscreen, but still a lot faster than software rendering
+(see section below).
+
+
+<sect1>Does it only run full screen?
+<p>
+See above. The &VooDoo; hardware is not window environment
+aware, neither is Linux &Glide;. Again, the experimental
+&Mesa; "window hack" covered below will allow for pasting
+the &VooDoo; board framebuffer's content into an X11 window.
+
+
+<sect1>What is the problem with AT3D/&VooRush; boards?
+<p>
+There is an inherent problem when using
+&VooRush; boards with Linux: Basically, these
+boards are meant to be VGA 2D/3D accelerator
+boards, either as a single board solution,
+or with a &VooRush; based daughterboard used
+transparently. The VGA component tied to the
+&VooRush; is a Alliance Semiconductor's
+ProMotion-AT3D multimedia accelerator.
+To use this e.g. with XFree86 at all, you need
+a driver for the AT3D chipset.
+<p>
+There is a mailing list on this, and a web site
+with FAQ at
+<htmlurl
+ url="http://www.frozenwave.com/linux-stingray128"
+ name="www.frozenwave.com/linux-stingray128">.
+Look there for most current info.
+There is a SuSE maintained driver at
+<htmlurl
+ url="ftp://ftp.suse.com/suse_update/special/xat3d.tgz"
+ name="ftp.suse.com/suse_update/special/xat3d.tgz">.
+Reportedly, the XFree86 SVGA server also
+works, supporting 8, 16 and 32 bpp.
+Official support will probably be in XFree86 4.0.
+XFree86 decided to prepare an intermediate XFree86 3.3.2
+release as well, which might already address the issues.
+<p>
+The
+following <tt>XF86Config</tt> settings reportedly work.
+<code>
+# device section settings
+Chipset "AT24"
+Videoram 4032
+
+# videomodes tested by Oliver Schaertel
+# 25.18 28.32 for 640 x 480 (70hz)
+# 61.60 for 1024 x 786 (60hz)
+# 120 for 1280 x 1024 (66hz)
+</code>
+In summary, there is nothing prohibiting this except
+for the fact that the drivers in XFree86 are not yet
+finished.
+<p>
+If you want a more technical explanation: &VooRush; support
+requires X server changes to support grabbing a buffer
+area in the video memory on the AT3D board, as the &VooRush;
+based boards need to store their back buffer and z buffer
+there. This memory allocation and locking requirement is not
+a &c3Dfx; specific problem, it is also needed e.g. for
+support of TV capture cards, and is thus under active
+development for XFree86. This means changes at the
+device dependend X level (thus XAA), which are currently
+implemented as an extension to XFree86 DGA (Direct Graphics
+Access, an X11 extension proposal implemented in different ways
+by Sun and XFree86, that is not part of the final X11R6.1
+standard and thus not portable). It might be part of an
+XFree86 GLX implementation later on. The currently distributed
+X servers assume they have full control of the framebuffer,
+and use anything that is not used by the visual region of the
+framebuffer as pixmap cache, e.g. for caching fonts.
+
+
+<sect1>What about GLX for XFree86?
+<p>
+There are a couple of problems.
+<p>
+The currently supported &VooDoo; hardware and the available
+revision of Linux &Glide; are full screen only, and not set up
+to share a framebuffer with a window environment. Thus GLX
+or other integration with X11 is not yet possible.
+<p>
+The &VooRush; might be capable of cooperating with XFree86
+(that is, an SVGA compliant board will work with the
+XFree86 SVGA server),
+but it is not yet supported by Linux &Glide;, nor do
+S3 or other XFree86 servers support these boards yet.
+<p>
+In addition, GLX is tied to &OGL; or, in the Linux case, to &Mesa;.
+The XFree86 team is currently working on integrating Mesa with
+their X Server. GLX is in beta, XFree86 3.3 has the hooks for GLX.
+See Steve Parker's GLX pages at
+<htmlurl
+ url="http://www.cs.utah.edu/~sparker/xfree86-3d/"
+ name="www.cs.utah.edu/~sparker/xfree86-3d/">
+for the most recent information.
+Moreover, there is a joint effort by XFree86 and
+SuSe, which includes a GLX, see
+<htmlurl
+ url="http://www.suse.de/~sim/"
+ name="www.suse.de/~sim/">.
+Currently, &Mesa; still uses its GLX emulation with Linux.
+
+
+<sect1>&Glide; and commerical X Servers?
+<p>
+I have not received any mail regarding use
+of &Glide; and/or Mesa with commercial X Servers.
+I would be interested to get confirmation on this,
+especially on Mesa and &Glide; with a commercial
+X Server that has GLX support.
+
+
+<sect1>&Glide; and SVGA?
+<p>
+You should have no problems running &Glide; based applications
+either single or dual screen using VGA modes. It might be a good
+idea to set up the 640x480 resolution in the SVGA modes, too,
+if you are using a single screen setup.
+
+<sect1>&Glide and GGI?
+<p>
+A GGI driver for &Glide; is under development by Jon
+M. Taylor, but has not officially been released and was put
+on hold till completion of GGI 0.0.9. For information about
+GGI see
+<htmlurl
+ url="http://synergy.caltech.edu/~ggi/"
+ name="synergy.caltech.edu/~ggi/">.
+If you are adventurous,
+you might find the combination of XGGI (a GGI based
+X Server for XFree86) and GGI for &Glide; an interesting
+prospect. There is also a GGI driver interfacing the
+&OGL; API; tested with unaccelerated Mesa. Essentially,
+this means X11R6 running on a &VooDoo;, using
+either Mesa or &Glide; directly.
+
+
+
+<sect>FAQ: &OGL;/&Mesa;?
+
+<sect1>What is &OGL;?
+<p>
+&OGL; is an immediate mode graphics programming API
+originally developed by SGI based on their previous
+proprietary Iris GL, and became in industry standard
+several years ago. It is defined and maintained by
+the Architectural Revision Board (ARB), an organization
+that includes members as SGI, IBM, and DEC, and Microsoft.
+<p>
+&OGL; provides a complete feature set for 2D and
+3D graphics operations in a pipelined hardware
+accelerated architecture for triangle and polygon
+rendering. In a broader sense, &OGL; is a powerful
+and generic toolset for hardware assisted computer
+graphics.
+
+
+<sect1>Where to get additional information on OpenGL?
+<p>
+The official site for &OGL; maintained by the members
+of the ARB, is
+<htmlurl
+ url="http://www.opengl.org/"
+ name="www.opengl.org">,
+<p>
+A most recommended site is Mark Kilgard's Gateway to &OGL;
+Info at
+<htmlurl
+ url="http://reality.sgi.com/mjk_asd/opengl-links.html"
+ name="reality.sgi.com/mjk_asd/opengl-links.html">:
+it provides pointers to book, online manual pages, GLUT,
+GLE, Mesa, ports to several OS, tons of demos and tools.
+<p>
+If you are interested in game programming using &OGL;,
+there is the <tt>OpenGL-GameDev-L@fatcity.com</tt> at
+<tt>Listserv@fatcity.com</tt>. Be warned, this is
+a high traffic list with very technical content, and
+you will probably prefer to use <tt>procmail</tt> to
+handle the 100 messages per day coming in. You cut
+down bandwidth using the
+ <tt>SET OpenGL-GameDev-L DIGEST</tt>
+command. It is also
+not appropriate if you are looking for introductions.
+The archive is handled by the ListServ software, use
+the
+ <tt>INDEX OpenGL-GameDev-L</tt>
+and
+ <tt>GET OpenGL-GameDev-L "filename"</tt>
+commands to get a preview before subscribing.
+
+
+
+<sect1>Is Glide an &OGL; implementation?
+<p>
+No, &Glide; is a proprietary &c3Dfx; API which several features
+specific to the &VooDoo; and &VooRush;. A &c3Dfx; OpenGL is
+in preparation (see below). Several Glide features would require
+EXTensions to OpenGL, some of which already found in other
+implementations (e.g. paletted textures).
+<p>
+The closest thing to a hardware accelerated Linux &OGL;
+you could currently get is Brian Paul's &Mesa;
+along with David Bucciarelli's &VooMesa; driver (see below).
+
+
+<sect1>Is there an &OGL; driver from &c3Dfx;?
+<p>
+Both the &c3Dfx; website and the Quantum3D website
+announced &OGL; for &VooDoo; to be available 4Q97.
+The driver is currently in Beta, and accessible only
+to registered deverloper's under written Beta test
+agreement.
+<p>
+A linux port has not been announced yet.
+
+
+<sect1>Is there a commercial &OGL; for Linux and &c3Dfx;?
+<p>
+I am not aware of any third party commercial OpenGL
+that supports the &VooDoo;. Last time I paid attention,
+neither MetroX nor XInside OpenGL did.
+
+
+<sect1>What is Mesa?
+<p>
+Mesa is a free implementation of the &OGL; API, designed
+and written by Brian Paul, with contributions from many
+others. Its performance is competitive, and while it
+is not officially certified, it is an almost fully
+compliant &OGL; implementation conforming to the ARB
+specifications - more complete than some commercial
+products out, actually.
+
+
+<sect1>Does Mesa work with &c3Dfx;?
+<p>
+The latest &Mesa; MesaVer; release works with
+Linux &Glide; &GlVer;. In fact, support was included
+in earlier versions, however, this driver is still under
+development, so be prepared for bugs and less than optimal
+performance. It is steadily improving, though, and bugs
+are usually fixed very fast.
+<p>
+You will need to get the Mesa library archive
+from the
+<htmlurl
+ url="ftp://iris.ssec.wisc.edu/"
+ name="iris.ssec.wisc.edu FTP site">.
+It is recommended to subscribe to the mailing list
+as well, especially when trying to track down bugs,
+hardware, or driver limitations. Make sure to get
+the most recent distribution. A Mesa-3.0 is in
+preparation.
+
+
+<sect1>How portable is &Mesa; with &Glide;?
+<p>
+It is available for Linux and Win32, and any application
+based on Mesa will only have the usual system specific
+code, which should usually mean XWindows vs. Windows,
+or GLX vs. WGL. If you use e.g. GLUT or Qt, you should
+get away with any system specifics at all for virtually
+most
+applications. There are only a few issues (like sampling
+relative mouse movement) that are not adressed by the
+available portable GUI toolkits.
+<p>
+&Mesa;/&Glide; is also available for DOS. The port
+which is 32bit DOS is maintained by Charlie Wallace
+and kept up to date with the main Mesa base. See
+<htmlurl
+ url="http://www.geocities.com/~charlie_x/"
+ name="www.geocities.com/~charlie_x/">.for the
+most current releases.
+
+
+<sect1>Where to get info on &Mesa;?
+<p>
+The &Mesa; home page is at
+<htmlurl
+ url="http://www.ssec.wisc.edu/~brianp/Mesa.html"
+ name="www.ssec.wisc.edu/~brianp/Mesa.html">.
+There is an archive of the Mesa mailing list.
+at
+<htmlurl
+ url="http://www.iqm.unicamp.br/mesa/"
+ name="www.iqm.unicamp.br/mesa/">. This list is
+not specific to &c3Dfx; and &Glide;, but if
+you are interested in using &c3Dfx; hardware
+to accelerate &Mesa;, it is a good place to
+start.
+
+<sect1>Where to get information on &VooMesa;?
+<p>
+For latest information on the &VooMesa; driver
+maintained by David Bucciarelli
+<htmlurl
+ url="mailto:tech.hmw@plus.it"
+ name="tech.hmw@plus.it">
+see the home page at
+<htmlurl
+ url="http://www-hmw.caribel.pisa.it/fxmesa/index.shtml"
+ name="www-hmw.caribel.pisa.it/fxmesa/">.
+
+
+
+<sect1>Does Mesa support multitexturing?
+<p>
+Not yet (as of &Mesa; &MesaVer;), but it is on the list.
+In &Mesa; you will probably have to use the &OGL;
+<tt>EXT_multitexture</tt> extension once it is
+available. There is no final specification for
+multitextures in &OGL;, which is supposed to be
+part of the upcoming &OGL; 1.2 revision. There might
+be a &Glide; driver specific implementation of
+the extension in upcoming Mesa releases, but as
+long as only certain Quantum3D Obsidian boards come
+with multiple TMU's, it is not a top priority. This
+will surely change once &VooD2; based boards are in
+widespread use.
+
+
+
+
+<sect1>Does Mesa support single pass trilinear mipmapping?
+<p>
+Multiple TMU's should be used for single pass
+trilinear mipmapping for improvement image
+quality without performance penalty in current
+Linux &Glide; already. Mesa support is not
+yet done (as of &Mesa; &MesaVer;), but is in
+preparation.
+
+
+
+<sect1>What is the Mesa "Window Hack"?
+<p>
+The most recent revisions of Mesa contain an experimental
+feature for Linux XFree86. Basically, the GLX emulation
+used by Mesa copies the contents of the &VooDoo; board's
+most recently finished framebuffer content into video
+memory on each <tt>glXSwapBuffers</tt> call. This feature
+is also available with Mesa for Windows.
+<p>
+This obviously puts some drain on the PCI, doubled by
+the fact that this uses X11 MIT SHM, not XFree86 DGA
+to access the video memory. The same approach could
+theoretically be used with e.g. SVGA. The major benefit
+is that you could use a &VooDoo; board for accelerated
+rendering into a window, and that you don't have to
+use the VGA passthrough mode (video output
+of the VGA board deteoriates in passing through,
+which is very visible with high end monitors like
+e.g. EIZO F784-T).
+<p>
+Note that this experimental feature is <em>NOT</em>
+&VooRush; support by any means. It applies only
+to the &VooDoo; based boards. Moreover, you need to
+use a modified GLUT, as interfacing the window
+management system and handling the events appropriately
+has to be done by the application, it is not handled
+in the driver.
+<p>
+Make really sure that you have enabled the
+following environment variables:
+<code>
+export SST_VGA_PASS=1 # to stop video signal switching
+export SST_NOSHUTDOWN=1 # to stop video signal switching
+export MESA_GLX_FX="window" # to initiate Mesa window mode
+</code>
+If you manage to forget one of the SST variables, your
+VGA board will be shut off, and you will loose the
+display (but not the actual X). It is pretty hard to
+get that back being effectively blind.
+<p>
+Finally, note that the libMesaGL.a (or .so) library can contain
+multiple client interfaces. I.e. the GLX, OSMesa, and fxMesa
+(and even SVGAMesa) interfaces call all be compiled into the
+same libMesaGL.a. The client program can use any of them freely,
+even simultaneously if it's careful.
+
+
+
+
+<sect1>How about GLUT?
+<p>
+Mark Kilgard's GLUT distribution is a very good place to
+get sample applications plus a lot of useful utilities.
+You will find it at
+<htmlurl
+ url="http://reality.sgi.com/mjk_asd/glut3/glut3.html"
+ name="reality.sgi.com/mjk_asd/glut3/">,
+and you should get it anyway. The current release is
+GLUT 3.6, and discussion on a GLUT 3.7 (aka GameGLUT)
+has begun. Note that Mark Kilgard has left SGI recently,
+so the archive might move some time this year - for the
+time being it will be kept at SGI.
+<p>
+There is also a GLUT mailing list,
+<tt>glut@perp.com</tt>. Send mail to
+<htmlurl
+ url="mailto:Majordomo@perp.com"
+ name="majordomo@perp.com">,
+with the (on of the) following
+in the body of your email message:
+<code>
+ help
+ info glut
+ subscribe glut
+ end
+</code>
+<p>
+As GLUT handles double buffers, windows, events,
+and other operations closely tied to hardware and operating
+system, using GLUT with &VooDoo; requires support, which
+is currently in development within GLX for Mesa. It
+already works for most cases.
+
+
+<sect>FAQ: But Quake?
+
+<sect1>What about that &c3Dfx; GL driver for Quake?
+<p>
+The &c3Dfx; Quake GL, aka mini-driver, aka miniport,
+aka Game GL, aka &c3Dfx; GL alpha, implemented only a
+Quake-specific subset of OpenGL (see
+<htmlurl
+url="http://www.cs.unc.edu/~martin/3dfx.html"
+name="http://www.cs.unc.edu/~martin/3dfx.html"> for
+an inofficial list of supported code paths). It is
+not supported, and not updated anymore.
+It was a Win32 DLL (<tt>opengl32.dll</tt>) released
+by &c3Dfx; and was available for Windows only. This
+DLL is not, and will not be ported to Linux.
+
+<sect1>Is there a &c3Dfx; based glQuake for Linux?
+<p>
+Yes. A Quake linuxquake v0.97 binary has been released
+based on Mesa with Glide. The Quake2 q2test binary
+for Linux and &VooDoo; has been made available as well.
+A full Quake2 for Linux was released in January 1998,
+with linuxquake2-3.10. Dave "Zoid" Kirsch is the
+official maintainer of all Linux ports of Quake,
+Quakeworld, and Quake2, including all the recent
+&Mesa; based ports. Note that all Linux ports, including
+the &Mesa; based ones, are not officially supported by
+id Software.
+<p>
+See
+<htmlurl
+url="ftp://ftp.idsoftware.com/idstuff/quake/unix/"
+name="ftp.idsoftware.com/idstuff/quake/unix/"> for
+the latest releases.
+
+<sect1>Does glQuake run in an XFree86 window?
+<p>
+A revision of &Mesa; and the &Mesa;-based Linux glQuake
+is in preparation. &Mesa; already does support this
+by GLX, but Linux glQuake does not use GLX.
+
+
+<sect1>Known Linux Quake problems?
+<p>
+Here is an excerpt, as of January 7th, 1998. I omitted
+most stuff not specific to &3Dfx; hardware.
+<itemize>
+<item>
+ You really should run Quake2 as root when using the SVGALib and/or GL
+ renders. You don't have to run as root for the X11 refresh, but the modes
+ on the mouse and sound devices must be read/writable by whatever user you
+ run it as. Dedicated server requires no special permissions.
+<item>
+ X11 has some garbage on the screen when 'loading'. This is normal in 16bit
+ color mode. X11 doesn't work in 24bit (TrueColor). It would be very slow
+ in any case.
+<item>
+ Some people are experiencing crashes with the GL renderer. Make sure you
+ install the libMesa that comes with Quake2! Older versions of libMesa don't
+ work properly.
+<item>
+ If you are experience video 'lag' in the GL renderer (the frame rate feels
+ like it's lagging behind your mouse movement) type "gl_finish 1" in the
+ console. This forces update on a per frame basis.
+<item>
+ When running the GL renderer, make sure you have killed selection and/or
+ gpm or the mouse won't work as they won't "release" it while Quake2 is
+ running in GL mode.
+</itemize>
+
+<sect1>Know Linux Quake security problems?
+<p>
+As Dave Kirsch posted on January 28th, 1998: an exploit
+for Quake2 under Linux has been published. Quake2 is using
+shared libraries. While the READMRE so far does not
+specifically mention it, note that Quake2 should not be
+<tt>setuid</tt>.
+<p>
+If you want to use the <tt>ref_soft</tt> and <tt>ref_gl</tt>
+renderers, you should run Quake2 as root. Do not make the
+binary setuid. You can only run both those renderers at
+the console only, so being root is not that much of an issue.
+<p>
+The X11 render does not need any root permissions
+(if <tt>/dev/dsp</tt> is writable by others for sound).
+The dedicated server mode does not need to be root either,
+obviously.
+<p>
+Problems such as root requirements for games has been sort
+of a sore spot in Linux for a number of years now. This is
+one of the goals that e.g. GGI is targetting to fix.
+A <tt>ref_ggi</tt> might be supported in the near future.
+
+<sect1>Does LinuxQuake use multitexturing?
+<p>
+To my understadnding, glQuake will use a multitexture
+EXTension if the &OGL; driver in question offers it.
+The current Mesa implementation and the &Glide; driver
+for Linux do not yet support this extension, so for the
+time being the answer is no. See section on Mesa and
+multitexturing for details.
+
+
+<sect1>Where can I get current information on Linux glQuake?
+<p>
+Try some of these sites: the "The Linux Quake Resource" at
+<htmlurl
+url="http://linuxquake.telefragged.com/"
+name="linuxquake.telefragged.com">, or
+the "Linux Quake Page" at
+<htmlurl
+url="http://www.planetquake.com/threewave/linux/"
+name="www.planetquake.com/threewave/linux/">.
+Alternatively, you could look for Linux Quake sites
+in the "SlipgateCentral" database at
+<htmlurl
+url="http://www.slipgatecentral.com/"
+name="www.slipgatecentral.com">.
+
+
+
+<sect>FAQ: Troubleshooting?
+
+<sect1>Has this hardware been tested?
+<p>
+See hardware requirements list above. I currently do not
+maintain a conclusive list of vendors and boards, as no
+particular board specific problems have been verified.
+Currently, only &c3Dfx; and Quantum3D provide boards
+for testing to the developers, so Quantum3D consumer
+boards are a safe bet. Every other &VooDoo; based board
+should work, too. I have reports regarding the
+Orchid Righteous 3D, Guillemot Maxi 3D Gamer, and
+Diamond Monster 3D.
+<p>
+If you are a board manufacturer who wants to make
+sure his &VooDoo;, &VooRush; or &VooD2; boards work
+with upcoming releases of Linux, Xfree86, Linux &Glide;
+and/or Mesa, please contact me, and I will happily forward
+your request to the persons maintaining the drivers in
+question. If you are interested in support for Linux &Glide;
+on other then the PC platfrom, e.g. DEC Alpha, please
+contact the maintainer of Linux &Glide; Daryll Strauss, at
+<htmlurl
+ url="mailto:daryll@harlot.rb.ca.us"
+ name="daryll@harlot.rb.ca.us">
+
+
+<sect1>Failed to change I/O privilege?
+<p>
+You need to be root, or <tt>setuid</tt> your
+application to run a &Glide; based application.
+For DMA, the driver accesses <tt>/dev/mem</tt>,
+which is not writeable for anybody but root,
+with good reasons. See the README in the
+&Glide; distribution for Linux.
+
+
+<sect1>Does it work without root privilege?
+<p>
+There are compelling case where the setuid requirement is a
+problem, obviously. There are currently solutions in
+preparation, which require changes to the library internals
+itself.
+
+
+<sect1>Displayed images looks awful (single screen)?
+<p>
+If you are using the analog pass through configuration,
+the common SVGA or X11 display might look pretty bad.
+You could try to get a better connector cable than
+the one provided with the accelerator board (the
+ones delivered with the Diamond Monster 3D are
+reportedly worse then the one accompanying the
+Orchid Righteous 3D), but up to a degree there will
+inevitably be signal loss with an additional
+transmission added.
+<p>
+If the 640x480 full screen image created by the
+accelerator board does look awful, this might indicate
+a real hardware problem. You will have to contact
+the board manufacturer, not &c3Dfx; for details, as
+the quality of the video signal has nothing to do
+with the accelerator - the board manufacturer chooses
+the RAMDAC, output drivers, and other components
+responsible.
+
+
+<sect1>The last frame is still there (single or dual screen)?
+<p>
+You terminated your application with Ctrl-C, or it
+did not exit normally. The accelerator board will
+dutifully provide the current content of the
+framebuffer as a video signal unless told otherwise.
+
+
+<sect1>Powersave kicks in (dual screen)?
+<p>
+When you application terminates in dual screen setups,
+the accelerator board does not provide video output
+any longer. Thus powersave kicks each time. To avoid
+this, use
+<code>
+setenv SST_DUALSCREEN 1
+</code>
+
+
+<sect1>My machine seem to lock (X11, single screen)?
+<p>
+If you are running X when calling a &Glide;
+application, you probably moved the mouse out
+of the window, and the keyboard inputs do
+not reach the application anymore.
+<p>
+If you application is supposed to run concurrently
+with X11, it is recommend to expose a full screen
+window, or use the <tt>XGrabPointer</tt> and
+<tt>XGrabServer</tt>
+functions to redirect all inputs to the application
+while the X server cannot access the display. Note
+that grabbing all input with <tt>XGrabPointer</tt> and
+<tt>XGrabServer</tt> does not qualify as well-behaved
+application, and that your program might block the
+entire system.
+<p>
+If you experience this problem without running X,
+be sure that there is no hardware conflict (see below).
+
+<sect1>My machine locks (single or dual screen)?
+<p>
+If the system definitely does not respond to any inputs
+(you are running two displays and know about the loss
+of focus), you might experience a more or less
+subtle hardware conflict.
+See installation troubleshooting section for details.
+<p>
+If there is no obvious address conflict, there might
+still be other problems (below). If you are writing your
+own code the most common reason for locking is that you
+didn't snap your vertices. See the section on snapping
+in the &Glide; documentation.
+
+<sect1>My machine locks (used with S3 VGA board)?
+<p>
+It is possible you have a problem with memory
+region overlap specific to S3. There is some
+info and a patch to the so-called S3 problem
+in the &c3Dfx; web site, but these apply to Windows
+only. To my understanding, the cause of the problem
+is that some S3 boards (older revisions of Diamond
+Stealth S3 968) reserve more memory space than
+actually used, thus the &VooDoo; has to be mapped
+to a different location. However, this has not
+been reported as a problem with Linux, and might
+be Windows-specific.
+
+
+<sect1>No address conflict, but locks anyway?
+<p>
+If you happen to use a motherboard with non-standard
+or incomplete PCI support, you could try to
+shuffle the boards a bit. I am running an ASUS
+TP4XE that has that non-standard modified "Media Slot",
+i.e. PCI slot4 with additional connector for
+ASUS-manufactured SCSI/Sound combo boards,
+and I experienced severe problems while running a
+Diamond Monster 3D in that slot. The system operates
+flawlessly since I put the board in one of the
+regular slots.
+
+
+<sect1>Mesa runs, but does not access the board?
+<p>
+Be sure that you recompiled all the libraries (including
+the toolkits the demo programs use - remember that
+GLUT does not yet support &VooDoo;), and that you
+removed the older libraries, run <tt>ldconfig</tt>,
+and/or set your <tt>LD_LIBRARY_PATH</tt> properly.
+&Mesa; supports several drivers in parallel (you could
+use X11 SHM, off screen rendering, and &VooMesa; at
+the same time), and you might have to create and
+switch contexts explicitely (see <tt>MakeCurrent</tt>
+function) if the &VooDoo; isn't chosen by default.
+
+
+<sect1>Resetting dual board SLI?
+<p>
+If a Quantum 3D Obsidian board using in an SLI setup
+exits abruptly (i.e., the application crashes, or is
+aborted by user), the boards are left in an undefined
+state. With the dual-board set, you can run a
+program called <tt>resetsli</tt> to reset them. Until
+you run the <tt>resetsli</tt> program, you will not
+be able to re-initialize the Obsidian board.
+
+
+<sect1>Resetting single board SLI?
+<p>
+The <tt>resetsli</tt> program mentioned above does not
+yet work with a single board Obsidian SLI (e.g. the
+Obsidian 100-4440SB). You will have to reboot your
+system by reset in order to reset the board.
+
+
+</article>
+
+
+
+
+<!-- ================================================= -->
+<!-- end of Linux3Dfx.sgml -->
+<!--
+ Local Variables:
+ mode: sgml
+ End: -->
+<!-- ================================================= -->
diff --git a/LDP/retired/BTI-PPP.sgml b/LDP/retired/BTI-PPP.sgml
new file mode 100644
index 00000000..69e5ee08
--- /dev/null
+++ b/LDP/retired/BTI-PPP.sgml
@@ -0,0 +1,882 @@
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
+<article>
+
+<artheader>
+ <title>BTinternet pppd mini-HOWTO
+
+
+ Matt
+ Wright
+
+ Matt Wright Consulting
+
+ matt@consultmatt.co.uk
+
+
+
+
+
+ Greg
+ Ferguson
+ Converted the mini-HOWTO from HTML to Docbook 3.1 (SGML).
+
+
+ 2002-03-26
+
+
+
+ v0.29
+ 2002-03-26
+ mww
+
+ Added a small bit of first-hand tech support about
+ cross-talk. Thanks goto Bill Staehle once again for typing,
+ technical and grammar points.
+
+
+
+ v0.28
+ 2002-01-17
+ mww
+
+ New information about PPPoATM involving kernels and
+ distibutions.
+
+
+
+ v0.27
+ 2001-12-20
+ mww
+
+ Minor technical problems highlighted by Robert Smith.
+
+
+
+ v0.26
+ 2001-11-21
+ mww
+
+ Added a point about the Kernel HOWTO.
+
+
+
+ v0.25
+ 2001-11-17
+ mww
+
+ Added a troubleshooting answer about "_mmx_memcpy". Other minor updates as well.
+
+
+
+ v0.24
+ 2001-11-09
+ mww
+
+ Technical detail with the chatscript timeout (and found a spelling mistake or two!). Thanks again to Bill Staehle.
+
+
+
+ v0.23
+ 2001-11-07
+ mww
+
+ Changed the Chatscript dialing method, thanks go to TonyC from btinternet.linux newsgroup.
+
+
+
+ v0.22
+ 2001-11-06
+ mww
+
+ Changed a couple more little botches. Thanks again go to Bill Staehle.
+
+
+
+ v0.21
+ 2001-11-03
+ mww
+
+ Changed discrepancies reported by Bill Staehle.
+
+
+
+ v0.20
+ 2001-11-01
+ mww
+
+ Added Alcatel Speedtouch Information.
+
+
+
+ v0.19
+ 2001-10-31
+ mww
+
+ Initial public release.
+
+
+
+
+
+
+ This document describes how to setup a modem pppd link to
+ Btinternet in the UK.
+
+
+
+
+
+
+Introduction
+
+This HOWTO exists because a mate of mine needed to easily set up an
+Internet connection to BTinternet and here is a quick and concise way
+to get a running PPPd to Btinternet. This HOWTO also briefly covers
+Howto setup basic IP Masquerading to allow connection sharing.
+
+
+
+Copyright and License
+
+This document is Copyright 2001 by Matt Wright. Permission is granted
+to copy, distribute and/or modify this document under the terms of
+the GNU Free Documentation License, Version 1.1 or any later version
+published by the Free Software Foundation; with no Invariant
+Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A
+copy of the license is available at
+http://www.gnu.org/copyleft/fdl.html
+
+
+Send feedback to
+matt@consultmatt.co.uk.
+
+
+
+
+
+Mailing Lists
+
+Please note: There is a mailing list available for this howto. If you wish to join please email majordomo@consultmatt.co.uk with the body:
+
+subscribe bti-howto
+
+This will then be followed up by the mailing list bot and subsequent emails should arrive confirming your request. The list is intended to be for annoucing changes to this HOWTO and also to dicuss the finer points of getting pppd to work on BTinternet.
+
+
+
+
+About the author
+
+ My name is Matt Wright. I'm 16 year-old student in Blackburn,
+Lancashire. I'm a freelance Linux consultant. I am the proud owner of
+a Duron 950Mhz (all I could easily afford) with 256MB SDRAM, Voodoo 4
+Video Card, ATI All-in-Wonder Pro Video Card. I also have a 266Mhz Cyrix
+that runs my USB ADSL connection, of which if you are reading this from
+http://www.consultmatt.co.uk
+you will be using.
+
+
+You can find me at www.consultmatt.co.uk. Or at matt@consultmatt.co.uk.
+
+
+
+
+Acknowledgements
+A major thanks of gratitude to the guys at Linuxdoc in particular Greg Ferguson and David Merrill for help with getting this into trusty SGML. Also to Rob Smith the guy behind me writing this :) (As he couldn't sort his own Linux box out :P). A great vote of thanks to Bill Staehle for his input in ironing out some major flaws. Also a thank you goes to TonyC at btinternet.linux and the rest of that newsgroup for originally getting me on my feet with BTi. Finally and most importantly my thanks goto my Lord and Saviour Jesus Christ, without whom I'd be lost.
+
+
+
+
+
+
+Requirements
+
+The following is needed to use this HOWTO:
+
+
+
+ A working modem, external or internal hardware modems are the easiest to get working, see Modem-HOWTO. If you have a WinModem then see Winmodems and Linux HOWTO
+
+ An account with Btinternet, this HOWTO covers
+ BTi Surftime and Anytime
+
+ Some basic understanding of the Linux OS and
+ its layout
+
+
+
+
+
+Surftime
+
+
+PPPd Setup
+
+ Right, to start off you will need a working installation of
+PPPd, I know from experience that Mandrake 8.0 that sometime is
+doesn't install pppd so check its installed first. Once it is it
+usually resides in /usr/sbin/pppd check that any
+users you want to access it have setuid access.
+
+Note: Setuid allows pppd to run as-if root allowing non-superusers to run pppd without less problems. To do this use the command chmod 4750 /usr/sbin/pppd. Beware: Some distributions have a watchdog program that will change the pppd permissions back to normal. I have not tested this but on RedHat derived systems with Linuxconf installed then removing the /usr/lib/linuxconf/redhat/perm/ppp should stop this happening.
+
+
+
+
+Chatscript (Dialup)
+
+ The Chatscript is a text file, usually residing in
+/etc/ppp that contains the commands passed to
+the modem to make it dial to BTi. If you want to compare this to DUN
+in Windows then this is the phone number and init commands.
+
+ Below is the chatscript used to dial BTi, I've now opted for putting the \T metacharacter in the script. The means when we run chat, inside the pppd command, we can use a -T parameter and supply the needed telephone number.
+
+
+
+ "" "ATZ"
+
+ # The next two lines should be left commented out until
+ # the script works.
+
+ # "OK" "ATL0"
+ # "OK" "ATM0"
+
+ SAY "Dialing modem...\n"
+ "OK" "ATDT \T"
+ ABORT BUSY
+ ABORT "NO CARRIER"
+ TIMEOUT 60
+ CONNECT \c
+
+
+
+ This script will dial BTi providing you put in the \T so we can added the telephone number later. I suggest saving the chatscript as something like /etc/ppp/chatscript Once you've saved it we can move onto setting up BTi's CHAP authentication.
+
+
+
+
+
+Authentication
+
+ With PPP dialup's the most widely used authentication method,
+apparently, is PAP (Password Authentication Protocol). However, just
+to be a pain in the backside BTi use CHAP (Challenge Handshake
+Authentication Protocol). To be fair CHAP is a more secure authentication method than PAP but it's still a pain. Now PPPd does support this but not through
+nice easy to use Linuxconf dialogs.
+
+In the
+/etc/ppp directory should be a
+chap-secrets that looks roughly like this when
+first installed:
+
+
+
+ # Secrets for authentication using CHAP
+ # client server secret IP addresses
+
+
+
+ We can safely ignore the IP Address column but the others me
+must worry about. So fill in the gaps like this:
+
+
+
+ # Secrets for authentication using CHAP
+ # client server secret IP addresses
+ "bloggs@btinternet.com" * "mypasswordhere"
+
+
+
+ These two extra lines will try and authenticate ANY outgoing
+PPP connection that responds using CHAP using your BTi details. It
+goes without saying that you replace
+bloggs@btinternet.com and
+mypasswordhere with your details. Also, the second line is not strictly needed but I've found it helps sometimes.
+
+Note: If you're not using BTi at this point you can usually get away with having identical chap-secrets and pap-secrets. If you the same kind of pattern as above it should work.
+
+I suggest that you do a "chmod 600 /etc/ppp/*secrets". It was pointed out to me that it stops pppd shouting about security.
+
+
+
+
+
+Setting your global options
+
+ In your /etc/ppp directory there is a
+file called options. If your open it with your
+favourite text editor you should see:
+
+
+
+ lock
+
+
+
+ And thats it, now we need to add some more settings in here so
+make it look like:
+
+
+
+ lock
+ usepeerdns
+ defaultroute
+ noipdefault
+ noauth
+ asyncmap 0
+ crtscts
+ modem
+ 115200
+
+
+
+ Don't worry what they do, if you're interested look at the man
+page for pppd. As a passing note if you would like PPPd to redial
+dropped connections then add persist to the end
+of your options file.
+
+
+
+
+Testing your link
+
+ Now you've created your Chatscript there are only two steps
+left till you should be on the Internet. First is getting a working
+link and second is creating a couple of easy dialup scripts to help
+you.
+
+
+To test your link try this command:
+
+
+
+pppd ttyS0 connect '/usr/sbin/chat -v -TPHONE_NUM_HERE -f /etc/ppp/chatscript' updetach debug name bloggs@btinternet.com
+
+ Now obviosuly if your testing at Daytiem rate add the Daytiem number where instead of PHONE_NUM_HERE and similar with Surftime.
+ This will tell PPPd to dial the modem on ttyS0 (COM1) using the chatscript. The tells PPPd to only fork away to the commandline after the connection is established and the will show all authentication commands onscreen (providing updetach it set) while it trys to connect.
+
+ If that connected then move onto the next section and we can
+make a set of scripts to allow easy dialing.
+
+
+
+
+Dialing scripts
+
+ Here I'll just set out a set of scripts that will let your
+dial BTi from a command line easily. The following should be
+self-explanatory, the italic filename is the filename to put the data
+into and the proceeding text the file contents:
+
+/etc/ppp/peers/bt-surf
+
+
+
+ ttyS0 connect '/usr/sbin/chat -v -TSURFTIME_NUMBER_HERE -f /etc/ppp/chatscript'
+ updetach name bloggs@btinternet.com
+
+
+
+/etc/ppp/peers/bt-day
+
+
+
+ ttyS0 connect '/usr/sbin/chat -v -TDAYTIME_NUMBER HERE -f /etc/ppp/chatscript'
+ updetach name bloggs@btinternet.com
+
+
+
+ Change any of the filenames to suit what you called them and
+the username. Do the same with this:
+
+/usr/bin/internet
+
+
+
+ #!/bin/bash
+ # a script to dial BTi
+ case "$1" in
+ daytime)
+ /usr/sbin/pppd call bt-day
+ ;;
+ surftime)
+ /usr/sbin/pppd call bt-surf
+ ;;
+ off)
+ killall pppd
+ ;;
+ esac
+
+
+
+ Once you've done that run this command at the command prompt:
+
+
+chmod a+x /usr/bin/internet
+
+ Now you've done, simply type
+internet daytime/surftime/off and it
+will connect you to the internet.
+
+
+
+
+
+BTi Anytime
+
+ I'm sorry, for all you Anytime customers its really hard!
+NOT! Read all the instructions for Surftime above. They all apply in
+most places, the only things to watch out for is you obviously don't
+need any of the Surftime/daytime distinctions. So only have one
+peers file (using the correct phoen number) and one dialup option in your /usr/bin/internet file. (eg. dial and off)
+
+
+
+
+BTOpenworld Home 500 (Alcatel Speedtouch USB)
+
+
+About this section
+
+ There is rather a large amount of credit due here, to
+Chris Jones for writing the
+Alcatel
+Speedtouch USB ASDL Modem mini-HOWTO that is now part of the
+DSL HOWTO.
+This helped me a great deal when trying to get my Speedtouch to work.
+
+
+
+Warning
+
+At home I use Linux Mandrake, although the version of the kernel I had was patched with the ATM kernel source I did end up patching a different kernel source to get it working. Please, please inspect your kernel source to see if you have the PPPoATM source patched against your kernel. To do this go into you kernel source directory, usually /usr/src/linux and do a make menuconfig. In the Network Device Support section check for:
+
+
+ Network device support->PPP over ATM
+
+
+If it does exist then make sure it is present it you current kernel and you can skim-read the "Patching you kernel" section to make sure you have the correc toptions compiled in and then carry on.
+
+This was just a minor warning as I orginially had a kernel patched with PPPoATM and without realising managed to trash my kernel tree by trying to force the patch onto it.
+
+
+
+
+Distribution Specific Information
+
+I have had reports about different distros that have varying
+PPPoATM support already builtin to the kernel:
+
+
+ Mandrake 8.0: The default 2.4.3 kernel already has the
+ PPPoATM patch applied, I cannot remember if it compiled in but ignore
+ steps refering the "Patching the Kernel" below. PS: You still need to
+ configure the kernel.
+ Mandrake 8.1: Mandrake 8.1 supports the Speedtouch
+ automatically, I have no had first hand experience but from what I can
+ gather you simply have to download the Alcatel binaries and then use
+ DrakNet to sort it out.
+ Debian: I have had reports that the standard Debian
+ installtion does not include libpam, this must be installed for the
+ PPPoATM plugin modules to work.
+
+
+NOTE: From roughly kernel 2.4.16 the PPPoATM patch is included in
+Linus' main source tree. Therefore you can miss out patching the kernel
+and just configure it.
+
+
+
+Requirements
+
+ To get your Speedtouch USB working in Linux you have a fairly
+heavyweight task ahead of you, but hey, if I could do it so can you!
+This is what you'll need to get it working:
+
+
+ You must have the kernel source installed and
+ know the procedure for installing and compiling a new kernel.
+ If this is a problem then read the Kernel HOWTO.
+
+ You must be running one of the following
+ Kernels: 2.3.39, 2.4.0-test4, 2.4.1-pre7, 2.4.7, 2.4.8-pre5.
+ This is because the PPPoATM patch for the kernel exists patched
+ against specific kernels, some may work with similar kernel
+ versions but I cannot vouch for that
+
+ You, obviously, need a USB controller of some
+ description with at least one free plug. It also must be Linux
+ compatible, nowadays this is most USB controllers that are
+ UHCI/OHCI based. If you don't have one your local supplier
+ would probably have a PCI USB Controller.
+
+ A heap-load of confidence with meddling with
+ your config. eg: kernel recompiling, program
+ installation...
+
+
+
+
+Software Downloads
+
+ To get the Speedtouch working under Linux you will need some
+software and kernel patches found below:
+
+
+ The kernel patch for your kernel. They can be found at http://www.kernel.org/pub/linux/kernel/people/axboe/PPPoATM/. Please note not all the kernels have patches.
+
+ The latest SpeedTouch driver from http://sourceforge.net/project/showfiles.php?group_id=3581
+
+ The latest SARlib library from http://sourceforge.net/project/showfiles.php?group_id=22221
+
+ The Alcatel speed management software. You can get it from http://www.alcatel.com/consumer/dsl/dvrreg_lx.htm. I can't distribute this because of Alcatel's licensing scheme so get it from them.
+
+ Some description of PPPoATM aware PPPd binary:
+
+ Red Hat 7 RPM (glibc 2.2): http://sourceforge.net/project/showfiles.php?group_id=23818
+ Debian (.deb): http://sourceforge.net/project/showfiles.php?group_id=23818
+ Tarball: http://sourceforge.net/project/showfiles.php?group_id=23818
+
+
+
+ The Linux Hotplug software from http://linux-hotplug.sourceforge.net. Get it installed as per their instructions. It seemed simple enough so I won't cover it here
+
+
+
+
+Patching your kernel
+
+ Once you have the PPPoATM kernel patch (this assumes you use
+the patch against kernel 2.4.7) you need to make sure you have a
+working 2.4.7 kernel tree, next unzip the PPPoATM patch by doing:
+
+
+NOTE: From rougly kernel 2.4.16 (I haven't tested to see hwo far
+back it goes) the PPPoATM patch is included in Linus' main kernel tree,
+therefore you may skip the patching below and resume ready to configure
+the kernel.
+
+gzip -d pppoatm-2.zip
+
+ Next we will need to test-patch the kernel using the following
+commands:
+
+patch -p1 -s -E --dry-run < /point/to/pppoatm-2
+
+ If that ran without failure then patch the kernel by removing
+the as such:
+
+patch -p1 -s -E < /point/to/pppoatm-2
+
+ That should have patched the kernel good-and-proper so we can
+go ahead and configure it, make sure the following options are
+selected along with your personal build options:
+
+
+ Code maturity levels->Prompt for development and/or incomplete code/drivers
+ Networking options->Asynchronous Transfer Mode (ATM)
+ Network device support->PPP (point-to-point protocol) support
+ Network device support->PPP support for async serial ports
+ Network device support->PPP Deflate compression
+ Network device support->PPP BSD-Compress compression
+ Network device support->PPP over ATM
+ USB support->Support for USB
+ USB support->Preliminary USB device filesystem
+ You have to make a choice here, if your USB controller is
+ UHCI based then select:
+ USB support->UHCI (Intel, PIIX4, VIA, ...) support
+ Alternatively choose:
+ USB Support->OHCI (Compaq, iMacs, OPTi, SiS, ALi, ...) support
+
+
+ You could select any of these as modules or compiled-in but as
+I followed Chris Jones' HOWTO I compiled the all but UHCI/OHCI as
+compiled-in code. Save the kernel config and compile the kernel and
+modules as you normally do.
+
+
+
+Kernel Drivers and Software
+
+ Now that the kernel will support using PPPoATM we can start
+compiling the bits to run the modem. Well start with the Kernel mode
+driver; first decompress the SARlib sources to a build directory.
+(Personally I build all my non-kernel sources
+in ~/sources) and do a
+make on it. There is no need to do
+a make install with this library.
+
+ Next return to your source root and decompress your Speedtouch
+drivers (from Sourceforge not Alcatel!), go in there and do a
+make, and then a make install.
+
+Note: If you get an "Error
+1" then check the Makefile for a line starting
+ and check it points to the right directory, the
+one where you just compiled SARlib.
+
+ Next install the Hotplug software and make sure it works. Once
+you've done that decompress Alcatel's binary management software and
+do a make on that. Then do a make
+install, the clever bit here is their installation
+registers the Speedtouch kernel driver and their binary to be run
+when the USB device is "hotplugged" (or coldplugged) into the system.
+Kiss goodbye to the hours of trying to writing modules
+loading scripts that always fail.
+
+ Next install the new PPPoATM aware PPPd program, I had no luck
+getting it compile from source on my machine so I used the RPM. Sorry
+you're on your own there!
+
+
+
+PPPd Configuration
+
+Warning: The action will
+remove all the default settings for any previous PPPd connection.
+(Not that you want them now you've got shiny new ADSL ;P)
+
+ In the /etc/ppp directory there is a file called
+options in that file put the following:
+
+
+
+ lock
+ defaultroute
+ noipdefault
+ noauth
+ passive
+ asyncmap 0
+ name bloggs@hg5.btinternet.com
+ user bloggs@hg5.btinternet.com
+ plugin /usr/lib/pppd/plugins/pppoatm.so
+ 0.38
+
+
+
+ Make sure of the following things:
+
+
+ That you replace both name
+ and user variables with your
+ username.
+
+ That you get the correct VPI/VCI ATM pair,
+ these are in the windows information software, from BTi my
+ VPI:0 and VCI:38 so I use . Make sure
+ you get this right or it will not
+ work.
+
+
+ Next in your /etc/ppp/chap-secrets put:
+
+
+
+
+ # Secrets for authentication using CHAP
+ # client server secret IP addresses
+ "bloggs@hg5.btinternet.com" * "mypasswordhere"
+
+
+
+
+
+Testing your link
+
+ Next thing to do is get the link up and test it. If you've got
+a nice distro like Mandrake you should find it will auto-init your
+USB drivers and filesystem, if not then the following can be used:
+
+
+/sbin/modprobe usb-uhci
+mount none /proc/bus/usb -tusbdevfs
+
+ Next load the Speedtouch driver by doing:
+/sbin/modprobe speedtch. Next use the speedmgmt
+program to get the modem init'ed: /usr/sbin/mgmt.
+After a while of the lights flashing on the modem the main console
+(and/or the syslog) should report:
+
+
+
+ Speedmgmt[2074]: Modem initialised at 576 kbit/s downstream and 288 kbit/s upstream
+
+
+
+ Once the modem has been init'ed now make sure the PPPoATM
+module is loaded by doing:
+
+modprobe pppoatm
+
+ Now start the PPP link by typing pppd You
+should see something similar to this:
+
+
+
+ Oct 28 14:01:25 ds9 pppd: PPPoATM plugin_init
+ Oct 28 14:01:25 ds9 pppd: PPPoATM setdevname_pppoatm
+ Oct 28 14:01:25 ds9 pppd: PPPoATM setdevname_pppoatm - SUCCESS
+ Oct 28 14:01:26 ds9 pppd: Using interface ppp0
+ Oct 28 14:01:26 ds9 pppd: Connect: ppp0 <--> 0.38
+ Oct 28 14:01:28 ds9 pppd: local IP address 255.255.255.255
+ Oct 28 14:01:28 ds9 pppd: remote IP address 255.255.255.255
+ Oct 28 14:01:28 ds9 pppd: primary DNS address 213.120.62.100
+
+
+
+ Once that's done you're in luck, now just configure the pppd
+to autodial at startup (beyond the scope of this HOWTO, sorry!).
+Hopefully HotPlug will get your device up and going before pppd needs
+it! :).
+
+
+
+
+
+
+Simple IP Masquerading
+
+ To allow sharing of your internet conenction you can eitehr
+use a proxy server or IP Masquerading. I'll cover IP Masquerding as
+it's simple to set up on the other client machines. I use a 2.4.x
+generation kernel and in effect I use IPTables. If you use a 2.2.x or
+2.0.x kernel then you need the
+IP
+Masquerading HOWTO.
+
+ This part of the HOWTO assumes that your Netfilter software is
+modularised, if it isnt then no big deal, either ignore the
+ lines or recompile your kernel.
+
+
+ Simple now, just run the commands:
+
+modprobe iptable_nat
+iptables -t nat -F POSTROUTING
+iptables -t nat -A POSTROUTING -o ppp0 -s 10.0.0.0/16 -j MASQUERADE
+echo 1 > /proc/sys/net/ipv4/ip_forward
+Note: The space between 1 and > is vital. It seems not to activate the IP Forwarding if the space is not there.
+
+ Change the and/or the
+ for your relevant network settings and
+put that file either before the in the
+internet file or somewhere in your startup.
+
+
+
+
+
+Troubleshooting
+
+
+Help! Lynx gives unable to access document
+
+Problem:
+Lynx is unable to access document or ping gives "No
+route to host" but the link is stable!
+
+Solution: Have a look at
+the output of route -n you should see a
+refenence specifing a gateway of either your Remote PPP IP
+and using the adapter/dev of ppp0. If not here is how to fix it. In
+your /etc/ppp/ip-up file above
+ on the last line type:
+
+
+
+ route del default
+ route add default gw $4 $1
+
+
+
+ Save the file and redial. The problem should be solved.
+
+
+
+
+My kernel < 2.4.2 crashes using the Alcatel driver
+
+Problem:
+Your kernel below 2.4.2 crashes using the Alcatel driver.
+
+
+Solution:
+You're probably using a kernel compiled with SMP support either don't
+use SMP or try here:
+http://sourceforge.net/project/showfiles.php?group_id=23818
+
+
+
+
+PPPd crashes when it loads the PPPoATM module
+
+Problem:
+When PPPd attempts to access the ATM device it crashes.
+
+
+Solution: The kernel was
+probably compiled on a different type of processor. I tried to get
+the kernel compiled quicker by compiling the kernel on my 950Mhz
+Duron, even with the processor type to suit the target 266Mhz Cyrix
+the ATM module crashes. So dont take short cuts and compile on the
+target processor.
+
+
+
+insmod speedtch.o gives: "Unresolved symbol: _mmx_memcpy"
+Problem:
+When you have compiled the Speedtouch Kernel driver (speedtch.o) trying to insmod/modprobe returns: "Unresolved symbol: _mmx_memcpy" or similar.
+
+
+Solution:
+Right, I haven't got a concrete answer here but I couldn't find it anywhere on the internet so here goes. I found this error come up when I recompiled my kernel once. It did it the first time but I forgot how to fix it. A combination of things fixed it for me:
+
+
+ Configured the kernel module support to ignore kernel version checking
+ Recompiled SARlib (this is what ultimately fixed it) before recompiling speedtch.o
+ Recompiled speedtch.o and reinstalled. Et voila!
+
+
+As I said I can't be sure about this one but it worked for me.
+
+
+
+
+
+There are strange noises on the telephone line when I pick up the
+phone.
+
+Problem:
+When you pick up the phone there are strange noises present, more over
+the use of the phone line causes the internet to disconnect.
+
+Solution:
+You seem to have something which I think is called cross-talk. The
+ADSL modem works by sending data down the unused frequencies of your
+copper phone line. If the hardware is set up so the ADSL and phone
+ranges overlap the two can "hear" each other. The best advice is to
+Ring BTO Customer Support and they should be able to help.
+
+
+
+
+
+
+
+Further Reading
+
+
+For further reading on related topics see this list:
+
+
+
+ The PPP-HOWTO
+ The IP Masquerading HOWTO
+ The DSL HOWTO
+ The Modem-HOWTO.
+ The Winmodems and Linux HOWTO
+
+
+
+
diff --git a/LDP/retired/Bangla-PDF-HOWTO.xml b/LDP/retired/Bangla-PDF-HOWTO.xml
new file mode 100644
index 00000000..e2265ea2
--- /dev/null
+++ b/LDP/retired/Bangla-PDF-HOWTO.xml
@@ -0,0 +1,1426 @@
+
+
+
+
+
+ Bangla PDF HOWTO
+
+
+ Progga
+
+ abulfazl AT juniv.edu
+
+
+
+ 2003-01-30
+
+
+
+ 1.1
+ 2003-04-14
+ Pro
+ PDF from Unicode, Caution about Bijoy
+
+
+
+ 1.0
+ 2003-01-30
+ Pro
+ Initial Release on Planet Earth, reviewed by LDP
+
+
+
+
+ This text mainly describes the PDF creation process using
+ KWord with the Bijoy2000
+ fonts and Bijoy keyboard, for working in the Bangla language. Some information
+ on PDF creation from Unicode encoded Bangla text files is also provided.
+
+
+
+
+ Introduction
+
+ PDF files, known for being viewable on most platforms, are a popular medium for distributing Bangla files over the Internet. Another use of PDF and
+Postscript files in the UNIX world is for printing. While PDF files can be created with various applications, this text is an attempt to describe the process of PDF creation using the free software KWord and ttf2pt1. The fonts used in this process are the Bijoy fonts included in the Bijoy2000
+package. The keyboard layout for typing in Bangla is also Bijoy (the
+typing method of ligatures or compound characters is slightly different
+from the original one).
+
+
+ Copyright & License
+
+ Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, version 1.1 or any later version published by the Free Software Foundation; with no Invariant sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is located at http://www.gnu.org/licences/fdl.html.
+
+
+
+ Bijoy fonts (c) Mustafa Jabbar, Ananda Computers, 8/6 Segun Bagicha, Dhaka-1000, Bangladesh.
+
+
+
+
+ Minimum Requirements
+
+ The test platform used were FreeBSD-4.6.0 RELEASE and RedHat-7.3. Earlier versions of RedHat won't do. Whatever is the platform, at least the following are required:
+
+
+
+
+ XFree86-4.2.0
+ (unsure about earlier versions)
+
+
+
+
+
+ KDE-3
+
+
+
+
+
+ KWord-1.1.1
+
+
+
+
+
+
+ TTF2PT1-3.4.3
+
+
+
+
+
+
+ Bijoy2000 fonts
+
+
+
+
+ Strong willingness to create a Bangla PDF.
+
+
+
+ There are many fonts that come with the Bijoy2000 package. In this text, to state a fontname, only SutonnyMJ has been used. This name can be replaced with others to meet individual needs.
+
+
+
+ Caution
+
+ After installing the Bijoy fonts and keyboard, one may be tempted to use them for purposes other than creating PDFs. But a little common sense and
+ farsightedness will reveal that the use of a nonstandard font and keyboard like
+ Bijoy is destined to create the same kind of chaos regarding Bangla in the Open
+ Source environment as is now prevailing in the proprietary world. PDF is a
+ different story though as they are font independent(if created properly) and
+ has no chance of getting into this kind of chaos. Now what if one needs to
+ create a Bangla text file? Easy - use Unicode. Recent developments has made it
+ possible to write Unicode based Bangla in GTK+ 2.0 (or higher) based softwares.
+ And the same thing is on the offing for QT (which is the backbone of KDE).
+ Even PDFs can be created from Unicode encoded Bangla text files. This has been
+ described in a later . So instead of relying on
+ nonstandard softwares like Bijoy, try to use Unicode based Bangla wherever
+ possible.
+
+
+
+
+
+ Fonts
+
+ While creating PDFs, KWord
+ gives the best result if Type1 fonts are used. But
+ Bangla Type1 fonts are quite rare, so converting TrueType
+ fonts to Type1 is a good option. This conversion is done with
+ the ttf2pt1
+ package. This package has some useful programs to carry out the
+ conversion properly. After downloading and uncompression, the
+ ttf2pt1
+ package can be installed using the following commands:
+
+
+ $ make all
+ $ make install
+
+
+ The last command needs to be executed as root. The
+ README of ttf2pt1
+ has some better descriptions of these.
+
+
+ TrueType to Type1 Conversion
+
+ The following steps describe converting TrueType Bijoy fonts to
+ Type1, suitable for PDF creation:
+
+
+
+ Instead of creating a Type1 font directly from
+ sutom___.ttf (TrueType font file of SutonnyMJ
+ font), create an interim file sutonnymj.t1a:
+
+
+ $ ttf2pt1 sutom___.ttf sutonnymj
+
+
+
+
+ Perform some correction to sutonnymj.t1a
+ using forceiso, a PERL script supplied with the
+ ttf2pt1 package, and create
+ sutonnymj2.t1a:
+
+
+ $ cat sutonnymj.t1a | /usr/local/share/ttf2pt1/scripts/forceiso \
+ "U00%x" > sutonnymj2.t1a
+
+
+ This correction is needed because some glyphs of Bijoy fonts
+ have no name. forceiso solves this problem by
+ assigning proper names to those otherwise nameless glyphs.
+
+
+
+
+
+ Finally, create the Type1 version of SutonnyMJ from
+ sutonnymj2.t1a using t1asm,
+ another program supplied with the ttf2pt1
+ package:
+
+
+ $ cat sutonnymj2.t1a | /usr/local/libexec/ttf2pt1/t1asm \
+ > sutonnymj.pfa
+
+
+ The last two steps can also be done in one go:
+
+
+ $ cat sutonnymj.t1a | /usr/local/share/ttf2pt1/scripts/forceiso \
+ "U00%x" | /usr/local/libexec/ttf2pt1/t1asm > sutonnymj.pfa
+
+
+
+
+
+
+ The final product, in this case sutonnymj.pfa,
+ is the actual Type1 font file. The first step also produces
+ sutonnymj.afm
+ which can be ignored through the rest of the text.
+
+
+
+
+ Font Installation
+
+ There are some programs that automate font installation, such as
+ type1inst for Type1,
+ ttmkfdir
+ for TrueType, KDE's own font installer for both types and some others. When
+ these are used, the font encoding can be wrong and needs hand-editing of the
+ fonts.scale file.
+ If any of the font installing programs were used, mkfontdir
+ must be executed after editing font.scale
+ by hand. For Type1 fonts, the encoding is adobe-fontspecific
+ and not iso8859-1. For TrueType fonts, the encoding is
+ apple-roman and not iso8859-1. Besides,
+ anti-aliasing must be stopped for these TrueType fonts to show up.
+
+ Alternatively, the next three sections can be considered to
+ install fonts manually. This is a bit cumbersome but when things go
+ wrong, it is easier to debug, as the user has a clear idea about the
+ whole thing.
+
+
+ Type1 Font Installation
+
+ The following steps describe manual installation of Type1
+ fonts:
+
+
+
+ Create a new directory,
+ /usr/local/share/fonts/type1/bijoy/, and copy the Type1 font there:
+
+
+
+ $ mkdir -p /usr/local/share/fonts/type1/bijoy/
+
+ $ cp sutonnymj.pfa /usr/local/share/fonts/type1/bijoy/
+
+
+
+
+ Create the file fonts.scale
+ and place it inside /usr/local/share/fonts/type1/bijoy/. The fonts.scale's creation process will be described later in .
+
+
+
+ Create another file fonts.dir
+ using mkfontdir:
+
+
+
+ $ cd /usr/local/share/fonts/type1/bijoy/
+
+ $ mkfontdir
+
+
+ If the fonts.scale
+ was created correctly then fonts.dir
+ will be created, otherwise some error messages will appear
+ after executing mkfontdir.
+
+
+
+ Open XF86Config and add
+ /usr/local/share/fonts/type1/bijoy/
+ as a new fontpath in the Files section:
+
+ FontPath "/usr/local/share/fonts/type1/bijoy/"
+
+ The XF86Config file is generally found inside
+ /etc/X11/.
+ If it's not present there then use find
+ to get the path:
+
+
+
+ $ find / -name XF86Config
+
+
+
+
+ Restart X server by pressing
+
+ Ctrl
+ Alt
+ Bksp
+ .
+ The font will be installed.
+
+
+
+ Check whether the font has really been installed by using
+ xlsfonts. This program shows the
+ XLFD of every font that is available to the X server.
+ grep can be used to find the desired font from
+ xlsfonts' output:
+
+
+
+ $ xlsfonts | grep sutonnymj
+
+
+ If sutonnymj is unavailable to X then grep will give no output. Otherwise the output will be the XLFD of sutonnymj:
+
+
+
+ -altsys-sutonnymj-medium-r-normal--0-0-0-0-p-0-adobe-fontspecific
+
+
+ If more than one font were installed then
+ grep altsys
+ will show them all (if present in xlsfonts' output).
+
+
+
+
+
+ Creating <filename>fonts.scale</filename>
+
+ The fonts.scale
+ file contains various information about the fonts in a directory
+ where that fonts.scale
+ itself is placed. This means every directory which has any font
+ file can have its own fonts.scale
+ (non-scalable fonts like Bitmap fonts do not need a
+ fonts.scale file). The
+ information that every line of a fonts.scale contains
+ (preceded by the name of the font file itself) is called XLFD
+ (X Logical Font Definition). An example line from a
+ fonts.scale file is:
+
+ sutonny.pfa -altsys-SutonnyMJ-medium-r-normal--0-0-0-0-p-0-adobe-fontspecific
+
+
+ The only difference is the very first line of
+ fonts.scale, which has only a
+ number instead of the usual font-file name followed by the
+ corresponding XLFD. This number is the total
+ number of XLFDs listed in that fonts.scale
+ file.
+
+ The structure of a fonts.scale
+ is like this:
+
+
+
+ Line 1: Total number of XLFD
+ Line 2: FontFileName1 XLFD
+ Line 3: FontFileName2 XLFD
+ ....
+ ....
+ ....
+
+
+ The following is a suitable XLFD for Type1 Bijoy fonts:
+
+
+ -altsys-SutonnyMJ-medium-r-normal--0-0-0-0-p-0-adobe-fontspecific
+
+
+ Please note that in the above string, SutonnyMJ
+ is the actual fontname. This name needs to be changed accordingly for
+ other fonts.
+
+
+ An example fonts.scale
+ file for two Type1 Bijoy fonts can be like this (Where
+ sutonnymj.pfa and rinkymj.pfa are the actual Type1 font files for
+ the fonts Sutonnymj and Rinkymj respectively):
+
+
+
+2
+sutonnymj.pfa -altsys-SutonnyMJ-medium-r-normal--0-0-0-0-p-0-adobe-fontspecific
+rinkymj.pfa -altsys-RinkyMJ-medium-r-normal--0-0-0-0-p-0-adobe-fontspecific
+
+
+
+ It's better not to press Return after writing the
+ XLFD in the last line. This sometimes create problem with the total
+ number of XLFD lines and the file is taken as having bad structure by
+ mkfontdir. If fonts.scale
+ is not created properly, the mkfontdir
+ command will give error message. Otherwise fonts.dir
+ will be created.
+
+ The adobe-fontspecific substring found at the end of every XLFD for Type1 Bijoy fonts is the encoding of that font. If iso8859-1 encoding is required, this can be done too by creating another file fonts.alias. Every line of fonts.alias contains two XLFDs. The first XLFD is the alias and the second one is the original. Unlike fonts.scale and fonts.dir, there is no number at the first line of fonts.alias. An example fonts.alias's
+structure looks like this:
+
+
+
+Line 1: -altsys-SutonnyMJ-medium-r-normal--0-0-0-0-p-0-iso8859-1
+ -altsys-SutonnyMJ-medium-r-normal--0-0-0-0-p-0-adobe-fontspecific
+Line 2: -altsys-RinkyMJ-medium-r-normal--0-0-0-0-p-0-iso8859-1
+ -altsys-RinkyMJ-medium-r-normal--0-0-0-0-p-0-adobe-fontspecific
+
+
+
+ Generally, some subdirectories under /usr/X11R6/lib/X11/fonts/ contain many font files and some fonts.scale files, fonts.dir and fonts.alias as well. A browse through these files can make it easier to create new ones. One thing to notice is that the content of both fonts.scale and fonts.dir are same but both are still needed.
+
+
+
+
+ TrueType Font Installation
+
+ The Bijoy font's TrueType installation method is quite similar
+ to that of Type1. Just keep a separate directory for the fonts, like,
+
+
+ /usr/local/share/fonts/ttfonts/bijoy/
+
+
+ and change the XLFD to:
+
+
+ -altsys-SutonnyMJ-medium-r-normal--0-0-0-0-p-0-apple-roman
+
+
+ In the example, the font encoding is apple-roman
+ instead of adobe-fontspecific. Also to use these fonts
+ anti-aliasing must be stopped, and this is where Xft
+ comes into business.In your $HOME
+ directory, create a hidden file ~/.xftconfig
+ and write the following lines in it ( the file may be
+ already present, in that case just add these lines):
+
+
+
+dir "/usr/local/share/fonts/ttfonts/bijoy/"
+
+match any family == "sutonnymj"
+edit antialias = false; encoding = "apple-roman";
+
+
+
+ The match any family == "sutonnymj" and the next line
+ prevents anti-aliasing for sutonnymj only. If there are other Bijoy
+ fonts in use, more similar lines must be added.
+
+ The presence of only ~/.xftconfig
+ is enough to make a TrueType font available to KWord. There is no
+ need to create fonts.scale and
+ fonts.dir. Even the fontpath needs not be added
+ in XF86Config. So these steps can be skipped if
+ wished.
+
+ Newer systems(like RH 8.0) use Xft 2.0 instead of Xft 1.0 .
+ Xft 2.0 doesn't use ~/xftconfig. Instead it uses
+ ~/.fonts . This file can be modified by
+ fontconfig . Here also, antialias must be
+ stopped and encoding remains apple-roman
+ .
+
+
+
+
+
+ On Using TrueType
+
+
+ KWord
+ can't create PDFs perfectly using TrueType fonts, so there is no
+ reason to use TrueType fonts for creating PDFs. But TrueType is useful
+ for creating PDFs from files written in MS Word
+ (i.e. *.doc files). Even then these PDFs are defective (due to the use
+ of Type3 fonts inside the PDFs) and so are not transferable to other
+ computers; they can be used for printing only. So the only suggested
+ use of TrueType is to create PDFs from MS Word
+ files for printing. Again, these PDFs are of low quality, so if it
+ is not urgently needed, TrueType should be avoided completely for
+ PDF creation.
+
+ To open an MS Word file in
+ KWord , the encoding of the relevant font(s) should be changed from
+ apple-roman to iso8859-1 in the ~/.xftconfig, for example:
+
+
+
+match any family == "sutonnymj"
+ edit antialias = false; encoding = "apple-roman";
+
+
+
+ will become:
+
+
+
+match any family == "sutonnymj"
+ edit antialias = false; encoding = "iso8859-1";
+
+
+
+ Type1 and TrueType versions of a font should not be used
+ together. To stop using TrueType fonts, the corresponding FontPath must
+ be commented out from the Files section of
+ XF68Config. The relevant entries for the font in
+ ~/.xftconfig must also be commented out. In both cases,
+ a # as the first character on any line comments out the whole
+ line. Given below is an example ~/.xftconfig,
+ where entry for a font has been commented out:
+
+
+
+# dir "/usr/local/share/fonts/ttfonts/"
+
+# match any family == "sutonnymj"
+# edit antialias = false; encoding = "apple-roman";
+
+
+
+
+
+
+ Keyboard
+
+
+ Using The Bijoy Keyboard
+
+ In X Window, all the keyboard related stuff is handled by XKB.
+ XKB relies on some configuration files called the symbol
+ files, to get the layout of a specific keyboard. The following steps describe the
+ installation process of a symbol file for the Bijoy Bangla keyboard:
+
+
+
+
+ Below is the symbol file for the Bijoy keyboard. Save it as
+ bn_bijoy
+ .
+
+
+
+ { [], [ 49, exclam ] };
+key { [], [ 50, 64 ] };
+key { [], [ 51, 35 ] };
+key { [], [ 52, 36 ] };
+key { [], [ 53, 37 ] };
+key { [], [ 54, 94 ] };
+key { [], [ 55, 117 ] };
+key { [], [ 56, asterisk ] };
+key { [], [ 57, parenleft ] };
+key { [], [ 48, parenright ] };
+key { [], [ minus, 209 ] };
+key { [], [ 61, plus ] };
+key { [], [ 79, 115 ] };
+key { [], [ 104, 113 ] };
+key { [], [ 87, 88 ] };
+key { [], [ 99, 100 ] };
+key { [], [ 85, 86 ] };
+key { [], [ 80, 81 ] };
+key { [], [ 82, 83 ] };
+key { [], [ 110, 84 ] };
+key { [], [ 77, 78 ] };
+key { [], [ 111, 112 ] };
+key { [], [ bracketleft, braceleft ]};
+key { [], [ bracketright, braceright]};
+key { [], [ U84, 169 ] };
+key { [], [ 121, 126 ] };
+key { [], [ 119, 120 ] };
+key { [], [ 118, 65 ] };
+key { [], [ Multi_key, 124 ] };
+key { [], [ 101, 102 ] };
+key { [], [ 75, 76 ] };
+key { [], [ 90, 95 ] };
+key { [], [ 96, 97 ] };
+key { [], [ semicolon, colon] };
+key { [], [ 213, 211 ] };
+key { [], [ 212, 210 ] };
+key { [], [ 114, 116 ] };
+key { [], [ 170, 168 ] };
+key { [], [ 73, U8a ] };
+key { [], [ U87, U89 ] };
+key { [], [ 105, 106 ] };
+key { [], [ 98, 89 ] };
+key { [], [ 109, 108 ] };
+key { [], [ 103, 107 ] };
+key { [], [ comma, less ] };
+key { [], [ period, greater]};
+key { [], [ slash, question]};
+
+} ;
+
+ ]]>
+
+
+
+
+ Copy bn_bijoy to
+ /usr/X11R6/lib/X11/xkb/symbols/
+
+
+
+
+ Edit the InputDevice section of
+ XF86Config so it looks like:
+
+
+.........
+.........
+
+Section "InputDevice"
+ Identifier "Keyboard0"
+ Driver "keyboard"
+
+ Option "XkbKeycodes" "xfree86"
+ Option "XkbTypes" "complete"
+ Option "XkbCompat" "complete+leds"
+ Option "XkbSymbols" "us(pc104)+bn_bijoy+group(lwin_toggle)"
+ Option "XkbGeometry" "pc(pc104)"
+EndSection
+..........
+..........
+
+
+
+ The above description is for a 104-key keyboard.
+
+
+
+ Restart X server by pressing
+
+ Ctrl
+
+ Alt
+
+ Bksp
+ .
+
+
+
+ After restarting X, the Bijoy keyboard should be
+ present along side the English one. To activate it, press the
+ left Win-key. If everything is okay, the
+ Scroll Lock LED will be on and the
+ key presses will produce codes according to the Bijoy keyboard
+ layout. Pressing the left Win-key
+ again will disable Bijoy and the Scroll Lock LED will go off.
+
+
+
+
+ To test the newly installed Bijoy keyboard, follow these steps:
+
+
+
+ Open KWord,
+
+
+
+ Select sutonnymj from the font list,
+
+
+
+ Press the left Winkey,
+
+
+
+ Start typing according to the Bijoy keyboard layout.
+
+
+
+
+
+ A handy tool for testing mouse and keypress events is
+ xev. This program shows all the generated codes from keypresses.
+
+
+
+
+ These steps are not enough, however, to write ligatures or compound
+ characters. The next section describes this very thing.
+
+
+
+ Writing Ligatures
+
+ The ligature writing process described here is not a standard one
+ . At best it can be called a work-around (it has a similarity to
+ cuckoos laying eggs in crows' nests). If this method is used, the
+ Multikey feature won't work on Latin characters (at least when Bijoy
+ keyboard is needed). If there is no need to use the Multikey for
+ typing various Latin characters like ssharp then this method is
+ okay. The typing sequence of characters for writing ligatures is
+ slightly different from the the original Bijoy keyboard. Whatever is
+ the situation, the following steps describe a way to get the ligatures
+ to appear on the screen:
+
+
+
+ Save the following as Compose.bijoy:
+
+
+ Means
+# Special Character
+
+# Special
+ : "\46"
+
+# Ka
+ : "\260"
+ : "\274"
+ : "\351"
+ : "\256\213"
+ : "\257\213"
+
+# Kha
+
+ : "\225\114"
+ : "\366"
+
+# Ga
+ : "\271"
+ : "\275"
+ : "\230\115"
+ : "\352"
+ : "\377"
+
+#Gha
+ : "\225\116"
+ : "\230\116"
+
+# Cha
+