--- MANUAL DE HIGHLIGHT - Versión 2.2-10 ----------------------- JULIO 2004 ---

OSI Certified Open Source Software

English manual: README

Highlight convierte código fuente a archivos HTML, XHTML, RTF, LaTeX, TeX, XSL-FO or XML con resalte de sintaxis. Las definiciones de lenguajes, temas de color e indentación son configurables.

CONTENIDO

Plataformas
Lenguajes de programación/marcado contemplados
Características
Instrucciones de uso
Formato del fichero Highlight
Definición de nuevos lenguajes
Definición de nuevos temas de color
Definición de nuevos esquemas de indentación
Fichero de configuración
Scripts
Bindings para Python
Información de contacto

1. PLATAFORMAS

Highlight está escrito en ISO C++. Existen tres versiones: - aplicación UNIX para consola
- aplicación W32 para consola
- aplicación W32 gráfica

El paquete fuente compila con gcc3.x, MS Visual .NET y MW Codewarrior 8.

2. LENGUAJES DE PROGRAMACIÓN / MARCADO CONTEMPLADOS:

Actualmente, highlight contempla los siguientes lenguajes de programación, marcado y ficheros de configuración:

Action Script, ADA 95, Agda, AMPL, Aspect, Assembler, Amtrix, Avenue, (G)AWK, Bash, BlitzBasic, BibTex, BMS, C,C++, C#, ClearBasic, Clipper, Cobol, Coldfusion MX, CSS, DOS-Batch, Eiffel, Erlang, Euphoria, Express, Felix, Fortran, Frink, Haskell, HTML, httpd.conf, Icon, IDL, INI, IO, Jasmin, Java, JavaScript, JSP, LaTeX, LDIF, Lisp, Lotos, Lotus Script, Lua, Make,Maya, Matlab, Maple, Modelica, Modula 3, Nasal, OCaml, (Object) Pascal, Objective C, Paradox, PATROL, Perl, PHP, Pike, PL/1, PL/SQL, PostScript, POV Ray, Progress, Prolog, Python, Relax NG Compact, Rexx, RPM Spec, Ruby, Small, SML, Spin, Squirrel, SuperX++, Sybase, VHDL, Visual Basic, XML.

3. CARACTERÍSTICAS:

resaltado de palabras clave, tipos, cadenas, números, secuencias de escape, comentarios, símbolos y directivas.
resaltado de conjuntos de palabras clave configurables.
salida coloreada en formato HTML, XHTML 1.1, RTF, TeX, LaTeX o XSL-FO
reformateo e indentación configurable de código fuente C, C++, C# y Java
división de lineas largas
números de línea
elección entre empotrar las definiciones CSS en el fichero (X)HTML o guardarlas como un fichero CSS aparte
50 temas de color
procesado por lotes recursivo de directorios
conversión de texto plano al formato elegido sin resalte de sintaxis.

4. INSTRUCCIONES DE USO:

Se puede obtener una pantalla de ayuda escribiendo "highlight -h":

Si no se indica un fichero de entrada, hay que indicar a highlight el sufijo usual del fichero con -S. Ejemplo: Si quieres convertir un fichero Python, highlight busca un fichero py.lang. El parámetro correcto de -S debería ser "py". Si indica directamente el nombre de fichero, highlight busca la extención .py, en cambio, si se usa redirección de la shell, el parámetro -S es necesario.

