Re: Again: Next libvorbis release?

Index: Vorbis_I_spec.cfg
===================================================================
--- Vorbis_I_spec.cfg	(Revision 15933)
+++ Vorbis_I_spec.cfg	(Arbeitskopie)
@@ -1,4 +1,5 @@
-\Preamble{html} 
+\Preamble{html,info}
+%\Preamble{xhtml,jsmath}
 \begin{document}
   \DeclareGraphicsExtensions{.png}
 \EndPreamble
Index: Makefile.am
===================================================================
--- Makefile.am	(Revision 15933)
+++ Makefile.am	(Arbeitskopie)
@@ -99,7 +99,7 @@
 	cp $< $@
 
 Vorbis_I_spec.html Vorbis_I_spec.css: $(SPEC_TEX) $(SPEC_PNG) xifish.png
-	htlatex $<
+	htlatex $< Vorbis_I_spec.cfg
 
 Vorbis_I_spec.pdf: $(SPEC_TEX) $(SPEC_PNG) xifish.png
 	pdflatex $<
Index: Vorbis_I_spec.tex
===================================================================
--- Vorbis_I_spec.tex	(Revision 15933)
+++ Vorbis_I_spec.tex	(Arbeitskopie)
@@ -1,103 +1,130 @@
 % $Id$
-% latex2html -show_section_numbers -split 0 -html_version 4.0 Vorbis_I_spec.tex
-%\documentclass[a4paper]{article}
-\documentclass[a4paper]{scrartcl}
-%\documentclass[twoside,idxtotoc,bibtotoc,a4paper,12pt,BCOR12mm,DIV13]{scrbook}
+\documentclass[12pt,paper=a4]{scrartcl}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % Packages
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-% ...
-%\usepackage[margin=3cm]{geometry}
-\usepackage{a4wide}
+% Customize paper layout (if a different margin is desired, etc.)
+\usepackage[top=2cm,left=3cm,right=3cm,bottom=4cm]{geometry}
+%\usepackage{a4wide}
 
-% ...
-\usepackage{enumitem}
-
-% ...
+% Load hyphenation patterns for english text
 \usepackage[english]{babel}
 
-%\usepackage[latin1]{inputenc}
-%\usepackage[T1]{fontenc}
-
 % Do not indent paragraphs, instead separate them via vertical spacing
 \usepackage{parskip}
 
 % Support for graphics, provides \includegraphics
 \usepackage{graphicx}
-%\graphicspath{{images/}}	% Specify subdir containing the images
 
 % Hyperref enriches the generated PDF with clickable links,
-% and provides many other useful features.
+% and provides many other useful features. Its subpackage
+% nameref provides the \nameref macro which we use to implement
+% our \xref macros. Since older hyperref versions don't load
+% nameref automatically, we list it here explicitly
+\usepackage[colorlinks,linkcolor=blue]{hyperref}
 \usepackage{nameref}
-%\usepackage{hyperref}
-\usepackage[colorlinks]{hyperref}
-%\usepackage[pdfborder={0 0 0}]{hyperref}
-\def\sectionautorefname{Section}	% Write section with capital 'S'
-\def\subsectionautorefname{Subsection}	% Write subsection with capital 'S'
 
 
-% provides the 'comment' env, which is useful to temporarily comment out a block of code
-\usepackage{verbatim}
-
-% ...
-%\usepackage{listings}
-%\lstset{language=Pascal} 
-
 % The fancyvrb package provides the "Verbatim" environment, which,
 % unlike the built-in "verbatim", allows embedding TeX commands, as
 % well as tons of other neat stuff (line numbers, formatting adjustments, ...)
 \usepackage{fancyvrb}
-%\fvset{tabsize=4,fontsize=\scriptsize,numbers=left}
-\fvset{tabsize=4,fontsize=\small}
-%\fvset{tabsize=4}
 
