Como devo trabalhar com vários filtros make4ht?

Question

À medida que uso tex4ht / make4ht mais, acho que estou construindo uma coleção de minhas próprias personalizações. Para ajudar a organizar isso, existe uma maneira recomendada de gerenciar, incluindo (vários) filtros / domfilters personalizados no make4ht?

Eu sei que (especificamente para um domfilter) posso fazer um arquivo build.luacom

local domfilter = require "make4ht-domfilter"
local process = domfilter {
  -- do stuff here
  return dom
  end
}
Make:match("html$", process)

e então corra make4ht -e build.lua.

Mas e se eu quiser ter alguns filtros (dom) diferentes para fazer coisas diferentes? Posso dividi-los em arquivos diferentes e especificar de alguma forma qual executar?

Além disso, é possível especificar filtros (personalizados ou 'padrão') para serem executados em um pacote .sty / .4ht ou em .cfg? (Eu reconheço que isso pode representar um risco de segurança ...)

Receio que haja muitas perguntas aqui, mas as respostas a qualquer uma seriam bem-vindas.

Answer 1

Infelizmente, não é possível modificar a sequência de construção do lado do TeX, tudo precisa ser feito em arquivos Lua.

Você pode definir facilmente novos módulos de filtro DOM. Você só precisa usar o esquema seguinte nome: domfilters/make4ht-<filtername>.lua. O domfiltersdiretório pode ser colocado em seu diretório atual, mas se você quiser torná-lo universalmente disponível, é melhor colocá-lo em sua árvore TEXMF local, no scripts/lua/diretório. Por exemplo, no meu sistema, pode ser ~/texmf/script/lua/domfiltersou ~/texmf/script/lua/make4ht/domfilters.

O módulo de filtro DOM deve exportar a função que pega o objeto DOM, faz modificações nele e depois o retorna. Veja os filtros DOM existentes para se inspirar.

O filtro DOM de amostra pode ser assim (nomeado ~/texmf/scripts/lua/make4ht/domfilters/make4ht-test.lua):

return function(dom)
  print "Hello world"
  return dom
end

Você pode exigir este filtro DOM de um arquivo de compilação como este:

local domfilters = require "make4ht-domfilter"

local process = domfilters {"test"}
Make:match("html$", process)

Você pode encadear vários filtros:

local process = domfilters {"test", "fixinlines"}

Cada etapa pega o objeto DOM do filtro anterior, portanto, você não precisa analisar o arquivo HTML novamente.

Se quiser disponibilizar sua sequência de construção em vários projetos, você tem duas opções:

1. arquivo de configuração make4ht
2. nova extensão

O arquivo de configuração make4ht é diferente do arquivo de configuração TeX4ht (arquivo TeX com .cfgextensão). É um arquivo especial de construção Lua que pode ser colocado em seu diretório pessoal ou na raiz de um projeto. Deve ser nomeado .make4ht. Portanto, você pode simplesmente pegar o exemplo de arquivo de construção acima, renomeá-lo para .make4hte colocá-lo em qualquer um dos diretórios pais do seu projeto e ele será usado automaticamente.

As extensões podem modificar vários aspectos do processo de construção. Eles devem ser colocados no make4ht/extensionsdiretório e nomeados como make4ht-ext-<filename>.lua. Eles precisam exportar tabelas com funções, principalmente modify_build.

Aqui está um exemplo de extensão make4ht-ext-sample.lua:

local M = {}

local filter = require "make4ht-domfilter"

function M.test(format)
  print("hello format", format)
  return true
end

function M.modify_build(make)
  -- number of filters that should be moved to the beginning
  print "hello modify build"
  local process = filter {"test"}
  make:match("html?$", process)
  return make
end

return M

A função M.testassume o formato de saída atual e decide se a extensão deve ser executada ou não. Algumas extensões suportam apenas HTML, por exemplo, então esta função retorna falsee não é usada.

A função M.modify_buildpode conter código semelhante aos arquivos de construção, mas a make4htvariável, passada como parâmetro, é usada em vez do Make4htobjeto global que é usado nos arquivos de construção comuns.

A extensão pode ser necessária usando o fparâmetro de make4ht, como

make4ht -f html5+sample filename.tex

A saída deste comando é:

[STATUS]  make4ht: Conversion started
[STATUS]  make4ht: Input file: sample.tex
hello format    html5
hello modify build
Hello world
[STATUS]  make4ht: Conversion finished