--------------------------------------------------------------------------------
---  MANUAL DE HIGHLIGHT - Versin 2.2-10 ----------------------- JULIO 2004 ---
--------------------------------------------------------------------------------

OSI Certified Open Source Software

English manual: README

--------------------------------------------------------------------------------

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


CONTENIDO:

1.  Plataformas
2.  Lenguajes de programacin/marcado contemplados
3.  Caractersticas
4.  Instrucciones de uso
5.  Formato del fichero Highlight
6.  Definicin de nuevos lenguajes
7.  Definicin de nuevos temas de color
8.  Definicin de nuevos esquemas de indentacin
9.  Fichero de configuracin
10. Scripts
11. Bindings para Python
13. Informacin de contacto


1. PLATAFORMAS
--------------------------------------------------------------------------------

Highlight est escrito en ISO C++. Existen tres versiones:
- aplicacin UNIX para consola
- aplicacin W32 para consola
- aplicacin W32 grfica

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


2. LENGUAJES DE PROGRAMACIN / MARCADO CONTEMPLADOS:

Actualmente, highlight contempla los siguientes lenguajes de
programacin, marcado y ficheros de configuracin:

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. CARACTERSTICAS:
--------------------------------------------------------------------------------

- resaltado de palabras clave, tipos, cadenas, nmeros, secuencias de
  escape, comentarios, smbolos 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 indentacin configurable de cdigo fuente  C, C++, C# y
  Java
- divisin de lineas largas
- nmeros de lnea
- eleccin 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
- conversin 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 parmetro correcto de -S debera ser
"py". Si indica directamente el nombre de fichero, highlight busca la extencin
.py, en cambio, si se usa redireccin de la shell, el parmetro -S es necesario.

Si existen mltiples sufijos (como C, cc, cpp, h para ficheros C++),
highlight intenta buscar el fichero de definicin 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, aadiendo .html, .xhtml, .rtf, .tex o .fo, de acuerdo con el
tipo de salida elegida. La opcin -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, guardndolos 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 (opcin
--include-css). El uso de las definiciones CSS referenciadas tiene la ventaja
de que toda la informacin 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
opcin -css-outfile.
La opcin -css-infile define otro fichero CSS que ser incluido al final de la
definicin CSS.
Si se indica la opcin --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 todava 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 opcin --fop-compatible.
 Problema: Hay un fallo en FOP, que genera lneas en blanco despus de los
 saltos de lnea.

 Anuncio en la pgina 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 cmodamente en una consola con la orden
highlight -A <inputfile> | less -R
Dado que los colores definidos para consola est muy limitado, slo existe
un tema fijo.


Acerca del procesamiento de texto
---------------------------------

Si una definicin del lenguaje se especifica como txt, highlight no realiza
ningn 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 configuracin de highlight se guardan en ficheros de texto.
El formato es simple:

$ParamName=ParamValue

ParamName es el identificador del parmetro, ParamValue es su valor.
Los nombres de parmetros no distinguen entre mayscula y minscula.
El valor puede ser un carcter simple o una lista de palabras. Las listas se
pueden separar en mltiples lneas.

Las lneas que comienzan con # en la primera columna son comentarios

6. DEFINICIN DE NUEVOS LENGUAJES:
--------------------------------------------------------------------------------

Una definicin de lenguajes es un fichero de texto, en el que las palabras clave
y los smbolos del lenguaje de programacin pertenecen a diferentes categoras.
Se debe guardar el fichero en directorio highlight/langDefs* con el siguiente
nombre:

<extensin propia de los fichero del lenguaje>.lang

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

Si existen mltiples sufijos, pngalos 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-lnea
$ML_COMMENT=<comment_begin comment_close>

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

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

# Fijado a 'true' si el cdigo fuente del lenguaje se puede reformatear
# (slo lenguajes tipo C!)
$REFORMATTING=<true / false>

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

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

# Fijado a 'true' si el lenguaje de programacin no distingue entre maysculas
# y minsculas
$IGNORECASE=<true / false>

# Incluye otra definicin 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
         instalacin por defecto, debes indicar a highlight otra ruta
	 donde buscar con la opcin --add-data-dir.



7. DEFINICIN DE NUEVOS TEMAS DE COLOR
--------------------------------------------------------------------------------

Los temas de color se guardan en ficheros ASCII, en los que se define el for-
mato de salida. La salida RTF ignora el atributo de color de fondo. Los fiche-
ros deben estar en el directorio themes* y deben tener extensin *.style.
Para aplicar un estilo se debe indicar la opcin -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

# Tamao de letra
$FONTSIZE=<number>

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

# Formato de los nmeros
$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 lnea
$SL-COMMENT=<ColourAttr> ( <FormatAttr> )

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

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

# Formato de los nmeros de lnea
$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.  DEFINICIN DE NUEVOS ESQUEMAS DE INDENTACIN
--------------------------------------------------------------------------------

Se pueden definir esquemas de indentacin y formateo a medida. Para habilitar el
reformateo de un lenguaje de programacin, la opcin $REFORMATTING=true debe
aadirse a la definicin del lenguaje. Note que el reconocedor 'Artistic Style'
se dise slo para manejar lenguajes tipo C (C++, Java, C#).
Los esquemas de indentacin se guardan en el directorio indentSchemes* y deben
tener extensin *.indent. Los esquemas se aplican con la opcin --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 definicin y dejarlas en los bloques de rdenes.
# "break-closing-headers": Separar llaves antes de las cabeceras de cierre (e.g. 'else',
#                          'catch', ..).  Se debera aadir a $brackets=attach o $brackets=linux.
$BRACKETS=<break | attach | linux | break-closing-headers>

# Inserta lneas vacas entre bloques no relacionados, etiquetas, clases, ...
# "true": modo por defecto
# "all":  tambin inserta lneas vacas entorno a las cabeceras de cierre
#        (e.g. 'else', 'catch', ...).
$BREAK-BLOCKS=<true | false | all>

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

# Aade indentacin extra para bloques (incluyendo las llaves).
$INDENT-BLOCKS=<true / false>

# Aade indentacin extra a las llaves.
$INDENT-BRACKETS=<true / false>

# Indenta las lneas 'case XXX:', de modo que se alineen con sus bloques de cdigo.
$INDENT-CASES=<true / false>

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

# Indenta etiquetas de modo que aparecen en un nivel de indentacin 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-lnea
$INDENT-PREPROCESSOR=<true / false>

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

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

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

# Indenta un mximo de <num> espacios en una sentencia continua, de forma relativa
# a la lnea previa
$MAX-INSTATEMENT-INDENT=<num>

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

# Separar smbolos con espacios en blanco:
# "paren": Inserta espacios slo alrededor de los parntesis
# "oper":  Inserta espacios slo alrededor de los operadores
# "all":   Inserta espacios alrededor de parntesis 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 CONFIGURACIN
--------------------------------------------------------------------------------

Slo los ejecutables para consola leen un fichero de configuracin.
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 lnea de rdenes. Las banderas (opciones sin parmetro) 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 lnea de
rdenes (excepto las banderas).


10. SCRIPTS
--------------------------------------------------------------------------------

En el subdirectorio /utils dentro del directorio de instalacin 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 pgina web para informacin 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 instruccin de instalacin y example.py para la referencia
de programacin.


12. INFORMACIN 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 ejecucin con la opcin --data-dir, o durante la compilacin (ver
INSTALL para ms detalles). Highlight espera encontrar los subdirectorios
langDefs/ y themes/.
