Back to Computer Support Back to PAV Home Page English version

TeX4HT sob o MiKTeX

Philip A. Viton

Translated by Alexandra Bernardo

11 de Junho de 2001

Conteúdo

Part I
Overview

1 Introdução

Este documento explica como instalar o TeX4ht, o sistema de tradução de TeX/LaTeX para hipertexto de Eitan Gurari, quando o sistema de Tex subjacente é o MiKTeX para plataformasWin32. Obrigado ao Eitan por ter respondido a imensas perguntas sobre o TeX4ht e ao Steve Mayer pela realização de uma grande diversidade de testes e sugestões válidas referentes ao htrun.

Note by the original author: Alexandra Bernardo has kindly provided this Portuguese translation of my installation instructions for TeX4ht+MiKTeX. However, she doesn't have the time, and I don't have the ability, to keep it up-to-date. So Portuguese users may want to at least skim the "updates" section of the original English edition.

2 Updates

Esta secção lista alterações e updates às instruções, como referência, se necessário.

18 de Fevereiro de 2001: Revisão geral da documentação relativa ao MiKTeX2.
12 de Janeiro de 2001: O LaTeX Win95/98/98 pode aparentemente não funcionar se for chamado por um ficheiro batch com as line-endings do Unix. O htlatex.tab distribuído (que copiará para htlatex.bat) pode ser um candidato à resolução do problema anteriormente mencionado. A secção 8 explica como resolver isto. Que eu saiba, isto nunca é um problema com o WinNT4 ou Win2k.
22 de Fevereiro de 2000:

Steve Mayer produziu uma interface GUI para o TeX4ht com um aspecto muito agradável (e para outras utilidades do TeX/LaTeX que correm sob o Win32) chamado de TeX Converter. Aqui se encontra um link para o seu web site.
Adição de uma secção Ajuda, usando o redir.exe.

Parte II
Instalação

3 Aquisição do Software

3.1 MiKTeX

Estas instruções assumem que já tem o MiKTeX instalado para a sua localização num subdirectório c:\Program Files. Se ainda não o fez, eu recomendo fortemente que adquira e instale as versões PostScript das fontes CM e AMS : estas estão no miktex-2.0-lvl-2.zip. Além disto, estas instruções assumem também que durante a instalação de rotina do MiKTeX tenha adicionado o directório bin do MiKTeX no seu path.

3.1.1 A versão 1.20 do MiKTeX ou uma anterior a esta

Se está a usar a versão 1.20 do MiKTeX ou uma anterior a esta, as instruções funcionarão, no entanto, terá de fazer concessões aos directórios criados por defeito como se tem a seguir:

Directory
For	MikTeX2	MiKTeX 1.20

Binaries	c:\Program Files\Miktex\Miktex\bin	c:\texmf\Miktex\bin
Fonts	c:\Program Files\Miktex\fonts	c:\texmf\fonts
Local fonts	c:\Local TeXMF\fonts	c:\LocalTeXMF\fonts

Se possuir versões anteriores do MiKTeX pode ignorar o uso do nome “short” (8.3) dos ficheiros aquando da montagem do TeX4ht (ver secção 6.2) — as localizações por defeito já se encontram nesse formato. Finalmente, o procedimento de update da base de dados do MiKTeX é ligeiramente diferente. Pode fazê-lo:

Iniciando uma sessão do DOS e fazer correr o comando initexmf -u
Clicando Start -> Programs -> MiKTeX -> Maintenance -> Refresh Filename database.

3.2 TeX4ht

Estas instruções suportam a versão do TeX4ht lançada a 18 de Fevereiro de 2001 (ou de data superior). Se tiver uma versão anterior, deve fazer um upgrade.

Browse até à página do TeX4ht, então:

Em “Installation” clique em “MS Windows”.
Clique no link que se encontra ao lado do seguinte excerto de texto “single file named wfiles.zip” (no fundo do item (b)) para efectuar o download do arquivo.

