groff - interfaz para el sistema de formateo de documentos GNU roff
Sinopsis
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 ...]
Descripción
groff es la interfaz principal para el sistema de formateo de documentos GNU roff. GNU roff es un sistema de composición tipográfica que lee archivos de texto sin formato que incluyen comandos de formateo para generar resultados en PostScript, PDF, HTML, DVI u otros formatos, o para mostrar en una terminal. Los comandos de formateo pueden ser primitivas de composición tipográfica de bajo nivel, macros de un paquete suministrado o macros definidas por el usuario. Se pueden combinar los tres enfoques. Si no se especifican archivos de operando o si el archivo es "-", groff lee el flujo de entrada estándar.
groff es una reimplementación y extensión del compositor de AT&T Unix y está presente en la mayoría de los sistemas POSIX debido a su larga asociación con los manuales de Unix (incluidas las páginas de manual). Groff y su predecesor se destacan por su capacidad para producir documentos tipográficamente sofisticados al tiempo que consumen recursos mínimos del sistema.
El comando groff orquesta la ejecución de preprocesadores, la transformación de documentos de entrada en un lenguaje de descripción de páginas independiente del dispositivo y la producción de resultados a partir de ese lenguaje.
Opciones
-h y --help muestran un mensaje de uso y salen.
Dado que groff está diseñado para subsumir la mayoría de las invocaciones directas del formateador troff(1) por parte de los usuarios, ambos programas comparten un conjunto de opciones. Sin embargo, groff tiene algunas opciones que troff no tiene, y otras que groff interpreta de manera diferente. Al mismo tiempo, no todas las opciones válidas de troff se pueden proporcionar a groff.
Opciones específicas de groff
Las siguientes opciones no existen en GNU troff o son interpretadas de manera diferente por groff.
-D enc Establece la codificación de entrada de respaldo utilizada por preconv(1) en enc; implica -k.
-e Ejecuta el preprocesador eqn(1).
-g Ejecuta el preprocesador grn(1).
-G Ejecuta el preprocesador grap(1); implica -p.
-I dir Funciona como la opción de troff (vea abajo), pero también implica -g y -s. Se pasa a soelim(1) y al controlador de salida, y a grn se le pasa una opción -M con dir como su argumento.
-j Ejecuta el preprocesador chem(1); implica -p.
-k Ejecuta el preprocesador preconv(1). Consulte su página de manual para conocer su comportamiento si tampoco se especifica ninguna de las opciones -K o -D de groff.
-K enc Establece la codificación de entrada utilizada por preconv(1) en enc; implica -k.
-l Envía la salida a un programa de cola de impresión. La directiva “print” en el archivo de descripción del dispositivo especifica el comando predeterminado que se utilizará; consulte groff_font(5). Si no hay dicha directiva para el dispositivo de salida, la salida se canaliza a lpr(1). Consulte las opciones -L y -X.
-L arg Pasa arg al programa de cola de impresión. Si se requieren varios argumentos, pase cada uno con una opción -L separada. groff no agrega un guion al principio de la opción antes de pasarla al programa de cola de impresión.
-M Funciona como la opción de troff (consulte a continuación), pero también se pasa a eqn(1), grap(1) y grn(1).
-N Prohíbe los saltos de línea entre los delimitadores de eqn: pasa -N a eqn(1).
-p Ejecuta el preprocesador pic(1).
-P arg Pasa arg al postprocesador. Si se requieren varios argumentos, pase cada uno con una opción -P separada. groff no agrega un guion al principio de la opción antes de pasarla al postprocesador.
-R Ejecuta el preprocesador refer(1). No se proporciona ningún mecanismo para pasar argumentos a refer, ya que la mayoría de las opciones de refer tienen elementos de lenguaje equivalentes que se pueden especificar dentro del documento.
-s Ejecuta el preprocesador soelim(1).
-S Opera en modo “más seguro”; consulte -U a continuación para su opuesto. Por razones de seguridad, el modo más seguro está habilitado de forma predeterminada.
-t Ejecuta el preprocesador tbl(1).
-T dev Indica a troff que formatee la entrada para el dispositivo de salida dev. groff luego llama a un controlador de salida para convertir la salida de troff a un formato adecuado para dev; consulte la subsección “Dispositivos de salida” a continuación.
-U Opera en modo inseguro: pasa la opción -U a pic y troff.
-v
--version
Escribe información de versión para groff y todos los programas que ejecuta en el flujo de salida estándar; es decir, la línea de comandos dada se procesa de la manera habitual, pasando -v al formateador y a cualquier preprocesador o postprocesador invocado.
-V Muestra la canalización que groff ejecutaría en el flujo de salida estándar, pero no la ejecuta. Si se especifica más de una vez, groff escribe y ejecuta la canalización.
-X Utiliza gxditview(1) en lugar del postprocesador habitual para (pre)visualizar un documento en una pantalla X11. Combinar esta opción con -Tps utiliza las métricas de fuente del dispositivo PostScript, mientras que las opciones -TX75 y -TX100 utilizan las métricas de las fuentes X11.
-Z Deshabilita el postprocesamiento. La salida de troff aparecerá en el flujo de salida estándar (a menos que se suprima con -z); consulte groff_out(5) para obtener una descripción de este formato.
Opciones transparentes
Las siguientes opciones se pasan tal cual al programa formateador troff(1) y se describen con más detalle en su página de manual.
-a Genera una aproximación de texto plano de la salida tipográfica.
-b Escribe un rastreo en el flujo de error estándar en cada error o advertencia.
-c Comienza con la salida de color desactivada.
-C Habilita el modo de compatibilidad AT&T troff; implica -c.
-d cs
-d name=string
Define string.
-E Inhibe los mensajes de error de troff; implica -Ww.
-f fam Establece la familia de fuentes predeterminada.
-F dir Busca en el directorio dir el directorio de archivos de descripción de dispositivos y fuentes del dispositivo de salida seleccionado.
-i Procesa la entrada estándar después de los archivos de entrada especificados.
-I dir Busca archivos de entrada en el directorio dir.
-m name
Procesa name.tmac antes de los archivos de entrada.
-M dir Busca archivos macro en el directorio dir.
-n num Numera la primera página num.
-o list
Muestra solo las páginas de la lista.
-r cnumeric-expression
-r register=numeric-expression
Define registro.
-w name
-W name
Habilita (-w) o inhibe (-W) la emisión de advertencias en la categoría name.
-z Suprime la salida formateada independiente del dispositivo de troff.
Uso
La arquitectura del sistema GNU roff sigue la de otras implementaciones roff independientes del dispositivo, que comprenden preprocesadores, paquetes macro, controladores de salida (o "postprocesadores"), un conjunto de utilidades y el formateador troff en su núcleo. Consulte roff(7) para obtener una descripción general de cómo funciona un sistema roff.
Los programas de interfaz disponibles en el sistema GNU roff facilitan su uso en comparación con los roff tradicionales que requerían la construcción de canalizaciones o el uso de archivos temporales para llevar un documento fuente desde una forma mantenible hasta una salida lista para el dispositivo. La discusión a continuación resume las partes constituyentes del sistema GNU roff. Complementa roff(7) con información específica de groff.
Comenzar
Aquellos que prefieran aprender experimentando o que deseen obtener comentarios rápidos del sistema pueden desean comenzar con un documento "¡Hola, mundo!".
$ echo "Hello, world!" | groff -Tascii | sed '/^$/d'
Hello, world!
Utilizamos un comando sed solo para eliminar las 66 líneas en blanco que de otro modo inundarían la pantalla del terminal. (Los sistemas roff se desarrollaron en la época de los terminales basados en papel con 67 líneas por
página).
Los usuarios de hoy en día pueden preferir la salida a un terminal compatible con UTF-8.
$ echo "Hello, world!" | groff -Tutf8 | sed '/^$/d'
Producir PDF, HTML o DVI de TeX también es sencillo. La parte difícil puede ser seleccionar un programa de visualización para la salida.
$ 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
Usar groff como REPL
Aquellos con una mentalidad de programador pueden estar interesados en saber que pueden usar groff en un bucle de lectura-evaluación-impresión (REPL). Hacer esto puede ser útil para verificar la comprensión del comportamiento del formateador y/o la sintaxis que acepta. Activar todas las advertencias con -ww puede ayudar a este objetivo.
$ groff -ww -Tutf8
# Este es un comentario. Definiamos un registro.
.nr a 1
# Realicemos aritmética entera con operadores evaluados de izquierda a derecha.
.nr b \n[a]+5/2
# Mostremos el resultado en el flujo de error estándar.
.tm \n[b]
3 \# Ahora definiremos una cadena.
.ds name Leslie\" Esta es otra forma de comentario.
.nr b (\n[a] + (7/2))
# Centremos las siguientes dos líneas de texto.
.ce 2
Hi, \\*[name].
Your secret number is \n[b].
# Veremos que la división se redondea hacia cero.
It is
# Aquí hay una estructura de control if-else.
.ie (\n[b] % 2) odd.
.el even.
# Este truco establece la longitud de la página en la posición vertical actual, para que no se muestren líneas en blanco cuando hayamos terminado.
.pl \n[nl]u
<Control-D>
Hi, Leslie.
Your secret number is 4.
It is even.
Formato de página
En GNU roff, las dimensiones de la página para el formateador troff y para los dispositivos de salida se gestionan por separado. En el formateador, se utilizan solicitudes para establecer la longitud de la página (.pl), el desplazamiento de la página (o margen izquierdo, .po) y la longitud de la línea (.ll). El margen derecho no se configura explícitamente; la combinación del desplazamiento de la página y la longitud de la línea proporciona la información necesaria para derivarlo. El paquete de macros papersize, cargado automáticamente por troff, proporciona una interfaz para configurar las dimensiones de la página mediante nombres convenientes, como "letter" o "A4"; consulte groff_tmac(5). El valor predeterminado del formateador en esta instalación es "A4".
Corresponde a cada paquete de macros respetar las dimensiones de la página configuradas de esta manera. Algunos ofrecen mecanismos alternativos.
Para cada dispositivo de salida, el tamaño del medio de salida se puede establecer en su archivo DESC. La mayoría de los controladores de salida también reconocen una opción de línea de comandos -p para anular las dimensiones predeterminadas y una opción -l para utilizar la orientación horizontal. Consulte groff_font(5) para obtener una descripción de la directiva papersize, que toma un argumento con el mismo formato que -p. La página del manual del controlador de salida, como grops(1), también puede ser útil. groff utiliza la opción de línea de comandos -P para pasar opciones a los dispositivos de salida; por ejemplo, utilice lo siguiente para la salida PostScript en papel A4 en orientación horizontal.
groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
Interfaz
El programa groff es un envoltorio alrededor del programa troff(1). Permite especificar preprocesadores a través de opciones de línea de comandos y ejecuta automáticamente el postprocesador apropiado para el dispositivo de salida seleccionado. Al hacerlo, se evita la construcción manual de canalizaciones o la gestión de archivos temporales que se requiere de los usuarios de los sistemas roff(7) tradicionales. Utilice el programa grog(1) para inferir una línea de comandos groff adecuada para formatear un documento.
Lenguaje
La entrada a un sistema roff está en texto plano intercalado con líneas de control y secuencias de escape. La combinación constituye un documento en una de las familias de lenguajes que también llamamos roff; consulte roff(7) para obtener información de fondo. Se puede encontrar una descripción general de la sintaxis y las características del lenguaje GNU roff, incluidas las listas de todas las secuencias de escape, solicitudes y registros predefinidos admitidos, en groff(7). Las extensiones GNU roff al lenguaje AT&T troff, un subconjunto común de los dialectos roff existentes en la actualidad, se detallan en groff_diff(7).
Preprocesadores
Un preprocesador interpreta un lenguaje específico de dominio que produce una salida en el lenguaje roff. Con frecuencia, dicha entrada se limita a secciones o regiones de un archivo de entrada roff (encerradas entre llamadas de macro específicas de cada preprocesador), que reemplaza. Por lo tanto, los preprocesadores a menudo interpretan un subconjunto de la sintaxis roff junto con su propio lenguaje. GNU roff proporciona reimplementaciones de la mayoría de los preprocesadores conocidos por los usuarios de AT&T troff; estos suelen tener características extendidas y/o requieren GNU troff para formatear su salida.
tbl formatea tablas; eqn escribe ecuaciones matemáticas; pic dibuja diagramas; refer procesa referencias bibliográficas; soelim preprocesa archivos de entrada "incorporados"; grn renderiza diagramas gremlin(1); chem dibuja fórmulas estructurales químicas utilizando pic; gperl llena los registros y cadenas de groff utilizando perl(1); glilypond incrusta partituras de LilyPond; y gpinyin facilita la entrada en chino mandarín utilizando Hanyu Pinyin.
Un preprocesador único de GNU roff es preconv(1), que convierte varias codificaciones de entrada a algo que GNU troff pueda entender. Cuando se utiliza, se ejecuta antes que cualquier otro preprocesador.
La mayoría de los preprocesadores encierran el contenido entre un par de tokens característicos. Dicho token debe aparecer al principio de una línea de entrada y utilizar el carácter de control punto. No debe haber espacios ni tabulaciones después del carácter de control ni antes del final de la línea de entrada. Desviarse de estas reglas impide que un preprocesador reconozca un token. Generalmente, los tokens se conservan en la salida del preprocesador y se interpretan como llamadas de macro posteriormente por troff. El preprocesador ideal aún no está disponible en groff.
┌──────────────┬─────────────────┬────────────────┐
│ preprocesador │ token de inicio │ token de finalización │
├──────────────┼─────────────────┼────────────────┤
│ 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 │
└──────────────┴─────────────────┴────────────────┘
Paquetes de macros
Los archivos de macros son archivos de entrada de roff diseñados para no generar ninguna salida por sí mismos, sino para facilitar la preparación de otros documentos de roff. Cuando un archivo de macros se instala en una ubicación estándar y es adecuado para su uso por un público en general, se denomina paquete de macros.
Los paquetes de macros se pueden cargar antes de cualquier documento de entrada de roff con la opción -m. El sistema GNU roff implementa la mayoría de los paquetes de macros conocidos de AT&T troff de una manera compatible y los extiende. Estos tienen nombres de una o dos letras que surgen de las intensas prácticas de economía de nombres en la cultura Unix temprana, un enfoque lacónico que llevó a que muchos de los paquetes se identificaran en el uso general con la letra de la opción nroff y troff utilizada para invocarlos, a veces con un efecto humorístico, como con “man” (abreviatura de “manual”) e incluso con el guion de la opción, como en el caso del paquete s, mucho mejor conocido como ms o incluso -ms.
Los paquetes de macros sirven para una variedad de propósitos. Algunos son paquetes de “servicio completo”, que asumen la responsabilidad del diseño de página, entre otras tareas fundamentales, y definen su propio léxico de macros para la composición de documentos; cada uno de estos paquetes funciona de forma independiente y un documento determinado puede utilizar como máximo uno.
an se utiliza para componer páginas de manual en el formato que se originó en Version 7 Unix (1979); consulte groff_man(7). Se puede especificar en la línea de comandos como -man.
doc se utiliza para componer páginas de manual en el formato que se originó en 4.3BSD-Reno (1990); consulte groff_mdoc(7). Se puede especificar en la línea de comandos como -mdoc.
e es el conjunto de macros de propósito general de Berkeley, desarrollado como una alternativa a la s de AT&T; consulte groff_me(7). Se puede especificar en la línea de comandos como -me.
m implementa el formato utilizado por el conjunto de macros de segunda generación de AT&T para documentos generales, un sucesor de s; consulte groff_mm(7). Se puede especificar en la línea de comandos como -mm.
om (invariablemente llamado “mom”) es un paquete moderno escrito por Peter Schaffter específicamente para GNU roff. Consulte el manual HTML de mom para obtener documentación completa. Ella, porque mom usa el pronombre femenino, se puede especificar en la línea de comandos como -mom.
s es el formato de documentos de propósito general original de AT&T; consulte groff_ms(7). Se puede especificar en la línea de comandos como -ms.
Otros son complementarios. Por ejemplo, andoc es un paquete complementario específico de GNU roff que reconoce si un documento utiliza el formato man o mdoc y carga el paquete de macros correspondiente. Se puede especificar en la línea de comandos como -mandoc. Un programa de biblioteca man(1) puede usar este archivo de macros para delegar la carga del paquete de macros correcto; por lo tanto, no es necesario que man escanee el contenido de un documento para decidir el problema.
Muchos archivos de macros complementan la funcionalidad de los paquetes completos o de los documentos roff que no utilizan dichos paquetes; estos últimos a veces se caracterizan como “sin formato”. Estos paquetes auxiliares se describen, junto con los detalles sobre el nombre y la ubicación de los archivos de macros, en groff_tmac(5).
Formateadores
El formateador, el programa que interpreta la entrada del lenguaje roff, es troff(1). Proporciona las características de los programas AT&T troff y nroff, así como muchas extensiones. La opción de línea de comandos -C cambia troff al modo de compatibilidad, que intenta emular AT&T troff lo más fielmente posible para permitir el formateo de documentos escritos para el sistema anterior.
Un script de shell, nroff(1), emula el comportamiento de AT&T nroff. Intenta codificar correctamente la salida en función de la configuración regional, lo que libera al usuario de la necesidad de especificar un dispositivo de salida con la opción -T y, por lo tanto, es conveniente para su uso con dispositivos de salida de terminal, que se describen en la siguiente subsección.
GNU troff genera la salida en un lenguaje de descripción de páginas independiente del dispositivo, pero no agnóstico del dispositivo, que se detalla en groff_out(5).
Dispositivos de salida
La salida de troff está formateada para un dispositivo de salida específico, que normalmente se especifica mediante la opción -T del formateador o un programa front-end. Si no se utiliza ni esta opción ni la variable de entorno GROFF_TYPESETTER, el dispositivo de salida predeterminado es ps. Un dispositivo de salida puede ser cualquiera de los siguientes.
ascii para terminales que utilizan el conjunto de caracteres y la codificación ISO 646 1991:IRV, también conocido como USASCII.
cp1047 para terminales que utilizan el conjunto de caracteres y la codificación de la página de código IBM 1047.
dvi para el formato TeX DVI.
html
xhtml para la salida HTML y XHTML, respectivamente.
latin1 para terminales que utilizan el conjunto de caracteres y la codificación ISO Latin-1 (ISO 8859-1).
lbp para impresoras Canon CaPSL (series LBP-4 y LBP-8).
lj4 para impresoras compatibles con HP LaserJet4 (u otras impresoras compatibles con PCL5).
pdf para la salida PDF.
ps para la salida PostScript.
utf8 para terminales que utilizan el conjunto de caracteres ISO 10646 (“Unicode”) en codificación UTF-8.
X75 para la previsualización con gxditview utilizando una resolución de 75 ppp y un tamaño de fuente base de 10 puntos.
X75-12 para la previsualización con gxditview utilizando una resolución de 75 ppp y un tamaño de fuente base de 12 puntos.
X100 para la previsualización con gxditview utilizando una resolución de 100 ppp y un tamaño de fuente base de 10 puntos.
X100-12 para la previsualización con gxditview utilizando una resolución de 100 ppp y un tamaño de fuente base de 12 puntos.
Postprocesadores
Cualquier programa que interprete la salida de GNU troff es un postprocesador. Los postprocesadores proporcionados por GNU roff son controladores de salida, que preparan un documento para su visualización o impresión. Son concebibles postprocesadores para otros fines, como la resecuenciación de páginas o la medición estadística de un documento.
Un controlador de salida admite uno o más dispositivos de salida, cada uno con su propio archivo de descripción de dispositivo.
Un dispositivo determina su posprocesador con la directiva postpro en su archivo de descripción de dispositivo;
consulte groff_font(5). La opción -X anula esta selección, haciendo que gxditview sirva como
controlador de salida.
`grodvi(1)`
proporciona dvi.
`grohtml(1)`
proporciona html y xhtml.
`grolbp(1)`
proporciona lbp.
`grolj4(1)`
proporciona lj4.
`gropdf(1)`
proporciona pdf.
`grops(1)`
proporciona ps.
`grotty(1)`
proporciona ascii, cp1047, latin1 y utf8.
`gxditview(1)`
proporciona X75, X75-12, X100 y X100-12, y además puede previsualizar ps.
Utilidades
GNU roff incluye un conjunto de utilidades.
`gdiffmk(1)`
marca las diferencias entre un par de archivos de entrada roff.
`grog(1)`
infiere el comando groff que requiere un documento.
Varias utilidades preparan descripciones de fuentes, lo que permite al formateador usarlas al generar la salida para un dispositivo determinado.
`addftinfo(1)`
agrega información a los archivos de descripción de fuentes AT&T troff para habilitar su uso con GNU troff.
`afmtodit(1)`
crea archivos de descripción de fuentes para fuentes PostScript Type 1.
`pfbtops(1)`
traduce una fuente PostScript Type 1 en formato PFB (Printer Font Binary) a PFA (Printer
Font ASCII), que luego puede ser interpretada por afmtodit.
`hpftodit(1)`
crea archivos de descripción de fuentes para la familia de impresoras HP LaserJet 4.
`tfmtodit(1)`
crea archivos de descripción de fuentes para el dispositivo DVI de TeX.
`xtotroff(1)`
crea archivos de descripción de fuentes para las fuentes del sistema X Window.
Un trío de herramientas transforma el material construido utilizando los lenguajes de preprocesamiento roff en archivos de imagen gráficos.
`eqn2graph(1)`
convierte una ecuación eqn en una imagen recortada.
`grap2graph(1)`
convierte un diagrama grap en una imagen recortada.
`pic2graph(1)`
convierte un diagrama pic en una imagen recortada.
Otro conjunto de programas trabaja con los archivos de datos bibliográficos utilizados por el preprocesador refer(1).
`indxbib(1)`
crea índices invertidos para bases de datos bibliográficas, acelerando las operaciones de búsqueda en ellas.
`lkbib(1)`
busca en las bases de datos.
`lookbib(1)`
busca interactivamente en las bases de datos.
Estado de salida
`groff` sale con un estado de error si hubo un problema al analizar sus argumentos y con un estado exitoso si alguna de las opciones `-h` o `--help` se especificó. De lo contrario, `groff` ejecuta una canalización para procesar su entrada; si todos los comandos dentro de la canalización se ejecutan correctamente, `groff` hace lo mismo.
Si no, el estado de salida de groff codifica un resumen de los problemas encontrados, estableciendo el bit 0 si un comando salió con un estado de error, el bit 1 si un comando se terminó con una señal y el bit 2 si un comando no se pudo ejecutar. (Por lo tanto, si los tres infortunios le sucedieron a uno, groff saldría con el estado 2^0 + 2^1 + 2^2 = 1+2+4 = 7). Para solucionar los problemas de la canalización, es posible que desee volver a ejecutar el comando groff con la opción -V y dividir la canalización informada en etapas separadas, inspeccionando el estado de salida y los mensajes de diagnóstico emitidos por cada comando.
Entorno
Normalmente, el separador de ruta en las variables de entorno que terminan en PATH es el signo de dos puntos; esto puede variar según el sistema operativo. Por ejemplo, Windows utiliza un punto y coma.
GROFF_BIN_PATH
Esta ruta de búsqueda, seguida de PATH, se utiliza para localizar los comandos ejecutados por groff. Si no está configurada, se busca en el directorio de instalación de los ejecutables GNU roff, /usr/bin, antes que en PATH.
GROFF_COMMAND_PREFIX
GNU roff se puede configurar en tiempo de compilación para aplicar un prefijo a los nombres de los programas que proporciona y que tenían una contraparte en AT&T troff, de modo que se eviten las colisiones de nombres en tiempo de ejecución. El prefijo predeterminado está vacío.
Cuando se utiliza, este prefijo suele ser la letra “g”. Por ejemplo, GNU troff se instalaría como gtroff. Además de troff, el prefijo se aplica al formateador nroff; a los preprocesadores eqn, grn, pic, refer, tbl y soelim; y a las utilidades indxbib y lookbib.
GROFF_ENCODING
El valor de esta variable se pasa a la opción -e del preprocesador preconv(1) para seleccionar la codificación de caracteres de los archivos de entrada. La existencia de esta variable implica la opción groff -k. Si está configurada pero está vacía, groff llama a preconv sin la opción -e. La opción -K de groff anula GROFF_ENCODING.
GROFF_FONT_PATH
Busca el directorio de archivos de descripción de dispositivos y fuentes del dispositivo de salida seleccionado en esta lista de directorios. Consulte troff(1) y groff_font(5).
GROFF_TMAC_PATH
Busca archivos de macro en esta lista de directorios. Consulte troff(1) y groff_tmac(5).
GROFF_TMPDIR
Crea archivos temporales en este directorio. Si no está configurada, pero la variable de entorno TMPDIR está configurada, los archivos temporales se crean allí en su lugar. En los sistemas Windows, si ninguno de los dos anteriores está configurado, también se comprueban las variables de entorno TMP y TEMP (en ese orden). De lo contrario, los archivos temporales se crean en /tmp. Los comandos refer(1), grohtml(1) y grops(1) utilizan archivos temporales.
GROFF_TYPESETTER
Establece el dispositivo de salida predeterminado. Si está vacía o no está configurada, se utiliza ps. La opción -T anula GROFF_TYPESETTER.
SOURCE_DATE_EPOCH
Una marca de tiempo (expresada como segundos desde la época Unix) que se utilizará como la marca de tiempo de creación de la salida en lugar de la hora actual. La hora se convierte a un formato legible por humanos utilizando gmtime(3) y asctime(3) cuando se inicia el formateador y se almacena en registros que pueden ser utilizados por los documentos y los paquetes de macro.
TZ La zona horaria que se utilizará al convertir la hora actual a un formato legible por humanos; consulte tzset(3). Si se utiliza SOURCE_DATE_EPOCH, siempre se convierte a un formato legible por humanos utilizando UTC.
Ejemplos
Los sistemas roff son más conocidos por formatear las páginas del manual. Una vez que un programa de biblioteca man(1) ha localizado una página del manual, puede ejecutar un comando groff similar al siguiente. groff -t -man -Tutf8 /usr/share/man/man1/groff.1 La biblioteca también canalizará la salida a través de un paginador, que puede que no interprete las secuencias de escape de terminal SGR que groff emite para el texto en negrita, el subrayado o el texto en cursiva; consulte la sección "Limitaciones" a continuación.
Para procesar un archivo de entrada roff utilizando los preprocesadores tbl y pic y el paquete de macros me de la manera a la que los usuarios de AT&T troff estaban acostumbrados, se escribiría (o se usaría un script) una tubería.
pic foo.me | tbl | troff -me -Tutf8 | grotty
Usando groff, esta tubería se puede acortar a un comando equivalente.
groff -p -t -me -T utf8 foo.me
Una forma aún más fácil de hacerlo es usar grog(1) para adivinar las opciones del preprocesador y las macros, y ejecutar el resultado utilizando la función de sustitución de comandos del shell.
$(grog -Tutf8 foo.me)
Cada opción de línea de comandos para un posprocesador debe especificarse con cualquier guion inicial requerido "-" porque groff pasa los argumentos tal cual al posprocesador; esto permite que se transmitan argumentos arbitrarios. Por ejemplo, para pasar un título al posprocesador gxditview, los comandos del shell groff -X -P -title -P 'prueba' mydoc.t y groff -X -Z mydoc.t | gxditview -title 'prueba' son equivalentes.
Limitaciones
Cuando se realiza la paginación de la salida para los dispositivos ascii, cp1047, latin1 y utf8, programas como more(1) y less(1) pueden requerir opciones de línea de comandos para manejar correctamente algunas secuencias de escape de terminal; consulte grotty(1).
En los hosts EBCDIC como OS/390 Unix, los dispositivos de salida ascii y latin1 no están disponibles. Inversamente, el dispositivo de salida cp1047 no está disponible en los sistemas basados en los estándares de codificación de caracteres ISO 646 o ISO 8859.
Directorios de instalación
GNU roff instala archivos en varias ubicaciones dependiendo de su configuración en tiempo de compilación. En esta instalación, se utilizan las siguientes ubicaciones.
/etc/X11/app-defaults
Directorio de valores predeterminados de la aplicación para gxditview(1).
/usr/bin
Directorio que contiene los comandos ejecutables de groff.
/usr/share/groff/1.23.0/eign
Lista de palabras comunes para indxbib(1).
/usr/share/groff/1.23.0
Directorio para archivos de datos.
/usr/dict/papers/Ind
Índice predeterminado para lkbib(1) y refer(1).
/usr/share/doc/groff-base
Directorio de documentación.
/usr/share/doc/groff-base/examples
Directorio de ejemplos.
/usr/share/groff/1.23.0/font
Directorio de fuentes.
/usr/share/doc/groff-base/html
Directorio de documentación HTML.
/usr/lib/font
Directorio de fuentes heredado.
/usr/share/groff/site-font
Directorio de fuentes local.
/usr/share/groff/site-tmac
Directorio de paquetes de macros local (archivo tmac).
/usr/share/groff/1.23.0/tmac
Directorio de paquetes de macros (archivo tmac).
/usr/share/groff/1.23.0/oldfont
Directorio de fuentes para la compatibilidad con versiones anteriores de groff; consulte grops(1).
/usr/share/doc/groff-base/pdf
Directorio de documentación PDF.
directorio de macros groff
La mayoría de los archivos de macros suministrados con GNU roff se almacenan en /usr/share/groff/1.23.0/tmac para la instalación correspondiente a este documento. Por lo general, se buscan varios directorios para los archivos de macros; consulte troff(1). Para obtener un catálogo de los archivos de macros que proporciona GNU roff, consulte groff_tmac(5).
directorio de descripción de dispositivos y fuentes de groff
Los archivos de descripción de dispositivos y fuentes suministrados con GNU roff se almacenan en /usr/share/groff/1.23.0/. fuente para la instalación correspondiente a este documento. Por lo general, se buscan varios directorios para obtener archivos de descripción de dispositivos y fuentes; consulte troff(1). Para obtener los formatos de estos archivos, consulte groff_font(5).
Disponibilidad
Obtenga enlaces a las versiones de groff para su descarga, su repositorio de código fuente, listas de correo para debates, un sistema de seguimiento de tickets de soporte e información adicional en la página de groff del sitio web de GNU.
Una implementación gratuita del preprocesador grap, escrita por Ted Faber, se puede encontrar en el sitio web de grap. groff solo admite este grap.
Autores
groff (tanto el comando de interfaz como el sistema general) fue escrito principalmente por James Clark. Los colaboradores de este documento incluyen Clark, Trent A. Fisher, Werner Lemberg, Bernd Warken y G. Branden Robinson.
Ver también
Groff: The GNU Implementation of troff, de Trent A. Fisher y Werner Lemberg, es el manual principal de groff. Puede explorarlo de forma interactiva con "info groff".
Introducción, historia y más información: roff(7)
Visor para documentos de groff (y AT&T device-independent troff): gxditview(1)
Preprocesadores: chem(1), eqn(1), neqn(1), glilypond(1), grn(1), preconv(1), gperl(1), pic(1), gpinyin(1), refer(1), soelim(1), tbl(1)
Paquetes de macros y utilidades específicas de los paquetes: groff_hdtbl(7), groff_man(7), groff_man_style(7), groff_mdoc(7), groff_me(7), groff_mm(7), groff_mmse(7) (solo en locales suecos), mmroff(1), groff_mom(7), pdfmom(1), groff_ms(7), groff_rfc1345(7), groff_trace(7), groff_www(7)
Herramientas de gestión de bases de datos bibliográficas: indxbib(1), lkbib(1), lookbib(1)
Idioma, convenciones y extensiones GNU: groff(7), groff_char(7), groff_diff(7), groff_font(5), groff_tmac(5)
Lenguaje de salida intermedio: groff_out(5)
Programa formateador: troff(1)
Envoltorios del formateador: nroff(1), pdfroff(1)
Postprocesadores para dispositivos de salida: grodvi(1), grohtml(1), grolbp(1), grolj4(1), gropdf(1), grops(1), grotty(1)
Utilidades de soporte de fuentes: addftinfo(1), afmtodit(1), hpftodit(1), pfbtops(1), tfmtodit(1), xtotroff(1)
Utilidades de conversión de gráficos: eqn2graph(1), grap2graph(1), pic2graph(1)
Utilidad de marcado de diferencias: gdiffmk(1)
Utilidad de "predicción de groff": grog(1)