Re: Again: Next libvorbis release?

[resending this w/o mini-algo attachments]

Am 06.03.2009 um 15:38 schrieb Ralph Giles:

> Ok, I've committed the spec conversion. Please test.

Cool :). Builds fine over here.

> Max, please merge your tree and let me know anything I missed.

Looks good. Now I can build on this and extend it a bit.

>
> On Fri, Mar 6, 2009 at 7:47 AM, Max Horn <[email protected]> wrote:
>
>> To change this, replace
>>  \usepackage{hyperref}
>> by either this (for colored text instead of boxes)
>> \usepackage[colorlinks]{hyperref}
>> or this (for no marking of links at all)
>> \usepackage[pdfborder={0 0 0}]{hyperref}
>> Other options can be used to tweak colors, see <http://www.tug.org/applications/hyperref/manual.html#x1-90003.5
>> >.
>
> I switched to 'colorlinks' for now. Note that I got an "unterminated
> command" error if I didn't remove the intermediate files after adding
> this option. 'make clean' seems to be sufficient.

Hm? Do you mean you got that error just after changing the option? Or  
is it reproducible? If you tell me how, I can look into it. But I just  
touch'ed  Vorbis_I_spec.tex, and run make again (no "make clean"), and  
got no errors of any kind.

Actually, I do get one crash, but unrelated: ghostscript dies trying  
to convert xifish.pdf to xifish.png. This can be avoided by invoking  
htlatex like this (in Makefile*):
  htlatex $< Vorbis_I_spec

This will tell it to use the *.cfg file, which in turn tells it to use  
only PNGs, never PDFs. Now, just provide a xifish.png as part of the  
repos and you are done. E.g.
  svn cp white-xifish.png xifish.png



[...]

> New questions:
>
> htlatex seems to use dvi->ps->png to generate equations and tex-side
> vector figures. We can probably assume dvips, but I guess I should add
> imagemagick's 'convert' util to the dependency check?

Yeah.

Well, actually, in theory one can tell tex4ht to use dvipng to create  
the PNGs, which is much faster and somewhat prettier. But I am not  
sure whether dvipng is widely available, either. But I believe that it  
is part of TeXLive 2007 at least. Furthermore, at least on my system  
this option is broken, due to a bug in a global config file  
(tex4ht.env). While I can fix that, it's no good to ask all users to  
edit a system wide config file just to get this working, I am afraid  
*sigh*.

Anyway, here is how you can use dvipng if your tex4ht.env is *not*  
broken:
  htlatex $< "Vorbis_I_spec.cfg" "" "-cdvipng"

Oh yeah: one can provide a custom tex4ht.env. Only that it completely  
replace the system's ones, and it has different content on Windows.  
Argh. I included a tex4ht.env.off in the tarball on my website, for  
the curious. To use it, either rename it to tex4ht.env, or invoke  
tex4ht this way:

  htlatex $< "Vorbis_I_spec.cfg" "" "-cdvipng -e tex4ht.env.off"


> Is there any way to capture the list of figure files it's generating?
> We need to be able to reliably clean/install/distribute that set. Can
> I rely on the current name scheme? Can we force a particular naming
> scheme or stuff them in a subdirectory so they're safer to glob?

To specify an output directory, use this (to specify "build"):

htlatex $< "Vorbis_I_spec" "" "-dbuild/"

The trailing slash is essential! So is the empty "". Combined with the  
above:

  htlatex $< "Vorbis_I_spec" "" "-dbuild -cdvipng"



> Does pdflatex use the .cfg file at all, or is that just a dependency
> for htlatex?

Only htlatex needs it, pdflatex never touches it.



> Any idea on the status of svg or mathml generation in htlatex? That
> would be better obviously, although we'll still need png equations for
> fallback.

tex4ht can generate XHTML + MathML, but I never tried that. See here: <http://www.cse.ohio-state.edu/~gurari/TeX4ht/mn-commands.html#QQ1-9-37 
 >. See also <http://www.cse.ohio-state.edu/~gurari/TeX4ht/mml.html>.  
