groff - interface para o sistema de formatação de documentos GNU roff
Sinopse
groff [-abcCeEgGijklNpRsStUVXzZ] [-d ctext] [-d string=text] [-D fallback-encoding] [-f fontfamily] [-F font-directory] [-I inclusion-directory] [-K input-encoding] [-L spoolerargument] [-m macro-package] [-M macro-directory] [-n page-number] [-o page-list]
[-P postprocessor-argument] [-r cnumeric-expression] [-r register=numeric-expression]
[-T output-device] [-w warning-category] [-W warning-category] [file ...]
groff -h
groff --help
groff -v [option ...] [file ...]
groff --version [option ...] [file ...]
Descrição
groff é a principal interface para o sistema de formatação de documentos GNU roff. GNU roff é um sistema de composição que lê arquivos de texto simples que incluem comandos de formatação para produzir saída em PostScript, PDF, HTML, DVI ou outros formatos, ou para exibição em um terminal. Os comandos de formatação podem ser primitivos de composição de baixo nível, macros de um pacote fornecido ou macros definidas pelo usuário. Todas as três abordagens podem ser combinadas. Se nenhum operando de arquivo for especificado ou se o arquivo for "-", groff lê o fluxo de entrada padrão.
Uma reimplementação e extensão do compositor do AT&T Unix, groff está presente na maioria dos sistemas POSIX devido à sua longa associação com os manuais do Unix (incluindo as páginas de manual). Ele e seu predecessor são notáveis por produzirem vários textos de engenharia de software de grande sucesso. groff é capaz de produzir documentos tipograficamente sofisticados, consumindo recursos mínimos do sistema.
O comando groff orquestra a execução de pré-processadores, a transformação de documentos de entrada em uma linguagem de descrição de página independente do dispositivo e a produção de saída dessa linguagem.
Opções
-h e --help exibem uma mensagem de uso e saem.
Como groff tem como objetivo subsumir a maioria das invocações diretas do formatador troff pelos usuários, os dois programas compartilham um conjunto de opções. No entanto, groff tem algumas opções que troff não tem e outras que groff interpreta de forma diferente. Ao mesmo tempo, nem todas as opções válidas de troff podem ser dadas a groff.
Opções específicas do groff
As opções a seguir não existem no GNU troff ou são interpretadas de forma diferente por groff.
-D enc Define a codificação de entrada de fallback usada por preconv(1) para enc; implica -k.
-e Executa o pré-processador eqn(1).
-g Executa o pré-processador grn(1).
-G Executa o pré-processador grap(1); implica -p.
-I dir Funciona como a opção de troff (veja abaixo), mas também implica -g e -s. Ele é passado para soelim(1) e o driver de saída, e grn recebe uma opção -M com dir como seu argumento.
-j Executa o pré-processador chem(1); implica -p.
-k Executa o pré-processador preconv(1). Consulte sua página de manual para obter informações sobre seu comportamento se nenhuma das opções -K ou -D do groff também for especificada.
-K enc Define a codificação de entrada usada por preconv(1) como enc; implica -k.
-l Envia a saída para um programa de spooling para impressão. O diretivo “print” no arquivo de descrição do dispositivo especifica o comando padrão a ser usado; veja groff_font(5). Se não houver tal diretivo para o dispositivo de saída, a saída é enviada por pipe para lpr(1). Veja as opções -L e -X.
-L arg Passa arg para o programa de spooling de impressão. Se vários argumentos forem necessários, passe cada um com uma opção -L separada. O groff não adiciona um hífen ao argumento antes de passá-lo para o spooler.
-M Funciona como a opção do troff (veja abaixo), mas também é passada para eqn(1), grap(1) e grn(1).
-N Impede quebras de linha entre delimitadores eqn: passa -N para eqn(1).
-p Executa o pré-processador pic(1).
-P arg Passa arg para o pós-processador. Se vários argumentos forem necessários, passe cada um com uma opção -P separada. O groff não adiciona um hífen ao argumento antes de passá-lo para o pós-processador.
-R Executa o pré-processador refer(1). Não há mecanismo fornecido para passar argumentos para refer, porque a maioria das opções de refer tem elementos de linguagem equivalentes que podem ser especificados dentro do documento.
-s Executa o pré-processador soelim(1).
-S Opera no modo “mais seguro”; veja -U abaixo para seu oposto. Por motivos de segurança, o modo mais seguro é habilitado por padrão.
-t Executa o pré-processador tbl(1).
-T dev Direciona o troff para formatar a entrada para o dispositivo de saída dev. O groff então chama um driver de saída para converter a saída do troff em um formato apropriado para dev; veja a subseção “Dispositivos de saída” abaixo.
-U Opera no modo inseguro: passa a opção -U para pic e troff.
-v
--version
Escreve informações de versão para o groff e todos os programas executados por ele para o fluxo de saída padrão; ou seja, a linha de comando fornecida é processada da maneira usual, passando -v para o formatador e quaisquer pré-processadores ou pós-processadores invocados.
-V Emite a linha de comando que o groff executaria para o fluxo de saída padrão, mas não a executa. Se for fornecido mais de uma vez, o groff escreve e executa a linha de comando.
-X Usa gxditview(1) em vez do pós-processador usual para (pré-)visualizar um documento em uma tela X11. Combinar esta opção com -Tps usa as métricas de fonte do dispositivo PostScript, enquanto as opções -TX75 e -TX100 usam as métricas das fontes X11.
-Z Desabilita o pós-processamento. A saída do troff aparecerá no fluxo de saída padrão (a menos que seja suprimida com -z); veja groff_out(5) para uma descrição deste formato.
Opções transparentes
As seguintes opções são passadas exatamente como estão para o programa formatador troff(1) e descritas com mais detalhes em sua página de manual.
-a
Gera uma aproximação em texto simples da saída formatada.
-b
Escreve um rastreamento para o fluxo de erro padrão em cada erro ou aviso.
-c
Inicia com a saída de cor desabilitada.
-C
Habilita o modo de compatibilidade AT&T troff; implica -c.
-d cs
-d name=string
Define string.
-E
Inibe as mensagens de erro do troff; implica -Ww.
-f fam
Define a família de fontes padrão.
-F dir
Pesquisa no diretório dir o diretório de arquivos de descrição de dispositivos e fontes do dispositivo de saída selecionado.
-i
Processa a entrada padrão após os arquivos de entrada especificados.
-I dir
Pesquisa dir por arquivos de entrada.
-m name
Processa name.tmac antes dos arquivos de entrada.
-M dir
Pesquisa o diretório dir por arquivos de macro.
-n num
Numera a primeira página num.
-o list
Emite apenas as páginas na lista.
-r cnumeric-expression
-r register=numeric-expression
Define um registro.
-w name
-W name
Habilita (-w) ou inibe (-W) a emissão de avisos na categoria name.
-z
Suprime a saída formatada e independente do dispositivo do troff.
Uso
A arquitetura do sistema GNU roff segue a de outras implementações de roff independentes de dispositivo, compreendendo pré-processadores, pacotes de macro, drivers de saída (ou "pós-processadores"), um conjunto de utilitários e o formatador troff em seu núcleo. Consulte roff(7) para uma visão geral de como funciona um sistema roff.
Os programas de front-end disponíveis no sistema GNU roff facilitam o uso em comparação com os roffs tradicionais que exigiam a construção de pipelines ou o uso de arquivos temporários para transportar um documento de origem de um formato gerenciável para uma saída pronta para o dispositivo. A discussão abaixo resume as partes constituintes do sistema GNU roff. Complementa roff(7) com informações específicas do groff.
Começando
Aqueles que preferem aprender experimentando ou que desejam obter feedback rápido do sistema podem querer começar com um documento "Olá, mundo!".
$ echo "Hello, world!" | groff -Tascii | sed '/^$/d'
Hello, world!
Usamos um comando sed apenas para eliminar as 65 linhas em branco que, caso contrário, inundariam a tela do terminal. (Os sistemas roff foram desenvolvidos na época dos terminais de papel com 66 linhas por página.)
Os usuários de hoje podem preferir a saída para um terminal compatível com UTF-8.
$ echo "Hello, world!" | groff -Tutf8 | sed '/^$/d'
Produzir PDF, HTML ou o DVI do TeX também é simples. A parte difícil pode ser selecionar um programa visualizador para a saída.
$ echo "Hello, world!" | groff -Tpdf > hello.pdf
$ evince hello.pdf
$ echo "Hello, world!" | groff -Thtml > hello.html
$ firefox hello.html
$ echo "Hello, world!" | groff -Tdvi > hello.dvi
$ xdvi hello.html
Usando groff como um REPL
Aqueles com uma mentalidade de programador podem ficar satisfeitos em saber que podem usar groff em um loop de leitura-avaliação-impressão (REPL). Fazer isso pode ser útil para verificar a compreensão do comportamento do formatador e/ou a sintaxe que ele aceita. Ligar todos os avisos com -ww pode ajudar nesse objetivo.
$ groff -ww -Tutf8
# This is a comment. Let's define a register.
.nr a 1
# Do integer arithmetic with operators evaluated left-to-right.
.nr b \n[a]+5/2
# Let's get the result on the standard error stream.
.tm \n[b]
3
# Now we'll define a string.
.ds name Leslie\" This is another form of comment.
.nr b (\n[a] + (7/2))
# Center the next two text input lines.
.ce 2
Hi, \\*[name].
Your secret number is \n[b].
# We will see that the division rounded toward zero.
It is
# Here's an if-else control structure.
.ie (\n[b] % 2) odd.
.el even.
# This trick sets the page length to the current vertical
# position, so that blank lines don't spew when we're done.
.pl \n[nl]u
<Control-D>
Hi, Leslie.
Your secret number is 4.
It is even.
Formato de papel
No GNU roff, as dimensões da página para o formatador troff e para os dispositivos de saída são tratadas separadamente. No formatador, são usados pedidos para definir o comprimento da página (.pl), o deslocamento da página (ou margem esquerda, .po) e o comprimento da linha (.ll). A margem direita não é configurada explicitamente; a combinação do deslocamento da página e do comprimento da linha fornece as informações necessárias para derivá-la. O pacote de macro papersize, carregado automaticamente pelo troff, fornece uma interface para configurar as dimensões da página por nomes convenientes, como "letter" ou "A4"; consulte groff_tmac(5). O padrão do formatador nesta instalação é "A4".
Cabe a cada pacote de macro respeitar as dimensões da página configuradas desta forma. Alguns oferecem mecanismos alternativos.
Para cada dispositivo de saída, o tamanho do meio de saída pode ser definido em seu arquivo DESC. A maioria dos drivers de saída também reconhece uma opção de linha de comando -p para substituir as dimensões padrão e uma opção -l para usar a orientação paisagem. Consulte groff_font(5) para obter uma descrição do diretivo papersize, que recebe um argumento da mesma forma que -p. A página de manual do driver de saída, como grops(1), também pode ser útil. O groff usa a opção de linha de comando -P para passar opções para os dispositivos de saída; por exemplo, use o seguinte para saída PostScript em papel A4 na orientação paisagem.
groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
Front-end
O programa groff é um wrapper em torno do programa troff(1). Ele permite especificar pré-processadores por meio de opções de linha de comando e executa automaticamente o pós-processador apropriado para o dispositivo de saída selecionado. Ao fazer isso, a construção manual de pipelines ou o gerenciamento de arquivos temporários necessários para os usuários dos sistemas roff(7) tradicionais podem ser evitados. Use o programa grog(1) para inferir uma linha de comando groff apropriada para formatar um documento.
Linguagem
A entrada para um sistema roff está em texto simples intercalado com linhas de controle e sequências de escape. A combinação constitui um documento em uma das famílias de linguagens que também chamamos de roff; consulte roff(7) para obter informações básicas. Uma visão geral da sintaxe e dos recursos da linguagem GNU roff, incluindo listas de todas as sequências de escape, pedidos e registros predefinidos suportados, pode ser encontrada em groff(7). As extensões GNU roff para a linguagem AT&T troff, um subconjunto comum dos dialetos roff existentes hoje, são detalhadas em groff_diff(7).
Pré-processadores
Um pré-processador interpreta uma linguagem de domínio específico que produz saída na linguagem roff. Frequentemente, essa entrada é restrita a seções ou regiões de um arquivo de entrada roff (delimitadas por chamadas de macro específicas para cada pré-processador), que ele substitui. Portanto, os pré-processadores geralmente interpretam um subconjunto da sintaxe roff, juntamente com sua própria linguagem. O GNU roff fornece reimplementações da maioria dos pré-processadores familiares aos usuários do AT&T troff; estes rotineiramente têm recursos estendidos e/ou exigem que o GNU troff formate sua saída.
tbl organiza tabelas; eqn formata expressões matemáticas; pic desenha diagramas; refer processa referências bibliográficas; soelim pré-processa arquivos de entrada "incorporados"; grn renderiza diagramas gremlin(1); chem desenha fórmulas de estrutura química usando pic; gperl preenche os registros e as strings groff usando perl(1); glilypond incorpora partituras LilyPond; e gpinyin facilita a entrada de chinês mandarim usando Hanyu Pinyin.
Um pré-processador exclusivo do GNU roff é o preconv(1), que converte várias codificações de entrada em algo que o GNU troff possa entender. Quando usado, ele é executado antes de qualquer outro pré-processador.
A maioria dos pré-processadores envolve o conteúdo entre um par de tokens característicos. Um token deve ocorrer no início de uma linha de entrada e usar o caractere de controle ponto. Espaços e tabulações não devem seguir o caractere de controle ou preceder o final da linha de entrada. O desvio dessas regras impede o reconhecimento de um token pelo pré-processador. Os tokens são geralmente preservados na saída do pré-processador e interpretados como chamadas de macro subsequentes pelo troff. O pré-processador ideal ainda não está disponível no groff.
┌──────────────┬─────────────────┬────────────────┐
│ preprocessor │ starting token │ ending token │
├──────────────┼─────────────────┼────────────────┤
│ chem │ .cstart │ .cend │
│ eqn │ .EQ │ .EN │
│ grap │ .G1 │ .G2 │
│ grn │ .GS │ .GE │
│ ideal │ .IS │ .IE │
│ │ │ .IF │
│ pic │ .PS │ .PE │
│ │ │ .PF │
│ │ │ .PY │
│ refer │ .R1 │ .R2 │
│ tbl │ .TS │ .TE │
├──────────────┼─────────────────┼────────────────┤
│ glilypond │ .lilypond start │ .lilypond stop │
│ gperl │ .Perl start │ .Perl stop │
│ gpinyin │ .pinyin start │ .pinyin stop │
└──────────────┴─────────────────┴────────────────┘
Pacotes de macro
Os arquivos de macro são arquivos de entrada roff projetados para não produzir saída, mas, em vez disso, facilitar a preparação de outros documentos roff. Quando um arquivo de macro é instalado em um local padrão e adequado para uso por um público em geral, ele é denominado pacote de macro.
Os pacotes de macro podem ser carregados antes de quaisquer documentos de entrada roff com a opção -m. O GNU roff implementa a maioria dos pacotes de macro conhecidos do AT&T troff de forma compatível e os estende. Esses pacotes têm nomes de uma ou duas letras, resultado de intensas práticas de economia de nomes na cultura Unix inicial, uma abordagem lacônica que levou muitos dos pacotes a serem identificados no uso geral com a letra da opção nroff e troff usada para invocá-los, às vezes com um efeito jocoso, como no caso de “man” (abreviação de “manual”) e até mesmo com o hífen da opção, como no caso do pacote s, muito mais conhecido como ms ou até mesmo -ms.
Os pacotes de macro servem a uma variedade de propósitos. Alguns são pacotes “completes”, assumindo a responsabilidade pelo layout da página, entre outras tarefas fundamentais, e definindo seu próprio léxico de macros para composição de documentos; cada um desses pacotes funciona de forma independente e um determinado documento pode usar apenas um.
an é usado para compor páginas de manual no formato que surgiu na Versão 7 Unix (1979); consulte
groff_man(7). Pode ser especificado na linha de comando como -man.
doc é usado para compor páginas de manual no formato que surgiu no 4.3BSD-Reno (1990); consulte
groff_mdoc(7). Pode ser especificado na linha de comando como -mdoc.
e é o conjunto de macros de propósito geral da Berkeley, desenvolvido como uma alternativa ao s da AT&T;
consulte groff_me(7). Pode ser especificado na linha de comando como -me.
m implementa o formato usado pelo conjunto de macros de segunda geração da AT&T para documentos
gerais, um sucessor de s; consulte groff_mm(7). Pode ser especificado na linha de comando como -mm.
om (invariavelmente chamado de “mom”) é um pacote moderno escrito por Peter Schaffter especificamente
para GNU roff. Consulte o manual HTML do mom para documentação extensa. Ela — pois mom usa o pronome
feminino — pode ser especificada na linha de comando como -mom.
s é o formato de documento de propósito geral original da AT&T; consulte groff_ms(7). Pode ser especificado
na linha de comando como -ms.
Outros são suplementares. Por exemplo, andoc é um pacote de wrapper específico para GNU roff que reconhece se um documento usa o formato man ou mdoc e carrega o pacote de macro correspondente. Ele pode ser especificado na linha de comando como -mandoc. Um programa man(1) de biblioteca pode usar este arquivo de macro para delegar o carregamento do pacote de macro correto; portanto, não é necessário que o próprio man examine o conteúdo de um documento para decidir a questão.
Muitos arquivos de macro aumentam a funcionalidade dos pacotes completos ou dos documentos roff que não utilizam tais pacotes – estes últimos são, às vezes, caracterizados como “brutos”. Estes pacotes auxiliares são descritos, juntamente com detalhes sobre a nomeação e o posicionamento de arquivos de macro, em groff_tmac(5).
Formatadores
O formatador, o programa que interpreta a entrada da linguagem roff, é troff(1). Ele fornece os recursos dos programas AT&T troff e nroff, bem como muitas extensões. A opção da linha de comando -C alterna troff para o modo de compatibilidade, que tenta emular AT&T troff o mais fielmente possível, a fim de permitir a formatação de documentos escritos para o sistema mais antigo.
Um script shell, nroff(1), emula o comportamento de AT&T nroff. Ele tenta codificar corretamente a saída com base no locale, aliviando o usuário da necessidade de especificar um dispositivo de saída com a opção -T e, portanto, é conveniente para uso com dispositivos de saída de terminal, conforme descrito na próxima subseção.
GNU troff gera saída em uma linguagem de descrição de página independente de dispositivo, mas não agnóstica de dispositivo, detalhada em groff_out(5).
Dispositivos de saída
A saída troff é formatada para um dispositivo de saída específico, normalmente especificado pela opção -T para o formatador ou um front-end. Se nenhuma dessas opções ou a variável de ambiente GROFF_TYPESETTER for usada, o dispositivo de saída padrão é ps. Um dispositivo de saída pode ser qualquer um dos seguintes:
ascii para terminais que usam o conjunto de caracteres e codificação ISO 646 1991:IRV, também conhecido como USASCII.
cp1047 para terminais que usam o conjunto de caracteres e codificação IBM code page 1047.
dvi para formato TeX DVI.
html
xhtml para saída HTML e XHTML, respectivamente.
latin1 para terminais que usam o conjunto de caracteres e codificação ISO Latin-1 (ISO 8859-1).
lbp para impressoras Canon CaPSL (séries LBP-4 e LBP-8).
lj4 para impressoras compatíveis com HP LaserJet4 (ou outras impressoras compatíveis com PCL5).
pdf para saída PDF.
ps para saída PostScript.
utf8 para terminais que usam o conjunto de caracteres ISO 10646 (“Unicode”) com codificação UTF-8.
X75 para visualização com gxditview usando resolução de 75 dpi e tamanho de fonte base de 10 pontos.
X75-12 para visualização com gxditview usando resolução de 75 dpi e tamanho de fonte base de 12 pontos.
X100 para visualização com gxditview usando resolução de 100 dpi e tamanho de fonte base de 10 pontos.
X100-12 para visualização com gxditview usando resolução de 100 dpi e tamanho de fonte base de 12 pontos.
Pós-processadores
Qualquer programa que interprete a saída de GNU troff é um pós-processador. Os pós-processadores fornecidos por GNU roff são drivers de saída, que preparam um documento para visualização ou impressão. Pós-processadores para outros fins, como reordenação de páginas ou medição estatística de um documento, são concebíveis.
Um driver de saída suporta um ou mais dispositivos de saída, cada um com seu próprio arquivo de descrição de dispositivo. Um dispositivo determina seu pós-processador com a diretiva postpro em seu arquivo de descrição de dispositivo; veja groff_font(5). A opção -X substitui esta seleção, fazendo com que o gxditview atue como o driver de saída.
grodvi(1)
fornece dvi.
grohtml(1)
fornece html e xhtml.
grolbp(1)
fornece lbp.
grolj4(1)
fornece lj4.
gropdf(1)
fornece pdf.
grops(1)
fornece ps.
grotty(1)
fornece ascii, cp1047, latin1 e utf8.
gxditview(1)
fornece X75, X75-12, X100 e X100-12 e, adicionalmente, pode visualizar ps.
Utilitários
GNU roff inclui um conjunto de utilitários.
gdiffmk(1)
marca as diferenças entre um par de arquivos de entrada roff.
grog(1)
infere o comando groff que um documento requer.
Vários utilitários preparam descrições de fontes, permitindo que o formatador as use ao produzir saída para um determinado dispositivo.
addftinfo(1)
adiciona informações aos arquivos de descrição de fonte AT&T troff para habilitar seu uso com GNU troff.
afmtodit(1)
cria arquivos de descrição de fonte para fontes PostScript Type 1.
pfbtops(1)
traduz uma fonte PostScript Type 1 no formato PFB (Printer Font Binary) para PFA (Printer
Font ASCII), que pode então ser interpretada por afmtodit.
hpftodit(1)
cria arquivos de descrição de fonte para a família de impressoras HP LaserJet 4.
tfmtodit(1)
cria arquivos de descrição de fonte para o dispositivo TeX DVI.
xtotroff(1)
cria arquivos de descrição de fonte para fontes do sistema X Window.
Um trio de ferramentas transforma materiais construídos usando linguagens de pré-processador roff em arquivos de imagem gráfica.
eqn2graph(1)
converte uma equação eqn em uma imagem recortada.
grap2graph(1)
converte um diagrama grap em uma imagem recortada.
pic2graph(1)
converte um diagrama pic em uma imagem recortada.
Outro conjunto de programas funciona com os arquivos de dados bibliográficos usados pelo pré-processador refer(1).
indxbib(1)
cria índices invertidos para bancos de dados bibliográficos, acelerando as operações de pesquisa neles.
lkbib(1)
pesquisa nos bancos de dados.
lookbib(1)
pesquisa interativamente nos bancos de dados.
Status de saída
groff sai com um status de falha se houver um problema ao analisar seus argumentos e um status de sucesso se alguma das opções -h ou --help for especificada. Caso contrário, groff executa um pipeline para processar sua entrada; se todos os comandos dentro do pipeline forem executados com sucesso, groff também o fará.
Se não, o status de saída de groff codifica um resumo dos problemas encontrados, definindo o bit 0 se um comando saiu com um status de falha, o bit 1 se um comando foi encerrado com um sinal e o bit 2 se um comando não pôde ser executado. (Assim, se todos os três infortúnios ocorrerem em um pipeline, groff sairia com o status 2^0 + 2^1 + 2^2 = 1+2+4 = 7.) Para solucionar problemas do pipeline, você pode querer executar novamente o comando groff com a opção -V e dividir o pipeline relatado em etapas separadas, inspecionando o status de saída e as mensagens de diagnóstico emitidas por cada comando.
Ambiente
Normalmente, o separador de caminho nas variáveis de ambiente que terminam com PATH é o dois pontos; isso pode variar dependendo do sistema operacional. Por exemplo, o Windows usa um ponto e vírgula.
GROFF_BIN_PATH
Este caminho de pesquisa, seguido por PATH, é usado para localizar os comandos executados pelo groff. Se não estiver definido, o diretório de instalação dos executáveis GNU roff, /usr/bin, será pesquisado antes de PATH.
GROFF_COMMAND_PREFIX
O GNU roff pode ser configurado em tempo de compilação para aplicar um prefixo aos nomes dos programas que ele fornece, que tinham um equivalente no AT&T troff, para que as colisões de nomes sejam evitadas em tempo de execução. O prefixo padrão está vazio.
Quando usado, este prefixo é convencionalmente a letra “g”. Por exemplo, o GNU troff seria instalado como gtroff. Além de troff, o prefixo se aplica ao formatador nroff; aos pré-processadores eqn, grn, pic, refer, tbl e soelim; e aos utilitários indxbib e lookbib.
GROFF_ENCODING
O valor desta variável é passado para a opção -e do pré-processador preconv(1) para selecionar a codificação de caracteres dos arquivos de entrada. A existência desta variável implica a opção groff -k. Se definido, mas vazio, o groff chama o preconv sem uma opção -e. A opção -K do groff substitui GROFF_ENCODING.
GROFF_FONT_PATH
Procure o diretório de arquivos de descrição de fontes e dispositivos do dispositivo de saída selecionado nesta lista de diretórios. Veja troff(1) e groff_font(5).
GROFF_TMAC_PATH
Procure arquivos de macro nesta lista de diretórios. Veja troff(1) e groff_tmac(5).
GROFF_TMPDIR
Crie arquivos temporários neste diretório. Se não estiver definido, mas a variável de ambiente TMPDIR estiver definida, os arquivos temporários serão criados lá em vez disso. Nos sistemas Windows, se nenhum dos anteriores estiver definido, as variáveis de ambiente TMP e TEMP (nessa ordem) também são verificadas. Caso contrário, os arquivos temporários são criados em /tmp. Os comandos refer(1), grohtml(1) e grops(1) usam arquivos temporários.
GROFF_TYPESETTER
Defina o dispositivo de saída padrão. Se estiver vazio ou não definido, ps será usado. A opção -T substitui GROFF_TYPESETTER.
SOURCE_DATE_EPOCH
Um registro de data/hora (expresso como segundos desde a época Unix) a ser usado como o registro de data/hora de criação da saída, em vez da hora atual. A hora é convertida para um formato legível por humanos usando gmtime(3) e asctime(3) quando o formatador é iniciado e armazenada em registros que podem ser usados por documentos e pacotes de macro.
TZ A zona de tempo a ser usada ao converter a hora atual para um formato legível por humanos; veja tzset(3). Se SOURCE_DATE_EPOCH for usado, ele sempre será convertido para um formato legível por humanos usando UTC.
Exemplos
Os sistemas roff são mais conhecidos por formatar páginas de manual. Depois que um programa bibliotecário man(1) localiza uma página de manual, ele pode executar um comando groff semelhante ao seguinte. groff -t -man -Tutf8 /usr/share/man/man1/groff.1 O bibliotecário também irá enviar a saída para um paginador, que pode não interpretar as sequências de escape do terminal SGR que o groff emite para negrito, sublinhado ou itálico; veja a seção "Limitações" abaixo.
Para processar um arquivo de entrada roff usando os pré-processadores tbl e pic e o pacote de macros me da maneira à qual os usuários do AT&T troff estavam acostumados, você digitaria (ou criaria um script) um pipeline.
pic foo.me | tbl | troff -me -Tutf8 | grotty
Usando groff, este pipeline pode ser encurtado para um comando equivalente.
groff -p -t -me -T utf8 foo.me
Uma maneira ainda mais fácil de fazer isso é usar grog(1) para adivinhar o pré-processador e as opções de macro e executar o resultado usando o recurso de substituição de comandos do shell.
$(grog -Tutf8 foo.me)
Cada opção de linha de comando para um pós-processador deve ser especificada com quaisquer prefixos de traço necessários “-”, porque groff passa os argumentos como estão para o pós-processador; isso permite que argumentos arbitrários sejam transmitidos. Por exemplo, para passar um título para o pós-processador gxditview, os comandos shell groff -X -P -title -P 'teste' mydoc.t e groff -X -Z mydoc.t | gxditview -title 'teste' são equivalentes.
Limitações
Ao paginar a saída para os dispositivos ascii, cp1047, latin1 e utf8, programas como more(1) e less(1) podem exigir opções de linha de comando para lidar corretamente com algumas sequências de escape do terminal; veja grotty(1).
Em hosts EBCDIC como OS/390 Unix, os dispositivos de saída ascii e latin1 não estão disponíveis. Inversamente, o dispositivo de saída cp1047 não está disponível em sistemas baseados nos padrões de codificação de caracteres ISO 646 ou ISO 8859.
Diretórios de instalação
GNU roff instala arquivos em locais variados, dependendo da configuração de tempo de compilação. Nesta instalação, os seguintes locais são usados.
/etc/X11/app-defaults
Diretório de padrões de aplicativo para gxditview(1).
/usr/bin
Diretório que contém os comandos executáveis do groff.
/usr/share/groff/1.23.0/eign
Lista de palavras comuns para indxbib(1).
/usr/share/groff/1.23.0
Diretório para arquivos de dados.
/usr/dict/papers/Ind
Índice padrão para lkbib(1) e refer(1).
/usr/share/doc/groff-base
Diretório de documentação.
/usr/share/doc/groff-base/examples
Diretório de exemplos.
/usr/share/groff/1.23.0/font
Diretório de fontes.
/usr/share/doc/groff-base/html
Diretório de documentação HTML.
/usr/lib/font
Diretório de fontes legado.
/usr/share/groff/site-font
Diretório de fontes local.
/usr/share/groff/site-tmac
Diretório de pacotes de macro local (arquivo tmac).
/usr/share/groff/1.23.0/tmac
Diretório de pacotes de macro (arquivo tmac).
/usr/share/groff/1.23.0/oldfont
Diretório de fontes para compatibilidade com versões mais antigas de groff; veja grops(1).
/usr/share/doc/groff-base/pdf
Diretório de documentação PDF.
diretório de macro groff
A maioria dos arquivos de macro fornecidos com GNU roff são armazenados em /usr/share/groff/1.23.0/tmac para a instalação correspondente a este documento. Como regra, vários diretórios são pesquisados para arquivos de macro; veja troff(1). Para um catálogo de arquivos de macro que GNU roff fornece, veja groff_tmac(5).
Diretório de descrição de dispositivo e fonte groff
Arquivos de descrição de dispositivo e fonte fornecidos com o GNU roff são armazenados em /usr/share/groff/1.23.0/.
fonte para a instalação correspondente a este documento. Como regra, vários diretórios são pesquisados
por arquivos de descrição de dispositivo e fonte; veja troff(1). Para os formatos desses arquivos, veja groff_font(5).
Disponibilidade
Obtenha links para os lançamentos do groff para download, seu repositório de código-fonte, listas de discussão, um rastreador de tickets de suporte e mais informações na página do groff no site GNU.
Uma implementação gratuita do pré-processador grap, escrita por Ted Faber, pode ser encontrada no site grap. O groff suporta apenas este grap.
Autores
groff (tanto o comando front-end quanto o sistema geral) foi escrito principalmente por James Clark. Colaboradores para este documento incluem Clark, Trent A. Fisher, Werner Lemberg, Bernd Warken e G. Branden Robinson.
Veja também
Groff: A implementação GNU de troff, de Trent A. Fisher e Werner Lemberg, é o manual principal do groff. Você pode navegar por ele interativamente com “info groff”.
Introdução, história e leitura adicional: roff(7)
Visualizador para documentos groff (e AT&T device-independent troff): gxditview(1)
Pré-processadores: chem(1), eqn(1), neqn(1), glilypond(1), grn(1), preconv(1), gperl(1), pic(1), gpinyin(1), refer(1), soelim(1), tbl(1)
Pacotes de macro e utilitários específicos do pacote: groff_hdtbl(7), groff_man(7), groff_man_style(7), groff_mdoc(7), groff_me(7), groff_mm(7), groff_mmse(7) (apenas em locais suecos), mmroff(1), groff_mom(7), pdfmom(1), groff_ms(7), groff_rfc1345(7), groff_trace(7), groff_www(7)
Ferramentas de gerenciamento de banco de dados bibliográfico: indxbib(1), lkbib(1), lookbib(1)
Linguagem, convenções e extensões GNU: groff(7), groff_char(7), groff_diff(7), groff_font(5), groff_tmac(5)
Linguagem de saída intermediária: groff_out(5)
Programa de formatação: troff(1)
Wrappers de formatação: nroff(1), pdfroff(1)
Pós-processadores para dispositivos de saída: grodvi(1), grohtml(1), grolbp(1), grolj4(1), gropdf(1), grops(1), grotty(1)
Utilitários de suporte de fonte: addftinfo(1), afmtodit(1), hpftodit(1), pfbtops(1), tfmtodit(1), xtotroff(1)
Utilitários de conversão de gráficos: eqn2graph(1), grap2graph(1), pic2graph(1)
Utilitário de marcação de diferenças: gdiffmk(1)
Utilitário “groff guess”: grog(1)