Capítulo 7. Primer XML

Índice
7.1. Visão Geral
7.2. Elementos, Tags e Atributos
7.3. A Declaração DOCTYPE
7.4. De Volta para o XML
7.5. Comentários
7.6. Entidades
7.7. Usando Entidades para Incluir Arquivos
7.8. Seções Marcadas
7.9. Conclusão

A maioria das documentações do FDP é escrita com linguagens markup baseadas em XML. Este capítulo explica o que isso significa, como ler e entender os arquivos fontes da documentação e as técnicas de XML utilizadas.

Partes desta seção foram inspiradas por Mark Galassi's Get Going With DocBook.

7.1. Visão Geral

Nos primórdios da era computacional, o texto eletrônico era simples. Havia poucos conjuntos de caracteres como ASCII ou EBCDIC, e apenas isso. Texto era texto, e o que você lia era realmente o texto que você tinha. Sem frescuras, sem formatação, sem inteligência.

Inevitavelmente, isso não era suficiente. Quando o texto está em um formato utilizável por computadores, espera-se que eles possam usá-lo e manipulá-lo de maneira inteligente. Os autores querem indicar que certas frases devem ser enfatizadas, adicionadas a um glossário ou transformadas em hiperlinks. Os nomes dos arquivos podem ser apresentados em uma fonte de estilo typewriter para exibição na tela do computador, ou como itálico quando impressos, ou qualquer outra opção dentre uma infinidade de opções para apresentação.

Esperava-se que a Inteligência Artificial (IA) facilitasse isso. O computador leria o documento e identificaria automaticamente frases-chave, nomes de arquivos, textos que o leitor deveria digitar, exemplos e outros tipos. Infelizmente, na vida real não foi dessa forma, e os computadores ainda precisam de assistência antes que possam processar o texto de maneira significativa.

Mais precisamente, eles precisam de ajuda para identificar o que é o quê. Considere este texto:

Para remover /tmp/foo, use rm(1).

% rm /tmp/foo

É fácil identificar quais partes são nomes de arquivos, quais são comandos a serem digitados, quais partes são referências a páginas de manual e assim por diante. Mas o computador que processa o documento não consegue. Para isso, precisamos utilizar markup.

Markup é geralmate utilizado assim adicionando valor ou aumentando o custo. O termo tem seus significados realçados quando aplicado ao texto. Markup é um texto adicional incluído no documento, diferenciado de alguma forma do conteúdo do documento, para que os programas que processam o documento possam ler a marcação e utiliza-la ao tomar decisões sobre o documento. Os editores podem ocultar o markup do usuário, para que este não se distraia com ela.

A informação extras armazenada no markup adiciona valor ao documento. Adicionar markup ao documento normalmente deve ser feito por uma pessoa - afinal, se os computadores pudessem reconhecer o texto suficientemente bem para adicionar a markup, não haveria necessidade de utilizar markup. Isto aumenta o custo (o esforço necessário) para criar algum documento.

O exemplo anterior é representado neste documento da seguinte forma:

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

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

O markup é claramente separado do conteúdo.

As linguagens markup definem o que as marcações significam e como elas devem ser interpretadas.

Claro, uma linguagem markup pode não ser suficiente. Uma linguagem markup para documentação técnica tem requisitos muito diferentes de uma linguagem markup destinada a receitas de culinária. Isso, por sua vez, seria muito diferente de uma linguagem markup utilizada para descrever uma poesia. O que é realmente necessário é uma primeira linguagem utilizada para escrever essas outras linguagens markup. Uma meta linguagem markup.

É exatamente isso que a eXtensible Markup Language (XML) é. Muitas linguagens markup foram escritas em XML, incluindo as duas mais utilizadas pelo FDP, XHTML e DocBook.

Cada definição de idioma é mais apropriadamente chamada de gramática, vocabulário, esquema ou Definição de Tipo de Documento (DTD). Existem vários idiomas para especificar uma gramática XML ou um schema.

Um schema é uma especificação completa de todos os elementos que podem ser utilizados, a ordem em que devem aparecer, quais elementos são obrigatórios, quais são opcionais e assim por diante. Isso torna possível escrever um XML parser que lê tanto o schema quanto um documento que afirma estar em conformidade com o schema. O parser pode confirmar se todos os elementos exigidos pelo vocabulário estão ou não na ordem correta do documento ou se há algum erro no markup. Isto é normalmente conhecido como a valiidação do documento.

Nota:

A validação confirma se a escolha dos elementos, sua ordenação e assim por diante estão em conformidade com os listados na gramática. Ela não valida se o markup correto foi utilizado no conteúdo. Se todos os nomes de arquivo em um documento fossem marcados como sendo nomes de função, o analisador não sinalizaria isso como um erro (supondo, é claro, que o schema define elementos para nomes de arquivos e funções e que eles possam aparecer no mesmo local).

A maioria das contribuições no Projeto de Documentação utilizará markup XHTML ou DocBook, em vez de alterações nos schemas. Por esse motivo, este livro não abordará como escrever um vocabulário.

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.