Muito recomendado: Adquira todos os updates do TeX4ht. Eitan Gurari publica-os periodicamente, e pode inclusive adquiri-los agora. Para o fazer:

Se não se encontra na página dos “Bug Fixes ” , volte à página principal do TeX4ht; clique em “Bug Fixes”
Se existirem updates, clique em “Alternative zipped”. Este procedimento irá remeter-lhe o new4ht.zip que contém todas os updates.

3.3 ImageMagick

Estas instruções aplicam-se apenas à versão 5.20 ou superiores. Se tiver uma versão anterior, deve fazer o seu upgrade.

Browse ao ImageMagick. A meio da página encontrará links para as distribuições do Windows que, de facto, se referem todas ao mesmo ficheiro.

3.4 GhostScript

Excepto pelo directório de instalação criado por defeito, estas instruções suportam as versões 6.0 ou posteriores do GhostScript.

Browse ao GhostScript. Clique no link “Obtaining AFPL GhostScript 6.50”, e procure a secção para MS-Windows, e faça o download do executável gs650w32.exe

4 Instalação do GhostScript

4.1 Instalação da distribuição

Clique duas vezes sobre gs650w32.exe, que contém uma rotina de instalação. Ser-lhe-á perguntado onde instalar: eu recomendo que aceite as localizações criadas por defeito, que colocarão o executável em c:\gs\bin. Não retire a selecção feita às fontes do GhostSript: poderá precisar delas. Não instale o GhostScript num directório cujo o path contenha um espaço - O TeX4ht não será capaz de o processar.

5 Instalação do ImageMagick

5.1 Instalação da distribuição

Descompacte a distribuição para c:\ preservando os subdirectórios. Este, normalmente, coloca os ficheiros executáveis em c:\ImageMagick-win2k. Não instale o ImageMagick num directório cujo path contenha um espaço — O TeX4ht não será capaz de o processar.

5.2 Configuração da distribuição

Para que o ImageMagick encontre o seu ficheiro delegates , precisa de preparar o “environment variable” magick_delegate_path a apontar para o directório que contém delegates.mgk, correntemente c:\ImageMagick-win2k. Também terá de preparar a “variable” magick_module_path para o local dos modules.mgk, que será o mesmo lugar de delegates.mgk. Pode deixar os ficheiros batch descritos na secção 13 fazê-los por si ou pode fazê-lo directamente como descrito no Apêndice A.

6 Instalação do TeX4ht

6.1 Instalação da distribuição

Descompacte wfiles.zip para c:\tex4ht preservando as pastas (subdirectórios). Isto coloca os ficheiros em c:\tex4ht e subdirectórios. Se adquiriu os updates do TeX4ht, descompacte-os para c:\tex4ht onde os novos ficheiros irão rescrever os ficheiros antigos.

Retorne ao directório TeX4ht. Os ficheiros style do TeX4ht têm que ser movidos para a LaTeX tree no MiKTeX. (O Plain TeX também os encontrará!)

Crie um novo directório na LaTeX tree, por exemplo c:\Program Files\miktex\tex\latex\tex4ht
Copie *.sty e *.4ht de c:\tex4ht para este directório. Apague-os de c:\tex4ht.
Agora surge a necessidade de fazer um update à base de dados do MiKTeX ou o TeX não encontrará esses ficheiros. Faça Start Menu -> Programs > MikTeX 2 -> MiKTeX Options. Na folha General tab, clique no botão Refresh Now.

6.2 Configuração da distribuição

A seguir, deverá configurar o tex4ht.env. A única dificuldade aqui, é que tem de ter a certeza de que está a usar o short (aka “8.3”) form dos directórios que instalou no MiKTeX para um directório top-level cujo nome contém um espaço. A localização do MiKTeX2 é, por defeito, c:\Program Files\miktex que recai nesta rubrica; tal como o directório c:\Local TeXMF.