-% ...
-\usepackage{color}      % Colored text, used for \TODO macro
-
-% ...
+% Normally, one can not use the underscore character in LaTeX without
+% escaping it (\_ instead of _). Since the Vorbis specs use it a lot,
+% we use the underscore package to change this default behavior.
 \usepackage[nohyphen]{underscore}
 
-% ...
+% In LaTeX, pictures are normally put into floating environments, and it is
+% left to the typesetting engine to place them in the "optimal" spot. These
+% docs however expect pictures to be placed in a *specific* position. So we
+% don't use \begin{figure}...\end{figure}, but rather a center environment.
+% To still be able to use captions, we use the capt-of package.
 \usepackage{capt-of}
 
+
+% Load the algorithmicx packages for typesetting algorithms:
+\usepackage{algorithmicx}
+\usepackage[ruled]{algorithm}
+\usepackage{algpseudocode}
+
+% AMS-LaTeX packages, for many useful math mode commands
+\usepackage{amsmath}
+\usepackage{amssymb}
+
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Various settings
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% Tell \nameref to refer to sections & subsections with a capital 'S'.
+\def\sectionautorefname{Section}
+\def\subsectionautorefname{Subsection}
+
+% % Specify subdir containing images
+%\graphicspath{{images/}}
+
+
+% Tell fancyvrb to use a small font and 4 spaces per tab
+\fvset{tabsize=4,fontsize=\scriptsize}
+%\fvset{tabsize=4,fontsize=\scriptsize,numbers=left}	% With line numbers
+
+% Configure graphics formats: Prefer PDF, fall back to PNG or JPG, as available.
+\DeclareGraphicsExtensions{.pdf,.png,.jpg,.jpeg}
+
+% ...
+%\algrenewcommand{\algorithmiccomment}[1]{\hskip3em$\triangleright$ #1} 
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % Custom commands
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 % Custom ref command, using hyperrefs autoref & nameref, to simulate the 
-% behavior of DocBooks's 'xref'.
+% behavior of DocBook's '<xref>'.
 \newcommand{\xref}[1]{\autoref{#1}, ``\nameref{#1}''}
 
-%...
+% Emulate DocBook's '<link>'.
 \newcommand{\link}[2]{\hyperref[#1]{#2}}
 
-% Redefine \~ to generate something that looks more appropriate when used in text.
-\renewcommand{\~}{$\sim$}
-
-% ...
+% Simple 'Note' environment. Can be customized later on.
 \newenvironment{note}{\subparagraph*{Note:}}{}
 
-% ...
+% Map DocBook's <programlisting> to fancyvrb's Verbatim environment
 \let\programlisting\Verbatim
 \let\endprogramlisting\endVerbatim
 
-% ...
+% Fake some more DocBook elements
 \newcommand{\function}[1]{\texttt{#1}}
 \newcommand{\filename}[1]{\texttt{#1}}
 \newcommand{\varname}[1]{\texttt{#1}}
 \newcommand{\literal}[1]{\texttt{#1}}
 
-% ...
+% Redefine \~ to generate something that looks more appropriate when used in text.
+\renewcommand{\~}{$\sim$}
+
+% Some math macros
+\newcommand{\abs}[1]{\lvert#1\rvert}        % absolute value: |foo|
+
+% Useful helper macro that inserts TODO comments very visibly into the generated
+% file. Helps you to not forget to resolve those TODOs... :)
 \newcommand{\TODO}[1]{\textcolor{red}{*** #1 ***}}
-\newcommand{\NOTE}[1]{\textcolor{blue}{*** #1 ***}}
 
-\DeclareGraphicsExtensions{.pdf,.png}
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Remarks
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-% TODO/FIXME: Things to watch out for:
-% - Translate some chars: ~ -> $\sim$,  % -> \%, & -> \&, ...
+% NOTE: Things to watch out for: Some chars are reserved in LaTeX. You need to translate them...
+%   ~ -> $\sim$ (or \~ which we defined above)
+%   % -> \%
+%   & -> \&
+%   < -> $<$
+%   > -> $>$
+% and others. Refer to any of the many LaTeX refs out there if in doubt!
 
 \begin{document}