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

** THIS FILE IS OUT OF DATE **

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:

1.  Plataformas
2.  Lenguajes de programaci�n/marcado contemplados
3.  Caracter�sticas
4.  Instrucciones de uso
5.  Formato del fichero Highlight
6.  Definici�n de nuevos lenguajes
7.  Definici�n de nuevos temas de color
8.  Definici�n de nuevos esquemas de indentaci�n
9.  Fichero de configuraci�n
10. Scripts
11. Bindings para Python
13. 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 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 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/.