As instruções que se seguem baseiam-se nas localizações criadas, por defeito, do MikTeX2.Pode verificar o short form de qualquer um destes ficheiros ou directórios iniciando uma sessão do DOS e fazendo dir /p no Win 95/98/ME ou dir /x/p no Win NT4/Win2k.

Abra o tex4ht.env num editor de texto e:

Na linha tc:\path\tfm! substitua path pelo short form do path do directório das fontes do MiKTeX. Por defeito, este é Progra~1\miktex\fonts logo, a linha terá o seguinte aspecto tc:\Progra~1\miktex\fonts\tfm! correspondendo ao local actual c:\Program Files\miktex\fonts\tfm.
Adicione outra linha t apontando para o local onde as suas font metrics podem ser instaladas novamente usando a sintaxe 8.3: na montagem por defeito deverá adicionar a linha tc:\Localt~1\fonts\tfm! (não se esqueça do t inicial e do ponto de exclamação no fim da linha), que corresponde ao local actual c:\Local TeXMF\fonts\tfm.
Se instalou o MiKTeX para incorporar outras LaTeX trees, adicione também linhas t para os ficheiros tfm.
Na linha que começa por Ggswin32c altere gswin32c para o nome completo da drive/path de gswin32c.exe: na instalação por defeito do GhostScript 6.50 este é Gc:\gs\bin\gswin32c. Certifique-se de não apagar o G inicial pois este é necessário ao TeX4ht.
Na linha que começa com Gconvert, altere convert para o nome completo da drive/path da utilidade convert do ImageMagick: na instalação por defeito este é Gc:\ImageMagick-win2k\convert. Certifique-se de não apagar o G pois este é necessário ao TeX4ht.

Guarde tex4ht.env.

A seguir, adicione o directório do TeX4ht (ie c:\tex4ht) no seu path. Pode fazer isto permanentemente a partir do painel de controlo doWindows NT ou editando o autoexec.bat no Windows 95/98 (note que se editar o autoexec.bat terá de reiniciar o seu computador para que as alterações tenham efeito) ou pode deixar que os ficheiros batch descritos na secção 13 o façam por si.

Finalmente, copie os ficheiros .tab (ht, htlatex, httex, e httexi) de modo a que se tornem ficheiros .bat e mude-os para um directório no seu path. Como o directório \ bin do MikTeX já estará no seu path, esta é uma escolha possível.

6.3 Aceleração a geração das imagens

Quando o TeX4ht precisa de representar um caracter singular não presente no default viewing font, este produz uma imagem gif usando o GhostScript e o ImageMagick. Estas imagens de caracteres singulares — as quais chamaremos “glyph-gifs” — nunca variam enquanto o documento está a ser processado e o TeX4ht é suficientemente “inteligente” para saber que, se estão presentes no directório corrente, não existe razão para as regerar.

TeX4ht também providência uma forma de usar programas diferentes para criar “glyph-gifs” e outros gifs, que aumentam a possibilidade de gerir de maneira mais sofisticada os “glyph-gifs”. Poderá fazer isto arranjando um F script no tex4ht.env. Se o fizer, o G script (linhas começadas por G) irá controlar outros gifs, enquanto o F script será invocado por “glyph-gifs”.

A maneira mais simples de fazer o set up de um F script é chamando um ficheiro batch, por exemplo glyphgif.bat. Para fazer isto basta adicionar a linha

Fglyphgif.bat %%1 %%2 %%3

ao tex4ht.env assegurando-se, no entanto, de dobrar o símbolo %.

O próximo passo é criar um glyphgif.bat em c:\tex4ht. Uma amostra glyphgif.bat que reflecte a montagem descrita neste documento, está incluída nas utilidades suplementares do Tex4ht-MiKTeX, as quais podem ser downloaded directamente daqui. Como pode ver o que faz é:

Verificar se o “glyph-gif” necessário já está presente, se sim, abandone.
Senão, verifique se o gif se encontra num local cache, neste caso c:\tex4ht\cache. Se aí for encontrado, copie- o para o directório corrente e abandone.
Senão, construa o gif usando a combinação usual GhostScript+ImageMagick, quando terminar, coloque uma cópia do ficheiro gif no cache, para uso futuro.

Para montar esta facilidade:

Crie um directório onde guardará os glyph-gifs: eu sugiro c:\tex4ht\cache
Abra o ficheiro tex4ht.env. A seguir às linhas que definem as G script, adicione a linha Fglyphgif.bat %%1 %%2 %%3 (assegure-se de dobrar o símbolo %).
Coloque o glyphgif.bat no seu directório TeX4ht, edite-o (se necessário) para que, reflicta o local que escolheu para cache, e faça com que as linhas que chamam dvips e convert coincidam da maneira que são referidas no tex4ht.env. (Se optou por cut-e-paste entre tex4ht.env e glyphgif.bat, certifique-se de remover o G inicial e mudar todos os %% para %).

Aviso Existe um senão ao usar a montagem cache. Suponha que precisa de gerar um “glyph-gif” mas, por qualquer razão, a geração de gifs (via ImageMagick + GhostScript) falha. Tem agora um incorrecto — tipicamente vazio — ficheiro “glyph-gif” no seu cache e o TeX4ht continuará a usá-lo até que os apague. De facto, terá de apagar, não apenas, o gif incorrecto no cache, mas também a versão no seu directório source, pois a primeira coisa que o glyphgif.bat fará a seguir é encontrar o gif no seu directório source e colocá-lo de volta dentro do cache, e estará de novo no início. Isto pode ser muito confuso a não ser que esteja atento ao que pode acontecer. Pode (temporariamente) impedir o F script de correr, abrindo o tex4ht.env e colocando um espaço antes do caracter F na linha do tex4ht.env chamando F script. Isto força todos os glyph-gifs a serem criados da forma normal e o cache não será consultado ou updated.

6.4 Outras utilidades

A secção 13 explica como obter e usar algumas utilidades que podem simplificar o uso do TeX4ht. Poderá desde já, dar-lhe uma olhadela. Além disso, poderá também dar uma vista de olhos ao TeXConverter de Steve Mayer, uma interface GUI para o TeX4ht e outros programas de conversão. Esta encontra-se disponível aqui. O TeXConverter assume que tem um MiKTeX+TeX4ht setup a funcionar, por isso deve verificar a instalação descrita acima, antes de o adquirir.

Parte III
Teste da instalação e Problemas frequentes

7 Teste da Instalação

A distribuição do TeX4ht contém dois ficheiros de teste. Cada um deles gera um ficheiro HTML contendo uma única linha de texto, um único “glyph-gif”, e um único gif. Para fazer correr estes testes, assumindo que já montou todo o ambiente e path variables correctamente:

Inicie uma sessão DOS e trabalhe num directório diferente de c:\tex4ht
Copie testa.tex e textb.tex de c:\tex4ht para este directório
Primeiro, teste a nova interface que não necessita explicitamente de um LaTeX package: digite o comando

htlatex testb

O compilador TeX irá trabalhar e haverá duas chamadas de ImageMagick/GhostScript para gerar gifs.

A seguir, teste a interface antiga onde refere explicitamente o TeX4ht package na sua source. Digite o comando

ht latex testa

O compilador TeX irá trabalhar mas, porque o glyph-gif já está presente, ImageMagick/GhostScript serão chamados apenas uma vez.

Se algo correr mal, consulte a secção que se segue.

8 Problemas Frequentes

8.1 Dificuldade em encontrar os ficheiros .tfm

Se o TeX4ht parece incapaz de encontrar os ficheiros .tfm e está a usar o MiKTeX2, verifique se usou os nomes short quando configurou as entradas t do tex4ht.env. Ver secção 6.2.

8.2 LaTeX não funciona sob o Win95/98/ME

