DocBook

DocBook é uma linguagem de marcação semântica para documentação técnica. Foi originalmente criada para escrita de documentos técnicos da área de informática, mas pode ser usada para publicação de todo tipo de documentação.

Como uma linguagem semântica, DocBook permite separar a apresentação do conteúdo, permitindo criar documentos numa forma neutra que captura a estrutura lógica do conteúdo; esse conteúdo poderá ser publicado depois numa variedade de outros formatos, incluindo HTML, XHTML, EPUB, PDF, páginas man e Ajuda HTML, sem que seja necessário alterar o documento fonte.

Resumo

DocBook é uma linguagem XML. Na sua versão (5.0), a linguagem do DocBook é formalmente definida por um schema RELAX NG com regras Schematron integradas. (Há também versões W3C XML Schema+Schematron e Document Type Definition (DTD) do esquema disponível, mas não são considerados padrões.)

Como uma linguagem semântica, um documento escrito em DocBook não descreve como "ele será apresentado" mas sim "o significado" do conteúdo do documento. Por exemplo, ao invés de definir como o resumo de um livro deve ser exibido ou formatado, o DocBook diz apenas que uma seção particular do documento é o resumo; Uma aplicação de processamento de texto externa é que decide onde e como o resumo deve estar na publicação final, inclusive se será publicado.

O DocBook oferece uma vasto conjunto de marcadores de elementos semânticos divididos em três categorias: estrutural, nível de bloco e em linha.

Os marcadores Estruturais definem as características gerais do documento: o elemento book, por exemplo, especifica que seus elementos filhos representam partes de um livro: o título, capítulos, glossário, apêndices e etc. Os marcadores estruturais do DocBook incluem, entre outros, são:

• set: uma coleção de um ou mais livros. Um set<> poderá conter outros sets.
• book: uma coleção de capítulos, artigos, e/ou partes, com conteúdos opcionais: glossários, apêndices e outros.
• part: uma coleção de um ou mais capítulos. Uma parte pode englobar outras partes. Pode ter um texto introdutório especial.
• article: uma coleção titulada e não numerada de elementos de nível de bloco.
• chapter: uma coleção titulada e numerada de elementos de nível de bloco. DocBook não requer a numeração obrigatória dos capítulos; é compreensível que semanticamente o número do capítulo atual é o do capítulo anterior mais um.
• appendix: o texto contido representa um adendo/apêndice.
• dedication: o texto representa a dedicatória do documento.

Os elementos estruturais podem conter outros elementos estruturais. Os elementos estruturais são os elementos permitidos somente de nível superior em um documento DocBook.

Marcadores de nível de Bloco são elementos que descrevem parágrafos, listas e outros. Nem todos eles podem conter textos diretamente neles. elementos de nível de bloco sequenciais devem ser apresentados um após o outro. Esse "após", neste caso, pode ter significado variados dependendo da língua. Em muitas línguas ocidentais, "após" significa abaixo: parágrafos são impressos abaixo da página. Em outroas línguas, como o japonês, o texto é escrito em colunas, com parágrafos dispostas da direita para a esquerda. As semânticas do DocBook são inteiramente neutras às línguas humanas.

Marcadores de nível de linha são elementos que descrevem textos enfatizados, atalhos (hyperlink) e outros. Eles quebram o texto dentro de um elemento de nível de bloco. Estes elementos não quebram o texto quando inseridos em parágrafos, mas normalmente fazem o processador de texto aplicar algum tratamento tipográfico ao texto delimitado, ou trocando o tipo da fonte de texto, tamanho ou atributos similares. (A especificação DocBook cita que é esperado tratamento tipográfico diferenciado, sem explicitar este tratamento), por exemplo, o marcador emphasis não obriga o processador de texto a usar "negrito" no texto enfatizado.

Exemplo Simples

 <?xml version="1.0" encoding="UTF-8"?>
 <book xml:id="simple_book" xmlns="http://docbook.org/ns/docbook" version="5.0">
   <title>Exemplo Simples de um Livro</title>
   <chapter xml:id="cap001">
     <title>Capitulo 1</title>
     <para>Ola', mundo!</para>
     <para>Desejo-te um <emphasis>maravilhoso</emphasis> dia!</para>
   </chapter>
   <chapter xml:id="cap002">
     <title>Capitulo 2</title>
     <para>Ola', de novo!</para>
   </chapter>
 </book>

Semanticamente, este documento é um "livro" with a "título" que contém 2 "capítulos". Cada "capítulo" contem seu "título" e 1 "parágrafo".

Olhando com mais detalhes, o elemento raiz do documento é o book. Todos os elementos DocBook estão em uma Namespace XML, assim o elemento raiz possui um atributo xmlns para definir o namespace atual. Também, o elemento razi do documento DocBook precisa ter um atributo version que especifica a versão do formato que o documento foi gerado.

(Documentos XML podem incluir elementos de múltiplos namespaces. Por simplicidade, o exemplo não ilustra isso.)

Um elemento book precisa conter um elemento title, ou um elemento info contendo um title. Isto deve acontecer antes de aparecer os demais elementos estruturais filhos. Após o título, segue os elementos filhos, neste caso, 2 elementos chapter. Cada um precisa ter um elemento title. Eles contem elementos de nível de bloco para que contém texto simples e outros elementos em linha como emphasis no segundo parágrafo do primeiro capítulo.

Esquemas e Validação

Regras como aquelas citadas no item anterior ("um elemento book deve conter um elemento title, ou um elemento info contendo um elemento title," etc.) são formalmente definidos no esquema' DocBook. Ferramentas de programação específicas podem ser usada para validar um documento XML (DocBook ou outro), frente ao seu esquema correspondente, para determinar se (e onde) o documento falha na conformidade do esquema. Ferramentas de edição XML podem também usar informações do esquema para evitar a criação de documentos fora do padrão.

