lsp2html - Manual do Usuário



Conteúdo



Introdução

lsp2html é uma aplicação capaz de formatar código fonte lisp em HTML. Este programa funciona em linha de comando e suas definições são lidas de arquivos de configuração.



Licença de Uso

Este programa é um software de livre distribuição que pode ser copiado e distribuído nos termos da Licença Pública Geral GNU (GNU General Public License - GPL) versão 2, ou, a seu critério qualquer versão posterior.

Este programa é feito na espectativa de ser útil a seus usuários, porém não há nenhuma garantia, expressa implícita, ou de atendimento a alguma determinada finalidade.

Uma cópia da Licença Pública Geral GNU deve estar incluída em cada distribuição deste programa, você também poderá obtê-la aqui.



Linguagens suportadas

Este programa foi desenvolvido inicialmente para o AutoLISP, porém suporta uma série de linguagens, com sintaxe ao estilo common-lisp. Este programa foi testado com as seguintes linguagens



Sistemas/Arquiteturas Suportados

Este programa foi desenvolvido inicialmente em linux sob i386, porém é suportado por todos os sistemas compatíveis com POSIX, e parcialmente outros como o Microsoft Windows. Este programa foi testado com os seguintes sistemas/arquiteturas.



Instalação

Instalação a partir do códido fonte

Programas distribuídos na forma de pacotes tar.gz de código fonte seguem um procedimento de instalação próprio. Estes programas precisam ser compilados no sistema do usuário, para serem posteriormente instalados. Utiliários como o GNU Make automatizam este procedimento.

Após obter o arquivo lsp2html-XXXX.tar.gz (onde XXX é a versão do programa), descompacte-o com:

tar -xzf lsp2html-XXXX.tar.gz

Em seguida, vá para o diretório lsp2html-XXXX e dispare o GNU Make para compilação

cd lsp2html-XXXX
make

Agora lsp2html estará compilado, para instalá-lo no sistema, digite:

make install

Este procedimento irá instalar os arquivos binários em /usr/bin e a documentação em /usr/doc/

Adicionalmente, você poderá criar um arquivo de definições da formatação HTML, chamado .lsp2html.conf em seu diretório HOME. Este arquivo será lido cada vez que você usar o programa, e suas definições serão aplicadas sempre que nenhum outro arquivo de configuração for informado.

Instalação a partir do binário RPM

RPM é um sistema de empacotamento de binários desenvolvido pela Red Hat e disponibilizado sob a GPL. Este sistema foi desenvolvido inicialmente para o Red Hat Linux, porém já foi portado para *vários* outros sistemas. RPM usa o conceito de pacotes gerenciados por um programa independente que mantém uma base de dados centralizada, com informações sobre todos os arquivos e suas versões, facilitando a atualização/manutenção e evitando conflitos de versões. Em geral este conceito é similar aos pacotes DEB usados pelo DEBIAN e aos pacotes PKG do Solaris

Para instalar o programa, após obter o arquivo lsp2html-XXXX.i386.rpm (onde XXXX é a versão deste programa, e i386 é a arquitetura desejada), digite

rpm -ivh lsp2html-XXXX.i386.rpm

Desta forma, o programa estará instalado no sistema e pronto para ser utilizado

Algumas operações adicionais ainda podem ser feitas, por exemplo, para obter informações do programa, digite

rpm -qi lsp2html

para verificar arquivos e diretórios, digite

rpm -ql lsp2html

para desinstalar o programa, digite

rpm -e lsp2html

Adicionalmente, você poderá criar um arquivo de definições da formatação HTML, chamado .lsp2html.conf em seu diretório HOME. Este arquivo será lido cada vez que você usar o programa, e suas definições serão aplicadas sempre que nenhum outro arquivo de configuração for informado.

Instalação no Microsoft Windows

O Microsoft Windows não é suportado por esta documentação, neste sistema a instalação deverá ser feita manualmente a partir dos binários, fornecidos em um pacote à parte.



Sintaxe da linha de comando

lsp2html irá aceitar uma linha de comando como:

lsp2html [-d arq_def] arq_lisp [...]

