From 41bcce747d05c78fdf69ee6325088c8666228fa1 Mon Sep 17 00:00:00 2001
From: "Martin A. Brown"
Date: Fri, 25 Mar 2016 09:54:56 -0700
Subject: [PATCH 01/11] initial commit of some migration tools
---
LDP/ref/migration-2016/guidemigration.py | 213 ++++++++++++
LDP/ref/migration-2016/howtomigration.py | 313 ++++++++++++++++++
LDP/ref/migration-2016/migration-helper.sh | 45 +++
.../migration-2016/migration-preparation.sh | 59 ++++
LDP/ref/migration-2016/old-migration.py | 138 ++++++++
5 files changed, 768 insertions(+)
create mode 100644 LDP/ref/migration-2016/guidemigration.py
create mode 100644 LDP/ref/migration-2016/howtomigration.py
create mode 100644 LDP/ref/migration-2016/migration-helper.sh
create mode 100644 LDP/ref/migration-2016/migration-preparation.sh
create mode 100644 LDP/ref/migration-2016/old-migration.py
diff --git a/LDP/ref/migration-2016/guidemigration.py b/LDP/ref/migration-2016/guidemigration.py
new file mode 100644
index 00000000..2dced884
--- /dev/null
+++ b/LDP/ref/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/ref/migration-2016/howtomigration.py b/LDP/ref/migration-2016/howtomigration.py
new file mode 100644
index 00000000..ab2a24d5
--- /dev/null
+++ b/LDP/ref/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.
+
+
+
+'''
+ return text.format(target, title, delay)
+
+
+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 howtos(stems, howtopath, newtree, pubdir, urlbase):
+ ldptree = dict()
+ for s, r in walk_html_chunked_files(stems, howtopath, howtopath):
+ ldptree[r] = htmlf(s, r, pubdir, newtree)
+ # print('chunked_files', s, r)
+
+ for s, r in walk_html_chunked_dirs(stems, howtopath, howtopath):
+ ldptree[r] = htmld(s, r, pubdir, newtree)
+ # print('chunked_dirs', s, r)
+
+ howto_htmls = opj(howtopath, 'html_single')
+ for s, r in walk_html_single(stems, howto_htmls, howtopath):
+ ldptree[r] = htmls(s, r, pubdir, newtree)
+ # print('html_single', s, r)
+
+ for s, r in walk_simple(stems, opj(howtopath, 'text'), howtopath):
+ ldptree[r] = txt(s, r, pubdir, newtree)
+ # print('text', s, r)
+
+ for s, r in walk_simple(stems, opj(howtopath, 'pdf'), howtopath):
+ ldptree[r] = pdf(s, r, pubdir, newtree)
+ # print('pdf', s, r)
+
+ # -- have to symlink the PDF and TXT files
+ #
+ for fname in sorted(ldptree.keys(), key=lambda x: x.lower()):
+ stem, relpath, newpath, pubpath = ldptree[fname]
+ url = pubpath.replace(pubdir, urlbase)
+ if fname.startswith('text/') or fname.startswith('pdf/'):
+ create_symlink(pubpath, newpath)
+ else:
+ url = pubpath.replace(pubdir, urlbase)
+ create_refresh_meta_equiv(newpath, 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
+ howtopath, howtocompat, pubdir, urlbase = argv
+ oldtree = opd(opn(howtopath))
+
+ stems = collect_published_stems(pubdir)
+
+ howtos(stems, howtopath, howtocompat, 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/ref/migration-2016/migration-helper.sh b/LDP/ref/migration-2016/migration-helper.sh
new file mode 100644
index 00000000..8f44d346
--- /dev/null
+++ b/LDP/ref/migration-2016/migration-helper.sh
@@ -0,0 +1,45 @@
+#! /bin/bash
+
+set -e
+set -x
+
+SELFNAME="$( readlink --canonicalize ${0})"
+ME="${SELFNAME##*/}" # -- basename
+DIR="${SELFNAME%/*}" # -- dirname
+
+HOWTO_MIGRATOR=${DIR}/howtomigration.py
+GUIDE_MIGRATOR=${DIR}/guidemigration.py
+
+CONTENTROOT=/home/mabrown/wip/tldp/website/html
+cd "$CONTENTROOT"
+
+# -- trailing slash, atypically included on PUBDIR, here
+PUBDIR="${CONTENTROOT}/en/"
+URL_PUBDIR=http://www.tldp.org/en/
+
+HOWTOS="${CONTENTROOT}/HOWTO"
+GUIDES="${CONTENTROOT}/LDP"
+
+# -- HOWTO handling: build symlinks and HTTP META-EQUIV files
+#
+HOWTO_COMPAT=HOWTO.compat/
+test -d "${HOWTO_COMPAT}" \
+ || mkdir "${HOWTO_COMPAT}"
+
+HOWTO_COMPAT=$( readlink --canonicalize "$HOWTO_COMPAT" )
+
+python \
+ "${HOWTO_MIGRATOR}" "${HOWTOS}" "${HOWTO_COMPAT}" "${PUBDIR}" "${URL_PUBDIR}"
+
+GUIDE_COMPAT=LDP.compat/
+test -d "${GUIDE_COMPAT}" \
+ || mkdir "${GUIDE_COMPAT}"
+
+rsync --archive --verbose ./LDP/ "${GUIDE_COMPAT}/"
+
+python \
+ "${GUIDE_MIGRATOR}" "${GUIDES}" "${GUIDE_COMPAT}" "${PUBDIR}" "${URL_PUBDIR}"
+
+exit 0
+
+# -- end of file
diff --git a/LDP/ref/migration-2016/migration-preparation.sh b/LDP/ref/migration-2016/migration-preparation.sh
new file mode 100644
index 00000000..52efa5da
--- /dev/null
+++ b/LDP/ref/migration-2016/migration-preparation.sh
@@ -0,0 +1,59 @@
+#! /bin/bash
+
+set -e
+set -x
+
+SELFNAME="$( readlink --canonicalize ${0})"
+ME="${SELFNAME##*/}" # -- basename
+DIR="${SELFNAME%/*}" # -- dirname
+
+CONTENTROOT=/home/mabrown/wip/tldp/website/html
+cd "$CONTENTROOT"
+
+# -- minor cleanup of dangling or otherwise broken symlinks:
+for LINK in \
+ html/pub/Linux/docs/HOWTO/translations/polish/.message \
+ html/pub/Linux/docs/HOWTO/translations/pl/.message \
+ html/LDP/LGNET/182/184 \
+ ; do
+
+ test -L "$LINK" && rm -f "$LINK"
+
+done
+
+ARCHIVE=archive
+test -d "${ARCHIVE}" \
+ || mkdir "${ARCHIVE}"
+
+# -- populate the archive with retired items
+#
+mv \
+ --target-directory "${ARCHIVE}" \
+ --verbose \
+ -- \
+ HOWTO/Netscape+Proxy.html \
+ HOWTO/Sendmail+UUCP.html \
+ HOWTO/GTEK-BBS-550.html \
+ HOWTO/DPT-Hardware-RAID.html \
+ HOWTO/Consultants-HOWTO.html \
+ HOWTO/WikiText-HOWTO \
+ HOWTO/Security-Quickstart-Redhat-HOWTO \
+
+# -- and populate the really ancient crap
+#
+TODELETE=todelete-$( date +%F )
+test -d "${TODELETE}" \
+ || mkdir "${TODELETE}"
+
+mv \
+ --target-directory "${TODELETE}" \
+ --verbose \
+ -- \
+ HOWTO/Acer-Laptop-HOWTO.html \
+ HOWTO/Linux-From-Scratch-HOWTO.html \
+ HOWTO/Distributions-HOWTO.html \
+ HOWTO/MIPS-HOWTO.html \
+ HOWTO/3Dfx-HOWTO.html \
+ HOWTO/PostgreSQL-HOWTO.html \
+
+# -- end of file
diff --git a/LDP/ref/migration-2016/old-migration.py b/LDP/ref/migration-2016/old-migration.py
new file mode 100644
index 00000000..f8c3af86
--- /dev/null
+++ b/LDP/ref/migration-2016/old-migration.py
@@ -0,0 +1,138 @@
+#! /usr/bin/python
+#
+# -- migrate to the new naming scheme
+
+from __future__ import absolute_import, division, print_function
+
+import os
+import sys
+import errno
+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.ERROR)
+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
+
+movingstems = dict()
+movingstems['intro-linux'] = 'Intro-Linux'
+
+def namegenerator(suffix, stem, dirname):
+ fname = os.path.join(dirname, stem, stem + suffix)
+ if os.path.exists(fname):
+ return fname
+ else:
+ return None
+
+pdf = functools.partial(namegenerator, '.pdf')
+txt = functools.partial(namegenerator, '.txt')
+html = functools.partial(namegenerator, '.html')
+htmls = functools.partial(namegenerator, '-single.html')
+
+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 printstems(fname):
+ print(fname)
+
+
+def firstdir(fdir):
+ if os.path.isabs(fdir):
+ raise ValueError("received absolute path")
+ desired = os.path.normpath(fdir)
+ while os.path.sep in desired:
+ desired, _ = os.path.split(desired)
+ return desired
+
+
+def stem_and_ext(name):
+ '''return (stem, ext) for any relative or absolute filename'''
+ return os.path.splitext(os.path.basename(os.path.normpath(name)))
+
+def extract_rs_html(root, name):
+ found = opj(root, name)
+ relpath = opr(found, start=root)
+ stem = firstdir(relpath)
+ return relpath, stem
+
+
+def extract_rs_htmls(root, name):
+ found = opj(root, name)
+ relpath = opr(found, start=opj(root, 'html_single'))
+ stem = firstdir(relpath)
+ return relpath, stem
+
+
+def extract_relpath_and_stem(root, name):
+ found = opj(root, name)
+ stem, _ = stem_and_ext(found)
+ relpath = opr(found, start=root)
+ return relpath, stem
+
+def extract_stem_firstdir(name, base):
+ relpath = opr(name, start=base)
+ stem = firstdir(relpath)
+ return stem
+
+
+def walktree(func, pubdir, oldtree, newtree, urlpath):
+ for root, dirs, files in os.walk(oldtree):
+ for x in files:
+ found = os.path.join(root, x)
+ relpath = os.path.relpath(found, start=oldtree)
+ _, ext = stem_and_ext(found)
+ if ext not in ('.pdf', '.html', '.txt'):
+ if not relpath.startswith('text'):
+ func(('skip', '', '', '', found))
+ continue
+ if relpath.startswith('text') and ext == '':
+ relpath, stem = extract_relpath_and_stem(oldtree, found)
+ newname = txt(stem, pubdir)
+ func(('TEXT', stem, relpath, newname, found))
+ elif relpath.startswith('pdf') and ext == '.pdf':
+ relpath, stem = extract_relpath_and_stem(oldtree, found)
+ newname = pdf(stem, pubdir)
+ func(('PDF', stem, relpath, newname, found))
+ elif relpath.startswith(opj(oldtree, 'html_single')):
+ stem = extract_stem_firstdir(found, opj(oldtree, 'html_single'))
+ newname = htmls(stem, pubdir)
+ func(('HTMLS', stem, relpath, newname, found))
+ elif root == oldtree: # -- plain-files at root
+ pass
+ else:
+ relpath, stem = extract_rs_html(oldtree, found)
+ newname = html(stem, pubdir)
+ func(('HTML', stem, relpath, newname, found))
+
+
+def main(fin, fout, argv):
+ me = os.path.basename(sys.argv[0])
+ usage = "usage: %s " % (me,)
+ if not validate_args(argv):
+ return usage
+ pubdir, oldtree, newtree, urlpath = argv
+ walktree(printstems, pubdir, oldtree, newtree, urlpath)
+ return os.EX_OK
+
+if __name__ == '__main__':
+ sys.exit(main(sys.stdin, sys.stdout, sys.argv[1:]))
+
+# -- end of file
From 1f2eb760199bd754c9538ce369bf2cffddaa7c5b Mon Sep 17 00:00:00 2001
From: "Martin A. Brown"
Date: Fri, 25 Mar 2016 09:55:40 -0700
Subject: [PATCH 02/11] putting directory in the correct place
---
LDP/{ref => }/migration-2016/guidemigration.py | 0
LDP/{ref => }/migration-2016/howtomigration.py | 0
LDP/{ref => }/migration-2016/migration-helper.sh | 0
LDP/{ref => }/migration-2016/migration-preparation.sh | 0
LDP/{ref => }/migration-2016/old-migration.py | 0
5 files changed, 0 insertions(+), 0 deletions(-)
rename LDP/{ref => }/migration-2016/guidemigration.py (100%)
rename LDP/{ref => }/migration-2016/howtomigration.py (100%)
rename LDP/{ref => }/migration-2016/migration-helper.sh (100%)
rename LDP/{ref => }/migration-2016/migration-preparation.sh (100%)
rename LDP/{ref => }/migration-2016/old-migration.py (100%)
diff --git a/LDP/ref/migration-2016/guidemigration.py b/LDP/migration-2016/guidemigration.py
similarity index 100%
rename from LDP/ref/migration-2016/guidemigration.py
rename to LDP/migration-2016/guidemigration.py
diff --git a/LDP/ref/migration-2016/howtomigration.py b/LDP/migration-2016/howtomigration.py
similarity index 100%
rename from LDP/ref/migration-2016/howtomigration.py
rename to LDP/migration-2016/howtomigration.py
diff --git a/LDP/ref/migration-2016/migration-helper.sh b/LDP/migration-2016/migration-helper.sh
similarity index 100%
rename from LDP/ref/migration-2016/migration-helper.sh
rename to LDP/migration-2016/migration-helper.sh
diff --git a/LDP/ref/migration-2016/migration-preparation.sh b/LDP/migration-2016/migration-preparation.sh
similarity index 100%
rename from LDP/ref/migration-2016/migration-preparation.sh
rename to LDP/migration-2016/migration-preparation.sh
diff --git a/LDP/ref/migration-2016/old-migration.py b/LDP/migration-2016/old-migration.py
similarity index 100%
rename from LDP/ref/migration-2016/old-migration.py
rename to LDP/migration-2016/old-migration.py
From 9e88cd7268b7feed323451ed8c321cb4c718bd59 Mon Sep 17 00:00:00 2001
From: "Martin A. Brown"
Date: Fri, 25 Mar 2016 10:06:39 -0700
Subject: [PATCH 03/11] removing unnecessary file
---
LDP/migration-2016/old-migration.py | 138 ----------------------------
1 file changed, 138 deletions(-)
delete mode 100644 LDP/migration-2016/old-migration.py
diff --git a/LDP/migration-2016/old-migration.py b/LDP/migration-2016/old-migration.py
deleted file mode 100644
index f8c3af86..00000000
--- a/LDP/migration-2016/old-migration.py
+++ /dev/null
@@ -1,138 +0,0 @@
-#! /usr/bin/python
-#
-# -- migrate to the new naming scheme
-
-from __future__ import absolute_import, division, print_function
-
-import os
-import sys
-import errno
-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.ERROR)
-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
-
-movingstems = dict()
-movingstems['intro-linux'] = 'Intro-Linux'
-
-def namegenerator(suffix, stem, dirname):
- fname = os.path.join(dirname, stem, stem + suffix)
- if os.path.exists(fname):
- return fname
- else:
- return None
-
-pdf = functools.partial(namegenerator, '.pdf')
-txt = functools.partial(namegenerator, '.txt')
-html = functools.partial(namegenerator, '.html')
-htmls = functools.partial(namegenerator, '-single.html')
-
-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 printstems(fname):
- print(fname)
-
-
-def firstdir(fdir):
- if os.path.isabs(fdir):
- raise ValueError("received absolute path")
- desired = os.path.normpath(fdir)
- while os.path.sep in desired:
- desired, _ = os.path.split(desired)
- return desired
-
-
-def stem_and_ext(name):
- '''return (stem, ext) for any relative or absolute filename'''
- return os.path.splitext(os.path.basename(os.path.normpath(name)))
-
-def extract_rs_html(root, name):
- found = opj(root, name)
- relpath = opr(found, start=root)
- stem = firstdir(relpath)
- return relpath, stem
-
-
-def extract_rs_htmls(root, name):
- found = opj(root, name)
- relpath = opr(found, start=opj(root, 'html_single'))
- stem = firstdir(relpath)
- return relpath, stem
-
-
-def extract_relpath_and_stem(root, name):
- found = opj(root, name)
- stem, _ = stem_and_ext(found)
- relpath = opr(found, start=root)
- return relpath, stem
-
-def extract_stem_firstdir(name, base):
- relpath = opr(name, start=base)
- stem = firstdir(relpath)
- return stem
-
-
-def walktree(func, pubdir, oldtree, newtree, urlpath):
- for root, dirs, files in os.walk(oldtree):
- for x in files:
- found = os.path.join(root, x)
- relpath = os.path.relpath(found, start=oldtree)
- _, ext = stem_and_ext(found)
- if ext not in ('.pdf', '.html', '.txt'):
- if not relpath.startswith('text'):
- func(('skip', '', '', '', found))
- continue
- if relpath.startswith('text') and ext == '':
- relpath, stem = extract_relpath_and_stem(oldtree, found)
- newname = txt(stem, pubdir)
- func(('TEXT', stem, relpath, newname, found))
- elif relpath.startswith('pdf') and ext == '.pdf':
- relpath, stem = extract_relpath_and_stem(oldtree, found)
- newname = pdf(stem, pubdir)
- func(('PDF', stem, relpath, newname, found))
- elif relpath.startswith(opj(oldtree, 'html_single')):
- stem = extract_stem_firstdir(found, opj(oldtree, 'html_single'))
- newname = htmls(stem, pubdir)
- func(('HTMLS', stem, relpath, newname, found))
- elif root == oldtree: # -- plain-files at root
- pass
- else:
- relpath, stem = extract_rs_html(oldtree, found)
- newname = html(stem, pubdir)
- func(('HTML', stem, relpath, newname, found))
-
-
-def main(fin, fout, argv):
- me = os.path.basename(sys.argv[0])
- usage = "usage: %s " % (me,)
- if not validate_args(argv):
- return usage
- pubdir, oldtree, newtree, urlpath = argv
- walktree(printstems, pubdir, oldtree, newtree, urlpath)
- return os.EX_OK
-
-if __name__ == '__main__':
- sys.exit(main(sys.stdin, sys.stdout, sys.argv[1:]))
-
-# -- end of file
From 181ac71be48d67fd72c162b12d7cd21e6fcad89f Mon Sep 17 00:00:00 2001
From: "Martin A. Brown"
Date: Fri, 25 Mar 2016 10:07:07 -0700
Subject: [PATCH 04/11] migration-preparation is the first step
some of the content was long-since decommissioned and is to be set aside into
a 'todelete' directory
some belongs properly in the archive
add the stuff from the refs directory
---
LDP/migration-2016/migration-preparation.sh | 5 ++++-
1 file changed, 4 insertions(+), 1 deletion(-)
diff --git a/LDP/migration-2016/migration-preparation.sh b/LDP/migration-2016/migration-preparation.sh
index 52efa5da..756231cd 100644
--- a/LDP/migration-2016/migration-preparation.sh
+++ b/LDP/migration-2016/migration-preparation.sh
@@ -38,8 +38,11 @@ mv \
HOWTO/Consultants-HOWTO.html \
HOWTO/WikiText-HOWTO \
HOWTO/Security-Quickstart-Redhat-HOWTO \
+ REF/palmdevqs \
+ REF/ls_quickref \
+ REF/Joe-Command-Reference \
-# -- and populate the really ancient crap
+# -- and toss aside the really ancient crap
#
TODELETE=todelete-$( date +%F )
test -d "${TODELETE}" \
From a733652cdce7b54fe930fe6423cd2f4aedbd65e9 Mon Sep 17 00:00:00 2001
From: "Martin A. Brown"
Date: Fri, 25 Mar 2016 11:15:15 -0700
Subject: [PATCH 05/11] retiring the WordPerfect FAQ
https://en.wikipedia.org/wiki/WordPerfect#Linux
---
LDP/{faq/docbook => retired}/WordPerfect-Linux-FAQ.sgml | 0
1 file changed, 0 insertions(+), 0 deletions(-)
rename LDP/{faq/docbook => retired}/WordPerfect-Linux-FAQ.sgml (100%)
diff --git a/LDP/faq/docbook/WordPerfect-Linux-FAQ.sgml b/LDP/retired/WordPerfect-Linux-FAQ.sgml
similarity index 100%
rename from LDP/faq/docbook/WordPerfect-Linux-FAQ.sgml
rename to LDP/retired/WordPerfect-Linux-FAQ.sgml
From 50cc0774b1b5bbfd22f8c6e1a44ac4b420b4f85c Mon Sep 17 00:00:00 2001
From: "Martin A. Brown"
Date: Fri, 25 Mar 2016 11:18:18 -0700
Subject: [PATCH 06/11] retiring PPP-FAQ, replaced in 2001 with PPP-HOWTO
---
LDP/{faq/linuxdoc => retired}/PPP-FAQ.sgml | 0
1 file changed, 0 insertions(+), 0 deletions(-)
rename LDP/{faq/linuxdoc => retired}/PPP-FAQ.sgml (100%)
diff --git a/LDP/faq/linuxdoc/PPP-FAQ.sgml b/LDP/retired/PPP-FAQ.sgml
similarity index 100%
rename from LDP/faq/linuxdoc/PPP-FAQ.sgml
rename to LDP/retired/PPP-FAQ.sgml
From a961647d66989aed2ccacbae82bb5860f2d5536b Mon Sep 17 00:00:00 2001
From: "Martin A. Brown"
Date: Fri, 25 Mar 2016 11:46:04 -0700
Subject: [PATCH 07/11] a set of scripts for reorganizing the output tree
---
LDP/migration-2016/faqmigration.py | 173 ++++++++++++++++++++
LDP/migration-2016/migration-helper.sh | 52 ++++--
LDP/migration-2016/migration-preparation.sh | 6 +-
LDP/migration-2016/refmigration.py | 172 +++++++++++++++++++
4 files changed, 389 insertions(+), 14 deletions(-)
create mode 100644 LDP/migration-2016/faqmigration.py
create mode 100644 LDP/migration-2016/refmigration.py
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/migration-helper.sh b/LDP/migration-2016/migration-helper.sh
index 8f44d346..26e79397 100644
--- a/LDP/migration-2016/migration-helper.sh
+++ b/LDP/migration-2016/migration-helper.sh
@@ -5,41 +5,67 @@ set -x
SELFNAME="$( readlink --canonicalize ${0})"
ME="${SELFNAME##*/}" # -- basename
-DIR="${SELFNAME%/*}" # -- dirname
-
-HOWTO_MIGRATOR=${DIR}/howtomigration.py
-GUIDE_MIGRATOR=${DIR}/guidemigration.py
+HERE="${SELFNAME%/*}" # -- dirname
+# -- SET THIS VARIABLE to the full path of the LDP content
+#
CONTENTROOT=/home/mabrown/wip/tldp/website/html
-cd "$CONTENTROOT"
# -- trailing slash, atypically included on PUBDIR, here
PUBDIR="${CONTENTROOT}/en/"
URL_PUBDIR=http://www.tldp.org/en/
-HOWTOS="${CONTENTROOT}/HOWTO"
-GUIDES="${CONTENTROOT}/LDP"
+cd "$CONTENTROOT"
# -- HOWTO handling: build symlinks and HTTP META-EQUIV files
#
+HOWTOS="${CONTENTROOT}/HOWTO/"
HOWTO_COMPAT=HOWTO.compat/
+HOWTO_MIGRATOR=${HERE}/howtomigration.py
+
test -d "${HOWTO_COMPAT}" \
|| mkdir "${HOWTO_COMPAT}"
-
HOWTO_COMPAT=$( readlink --canonicalize "$HOWTO_COMPAT" )
-
python \
"${HOWTO_MIGRATOR}" "${HOWTOS}" "${HOWTO_COMPAT}" "${PUBDIR}" "${URL_PUBDIR}"
+
+# -- guide handling: build symlinks and HTTP META-EQUIV files
+#
+GUIDES="${CONTENTROOT}/LDP/"
GUIDE_COMPAT=LDP.compat/
-test -d "${GUIDE_COMPAT}" \
- || mkdir "${GUIDE_COMPAT}"
-
-rsync --archive --verbose ./LDP/ "${GUIDE_COMPAT}/"
+GUIDE_MIGRATOR=${HERE}/guidemigration.py
+rsync --archive --verbose -- "${GUIDES}" "${GUIDE_COMPAT}"
+GUIDE_COMPAT=$( readlink --canonicalize "$GUIDE_COMPAT" )
python \
"${GUIDE_MIGRATOR}" "${GUIDES}" "${GUIDE_COMPAT}" "${PUBDIR}" "${URL_PUBDIR}"
+
+# -- ref handling: build symlinks and HTTP META-EQUIV files
+#
+REFS="${CONTENTROOT}/REF/"
+REF_COMPAT=REF.compat/
+REF_MIGRATOR=${HERE}/refmigration.py
+
+rsync --archive --verbose -- "${REFS}" "${REF_COMPAT}"
+REF_COMPAT=$( readlink --canonicalize "$REF_COMPAT" )
+python \
+ "${REF_MIGRATOR}" "${REFS}" "${REF_COMPAT}" "${PUBDIR}" "${URL_PUBDIR}"
+
+
+# -- ref handling: build symlinks and HTTP META-EQUIV files
+#
+FAQS="${CONTENTROOT}/FAQ/"
+FAQ_COMPAT=FAQ.compat/
+FAQ_MIGRATOR=${HERE}/faqmigration.py
+
+rsync --archive --verbose -- "${FAQS}" "${FAQ_COMPAT}"
+FAQ_COMPAT=$( readlink --canonicalize "$FAQ_COMPAT" )
+python \
+ "${FAQ_MIGRATOR}" "${FAQS}" "${FAQ_COMPAT}" "${PUBDIR}" "${URL_PUBDIR}"
+
+
exit 0
# -- end of file
diff --git a/LDP/migration-2016/migration-preparation.sh b/LDP/migration-2016/migration-preparation.sh
index 756231cd..52c6edac 100644
--- a/LDP/migration-2016/migration-preparation.sh
+++ b/LDP/migration-2016/migration-preparation.sh
@@ -41,8 +41,12 @@ mv \
REF/palmdevqs \
REF/ls_quickref \
REF/Joe-Command-Reference \
+ FAQ/Linux-FAQ \
+ FAQ/sig11 \
+ FAQ/Threads-FAQ \
+ FAQ/WordPerfect-Linux-FAQ \
-# -- and toss aside the really ancient crap
+# -- and toss aside the neolithically-ancient crap
#
TODELETE=todelete-$( date +%F )
test -d "${TODELETE}" \
diff --git a/LDP/migration-2016/refmigration.py b/LDP/migration-2016/refmigration.py
new file mode 100644
index 00000000..ffcfb8fe
--- /dev/null
+++ b/LDP/migration-2016/refmigration.py
@@ -0,0 +1,172 @@
+#! /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
+
+refdocs = '''CVS-BestPractices
+VideoLAN-Quickstart
+VLC-User-Guide
+VLS-User-Guide
+INTRO/Backup-INTRO
+INTRO/Intrusion-INTRO
+INTRO/PhysSecurity-INTRO
+INTRO/SecuringData-INTRO
+INTRO/Virus-INTRO'''.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
+ # add_renamed_stems(d)
+ # add_skipped_stems(d)
+ 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 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
From 568ccc1088bb3475a9fce1669c0f29eccb43f264 Mon Sep 17 00:00:00 2001
From: "Martin A. Brown"
Date: Fri, 25 Mar 2016 15:44:21 -0700
Subject: [PATCH 08/11] original SGML files found in output directory
---
LDP/retired/3Dfx-HOWTO.sgml | 2278 ++++++++++
LDP/retired/Beowulf-HOWTO.sgml | 1211 ++++++
LDP/retired/IP-Subnetworking.sgml | 630 +++
LDP/retired/ISP-Connectivity.sgml | 299 ++
LDP/retired/KickStart-HOWTO.sgml | 1184 ++++++
LDP/retired/Laptop-HOWTO.sgml | 3721 +++++++++++++++++
.../Loopback-Encrypted-Filesystem-HOWTO.sgml | 400 ++
LDP/retired/Loopback-Root-FS.sgml | 743 ++++
LDP/retired/MGR-HOWTO.sgml | 601 +++
LDP/retired/MIPS-HOWTO.sgml | 1651 ++++++++
LDP/retired/MMBase.sgml | 262 ++
LDP/retired/Oracle-8-HOWTO.sgml | 1151 +++++
LDP/retired/SCSI-Programming-HOWTO.sgml | 2430 +++++++++++
LDP/retired/Ultra-DMA.sgml | 794 ++++
LDP/retired/VPN.sgml | 360 ++
LDP/retired/WWW-HOWTO.sgml | 1222 ++++++
16 files changed, 18937 insertions(+)
create mode 100644 LDP/retired/3Dfx-HOWTO.sgml
create mode 100644 LDP/retired/Beowulf-HOWTO.sgml
create mode 100644 LDP/retired/IP-Subnetworking.sgml
create mode 100644 LDP/retired/ISP-Connectivity.sgml
create mode 100644 LDP/retired/KickStart-HOWTO.sgml
create mode 100644 LDP/retired/Laptop-HOWTO.sgml
create mode 100644 LDP/retired/Loopback-Encrypted-Filesystem-HOWTO.sgml
create mode 100644 LDP/retired/Loopback-Root-FS.sgml
create mode 100644 LDP/retired/MGR-HOWTO.sgml
create mode 100644 LDP/retired/MIPS-HOWTO.sgml
create mode 100644 LDP/retired/MMBase.sgml
create mode 100644 LDP/retired/Oracle-8-HOWTO.sgml
create mode 100644 LDP/retired/SCSI-Programming-HOWTO.sgml
create mode 100644 LDP/retired/Ultra-DMA.sgml
create mode 100644 LDP/retired/VPN.sgml
create mode 100644 LDP/retired/WWW-HOWTO.sgml
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
+Bernd Kreimeier
+ ()
+v1.16, 6 February 1998
+
+
+
+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
+
+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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Hardware accelerated 3D graphics with 3Dfx Voodoo
+
+XFree86 and 3Dfx Voodoo
+OpenGL and 3Dfx Voodoo
+Mesa and 3Dfx Voodoo
+GLUT and 3Dfx Voodoo
+GGI and 3Dfx Voodoo
+
+3Dfx
+Voodoo chipset
+Glide API for Linux
+
+Quantum 3D
+Obsidian graphics boards
+
+Orchid Righteous 3D
+Canopus Pure 3D
+Hercules Stealth 3D
+Diamond Monster 3D
+
+Quake for Linux
+GLQuake for Linux
+GLQuake and 3Dfx Voodoo
+
+
+ ]]>
+
+
+
+Introduction
+
+
+
+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.
+
+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.
+
+
+Contributors and Contacts
+
+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.
+
+Daryll Strauss
+ did the port,
+Paul J. Metzger
+
+modified the &VooMesa; driver (written by
+David Bucciarelli
+) for Linux,
+Brian Paul
+
+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
+.
+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 .
+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.
+
+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
+.
+
+
+Acknowledgments
+
+&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.
+
+Revision History
+
+
+Version 1.03First version for public release.
+Version 1.16Current version &CurrentVer; &CurrentDate;.
+
+
+Internal Revision History
+
+The verbose revision history below is for internal use only,
+to provide assistance during the review/copy editing process.
+
+
+ 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
+ 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.
+
+
+
+ ]]>
+
+
+
+
+New versions of this document
+
+You will find the most recent version of this document at
+.
+
+New versions of this document will be periodically posted to the
+ newsgroup. They will also be uploaded
+to various anonymous ftp sites that archive such information including
+.
+
+Hypertext versions of this and other Linux HOWTOs are available on
+many World-Wide-Web sites, including
+. Most Linux CD-ROM
+distributions include the HOWTOs, often under the
+/usr/doc/directory, and you can also buy printed copies from
+several vendors.
+
+If you make a translation of this document into another language, let
+me know and I'll include a reference to it here.
+
+
+Feedback
+
+I rely on you, the reader, to make this HOWTO useful. If you have any
+suggestions, corrections, or comments, please send them to me (
+), and I will try to
+incorporate them in the next revision. Please add
+HOWTO 3Dfx to the Subject-line of the mail, so procmail
+will dump it in the appropriate folder.
+
+Before sending bug reports or questions, please read all of the
+information in this HOWTO, and send detailed information
+about the problem.
+
+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
+(),
+for more information.
+
+
+Distribution Policy
+
+Copyright (c) 1997, 1998 by Bernd Kreimeier.
+This document may be
+ distributed under the terms set forth in the LDP license
+ at
+.
+
+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
+without any warranty; without even the implied warranty of
+merchantability or fitness for a particular purpose.
+See the LDP license for more details.
+
+
+
+
+
+Graphics Accelerator Technology
+
+Basics
+
+This section gives a very 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.
+
+Hardware configuration
+
+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.
+
+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.
+
+A bit of &VooDoo; architecture
+
+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.
+
+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).
+
+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.
+
+
+Installation
+
+Configuring Linux to support &c3Dfx; accelerators involves the
+following steps:
+
+
+- Installing the board.
+
- Installing the &Glide; distribution.
+
- Compiling, linking and/or running the application.
+
+
+The next sections will cover each of these steps in detail.
+
+Installing the board
+
+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.
+
+As &c3Dfx; does not develop or sell any boards, do not contact
+them on any problems.
+
+Troubleshooting the hardware installation
+
+To check the installation and the memory mapping, do
+cat /proc/pci. The output should contain something like
+
+ 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.
+
+for a Diamond Monster 3D used with a Diamond Stealth-64. Additionally
+a cat /proc/cpuinfo /proc/meminfo might be helpfull for
+tracking down conflicts and/or submitting a bug report.
+
+With current kernels, you will probably get a boot warning
+like
+
+Jun 12 12:31:52 hal kernel: Warning : Unknown PCI device (121a:1).
+Please read include/linux/pci.h
+
+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 /usr/include/linux/pci.h
+and send all necessary information
+to
+.
+
+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.
+
+Configuring the kernel
+
+There is no kernel configuration necessary, as long as PCI
+support is enabled.
+The should be consulted for the details of
+building a kernel.
+
+
+Configuring devices
+
+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 /dev/dsp and /dev/audio). The
+driver uses the /dev/mem device which should
+always be available. In consequence, you need to use
+setuid or root privileges to access the
+accelerator board.
+
+Setting up the Displays
+
+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.
+
+Single screen display solution
+
+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.
+
+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.
+
+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.
+
+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.
+
+
+Single screen dual cable setup
+
+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.
+
+
+Dual screen display solution
+
+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.
+
+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
+
+setenv SST_DUALSCREEN 1
+
+to force continued video output in this setup.
+
+Installing the &Glide; distribution
+
+The &Glide; driver and library are provided as a single
+compressed archive. Use tar and gzip
+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.
+
+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
+can't load library 'libglide.so'.
+
+
+
+Using the detect program
+
+There is a bin/detect program in the distribution
+(the source is not available). You have to run it as root,
+and you will get something like
+
+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
+
+as a result. If you do not have root privileges, the program will
+bail out with
+
+Permission denied: Failed to change I/O privilege. Are you root?
+
+output might come handy for a bug report as well.
+
+
+
+Using the test programs
+
+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
+ for details.
+
+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 alpha.3df 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 Press A Key To Begin Test. Beware
+of loss of input scope if running X11 on the same screen
+at the same time.
+
+See the README.test for a list of programs, and other details.
+
+
+
+
+
+Answers To Frequently Asked Questions
+
+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
+
+- FAQ: Requirements?
+
- FAQ: &VooDoo;? &c3Dfx;?
+
- FAQ: &Glide;?
+
- FAQ: &Glide; and SVGA?
+
- FAQ: &Glide; and XFree86?
+
- FAQ: &Glide; versus OpenGL/Mesa?
+
- FAQ: But Quake?
+
- FAQ: Troubleshooting?
+
+Each section lists several questions and answers, which
+will hopefully address most problems.
+
+
+FAQ: Requirements?
+
+What are the system requirements?
+
+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.
+
+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.
+
+Does it work with Linux-Alpha?
+
+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.
+
+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.
+
+
+Which &c3Dfx; chipsets are supported?
+
+Currently, the &c3Dfx; &VooDoo; chipset is supported
+under Linux. The &VooRush; chipset is not yet supported.
+
+Is the &VooRush; supported?
+
+The current port of &Glide; to Linux does not support
+the &VooRush;. An update is in the works.
+
+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.
+
+Thus &VooRush; based boards like the
+Hercules Stingray 128/3D
+or Intergraph Intense Rush are not supported
+yet.
+
+
+Which boards are supported?
+
+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.
+
+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.
+
+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.
+
+Boards that are not based on &c3Dfx; chipsets (e.g. manufactured
+by S3, Matrox, 3Dlabs, Videologic) do not work with the &c3Dfx;
+drivers and are beyond the scope of this document.
+
+
+
+How do boards differ?
+
+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.
+
+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.
+
+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.
+
+
+What about AGP?
+
+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.
+
+
+
+FAQ: &VooDoo;? &c3Dfx;?
+
+Who is &c3Dfx;?
+
+&c3Dfx is a San Jose based manufacturer of 3D graphics
+accelerator hardware for arcade games, game consoles,
+and PC boards.
+Their official website is
+. &c3Dfx; does not sell any boards,
+but other companies do, e.g. Quantum3D.
+
+
+Who is Quantum3D?
+
+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
+
+for additional information. For general inquiries
+regarding Quantum3D,
+please send mail to
+.
+
+
+
+What is the &VooDoo;?
+
+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.
+
+What is the &VooRush;?
+
+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.
+
+What is the &VooD2;?
+
+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.
+
+The &VooD2; is supposed to be backwards compatible.
+However, a new version of &Glide; will have to be
+ported to Linux.
+
+
+What is VGA pass-though?
+
+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.
+
+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.
+
+What is &Texelfx; or TMU?
+
+&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.
+
+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.
+
+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.
+
+
+What is a &Pixelfx; unit?
+
+&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.
+
+
+What is SLI mode?
+
+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.
+
+The &Pixelfx; in question can be on the same board,
+or on two boards properly connected. Some Quantum3D
+Obsidian boards support SLI with &VooDoo;.
+
+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.
+
+
+Is there a single board SLI setup?
+
+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.
+
+
+How much memory? How many buffers?
+
+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.
+
+ "SLI / Pixelfx / Texelfx1 / Texelfx2 "
+
+It means that a common 2MB+2MB board would be a
+1/2/2/0 solution, with the minimally
+required total 4Mb of memory. A Canopus Pure 3D
+would be 1/2/4/0, or 6MB. An Obsidian-2220
+board with two Texelfx would be 1/2/2/2,
+and an Obsidian SLI-2440 board would be 2/2/4/4.
+A fully featured dual board solution (2 Pixelfx, each
+with 2 Texelfx and 4MB frame buffer, each Texelfx 4 MB
+texture cache) would be 2/4/4/4, and the
+total amount of memory would be
+SLI*(Pixelfx+Texelfx1+Texelfx2), or 24 MB.
+
+So there.
+
+Does the &VooDoo; do 24 or 32 bit color?
+
+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.
+
+Does the &VooDoo; store 24 or 32 bit z-buffer per pixel?
+
+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.
+
+What resolutions does the &VooDoo; support?
+
+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.
+
+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.
+
+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.
+
+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.
+
+
+What texture sizes are supported?
+
+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.
+
+Does the &VooDoo; support paletted textures?
+
+The &VooDoo; hardware and &Glide; support the palette
+extension to &OGL;. The most recent version of
+&Mesa; does support the
+GL_EXT_paletted_texture
+and
+GL_EXT_shared_texture_palette extensions.
+
+
+What about overclocking?
+
+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.
+
+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.
+
+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.
+
+
+Where could I get additional info on &VooDoo;?
+
+There is a FAQ by &c3Dfx;, which should be available
+at their
+.
+You will find retail information
+at the following locations:
+
+and
+.
+
+Inofficial sites that have good info
+are "Voodoo Extreme" at
+, and
+"Operation 3Dfx"
+at
+.
+
+
+
+FAQ: &Glide;? &TexUs;?
+
+What is &Glide; anyway?
+
+&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.
+
+What is &TexUs;?
+
+In the distribution is a libtexus.so, 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.
+
+The &TexUs; utility program texus
+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 texus, and the
+API, see the &TexUs; documentation.
+
+
+Is &Glide; freeware?
+
+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;.
+
+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!
+
+Where do I get &Glide;?
+
+The entire &c3Dfx; SDK is available for download off their
+public web-site located at
+. Anything
+else &c3Dfx; publicly released by &c3Dfx; is nearby on
+their website, too.
+
+There is also an FTP site,
+. The FTP has a longer timeout, and some
+of the larger files have been broken into 3 files
+(approx. 3MB each).
+
+
+Is the &Glide; source available?
+
+Nope. The &Glide; source is made available only based
+on a special agreement and NDA with &c3Dfx;.
+
+Is Linux &Glide; supported?
+
+Currently, Linux &Glide; is unsupported. Basically,
+it is provided under the same disclaimers
+as the 3Dfx GL DLL (see below).
+
+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).
+
+In addition, the Quantum3D web page claims that
+Linux support (for Obsidian) is planned for both Intel
+and AXP architecture systems in 2H97.
+
+Where could I post &Glide; questions?
+
+There are newsgroups currently available only on
+the NNTP server 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:
+
+3dfx.events
+3dfx.games.glquake
+3dfx.glide
+3dfx.glide.linux
+3dfx.products
+3dfx.test
+
+and the 3dfx.oem.products.* group for
+specific boards, eg. 3dfx.oem.products.quantum3d.obsidian.
+Please use
+ for all
+Lnux &Glide; related questions.
+
+A mailing list dedicated to Linux &Glide; is in preparation
+for 1Q98. Send mail to
+, no subject,
+body of the message info linux-3dfx to get
+information about the posting guidelines, the
+hypermail archive and how
+to subscribe to the list or the digest.
+
+
+Where to send bug reports?
+
+Currently, you should rely on the newsgroup (see above),
+that is
+.
+There is no official support e-mail set up yet.
+For questions not specific to Linux Glide, make sure
+to use the other newsgroups.
+
+Who is maintaining it?
+
+&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
+
+
+How can I contribute to Linux &Glide;?
+
+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.
+
+
+Do I have to use &Glide;?
+
+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.
+
+
+
+Should I program using the Glide API?
+
+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;.
+
+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.
+
+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.
+
+
+What is the &Glide; current version?
+
+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.
+
+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.
+
+
+Does it support multiple &Texelfx; already?
+
+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.
+
+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.
+
+
+
+Is Linux &Glide; identical to DOS/Windows &Glide;?
+
+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.
+
+Where to I get information on &Glide;?
+
+There is exhaustive information available from
+&c3Dfx;. You could download it from their home
+page at
+.
+These are for free, presuming you bought a &c3Dfx;
+hardware based board. Please read the licensing regulations.
+
+Basically, you should look for some of the following:
+
+- Glide Release Notes
+
- Glide Programming Guide
+
- Glide Reference Manual
+
- Glide Porting Guide
+
- TexUs Texture Utility Software
+
- ATB Release Notes
+
- Installing and Using the Obsidian
+
+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
+ as well. Note that the release
+numbers are not always in sync with those of &Glide;.
+
+
+Where to get some &Glide; demos?
+
+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.
+
+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.
+
+
+What is ATB?
+
+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.
+
+
+FAQ: &Glide; and XFree86?
+
+Does it run with XFree86?
+
+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.
+
+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).
+
+
+Does it only run full screen?
+
+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.
+
+
+What is the problem with AT3D/&VooRush; boards?
+
+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.
+
+There is a mailing list on this, and a web site
+with FAQ at
+.
+Look there for most current info.
+There is a SuSE maintained driver at
+.
+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.
+
+The
+following XF86Config settings reportedly work.
+
+# 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)
+
+In summary, there is nothing prohibiting this except
+for the fact that the drivers in XFree86 are not yet
+finished.
+
+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.
+
+
+What about GLX for XFree86?
+
+There are a couple of problems.
+
+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.
+
+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.
+
+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
+
+for the most recent information.
+Moreover, there is a joint effort by XFree86 and
+SuSe, which includes a GLX, see
+.
+Currently, &Mesa; still uses its GLX emulation with Linux.
+
+
+&Glide; and commerical X Servers?
+
+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.
+
+
+&Glide; and SVGA?
+
+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.
+
+&Glide and GGI?
+
+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
+.
+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.
+
+
+
+FAQ: &OGL;/&Mesa;?
+
+What is &OGL;?
+
+&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.
+
+&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.
+
+
+Where to get additional information on OpenGL?
+
+The official site for &OGL; maintained by the members
+of the ARB, is
+,
+
+A most recommended site is Mark Kilgard's Gateway to &OGL;
+Info at
+:
+it provides pointers to book, online manual pages, GLUT,
+GLE, Mesa, ports to several OS, tons of demos and tools.
+
+If you are interested in game programming using &OGL;,
+there is the OpenGL-GameDev-L@fatcity.com at
+Listserv@fatcity.com. Be warned, this is
+a high traffic list with very technical content, and
+you will probably prefer to use procmail to
+handle the 100 messages per day coming in. You cut
+down bandwidth using the
+ SET OpenGL-GameDev-L DIGEST
+command. It is also
+not appropriate if you are looking for introductions.
+The archive is handled by the ListServ software, use
+the
+ INDEX OpenGL-GameDev-L
+and
+ GET OpenGL-GameDev-L "filename"
+commands to get a preview before subscribing.
+
+
+
+Is Glide an &OGL; implementation?
+
+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).
+
+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).
+
+
+Is there an &OGL; driver from &c3Dfx;?
+
+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.
+
+A linux port has not been announced yet.
+
+
+Is there a commercial &OGL; for Linux and &c3Dfx;?
+
+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.
+
+
+What is Mesa?
+
+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.
+
+
+Does Mesa work with &c3Dfx;?
+
+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.
+
+You will need to get the Mesa library archive
+from the
+.
+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.
+
+
+How portable is &Mesa; with &Glide;?
+
+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.
+
+&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
+.for the
+most current releases.
+
+
+Where to get info on &Mesa;?
+
+The &Mesa; home page is at
+.
+There is an archive of the Mesa mailing list.
+at
+. 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.
+
+Where to get information on &VooMesa;?
+
+For latest information on the &VooMesa; driver
+maintained by David Bucciarelli
+
+see the home page at
+.
+
+
+
+Does Mesa support multitexturing?
+
+Not yet (as of &Mesa; &MesaVer;), but it is on the list.
+In &Mesa; you will probably have to use the &OGL;
+EXT_multitexture 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.
+
+
+
+
+Does Mesa support single pass trilinear mipmapping?
+
+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.
+
+
+
+What is the Mesa "Window Hack"?
+
+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 glXSwapBuffers call. This feature
+is also available with Mesa for Windows.
+
+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).
+
+Note that this experimental feature is NOT
+&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.
+
+Make really sure that you have enabled the
+following environment variables:
+
+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
+
+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.
+
+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.
+
+
+
+
+How about GLUT?
+
+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
+,
+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.
+
+There is also a GLUT mailing list,
+glut@perp.com. Send mail to
+,
+with the (on of the) following
+in the body of your email message:
+
+ help
+ info glut
+ subscribe glut
+ end
+
+
+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.
+
+
+FAQ: But Quake?
+
+What about that &c3Dfx; GL driver for Quake?
+
+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
+ for
+an inofficial list of supported code paths). It is
+not supported, and not updated anymore.
+It was a Win32 DLL (opengl32.dll) released
+by &c3Dfx; and was available for Windows only. This
+DLL is not, and will not be ported to Linux.
+
+Is there a &c3Dfx; based glQuake for Linux?
+
+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.
+
+See
+