I used this command to generate an .xml file, based on the suggestions  
from there:

  htlatex Vorbis_I_spec.tex "xhtml,mozilla" " -cmozhtf" "-cvalidate - 
dbuild/ -cdvipng -e tex4ht.env.off -i"

(the -cvalidate would run xmllint -- only that it doesn't because it  
is disabled in my global tex4ht.env. I re-enabled it in my custom .env  
file. Nasty).
Unfortunately, this generates invalid XML in my version of tex4ht.  
Maybe I did something wrong, though -- didn't investigate it. Please  
note that I don't know MathML, and have no idea what some in that  
command above really means.

Moreover, while I am a mathematician, I never used MathML and kinda  
thought it was a dead standard ;-). It seems that <http://www.math.union.edu/~dpvc/jsMath/ 
 > is a nice approach, though, checkout.. And tex4ht supports that,  
too, at least in theory, but I didn't try.


>
> Right now, I'd consider these issues with the spec release critical:
>
> * Resolve ambiguous floor 0 LSP formulae
> * Install/dist the generated png files for the html spec

Use the -dbuild/ (or whatever) option.

BTW, you could also keep the PNG files in a subdir in SVN, e.g.  
images/, and tell LaTeX to search there. There is already a command  
for that (commented out) in Vorbis_I_spec.tex.

> * Fix long psuedocode lines so the pdf is readable; either shrink the
> font or wrap the lines

You can set a smaller font by modifying
  \fvset{tabsize=4,fontsize=\small}
E.g. use this to get a smaller font, plus automatic line numbers on  
the left side:
  \fvset{tabsize=4,fontsize=\scriptsize,numbers=left}

I attached a patch which does that and also cleans up the preamble in  
Vorbis_I_spec.tex abit.


>
> Not release critical, but would be nice:
>
> * Add convert and other htlatex dependencies to the configure check
> * Remove the built docs from svn and --enable-docs by default (pending
> testing and the above fix)
> * Remove the obsolete docbook files
> * Avoid page breaks inside the bitpacker verbatim "figures"
> * Adapt the css file to integrate with the website theme

One can place custom CSS (e.g. a statment that includes another .css  
file) into the generated .css by adding commands to the .cfg file, see  
<http://www.tug.org/applications/tex4ht/mn11.html#QQ1-11-61>

> * Generate v-comment.html automatically from 05-comment.tex
> * Update xifish to the current version
> * Improve psuedocode layout and variable notation

One package I personally like is algoritmicx. I whipped up a quick  
example, together with a question on the render_line algo ... :). See  
here:
* http://dev.quendi.de/vorbis/mini-algo.tex
* http://dev.quendi.de/vorbis/mini-algo.pdf
* http://dev.quendi.de/vorbis/mini-algo.html
(the HTML version suffers from "wrong" indention on the line numbers,  
but I believe that could be fixed).


> * Redraw some of the figures in a vector format
>
> Thanks again for all your work on this,
> -r
>


Max

_______________________________________________
Vorbis-dev mailing list
[email protected]
http://lists.xiph.org/mailman/listinfo/vorbis-dev

Index: Vorbis_I_spec.tex
===================================================================
--- Vorbis_I_spec.tex	(Revision 15754)
+++ Vorbis_I_spec.tex	(Arbeitskopie)
@@ -1,8 +1,5 @@
 % $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
@@ -13,9 +10,6 @@
 \usepackage{a4wide}
 
 % ...
-\usepackage{enumitem}
-
-% ...
 \usepackage[english]{babel}
 
 %\usepackage[latin1]{inputenc}
@@ -31,73 +25,72 @@
 % Hyperref enriches the generated PDF with clickable links,
 % and provides many other useful features.
 \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}
+\fvset{tabsize=4,fontsize=\scriptsize,numbers=left}
 
-% ...
-\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}
 
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % 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}''}
 
-%...
+% Emulat 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$}
+
+% 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}
+% Configure graphics formats: Prefer PDF, fall back to PNG or JPG, as available.
+\DeclareGraphicsExtensions{.pdf,.png,.jpg,.jpeg}
 
 
-% 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}