Primer do Projeto de Documentação do FreeBSD para novos colaboradores
Anterior |  | Próxima

# Capítulo 3 SGML Primer

A maioria dos documentos do FDP é escrita utilizando SGML. Este capítulo irá explicar exatamente o que isso significa, como ler e compreender os fontes dos documentos e os truques de SGML que você irá se defrontar na documentação.

Partes desta seção foram inspiradas no documento Começando a utilizar o DocBook de autoria do Mark Galassi.

# 3.1 Visão Geral

Antigamente, era simples de se lidar com um texto eletrônico. Naquela época, você tinha que saber em qual conjunto de caracteres o seu documento havia sido escrito (ASCII, EBCDIC ou um dos inúmeros outros), e mais nada. O texto era texto, e o que você via era realmente o que você tinha. Nenhuma frescura, nenhuma formatação, nenhuma inteligência.

Inevitavelmente, isto não era o suficiente. Uma vez que você tem o texto em uma máquina num formato utilizável, você espera que o equipamento seja capaz de usá-lo e manipulá-lo de forma inteligente. Você pode desejar indicar que uma determinada frase deve ser enfatizada, ou adicionada a um glossário, ou ser interligada a outra parte do documento. Você pode querer que os nomes dos arquivos sejam exibidos com uma fonte de estilo “typewriter” quando forem exibidos na tela, mas como “itálico ” quando impresso, ou qualquer outra opção dentre a infinidade de opções disponíveis para apresentação.

Esperava-se que a inteligência artificial (AI) torna-se isso fácil. O seu computador leria o documento e identificaria automaticamente as frases chave, nomes de arquivos, os campos que o leitor teria que preencher, e muito mais. Infelizmente, a vida real não evoluiu como esperado, e os nossos computadores necessitam de algum auxílio antes que eles possam processar significativamente nosso texto.

Mais precisamente, eles precisam de ajuda para identificar o que é o que. Vejamos o texto abaixo:

> Para remover o `/tmp/foo` utilize rm(1).

>     % rm /tmp/foo

Nele podemos facilmente visualizar quais partes são nomes de arquivos, quais são comandos que devem ser digitados, quais partes são referências às páginas de manual, etc. Mas o computador processando o documento não pode. Para isto nós precisamos utilizar uma marcação (`markup`).

A “marcação” é comumente utilizada para descrever a “adição de valor” ou o “aumento de custo”. O termo (term) faz exame de ambos os meios quando aplicados ao texto. A marcação é um texto adicional incluído no documento, e de alguma forma destacado do seu conteúdo, de modo que os programas que forem processá-lo possam ler as marcações e utilizá-las ao tomar decisões sobre o documento. Os editores podem ocultar a marcação do usuário, de forma que o usuário não se distraia com ele.

As informações extras armazenadas na marcação adicionam valor ao documento. Tipicamente a adição da marcação ao documento precisa ser realizada por uma pessoa — apesar de tudo, se os computadores pudessem reconhecer suficientemente bem o texto para adicionar as marcações, então não haveria necessidade de adicioná-las em primeiro lugar. Isto aumenta o custo (isto é, o esforço requerido) para criar o documento.

O exemplo acima foi na verdade escrito neste documento como se segue:

    <para>Para remover <filename>/tmp/foo</filename> utilize &man.rm.1;.</para>

    <screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>

Como você pode ver, a marcação está claramente separada do conteúdo.

Obviamente, se você estiver iniciando no uso de marcações, você precisa definir o que a sua marcação significa, e como ela será interpretada. Você vai precisar de uma linguagem de marcação a qual você possa seguir quando estiver marcando os seus documentos.

Naturalmente, uma linguagem de marcação pode não ser o bastante. Os requisitos de uma linguagem de marcação destinada formatação de documentos técnicos são diferentes dos requisitos de uma linguagem de marcação destinada a formatação de receitas culinárias. Esta, por sua vez, seria muito diferente de uma linguagem de marcação usada para formatar poemas. O que você realmente precisa é de uma linguagem primária, a qual você possa utilizar para escrever estas e outras linguagens de marcação. Uma meta linguagem de marcação.

É exatamente isso que a Standard Generalized Markup Language (SGML) é. Muitas linguagens de marcação foram escritas em SGML, incluindo as duas mais utilizadas pelo FDP, o HTML e o DocBook.

Cada definição de linguagem é mais corretamente chamada de Definição de Tipo de Documento (DTD). O DTD especifica o nome dos elementos que podem ser utilizados, em qual ordem eles aparecem (e se alguma marcação pode ser utilizada dentro de outra marcação) e as informações relacionadas. Um DTD é algumas vezes referenciado como uma aplicação do SGML.

Um DTD é uma especificação completa de todos os elementos que podem ser utilizados, da ordem em que podem aparecer, quais elementos são obrigatórios, quais são opcionais, e assim por diante. Isto torna possível escrever um interpretador (parser) SGML, que leia ambos os DTD e um documento que reividique se adequar ao DTD. O interpretador pode então confirmar se todos os elementos obrigatórios do DTD estão (ou não) presentes no documento na ordem correta, e se existem erros na marcação. Isto é normalmente referenciado como “validação do documento”.

> Nota: Este processamento simplesmente confirma se a escolha dos elementos, a sua ordenação, etc, estão de acordo com o especificado no DTD. Ele não verifica se você utilizou a marcação adequada para o conteúdo. Se você tentasse marcar todos os nomes de arquivo em seu documento como nomes de funções, o interpretador não iria apontar isto como um erro (assumindo, naturalmente, que a sua DTD define elementos para nomes de arquivos e para funções, e que eles podem ser utilizados nos mesmos lugares).

É provável que a maioria das suas contribuições ao projeto de documentação irão se constituir de conteúdos marcados tanto em HTML quanto em DocBook, em vez de alterações nos DTDs. Por esta razão este livro não irá abordar a criação de um DTD.

Anterior | Principal | Próxima
Ferramentas Opcionais |  | Elementos, tags, e atributos

Este, e outros documentos, podem ser obtidos em ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

Para perguntas sobre FreeBSD, leia a documentação antes de contatar <questions@FreeBSD.org>.
Para perguntas sobre esta documentação, envie e-mail para <doc@FreeBSD.org>.