onde arq_lisp é o arquivo fonte do código LISP e -d indica que o próximo argumento é um arquivo de definição da formatação HTML (arq_def) que será aplicado aos arquivos LISP subsequentes.

Inicialmente, lsp2html irá tentar carregar as definições padrões definidas a nível de usuário, em um arquivo .lsp2html.conf localizado no diretório HOME do usuário atual. Caso este arquivo não exista, definições padrões definidas durante a compilação serão utilizadas. Este recurso existe apenas na versão para UNIX deste programa.

Em seguida, lsp2html irá interpretar os argumentos da linha de comando da esquerda para a direita, de forma que o argumento atual jamais irá interferir no argumento que o precede, porém poderá influenciar o argumento que o procede. Exemplo:

lsp2html teste1.lsp -d def1.conf teste2.lsp

Neste caso, as definições de def1.conf serão aplicadas a teste2.lsp, porém não serão aplicadas a teste1.lsp.

Esta característica permite vários arquivos de definição sejam aplicados a vários arquivos LISP na mesma linha de comando. Se nenhum arquivo de definição for utilizado, as definições padrões serão aplicadas. Exemplo:

lsp2html teste1.lsp -d def1.conf teste2.lsp teste3.lsp -d def2.conf teste4.lsp

Neste caso, teste1.lsp será formatado com as definições padrões, teste2.lsp, e teste3.lsp serão formatados de acordo com def1.conf e teste4.lsp será formatado de acordo com def2.conf.



O Arquivo de definições