Edição no DocBook

Porque o DocBook é um texto XML, os documentos podem ser criados e editados em qualquer editor de texto. Qualquer editor XML é um editor DocBook funcional. Alguns editores gráficos, como o MS Word, vêm com a capacidade de editar arquivos DocBook.

Processamento do DocBook

Porque o DocBook é um formato XML, todo documentos DocBook poderá ser validado e processado usando qualquer ferramenta que inclua suporte ao XML.

Arquivos DocBook são usados para gerar saídas numa variedade de formatos. Quase sempre, eles vêm acompanhado de arquivos contendo folhas de estilo que transformam documentos DocBook em outros (HTML, XSL-FO, PDF, etc).

Porque as folhas de estilo XLS padrões do DocBook são bem-formadas, e o DocBook é um XML bem-formado, qualquer um pode escrever sua própria folha de estilo e usar um processador XLS para gerar sua própria saída alternativa.

História

O DocBook começou em 1991 como um projeto conjunto da HAL Computer Systems e O'Reilly & Associates e manteve sua própria equipe de mantenedores (the Davenport Group) até ser movido (1998) para o SGML Open consortium, que depois passou a se chamar OASIS. o Comitê Técnico do DocBook é quem mantem as especificações DocBook dentro da OASIS.

DocBook está disponível nos formatos SGML e XML, como uma DTD. Os formatos RELAX NG e W3C XML Schema da versão XML também estão disponíveis. A partir do DocBook 5, a versão RELAX NG é a forma "normativa" da qual os outros formatos são gerados.

DocBook inicialmente começou como uma aplicação SGML, mas uma aplicação XML equivalente foi desenvolvida veio a substituí-la.

O DocBook foi adotado pela comunidade de código aberto e se tornou padrão na criação de documentação para muitos projetos, incluindo FreeBSD, KDE, documentação GNOME, referências do API de GTK+, a documentação do Linux (núcleo)kernel Linux, e o trabalho do Projeto de Documentação Linux (LDP).

Norman Walsh e a equipe de desenvolvimento do projeto DocBook mantêm a aplicação-chave para produzir a saída de documentos fonte DocBook: um conjunto de folhas de estilo XSL (bem como um legado conjunto de folhas de estilo DSSSL) que pode gerar HTML de alta qualidade e arquivos (FO/PDF) de saída, assim como a saída em outros formatos, incluindo RTF , páginas man e HTML Help.

Walsh também é o autor principal do livro DocBook: The Definitive Guide, a documentação oficial do DocBook. Este livro está disponível on-line sob a GFDL, e também como uma publicação impressa.

Pré DocBook v5.0

A atual versão do DocBook, 5.0, é ainda muito recente. Como versões anteriores do DocBook ainda são muito usadas, esta seção oferece um resumo do que mudou no DocBook 5.0 em relação às versões 4.x e anteriores.

Até o lançamento do DocBook 5, o DocBook era definido por um documento DTD. Como o DocBook foi construído originariamente como uma aplicação da SGML, o DTD foi a única linguagem de esquema disponível. Os formatos do DocBook 4.x podem ser o SGML ou XML, mas a versão XML não possui seu próprio espaço de nomes XML.

Como uma conseqüência da definição de um DTD, os formatos do DocBook 4.x sofreram restrições de quem é definida por um DTD. O mais importante para o idioma é que um nome de elemento define exclusivamente o seu conteúdo possível. Ou seja, um elemento nomeado inf deve conter as mesmas informações não importa onde ele é declarado no arquivo DocBook. Como tal, há muitos tipos de elementos info no DocBook 4.x: bookinfo, chapterinfo, etc. Cada um possui um teor de modelo diferente, mas eles compartilham alguns de seus modelos de conteúdo. Além disso, eles repetem a informação de contexto. O elemento info do book, por ser um filho direto do livro, ele não precisa ser nomeado especialmente para um leitor humano. No entanto, porque o formato foi definido por um DTD, ele teve que ser chamado como tal.

O elemento raiz não precisa ter uma version, pois a versão está embutida na declaração DTD no topo do documento pre-DocBook 5.

Os documentos DocBook 4.x não são compatíveis com o DocBook 5, mas podem ser convertidos através de uma folha de estilo XSLT que vem no pacote da distribuição DocBook 5.

DocBook Simplificado

O DocBook oferece um grande número de características que podem ser trazer confusão para o novo usuário. Para aqueles que querem aprender o básico do DocBook sem grande esforço foi disponibilizado o DockBook Simplificado. Ele é uma pequena parte do DocBook desenvolvida para pequenos documentos como artigos ou pequenos livros. O DTD do DocBook Simplificado está ainda na versão 1.1.

Ver também

• Lista de linguagens de marcação para documentos
• Comparação entre linguagens de marcação para documentos
• DocBook XSL - um grupo de folhas de estilo XSLT para transformação de DocBook em vários formatos de exibição.

Ligações externas

• DocBook.org - Coleção de informações sobre DocBook, incluindo versão 4.x e 5.0 do DocBook: The Definitive Guide e todas as versões dos schemas/DTDs DocBook.
• DocBook Repository at OASIS - Sítio normativo para o schema/DTD DocBook.
• Página do projeto DocBook XSL em SourceForge.net
• DocBook Demystification HOWTO
• DocBook: The Definitive Guide, 1st edition, v. 2.0.6 - Versão em PDF (com bookmarks) do Guide for DocBook 3.x and 4.x.