Sob o Win95/98/ME, o LaTeX pode não funcionar se for chamado de um ficheiro batch com Unix line-endings; os ficheiros batch fornecidos, tais como o htlatex.bat (que copiou de htlatex.tab) estão qualificados. O sintoma é uma mensagem que começa com This program has performed an illegal operation and will be shut down. A maneira de solucionar o problema é converter estes em ficheiros com line-endings Windows/DOS. A utilidade unix2win.exe, que se encontra aqui em unix2win.zip resolver-lhe-á o problema. (O arquivo .zip também está incluído nas utilidades suplementares descritas em baixo). Para usar isto, no caso de htlatex:

Descompacte unix2win.zip para o directório principal do TeX4ht.
Certifique-se de que ainda possui htlatex.tab. Senão, copie htlatex.bat para htlatex.tab.
Corra unix2win htlatex.tab htlatex.bat

O ficheiro batch htlatex.bat deverá agora funcionar.

8.3 Outros problemas

Deverá também :

Certificar-se que o MikTeX está a funcionar em condições, especialmente se acabou de o instalar. Se testar o ficheiro testa.tex e comentar (basta inserir um % no início da linha) a linha \usepackage{tex4ht}, este ficheiro deverá ser processado sem problemas pelo MiKTeX, e visualizado através do yap. Lembre-se de remover o comentário após o teste se ter realizado com sucesso.
Se o compilador TeX se queixar de não ser capaz de encontrar ficheiros, a causa mais provável é ter-se esquecido de fazer o update da base de dados do MiKTeX . Ver secção 6.2.
Senão, olhe para o ecrã com cuidado. A parte de geração das imagens do processo de conversão escreverá uma série de linhas com System return: 0 no seu monitor. Um valor diferente de zero indica que essa parte está a correr mal.
Se tem erro que começa por Error: /invalidfont in findfont isto significa que o GhostScript não encontra uma fonte da qual precisa. Certifique-se que todas as linhas de comando dvips (em tex4ht.env e glyphgif.bat) contêm -Pamz -Pcmz

Se pensa que o post-processing (GhostScript + ImageMagick) não adquire os parâmetros correctos, pode verificar isto adicionando linhas ao G script, tal como, por exemplo, o que se segue:

 Gecho parameter 1 is:  %%1      parameter 2 is:  %%2

 Gecho parameter 3 is:  %%3      parameter 4 is:  %%4

(Isto demonstra como estes scripts, fazem quase tudo o que deseja).

9 Ajuda

Se tudo isto falhar, estou disposto a tentar ajudar na aquisição do sistema TeX4ht set up. (Este é distinto do suporte do TeX4ht pelo qual deve contactar Eitan Gurari). Aqui tem os passos a seguir:

Vai precisar de redir a utilidade incluída nas utilidades suplementares do TeX4ht-MiKTeX , disponíveis a partir de aqui. Descompacte redir.zip de modo que o redir.exe se encontre num directório do seu path. Pode apagar redir.c.
Construa um ficheiro short source (.tex) que exiba a essência do problema. Por exemplo, se um glyph não gera o ficheiro gif correcto, a source deve conter pelo menos uma linha de texto, mais o caracter envolvido. Se o problema é um problema com gráficos deve também inclui-lo certificando-se de não inserir mais do que um.
Copie o ficheiro source (e qualquer ficheiro gráfico necessário) para um directório vazio.
Copie o ficheiro batch que usa para correr o TeX4ht para este directório. Se este ficheiro começa por @echo off altere para @echo on.
Digite o seguinte comando: set kpathsea_debug=-1 (sem espaços)
Agora corra o comando:

redir -o viton.txt -eo xht,

onde xht é o comando completo do TeX4ht, começando com o nome do ficheiro batch apropriado. Não deverá ver qualquer output. Se obtiver a seguinte mensagem The VDM redirector is already loaded então repita o comando com o path completo para redir (por exemplo c:\mydir\redir -o viton.txt -eo xht).

Isto criará o ficheiro