Um guia para os não (tão) iniciados Jorge Godoy &conectivasa; &deppubintranet;

godoy@conectiva.com

1.0 seg jul 17 14:13:34 BRT 2000 Versão inicial. Este documento procura introduzir alguns conceitos relativos à marcação estruturada de documentos. Algumas comparações são feitas com o LaTeX, uma outra linguagem de marcação. Este documento NÃO procura explicar ou ensinar elementos SGML ou DocBook ou ainda alguma ferramenta de edição de documentos desse gênero. Tais informações encontram-se em outros documentos como o DocBook HOWTO. Quaisquer sugestões ou críticas devem ser encaminhadas para o autor no endereço acima.

Fala-se muito a respeito de Docbook, SGML, XML e DSSSL mas o que significam estas siglas? A sigla SGML é na verdade um padrão ISO (ISO 8879). Esse padrão especifica as regras para a criação de linguagens de marcação indepente da plataforma. SGML significa Standard Generalized Markup Language. A sigla XML define um subconjunto da linguagem SGML. Suas especificações podem ser encontradas no World Wide Web Consortium onde se fala sobre Extensible Markup Language. A sigla DSSSL é também uma norma ISO (ISO/IEC 10179:1996) que define uma linguagem para a elaboração de estilos para documentos SGML/XML. XML significa Document Style Semantics and Specification Language. A sigla DTD significa Document Type Declaration. O DTD é um conjunto de declarações que define o nome dos elementos e seus atributos. É ele também quem define regras para sua combinação e seqüência.

O LaTeX é um sistema genérico de impressão que usa TeX como seu mecanismo de formatação. Devido a sua facilidade de uso e versatilidade o LaTeX está presente em quase todas as áres de ciência e humanidades. Os arquivos fonte do LaTeX são simples arquivos texto, o que possibilita usá-los em diversas arquiteturas e sistemas sem nenhuma preparação ou conversão especial.

A filosofia entre os dois sistemas é bem diferente e é ela o principal motivo pelo qual o &deppubintranet; trocou sua linguagem de marcação. Como explicado anteriormente, o LaTeX é otimizado para a geração de documentos impressos, permitindo um ajuste fino para, por exemplo, um livro. Não há uma preocupação por parte do sistema TeX (LaTeX, AMSTeX, etc.) em gerar uma saída diferente da impressa, mas isso não reflete os anseios de seus usuários, portanto há programas que visam realizar essa troca. Já a preocupação de sistemas SGML é com a descrição dos elementos presentes no texto. A otimização é feita para ter-se o máximo de elementos possíveis descritos de uma maneira coerente e que possa ser usada para destacar ou facilitar a procura de informações. Descrevendo-se o máximo possível de elementos podemos fazer estatísticas de uso de comandos, prompts usados, exemplos dados, etc. Vamos comparar duas estruturas: \chapter{Projetos de Documentação Existentes Para o Linux} \label{cap:ldp} \index{LDP} \noindent \section{LDP - Projeto de Documentação do Linux} A LDP (Linux Documentation Project) é um projeto que visa documentar o Linux. É sabido que os programadores não são muito fãs de escrever o que fazem. Se você quer saber algo, basta olhar o código, certo? Bem... seria se todos fôssemos programadores e todos tivéssemos a mesma familiaridade com a programação. O projeto LDP visa documentar em linguagem leiga ou técnica os programas e torná-los acessíveis para os que não sabem programar ou não têm tempo de olhar o código mas possuem um mínimo de conhecimentos técnicos. %LDP - criada há muito tempo para documentar o Linux. Sítio oficial:~\url{http://www.linuxdoc.org}. Este exemplo está presente no Guia do Usuários do &cl; 5.0. Se tivesse sido marcado com DocBook teríamos: chapter id="cap-ldp" titleProjetos de Documentação Existentes Para o Linuxtitle indexterm primaryLDPprimary indexterm section titleLDP - Projeto de Documentação do Linuxtitle paraA acronymLDPacronym (foreignphrase lang="en"Linux Documentation Projectforeignphrase) é um projeto que visa documentar o applicationLinuxapplication. É sabido que os programadores não são muito fãs de escrever o que fazem. Se você quer saber algo, basta olhar o código, certo? Bem... seria se todos fôssemos programadores e todos tivéssemos a mesma familiaridade com a programação. O projeto acronymLDPacronym visa documentar em linguagem leiga ou técnica os programas e torná-los acessíveis para os que não sabem programar ou não têm tempo de olhar o código mas possuem um mínimo de conhecimentos técnicos.para <!-- LDP - criada há muito tempo para documentar o Linux. --> paraSítio oficial: ulink url="http://www.linuxdoc.org"http://www.linuxdoc.orgulinkpara section chapter Reparem que já temos condições de dar um tratamento diferenciado para, por exemplo, a palavra LDP e também para a sua explicação que pode, inclusive, receber o tratamento correto quanto a divisão silábica do inglês e uma fonte diferenciada para destacá-la do restante do texto. As utilidades e diferenças aparecem mais ainda quando se descreve, por exemplo, códigos de programa. O LaTeX não possui um ambiente onde seja preservada a aparência do que ali foi escrito e sejam tratados comandos LaTeX ao mesmo tempo. O DocBook já possui essa facilidade e foi através dela que montei o código acima. #include <stdio.h> #include <string.h> #define FIM_CR 13 #define FIL_LF 10 int main int argc char *argv[] FILE *input_file; FILE *output_file; char caractere; char fim_de_caractere; int tamanho_caractere; char appendix[5] = ".dos"; char *output_name; char *input_name; if (argc < 2) { puts("Você precisa passar o nome de um arquivo.\n"); return 0; } /* Creates the output filename based on the input plus a suffix. */ input_name = argv[1]; output_name = strcat(input_name, appendix); /* Open input and output files. */ if ((output_file = fopen(output_name, "w")) == NULL) { fprintf(stderr, "Cannot open %s\n", output_name); return 0; } if ((input_file = fopen(input_name, "r")) == NULL) { fprintf(stderr, "Cannot open %s\n", input_name); return 0; } /* Varre a caractere procurando pelo LF */ caractere = fgetc(input_file); while ( caractere != EOF ) { if ( caractere == FIM_LF ) { /* Se achou o LF acrescenta antes o CR */ fputc(FIM_CR, output_file); } /* Grava a caractere alterada ou não */ fputc(caractere, output_file); /* Lê o próximo caractere */ caractere = fgetc(input_file); } fclose(output_file); fclose(input_file); } A inclusão desta biblioteca é algo muito comum para programas que lidam com entrada e saída. A inclusão desta biblioteca já acontece quando temos programas manipulando strings. Este é um exemplo de uma declaração de um array com 5 posições. Aqui está sendo atribuído um valor ao array, juntamente com sua declaração. Repare que ele possui apenas 4 posições e também o \0. As únicas marcações adicionadas ao código acima são no que diz respeito à prototipação da função main e de seus parâmetros. Ainda marquei os defines e seus valores, para termos um possível destaque nesse ponto.