O arquivo de definições da formatação HTML usado por lsp2html é semelhante aos arquivos .conf usados pela maioria das aplicações do mundo UNIX. É composto por uma chave, separada do respectivo valor por espaços, tabs, ou qualquer combinação de ambos. Os comentários iniciam com um ; e são válidos até o fim da linha. Muitas aplicações utilizam o sustenido (#) como sinal de início de comentário, porém, lsp2html o reserva para a especificação de cores do html. Todas as chaves são sensíveis a maiúsculas e minúsculas.

Segue um exemplo funcional de um arquivo de definições.

; Exemplo de um arquivo de definições
;
;
;

header             teste_header.html
footer             teste_footer.html
title              Apenas um teste
author             Alexandre Erwin Ittner
keywords           teste lisp
body_color         white
code_color         black
string_color       #dd0000  ;vermelho escuro
comment_color      green
escape_color       purple
parentheses_color  gray
line_number_color  navy
code_size          +0
parentheses_size   +1
bold_parentheses   1
italict_comments   0
show_title         1
show_line_numbers  1
show_timestamp     1
spaces_per_tab     4

onde

header

Define o nome do arquivo de cabeçalho. Este arquivo será inserido após o título do documento e antes do código lisp formatado. O arquivo será inserido sem nenhuma formatação adicional. Para não utilizar um arquivo de cabecalho, não defina esta chave ou deixe-a em branco.

footer

Define o nome do arquivo de rodapé. Este arquivo será inserido após o código lisp formatado e antes do timestamp. O arquivo será inserido sem nenhuma formatação adicional. Para não utilizar um arquivo de rodapé, não defina esta chave ou deixe-a em branco.

title

Define o título do documento HTML. Caso show_title esteja definido, este título também será inserido em <h1> no início do documento.

author

Define o nome do autor do programa lisp. Este valor irá preecher a meta tag author do documento HTML, e também será incluído no timestamp do documento.

keywords

Define a meta tag keywords do documento HTML. Esta tag é útil para realizar buscas indexadas em documentos HTML. Robôs de busca geralmente procuram por esta tag ao vasculhar a web.

body_color

Define a cor de fundo do documento HTML. Este valor pode ser representado na forma de uma string reconhecida como nome de cor pelo HTML ou de uma sequência de bytes em hexadecimal representando a cor desejada no sistema RGB. Não use aspas. Por exemplo, blue é o mesmo que #0000ff.

code_color

Define a cor do código LISP. Este valor pode ser representado na forma de uma string reconhecida como nome de cor pelo HTML ou de uma sequência de bytes em hexadecimal representando a cor desejada no sistema RGB. Não use aspas.

string_color

Define a cor das strings encontradas no código LISP. Esta cor também será aplicada às aspas que delimitam a string. Este valor pode ser representado na forma de uma string reconhecida como nome de cor pelo HTML ou de uma sequência de bytes em hexadecimal representando a cor desejada no sistema RGB. Não use aspas.

comment_color

Define a cor dos comentários no código LISP. Este valor pode ser representado na forma de uma string reconhecida como nome de cor pelo HTML ou de uma sequência de bytes em hexadecimal representando a cor desejada no sistema RGB. Não use aspas.

escape_color

Define a cor dos caracteres de escape do código lisp. Um caracter de escape é uma sequência como \n, ou \010. Este valor pode ser representado na forma de uma string reconhecida como nome de cor pelo HTML ou de uma sequência de bytes em hexadecimal representando a cor desejada no sistema RGB. Não use aspas.

parentheses_color

Define a cor dos parênteses funcionais encontrados no código lisp. Esta cor é aplicada apenas aos parênteses que representam algo no código, e não será aplicada aos parênteses encontrados dentro de strings ou comentários. Este valor pode ser representado na forma de uma string reconhecida como nome de cor pelo HTML ou de uma sequência de bytes em hexadecimal representando a cor desejada no sistema RGB. Não use aspas.

line_number_color

Define a cor dos números das linhas, colocados antes de cada linha do código lisp caso show_line_numbers esteja definido. Este valor pode ser representado na forma de uma string reconhecida como nome de cor pelo HTML ou de uma sequência de bytes em hexadecimal representando a cor desejada no sistema RGB. Não use aspas.

code_size

Define o tamanho da fonte do código lisp, comentários e strings. Este valor irá diferenciar pelo tamanho o código dos parênteses. Podem ser usados tanto valores absolutos, quanto valores relativos.

parentheses_size

Define o tamanho da fonte dos parênteses funcionais encontrados no código lisp. Podem ser usados tanto valores absolutos, quanto valores relativos.

bold_parentheses

Define se os parênteses funcionais do código LISP devem aparecer em negrito no documento HTML. Defina esta chave para um valor diferente de zero para ativá-la, defina-a para zero para desativá-la. Um valor não numérico inserido nesta chave será interpretado como zero.

italict_comments

Define se os comentários deverão aparecer em itálico no documento HTML. Defina esta chave para um valor diferente de zero para ativá-la, defina-a para zero para desativá-la. Um valor não numérico inserido nesta chave será interpretado como zero.

show_title

Define se o título do documento (definido em title) deverá ser inserido no início do documento HTML. Defina esta chave para um valor diferente de zero para ativá-la, defina-a para zero para desativá-la. Um valor não numérico inserido nesta chave será interpretado como zero.

show_line_numbers

Define se cada linha do código formatado deverá ser numerada. A cor do números de linha é definida em line_number_color. Defina esta chave para um valor diferente de zero para ativá-la, defina-a para zero para desativá-la. Um valor não numérico inserido nesta chave será interpretado como zero.

show_timestamp

Caso esta chave esteja ativa, uma linha contendo a data e a hora atuais, o nome do arquivo e o nome do autor (definido em author) será inserida no final do documento HTML. Defina esta chave para um valor diferente de zero para ativá-la, defina-a para zero para desativá-la. Um valor não numérico inserido nesta chave será interpretado como zero.

spaces_per_tab

Esta chave indica o número de espaços que deve ser inserido no documento formatado no lugar do caracter tab ("\t"). Defina-a para zero para manter os tabs no código formatado.



Ei!! Tem algo errado aqui!

Não se assuste ;-) Primeiramente certifique-se de que os resultados estranhos que você obteve não foram causados por alguma opção definida incorretamente, ou não definida.

Caso os problemas persistam, entre em contato enviando uma descrição o mais completa possível do seu problema. Tentarei verificá-lo o mais rápido possível (o que é bastante relativo, pois o tempo que disponho para desenvolver este programa é bastante limitado). Sugestões também são bem vindas.



Contato

Alexandre Erwin Ittner
E-mail: aittner@netuno.com.br
URL: http://users.netuno.com.br/aittner/
Jaraguá do Sul, SC, Brasil.



Última atualização: qui dez 27 11:19:39 GMT-3 2001