Si existen múltiples sufijos (como C, cc, cpp, h para ficheros C++), highlight intenta buscar el fichero de definición de lenguaje que corresponda (ver el fichero extensions.conf" en el directorio de highlight*).

En el modo por lotes, highlight guarda los ficheros generados con el nombre de fichero original, añadiendo .html, .xhtml, .rtf, .tex o .fo, de acuerdo con el tipo de salida elegida. La opción -O resulta útil con -b. Use --quiet para aumentar la velocidad (recomendado para shell scripting).

Ejemplo

highlight -X -B '*.cpp' -O /home/you/html_code/ convierte todos los ficheros *.cpp del directorio actual y sus subdirectorios a ficheros xhtml, y los guarda en /home/you/html_code.

highlight -L * -O /home/you/latex_code/ convierte todos los ficheros a LaTeX, guardándolos en /home/you/latex_code/.

Acerca de la salida (X)HTML:

La salida (X)HTML se formatea mediante Cascading Style Sheets (CSS). Las definiciones CSS se pueden guardar en un fichero externo, que se referencia en el fichero HTML generado, o se puede incluir en la salida HTML (opción --include-css). El uso de las definiciones CSS referenciadas tiene la ventaja de que toda la información de formato está centralizada, de modo que afecta a todos los ficheros HTML que la referencian. Si highlight se invoca sin --include-css, se genere un fichero highlight.cc en el directorio actual, y se incluye un enlace a "highlight.css" en el fichero HTML de salida. El nombre y la ruta del fichero CSS se pueden modificar con la opción -css-outfile.
La opción -css-infile define otro fichero CSS que será incluido al final de la definición CSS.
Si se indica la opción --outdir, todos los ficheros generados, incluidos los CSS, se guardan en ese directorio

Acerca de la salida XSL-FO:

La salida XSL-FO es experimental. La salida actual es compatible con Apache FOP y xsltproc/xmlto, pero todavía hay algunos problemas:

xsltproc y xmlto

Version xsltproc:
Using libxml 20604, libxslt 10102 and libexslt 802 xsltproc was compiled against libxml 20604, libxslt 10102 and libexslt 802 libxslt 10102 was compiled against libxml 20604 libexslt 802 was compiled against libxml 20604

Version xmlto: 0.0.18

Problema: Los ficheros generados son grandes, y el procesamiento es muy lento.

Apache FOP

Version: 0.20.5

La salida FO se puede modificar para FOP con la opción --fop-compatible. Problema: Hay un fallo en FOP, que genera líneas en blanco después de los saltos de línea.

Anuncio en la página de Apache:
"Due to a bug in current versions of FOP, setting white-space-collapse='false' will also preserve line breaks in the text. Do not rely on this behavior, as it is non-conformant and will be changed."

Acerca de la salida RTF:

RTF siempre utiliza blanco para el color de fondo.

Acerca de la salida ANSI:

Puede visualizar ficheros fuente cómodamente en una consola con la orden highlight -A <inputfile> | less -R
Dado que los colores definidos para consola está muy limitado, sólo existe un tema fijo.

Acerca del procesamiento de texto

Si una definición del lenguaje se especifica como txt, highlight no realiza ningún tipo de coloreado y el fichero se convierte simplemente al formato de salida.

Ejemplo

highlight -S txt -L README > README.tex

5. FORMATO DEL FICHERO HIGHLIGHT

Todos los ficheros de configuración de highlight se guardan en ficheros de texto. El formato es simple:

$ParamName=ParamValue

ParamName es el identificador del parámetro, ParamValue es su valor. Los nombres de parámetros no distinguen entre mayúscula y minúscula. El valor puede ser un carácter simple o una lista de palabras. Las listas se pueden separar en múltiples líneas.

Las líneas que comienzan con # en la primera columna son comentarios

6. DEFINICIÓN DE NUEVOS LENGUAJES:

Una definición de lenguajes es un fichero de texto, en el que las palabras clave y los símbolos del lenguaje de programación pertenecen a diferentes categorías. Se debe guardar el fichero en directorio highlight/langDefs* con el siguiente nombre:

<extensión propia de los fichero del lenguaje>.lang

Ejemplos: PHP -> php.lang, Java -> java.lang

Si existen múltiples sufijos, póngalos en extensions.conf*.

FORMATO DEL FICHERO:

# Regular expression to describe valid number tokens # Default value: (?:0x|0X)?\d*[\.]?\d+(?:[eE][\-\+]\d+)?[lLuU]? $DIGIT=regex(<RE>)

# Regular expression to describe valid identifier tokens # Default value: [a-zA-Z_]\w*
$IDENTIFIER=regex(<RE>)

# Lista de palabras reservadas; <group> es el nombre de la clase de palabras # reservadas
# La clase debe estar definida en el tema de color aplicado para que el estilo # de resalte coincida
$KW_LIST(<group>)=<List>

# Regular expression which describes keywords $KW_RE(<group>)=regex(<RE>)

# Delimitadores para marcas de apertura y cierre # Las marcas se formatean como palabras clave de la clase especificada $TAG_DELIM(<group>)=<tag_open tag_close>

# Lista de delimitadores de cadena
$STRINGDELIMITERS=<List>

# Par de delimitadores de cadena diferentes # Ejemplo: s" " en Forth
$STRINGDELIMITERPAIR=<open close>

# Lista de caracteres de escape en cadenas (ie. "\") $ESCCHAR=<List> | regex(<RE>)

# Set true if escape characters may appear outside of strings $ALLOWEXTESCAPE=<true|false>

# Prefijo que desactiva el resalte de caracteres de escape # para la siguiente cadena
$RAWSTRINGPREFIX=<Character>

# Delimitadores de comentarios multi-línea $ML_COMMENT=<comment_begin comment_close>

# Lista de cadenas que comienzan comentarios de una línea $SL_COMMENT=<List> | regex(<RE>)

# Cadena de comienzo de las directivas del preprocesador $DIRECTIVE=<prefix> | regex(<RE>)

# Fijado a 'true' si el código fuente del lenguaje se puede reformatear # (sólo lenguajes tipo C!)
$REFORMATTING=<true / false>

# Símbolos que se pueden colorear (llaves, operadores, etc) $SYMBOLS=<List>

# Fijado a 'true' si los comentarios multi-línea se pueden anidar $ALLOWNESTEDCOMMENTS=false

# Fijado a 'true' si el lenguaje de programación no distingue entre mayúsculas # y minúsculas
$IGNORECASE=<true / false>

# Incluye otra definición de lenguaje almacenada en el mismo directorio $INCLUDE=<language definition>

Ejemplo

#Contenido de pas.lang (Pascal/Object Pascal)

$KW_LIST(kwa)=true false if else then nil maxint case goto label and div downto in mod not of or packed with do for do repeat while to until procedure function program begin end const var type unit interface implementation uses private public

$KW_LIST(kwb)=array boolean char integer file pointer real set string text record

$STRINGDELIMITERS=" '
$SL_COMMENT=//
$ML_COMMENT={ }
$IGNORECASE=true

CONSEJO: Si no quieres guardar definiciones de lenguajes nuevas en el directorio de

         instalación por defecto, debes indicar a highlight otra ruta
         donde buscar con la opción --add-data-dir.

7. DEFINICIÓN DE NUEVOS TEMAS DE COLOR

Los temas de color se guardan en ficheros ASCII, en los que se define el formato de salida. La salida RTF ignora el atributo de color de fondo. Los ficheros deben estar en el directorio themes* y deben tener extensión *.style. Para aplicar un estilo se debe indicar la opción -s.

FORMATO DEL FICHERO:

#<ColourAttr> = RR GG BB
#RR GG BB describe los valores rojo/verde/azul en hexadecimal que definen el color. #(Rango: 00 (nada) - FF (todo))

#<FormatAttr> = <bold> <italic> <underline> #Negrita, cursiva y subrayado son atributos opcionales que se pueden combinar

# Color del texto no reconocido
$DEFAULTCOLOUR=RR GG BB

# Color de fondo (ignorado por RTF)
$BGCOLOUR=RR GG BB

# Tamaño de letra
$FONTSIZE=<number>

# Formato de palabras reservadas, que pertenece a la clase correspondiente $KW_GROUP(<group>)=<ColourAttr> ( <FormatAttr> )

# Formato de los números
$NUMBER=<ColourAttr> ( <FormatAttr> )

# Formato de los caracteres de escape
$ESCAPECHAR=<ColourAttr> ( <FormatAttr> )

# Formato de las cadenas
$STRING=<ColourAttr> ( <FormatAttr> )

# Formato de las cadenas con directivas del compilador $STRING_DIRECTIVE=<ColourAttr> ( <FormatAttr> )

# Formato de los comentarios
$COMMENT=<ColourAttr> ( <FormatAttr> )

# Formato de los comentario de una línea $SL-COMMENT=<ColourAttr> ( <FormatAttr> )

# Formato de las directivas del compilador $DIRECTIVE=<ColourAttr> ( <FormatAttr> )

# Formato de símbolos (opcional, igual a $DEFAULTCOLOUR si se omite) $SYMBOL=<ColourAttr> ( <FormatAttr> )

# Formato de los números de línea
$LINE=<ColourAttr> ( <FormatAttr> )

Ejemplo

# Golden.style
$DEFAULTCOLOUR=dd bb 00
$BGCOLOUR=00 00 00
$FONTSIZE=10
$KW_GROUP(kwa)=dd bb 00 bold
$KW_GROUP(kwb)=dd bb 00
$NUMBER=ff ff ff
$ESCAPECHAR=ff 00 00
$STRING=ff 00 00
$STRING_DIRECTIVE=ff 00 00
$COMMENT=97 83 45 italic
$DIRECTIVE=ff dd aa
$LINE=97 83 45

8. DEFINICIÓN DE NUEVOS ESQUEMAS DE INDENTACIÓN

Se pueden definir esquemas de indentación y formateo a medida. Para habilitar el reformateo de un lenguaje de programación, la opción $REFORMATTING=true debe añadirse a la definición del lenguaje. Note que el reconocedor 'Artistic Style' se diseñó sólo para manejar lenguajes tipo C (C++, Java, C#). Los esquemas de indentación se guardan en el directorio indentSchemes* y deben tener extensión *.indent. Los esquemas se aplican con la opción --format-style.

FORMATO DEL FICHERO:

# manejo de llaves:
# "break": Separar llaves del bloque precedente (i.e. ANSI C/C++ style). # "attach": Dejar las llaves junto al bloque precedente (i.e. Java/K&R style). # "linux": Separar llaves en los bloques de definición y dejarlas en los bloques de órdenes. # "break-closing-headers": Separar llaves antes de las cabeceras de cierre (e.g. 'else', # 'catch', ..). Se debería añadir a $brackets=attach o $brackets=linux. $BRACKETS=<break | attach | linux | break-closing-headers>

# Inserta líneas vacías entre bloques no relacionados, etiquetas, clases, ... # "true": modo por defecto
# "all": también inserta líneas vacías entorno a las cabeceras de cierre # (e.g. 'else', 'catch', ...).
$BREAK-BLOCKS=<true | false | all>

# Divide las sentencias 'else if()' en dos líneas diferentes. $BREAK-ELSEIFS=<true / false>

# Añade indentación extra para bloques (incluyendo las llaves). $INDENT-BLOCKS=<true / false>

# Añade indentación extra a las llaves. $INDENT-BRACKETS=<true / false>

# Indenta las líneas 'case XXX:', de modo que se alineen con sus bloques de código. $INDENT-CASES=<true / false>

# Indenta los bloques 'class' 'class' blocks, así como su 'public:', 'protected:' and 'private:'
# Las cabeceras se indentan en relación a bloque de la clase. $INDENT-CLASSES=<true / false>

# Indenta etiquetas de modo que aparecen en un nivel de indentación menos que el actual, # en lugar de completamente a la izquierda (que es el comportamiento por defecto). $INDENT-LABELS=<true / false>

# Indenta el contenido de los bloques 'namespace'. $INDENT-NAMESPACES=<true / false>

# Indenta las sentencias #define multi-línea $INDENT-PREPROCESSOR=<true / false>

# Indenta usando <num> espacios por indentación. Si no se especifica <num> se # aplica el valor por defecto, que son 4 espacios por indentación. $INDENT-SPACES=<num>

# Indenta los bloques 'switch', de modo que sus 'case XXX:' se indentan en relación # al bloque switch block.
$INDENT-SWITCHES=<true / false>

# Indenta un fichero fuente Java
$JAVA-STYLE=<true / false>

# Indenta un máximo de <num> espacios en una sentencia continua, de forma relativa # a la línea previa
$MAX-INSTATEMENT-INDENT=<num>

# Indenta un mínimo de <num> espacios en sentencias condicionales continuas. $MIN-CONDITIONAL-INDENT=<num>

# Separar símbolos con espacios en blanco: # "paren": Inserta espacios sólo alrededor de los paréntesis # "oper": Inserta espacios sólo alrededor de los operadores # "all": Inserta espacios alrededor de paréntesis Y operadores $PAD=<paren | oper | all>

Ejemplo

# K&R indentation scheme
$indent-brackets=false
$indent-spaces=4
$brackets=attach
$indent-classes=false
$indent-switches=false
$indent-namespaces=false

9. FICHERO DE CONFIGURACIÓN

Sólo los ejecutables para consola leen un fichero de configuración. Se debe guardar un fichero de texto ASCII en la siguiente ruta, dependiendo de la plataforma:

UNIX: $HOME/.highlightrc
W32 : <Path of highlight.exe>\highlight.conf

Las opciones del fichero se comportan como sus equivalentes del mismo nombre en la línea de órdenes. Las banderas (opciones sin parámetro) esperan 'true' o 'false' como valor.

Ejemplo

$style=emacs
$linenumbers=true
$css-outfile=format.css
$format-style=gnu

Las opciones definidas en el fichero se pueden redefinir en la línea de órdenes (excepto las banderas).

10. SCRIPTS

En el subdirectorio /utils dentro del directorio de instalación de highlight puede encontrar algunos scripts que hacen uso de highlight.

./cgi/perl/highlight.cgi

un script Perl que invoca highlight y genera HTML.

./cgi/php/SyntaxHighlighter.php

Dos plugins para PHP Wiki.

Ver la página web para información sobre el frontend PyQt.

11. USO DE HIGHLIGHT CON PYTHON

En /utils/python-binding se encuentran los bindings para Python 2.3 Ver README_PYTHON para instrucción de instalación y example.py para la referencia de programación.

12. INFORMACIÓN DE CONTACTO

Andre Simon
andre.simon1@gmx.de
http://www.andre-simon.de/

---
* El directorio de highlight puede ser uno de los directorios listados en INSTALL. Para UNIX, normalmente es /usr/share/highlight, para Window$, es la ruta al ejecutable de highlight. Se puede redefinir este directorio en tiempo de ejecución con la opción --data-dir, o durante la compilación (ver INSTALL para más detalles). Highlight espera encontrar los subdirectorios langDefs/ y themes/.