Docbook - Telbit

Docbook
Telbit
Aveiro
4 de Abril de 2006
Tópicos
Introdução
Elementos DocBook e exemplos
Transformações DocBook
Personalização das transformações
Software de desenvolvimento DocBook
JavaHelp
Futuro do DocBook
Introdução
O formato Docbook foi desenvolvido pelo consórcio
OASIS especificamente para documentação técnica
É uma linguagem XML
Especificado em SGML, XML DTD e Relax NG (versão
5.0)
DocBook não é uma linguagem de apresentação
Docbook é bastante extensivo
As tags DocBook são longas e intuitivas
Ferramentas DocBook
Conjuntos de ficheiros XSL
Conversão para outros formatos
Formatos incluídos:
Eclipse – plugins e standalone infocenter content
XSL-FO
HTML
Microsoft HTML Help
JavaHelp
TeX e LaTeX
UNIX man pages
Processadores XSLT
Saxon
Escrito em JAVA
Versão 6 (XSLT 1.0) e versão 8 (XSLT 2.0)
Xalan
Escrito em C++ e JAVA
Xsltproc
Escrito em C
É considerado o processador mais rápido
XSL-FO
Mistura de do ficheiro XML original com tags XSL-FO de
formatação
Gera ficheiros PDF ou PostScript
Processadores XSL-FO
E3 (Livre)
FOP (Livre)
PassiveTex (Livre)
XEP (Comercial)
Xinc (Comercial)
XML2PDF (Comercial)
Elementos principais
book - livro
article - artigo
refentry – equivalente às man pages
chapter – capítulo de um livro ou artigo
sect1 ... sect5 – secções ou subsecções de um capítulo
title – título
para - parágrafo
Estrutura
Book:
●
book
meta information
chapter
sect1
sect2
sect1
chapter
sect1
appendix
sect1
appendix
sect1
...
glossary
Article:
●
article
meta information
sect1
sect1
sect2
sect1
...
Primeiro Exemplo
Utilização de entidades
Reutilização de texto
Declaração
– Utilização
Utilização de entidades
Junção de diversos ficheiros
Elementos – Meta Informação
bookinfo – meta informação de um book
title – texto de um título
authorgroup – informação sobre os autores
author – informação sobre um autor
authorinitials – iniciais de um autor
firstname – primeiro nome
othername – outro nome
surname – nome de família
Elementos – Meta Informação (2)
keywordset – conjunto de termos que descrevem o
conteúdo de um documento
keyword - termo que descreve o conteúdo de um
documento
releaseInfo – informação sobre um versão do documento
revhistory – histórico das revisões
revision – nodo filho de revhistory, que descreve uma
revisão efectuada
revnumber – número da revisão
revremark – descrição da revisão
abstract – sumário do documento
date – data da publicação ou revisão do documento
Exemplo – meta informação
Elementos - Listas
simplelist – lista de palavras ou pequenas frases
member – membro de uma simplelist
itemizedlist – lista na qual cada elemento tem uma marcação
orderedlist – lista na qual cada elemento é numerado
sequencialmente
listitem – membro de uma orderedlist ou itemizedlist (elemento
composto)
variablelist – lista na qual cada entrada é composta por um
conjunto de um ou mais termos com listitem's associadas
varlistentry – entrada de uma variablelist
term – termo de uma varlistentry
segmentedlist – lista de conjuntos de informação
(título,descrição)
Elementos – Listas (2)
segtitle – título de uma segmentedlist
seglistitem – descrições de uma segmentedlist
seg – elemento de uma seglistitem
qandaset – conjunto de perguntas-respostas
qandaentry – entrada pergunta-resposta de uma quandset
question – questão de uma quadentry
answer – resposta de uma quadentry
procedure – lista para descrever um procedimento passo-apasso
step – passo de um procedimento (elemento composto)
substeps – sub-passo de um procedimento (elemento
composto)
Exemplos - Listas
●
itemizedlist
Apples - my favorite fruit.
Oranges - yummy, but sticky.
Bananas - they ripen too quickly!
Grapefruit - great when eaten in halves.
Black Beans - go well with rice
Exemplos – Listas (2)
Black Beans
My favorite black bean recipe is black bean soup, but they also go well with
rice.
Apples
Bananas
You can eat them straight, but they also go well in salads and in desserts.
Exemplos – Listas (3)
●
segmentedlist
Name: Tux
Occupation: Linux mascot
Favorite Food: Herring
Name: Konqui
Occupation: The KDE Dragon
Favorite Food: Gnomes
Exemplos – Listas (4)
●
quandset
1. What are little boys made of?
Snips and snails and puppy dog tails.
2. What are little girls made of?
Sugar and spice and everything nice.
Elementos - tabelas
table – tabela
Informaltable – tabela sem nome
thead – primeira linha da tabela
tfoot – última linha da tabela
tgroup – elemento pai de uma tabela ou de grande
parte de tabela com informação de formatação
tbody – elemento pai das linhas de uma tabela
row – linha num tbody, thead, or tfoot
entry – célula de uma tabela
entrytbl – subtabela (utilizada em vez de entry)
Exemplo - tabelas
Exemplo – tabelas (2)
Elementos - Gráficos
screeninfo – informação acerca do screenshot
screenshot – screenshot
mediaobject – imagem, som, texto, ... (não
renderizado separado do bloco)
inlinemediaobject - imagem, som, texto, ...
(não renderizado dentro do bloco)
imagedata – aponta para uma imagem externa
Exemplo – Gráficos
Screenshot no Centaur
Elementos - Links
anchor – âncora no texto
email – endereço de email
link – link para uma âncora no texto
ulink – link para um endereço URL
●
Exemplo
Elementos – interface
example – exemplo de um programa ou de informação
relacionada
informalexample – exemplo sem título
programlisting – listagem de texto fonte de um programa
screen – texto que o utilizador espera ver no ecrã
KeyCap – texto escrito na tecla física
KeyCode – designação numérica computacional de uma tecla
KeyCombo – combinação de teclas
MenuChoice – escolha ou conjuntos de escolhas sobre menus
Elementos – interface (2)
MouseButton – tecla do rato
Interface – elemento do interface gráfico
GUIButton -texto de um botão do interface gráfico
GUIIcon – texto ou gráfico de um ícone do interface gráfico
GUILabel – texto no interface gráfico
GUIMenu – nome de um menu no interface gráfico
GUIMenuItem – nome de um menu terminal no interface gráfico
GUISubmenu - nome de um sunmenu no interface gráfico
Action – acção desencadeada por uma interacção do utilizador
Exemplos - interface
●
Variablelist com especificação dos menus
●
Poderia se transformar...
Transformação de documentos
Utilizando o Saxon
Sintaxe geral:
java -jar saxon.jar \
options \
xml-document \
stylesheet-path \
param=value
Exemplo HTML:
java -jar saxon.jar -o myfile.html myfile.xml \
../docbook-xsl/html/docbook.xsl use.extensions=1
FO example:
java -jar saxon.jar -o myfile.html myfile.xml \
../docbook-xsl/fo/docbook.xsl use.extensions=1
Transformação de documentos
De XSL-FO para PDF (utilizando o FO)
fop.bat -fo myfile.fo -pdf myfile.pdf
De XSL-FO para PS (utilizando o FO
fop.bat -fo myfile.fo -ps myfile.ps
Personalizar as transformações
Passando parametros às stylesheets
Adicionando mais uma camada de stylesheets
Substituição de XSL templates da colecção disponível
Parâmetros nas transformações
É possível passar parâmetros às stylesheets para
personalizar o resultado
Existem dezenas de parâmetros
Fácil utilização
Linha de comandos ou ficheiro
Optimizações específicas para cada processador
Pode não existir parâmetro para a modificação
pretendida
Exemplos
Linha de comandos
java -jar saxon.jar -o myfile.html myfile.xml docbook.xsl \
html.stylesheet="corpstyle.css" \
admon.graphics=1
Ficheiro (em vez da stylesheet original)
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:import href="path/docbook.xsl"/>
<xsl:param name="html.stylesheet" select="'corpstyle.css'"/>
<xsl:param name="admon.graphics" select="1"/>
</xsl:stylesheet>
Parâmetros HTML
Directório destino dos ficheiros
Encoding dos ficheiros
Utilização do atributo id para o nome dos ficheiros
Atribuição de uma CSS
Controlo da numeração dos capítulos e secções
Utilização de icons para algumas tags
Formato das datas e horas
Parâmetros PDF
Personalização da página (tamanho, layout, margens,
identação do texto, impressão nas duas páginas,
espaçamento entre linhas, ...)
Tamanho e tipos de letra (texto e cabeçalhos)
Controlo da numeração dos capítulos e secções
PDF Bookmarks
Utilização de icons para algumas tags
Processamento de apenas parte do documento
Adicionar stylesheets
Stylesheet que é aplicada ao resultado das stylesheets
DocBook
Não altera as stylesheets DocBook originais
Independente de futuras versões do DocBook
Fácil distribuição
Fácil resolução de problemas
Software – XMLMind XML Editor
Suporta DTD, W3C XML Schema, RELAX NG schemas,
XML namespace, XSLT, XPath, XInclude, XML catalog
Vista tipo processador de texto
Objectos do tipo lista, tabelas, check boxes, etc podem
ser embebidas na vista tipo processador de texto
Processador XSLT embutido
Processador FO disponível com plug-in
Suporte nativo para documentos DocBook
Multi-plataforma
Software – XMLMind XML Editor (2)
Software – XMLMind XML Editor (3)
JavaHelp
Extensão ao ambiente de programação JAVA
Desenvolvido pela Sun
Componentes JavaHelp:
Páginas HTML
Ficheiro HelpSet (.hs)
Ficheiro de mapeamento JavaHelp
Ficheiro TOC de JavaHelp
Todos os ficheiros são gerados automaticamente pelo
DocBook
JavaHelp - Componentes
HelpSet
Informação acerca do JavaHelp
Ficheiro que é carregado no arranque
Ficheiro de mapeamento
Mapeia as classes JAVA como o ficheiro de ajudo apropriado
Ficheiro TOC
TOC (Table of contents) do sistema de ajuda
JavaHelp – código JAVA
●
Inicialização
private HelpSet hs = null;
private HelpBroker hb = null;
...
public synchronized HelpSet getHelpSet(){
if (hs == null) {
String helpHS = "jhelpset.hs";
ClassLoader cl = FmsApp.class.getClassLoader();
try {
URL hsURL = HelpSet.findHelpSet(cl,helpHS);
hs = new HelpSet(null,hsURL);
} catch (HelpSetException e) {
MsgManager.warn(logger, languageBundle.getString("L_FmsAppHelpSetError"));
com.telbit.util.MsgManager.error(logger, e, null);
}
}
return hs;
}
JavaHelp – código JAVA (2)
●
Indicação da secção a carregar
public synchronized HelpBroker setHelp(JComponent comp, String id){
HelpBroker hb = getHelpBroker();
if (hb != null) {
hb.enableHelpKey(comp.getRootPane(),id,hs);
}
return hb;
}
...
FmsApp.getInstance().setHelp(getRootPane(), "sct_GuiAdmGestProc");
Futuro
Versão 5.0:
Introdução de um Namespace em todos os elementos
Utilização de Relax NG
Linguagem bastante poderosa de especificação de documentos XML
É a mais completa
Um documento validado pelo DTD pode não ser pelo Relax NG
Revisão de algumas elementos (redução do número de
elementos)
Stylesheets baseadas no XSLT 2.0
Fim
Questões