O DocBook foi originalmente desenvolvido por HaL Computer Systems e O'Reilly & Associates como um DTD para escrever documentação técnica [3]. E desde 1998 tem sido mantido pelo DocBook Technical Committee. Desta forma, ao contrário do LinuxDoc e do HTML, o DocBook é fortemente orientado a marcação que descreve o que é alguma coisa, ao invés de descrever como ela deve ser apresentada.
Alguns elementos podem existir em duas formas, formal e informal. Tipicamente, a versão formal dos elementos consistirá de um título seguido da versão informal do elemento. A versão informal não terá um título.
O DocBook DTD está disponível na
coleção de ports como
textproc/docbook
.
Ele é automaticamente instalado como parte do port
textproc/docproj
.
O Projeto de Documentação do FreeBSD ampliou o DocBook DTD adicionando alguns elementos novos. Estes elementos têm como objetivo tornar algumas marcações mais precisas.
Os elementos específicos introduzidos pelo FreeBSD estarão claramente destacados quando forem listados abaixo.
No restante deste documento, o termo “DocBook” deve ser interpretado como sendo a versão do DocBook DTD ampliado pelo projeto de documentação do FreeBSD.
Não existe nada nestas extenssões
que seja específico ao FreeBSD, apenas percebemos
que elas seriam melhorias para este projeto em particular.
Se alguém dos demais projetos *nix (NetBSD, OpenBSD,
Linux, ...) tiver interesse em colaborar para a
criação de um conjunto de extensões
DocBook padrão, por favor entre em
contato com Equipe de Engenharia de Documentação
<doceng@FreeBSD.org>
.
As extensões FreeBSD não estão (atualmente) na coleção de ports. Elas estão armazenadas na árvore Subversion do FreeBSD, como head/share/xml/freebsd.dtd.
De acordo com as diretrizes DocBook para a escrita de IPF's para adaptação do DocBook, o IPF para o DocBook estendido do FreeBSD é:
DocBook permite que você estruture sua documentação de várias maneiras. No projeto de documentação do FreeBSD nós estamos utilizando dois tipos primários de documentos DocBook: o livro e o artigo.
Um livro é organizado em
chapter
s (capítulos). Isso é um
requerimento obrigatório. Podem existir
part
s (partes) entre o livro e os
capítulos para fornecer mais uma camada de
organização. O Handbook, por exemplo,
é organizado desta maneira.
Um capítulo pode (ou não) conter uma ou mais
sessões. Estas são indicadas pelo elemento
sect1
. Se uma sessão
contém outra sessão, então use o
elemento sect2
, e assim por diante
até sect5
.
Capítulos e sessões contém o restante do conteúdo.
Um artigo é mais simples do que um livro, e
não usa capítulos. Ao invés disso, o
conteúdo de um artigo é organizado em uma ou
mais sessões, usando os mesmos elementos
sect1
(e sect2
e assim por
diante) que são usados nos livros.
Obviamente, você deve considerar a natureza da documentação que você esta escrevendo para poder decidir se é melhor uma marcação formatada como um livro ou um artigo. Artigos suportam bem informações que não precisam ser divididas em capítulos, isto é, relativamente pequena, com mais ou menos 20 a 25 páginas de conteúdo. Livros suportam melhor informações que se dividem em capítulos com apêndices e conteúdos similares.
Os tutoriais sobre FreeBSD estão marcados na forma de artigos, enquanto por exemplo este documento, o FAQ do FreeBSD, e o Handbook do FreeBSD estão marcados na forma como livros.
O conteúdo de um livro deve estar contido
dentro do elemento book
. Assim como
outros elementos de marcação estrutural, esse
elemento pode conter elementos que incluam
informações adicionais sobre o livro. Isto
é tanto meta-informação, utilizada para
fins de referência, ou conteúdo adicional
usado para produzir uma página de
título.
Estas informações adicionais devem estar
contidas dentro do elemento bookinfo
.
book
com
bookinfo
Seu título aqui
</title>
<author>
<firstname>Seu primeiro nome aqui
</firstname>
<surname>Seu sobrenome
</surname>
<affiliation>
<address><email>Seu endereço de correio eletrônico aqui
</email></address>
</affiliation>
</author>
<copyright>
<year>1998
</year>
<holder role="mailto:seu endereço de email
">Seu nome
</holder>
</copyright>
<releaseinfo>$FreeBSD$</releaseinfo>
<abstract>
<para>Inclua um resumo do conteúdo do seu livro aqui.
</para>
</abstract>
</bookinfo>
…
</book>O conteúdo do artigo deve estar contido dentro
do elemento article
. Assim como
outros elementos de marcação estrutural,
esse elemento pode conter elementos que incluam
informações adicionais sobre o artigo.
Isto é tanto meta-informação,
utilizada para fins de referência, ou conteúdo
adicional usado para produzir uma página de
título.
Estas informações adicionais devem estar
contidas dentro do elemento
articleinfo
.
article
com
articleinfo
Seu título aqui
</title>
<author>
<firstname>Seu primeiro nome
</firstname>
<surname>Seu sobrenome
</surname>
<affiliation>
<address><email>Seu endereço de email
</email></address>
</affiliation>
</author>
<copyright>
<year>1998
</year>
<holder role="mailto:seu endereço de email
">Seu nome
</holder>
</copyright>
<releaseinfo>$FreeBSD$</releaseinfo>
<abstract>
<para>Inclua um resumo do conteúdo do artigo aqui.
</para>
</abstract>
</articleinfo>
…
</article>Utilize chapter
para marcar seus
capítulos. Cada capítulo tem
obrigatoriamente um title
.
Artigos não contêm capítulos, estes
são reservados para os livros.
Um capítulo não pode ser vazio; ele
precisa conter elementos além do
title
. Se você precisar incluir
um capítulo vazio então você
precisará incluir um parágrafo vazio.
Em um livro, os capítulos podem (mas não
é obrigatoriamente necessário) ser
quebrados em seções, subseções,
e assim por diante. Em um artigo, as seções
são os principais elementos estruturais, e cada artigo
deve conter pelo menos uma seção. Utilize o
elemento sect
. O
n
n
indica o número da
seção o qual identifica o nível da
seção.
A primeira
sect
é
n
sect1
. Você pode ter uma ou mais
desta em um só capítulo. Elas podem conter
um ou mais elementos sect2
, e assim por
diante, até sect5
.
Este exemplo inclui os números das seções nos títulos de seções. Você não deve fazer isso nos seus documentos. A inserção dos números de seção é realizada pelas folhas de estilo (falaremos delas mais a frente), e você não precisa gerenciá-los manualmente.
Você pode introduzir outra camada de
organização entre book
e
chapter
utilizando uma ou mais
part
s. Isto não pode ser
feito em um article
.
O DocBook suporta três tipos de parágrafos:
formalpara
, para
, e
simpara
.
Na maioria das vezes você só vai precisar
usar para
. O
formalpara
inclui um elemento
title
, e o simpara
desabilita alguns elementos dentro de
para
. Fique com o
para
.
para
Uso:
Aparência:
Isso é um parágrafo. E pode conter quase qualquer outro elemento.
Um bloco de citação é uma longa citação de outro documento que não deveria aparecer no parágrafo atual. Você não irá usá-lo com muita frequência.
Um bloco de citação pode conter opcionalmente um título e uma atribuição (ou eles podem ser deixados sem título e sem atributos)
blockquote
Uso:
Aparência:
Um pequeno pedaço da Constituição dos Estados Unidos
Preâmbulo da constituição dos Estados Unidos. Nós, povo dos Estados Unidos, com o objetivo de fazer uma união mais perfeita, estabelecer justiça, garantir tranquilidade doméstica, promover uma defesa comum, promover bem estar geral, assegurar as benções da liberdade para nós mesmos e nossa posteridade, organizamos e estabelecemos essa constituição para os estados Unidos da América. | ||
--Copiado de um site qualquer |
Talvez você precise incluir informações extras separadas do corpo principal do texto. Tipicamente isto é “meta” informação que o usuário deve tomar conhecimento.
Dependendo da natureza da informação,
devemos utilizar o elemento tip
,
note
, warning
,
caution
, ou important
.
Alternativamente, se a informação é
relacionada ao corpo principal do texto e não se
encaixa em nenhum dos objetos acima, utilize
sidebar
.
As circunstâncias na qual se deve escolher um elemento ao invés do outro não é clara. A documentação do DocBook sugere que:
A note
é uma
informação que deve ser lida por todos
os leitores.
A important
é uma
variação do note
.
A caution
é usada para
informar sobre uma possível perda de dados ou
possível dano causado pelo software.
O warning
é usado para
informações sobre possíveis danos
ao hardware, sobre risco de vida ou de ferimento a um
membro.
warning
Uso:
Aparência:
Instalar o FreeBSD talvez faça com que você queira desinstalar o Windows do seu Hard disk.
Você frequentemente vai precisar listar fragmentos de informação para o usuário, ou apresentar para eles um passo a passo o qual eles devem seguir para alcançar um objetivo específico.
Para fazer isso, utilize
itemizedlist
,
orderedlist
, ou
procedure
[4].
Os elementos itemizedlist
e
orderedlist
são similares aos
seus equivalentes em HTML, ul
e
ol
. Cada um consiste de um ou mais
elementos listitem
, e cada
listitem
contém um ou mais
elementos de bloco. O elemento listitem
é analogo à li
do HTML.
Entretanto, ao contrário do que ocorre no HTML, aqui
elas são obrigatórias.
O elemento procedure
é
ligeiramente diferente. Ele consiste de
step
s, que por sua vez consistem de
mais step
s ou
substep
s. Cada step
contém elementos de bloco.
itemizedlist
,
orderedlist
, e
procedure
Uso:
Aparência:
Esse é o primeiro item enumerado.
Esse é o segundo item enumerado.
Esse é o primeiro item ordenado.
Esse é o segundo item ordenado.
Faça isto.
Depois faça isto.
E agora faça isto.
Se você quiser mostrar um trecho de um
arquivo (ou talvez um arquivo inteiro) ao usuário,
use o elemento programlisting
Espaços e quebras de linha
são importantes dentro do
programlisting
. Em particular, isso
significa que a tag de abertura deve aparecer na mesma
linha que a primeira linha do programa, e a tag de
fechamento deve estar na última linha do programa,
do contrário linhas em branco espúrias podem ser
incluídas.
programlisting
Uso:
Note como os colchetes na linha
#include
precisaram ser referenciados
através de suas entidades ao invés de
incluídas literalmente.
Aparência:
Quando você tiver terminado, seu programa deve estar assim;
Uma chamada é um mecanismo para fazer referência a um pedaço de texto ou uma posição específica de um exemplo anterior sem ligar a ele no texto.
Para fazer isso, marque as áreas de interesse
no seu exemplo (programlisting
,
literallayout
, ou o que for) com o
elemento co
. Cada elemento deve ter
um id
único atribuído a ele.
Insira um calloutlist
no final do
exemplo acima fazendo referência de volta a ele,
exibindo comentários adicionais.
co
e
calloutlist
Aparência:
Quando você tiver terminado, seu programa deve estar assim;
Ao contrário do HTML, você não precisa usar tabelas para acertar o layout, as folhas de estilo cuidam disto para você. Utilize tabelas apenas para marcação de dados tabulares.
De maneira geral (veja a documentação
do DocBook para mais detalhes) uma tabela (que pode ser
formal ou informal) consiste de um elemento
table
. O qual contém ao menos um
elemento tgroup
, que especifica (como
um atributo) o número de colunas neste grupo da
tabela. Dentro do grupo tabela você pode ter um elemento
thead
, que contém os elementos
para o cabeçalho da tabela (cabeçalho da
coluna), e um tbody
que contém
o corpo da tabela.
Tanto o tgroup
quanto o
thead
contém elementos
row
, que por sua vez contém
elementos entry
. Cada elemento
entry
especifica uma célula da
tabela.
informaltable
Uso:
Aparência:
Este é o cabeçalho da coluna 1 | Este é o cabeçalho da coluna 2 |
---|---|
Linha 1, coluna 1 | Linha 1, coluna 2 |
Linha 2, coluna 1 | Linha 2, coluna 2 |
Sempre utilize o atributo pgwide
com o valor 1
junto ao elemento
informaltable
. Um bug no Internet
Explorer pode fazer com que a tabela renderize de forma
incorreta se ele for omitido.
Se você não quiser borda na tabela
adicione o atributo frame
ao elemento
informaltable
com o valor
none
(i.e., <informaltable
frame="none">
).
frame="none"
Aparência:
Este é o cabeçalho da coluna 1 | Este é o cabeçalho da coluna 2 |
---|---|
Linha 1, coluna 1 | Linha 1, coluna 2 |
Linha 2, coluna 1 | Linha 2, coluna 2 |
Muitas vezes você irá precisar mostrar exemplos para que o usuário siga. Normalmente, isso irá consistir de diálogos com o computador, nos quais o usuário digita um comando, e obtém uma resposta de volta, ele digita outro comando e recebe outra reposta, e assim por diante.
Vários elementos e entidades podem ser utilizados nestes casos.
screen
Tudo que o usuário visualizar neste exemplo
estará na tela do computador, assim o
próximo elemento é
screen
.
Dentro da marcação do
screen
, espaços em branco
são significativos.
prompt
,
&prompt.root;
e
&prompt.user;
Algumas das coisas que o usuário
irá visualizar na tela
são prompts do computador (seja do
sistema operacional, da linha de comando shell ou
de uma aplicação). Estes prompts devem
ser marcados usando prompt
.
Por serem especiais, os prompts de shell do
usuário normal e do usuário root
estão disponíveis como uma entidade.
Sempre que quiser indicar que o usuário
está em um prompt do shell, use
&prompt.root;
para o
usuário root e
&prompt.user;
para o
usuário normal, conforme for necessário.
Estas entidades não precisam estar dentro de
um prompt
.
&prompt.root;
e
&prompt.user;
são
extensões do FreeBSD ao DocBook, e
não são parte do DTD original.
userinput
Quanto estiver mostrando um texto que o
usuário deva digitar, envolva-o com as tags
userinput
. Ele provavelmente
será mostrado diferente para o
usuário.
screen
, prompt
, e
userinput
Uso:
Aparência:
%
ls -1
foo1
foo2
foo3
%
ls -1 | grep foo2
foo2
%
su
Password:
#
cat foo2
This is the file called 'foo2'Ainda que estejamos mostrando o conteúdo do
arquivo foo2
, ele
não está marcado como
programlisting
. Deixe o
programlisting
para mostrar fragmentos
de arquivos fora do contexto de ação do
usuário.
Quando você quiser enfatizar uma palavra ou frase
em particular, use emphasis
. Ela pode
ser apresentada em itálico, ou negrito, ou pode ser
falada diferentemente com um sistema texto-para-fala.
Não há uma maneira de mudar a
apresentação da ênfase no seu documento,
não existe um equivalente ao b
e
ao i
do HTML. Se a
informação que você está
apresentando é importante então considere
usar important
ao invés de
emphasis
.
emphasis
Uso:
Aparência:
O FreeBSD é sem dúvida o melhor sistema operacional tipo Unix para a arquitetura Intel.
Para citar um texto de outro documento ou fonte, ou para
denotar uma frase que está sendo usada figuradamente, use
quote
. Dentro da tag
quote
, você pode usar a maioria
das marcações disponíveis para um texto
normal.
Uso:
Aparência:
Entretanto, certifique-se que a busca não vá além do “limite entre a administração local e pública” como diz o RFC 1535.
Para se referir a uma tecla específica do
teclado, use keycap
. Para se referir
a um botão do mouse, use
mousebutton
. E para se referir a
combinação de digitar uma tecla e um clique do
mouse, envolva-os com keycombo
.
O keycombo
tem um atributo chamado
action
, que pode ser
click
, double-click
,
other
, press
,
seq
, ou simul
. Os
dois últimos dizem se teclas ou botões devem
ser pressionados em sequência ou simultaneamente.
As folhas de estilo colocam automaticamente o
símbolo de ligação, tal como
+
, entre os nomes das teclas, quando
elas estiverem envolvidas com
keycombo
.
Uso:
Aparência:
Para mudar para o segundo terminal virtual, digite Alt+F1.
Sair do vi
sem salvar o seu
trabalho, digite Esc : q !.
Meu gerenciador de janela é configurado de forma que Alt+ do mouse é usado para mover as janelas.
Frequentemente você irá fazer referência tanto a aplicações quanto a comandos quando estiver escrevendo a documentação. A distinção entre eles é simples: uma aplicação é o nome de um pacote de programas (ou possivelmente apenas um) que executa uma tarefa em particular. Um comando é o nome de um programa que o usuário pode executar.
Além disso, você eventualmente precisará listar uma ou mais opções que um comando pode aceitar.
Finalmente, você irá querer listar um comando com o número da sua seção no manual, na forma “comando(número)” que é tão comum nos manuais de Unix.
Você deve marcar o nome de uma
aplicação com application
.
Quando você quiser listar um comando com o
número da sua seção no manual (o que
deve acontecer na maioria das vezes) o elemento do DocBook
que deve ser utilizado é o
citerefentry
. Ele irá ter mais
dois elementos, refentrytitle
e
manvolnum
. O conteúdo de
refentrytitle
é o nome do comando,
e o conteúdo de manvolnum
é
a seção da página do manual.
Pode ser trabalhoso escrever desta forma, para
facilitar este processo foram criadas uma série de
entidades
gerais. Cada entidade está na
forma &man.
.manual-page
.manual-section
;
O arquivo que contém estas entidades
é o doc/share/xml/man-refs.ent
,
o qual pode ser referenciado utilizando o seguinte FPI:
Portanto, a introdução à sua documentação provavelmente será assim:
Use o elemento command
quando quiser
incluir um comando “in-line” para ser
apresentado como algo que deveria ser digitado pelo
usuário.
Use o elemento option
para marcar as
opções que serão passadas para um
comando.
Quando diversas referências a um mesmo comando
estiverem próximas é melhor usar a
notação &man.
para marcar a primeira referência ao mesmo e depois
utilizar command
.section
;command
para marcar as
referências subsequentes. Isto fará a
saída gerada, especialmente em HTML, ficar
visualmente melhor.
Isto pode ser confuso, e muitas vezes a escolha nem sempre é clara. Acredito que o exemplo abaixo ajudará a tornar as coisas mais claras.
Uso:
Aparência:
O Sendmail é a aplicação de email mais utilizada em Unix.
O Sendmail inclui os programas sendmail(8), mailq(1), and newaliases(1).
Um dos parâmetros de linha de comando para o
sendmail(8),
-bp
, irá mostrar o atual estado
da mensagem na fila de email. Verifique isto na linha de
comando usando sendmail -bp
.
Veja como a notação
&man.
é mais fácil de acompanhar.command
.section
;
Sempre que quiser se referir ao nome de um arquivo,
diretório ou uma extensão de arquivo, use
o elemento filename
.
filename
Uso:
Aparência:
O fonte SGML do Handbook em Inglês pode ser
encotrado em /usr/doc/en/handbook/
.
O primeiro arquivo neste diretório é
chamado handbook.xml
. Você
também deve ver o Makefile
e alguns arquivos com a extensão
.ent
.
Estes elementos são parte das extensões do FreeBSD ao DocBook, e não existem no DTD DocBook original.
Você pode precisar incluir o nome de um programa
da Coleção de Ports do FreeBSD na
documentação. Use a tag
filename
com o atributo
role
ajustado para package
para identificá-lo. Uma vez que a
coleção de ports pode ser instalada em diversos
lugares, inclua apenas a categoria e o nome do port,
não inclua o /usr/ports
.
filename
com o atributo
package
Use:
Aparência:
Instale o port
net/ethereal
para ver o tráfego na rede.
Estes elementos são parte das extensões do FreeBSD ao DocBook, e não existem no DTD DocBook original.
Você tem 2 opções para se referir a
um dispositivo. Você pode se referir ao dispositivo
da forma como ele aparece no /dev
,
ou você pode usar o nome do dispositivo como ele aparece
no kernel. No segundo caso, use o elemento
devicename
.
Em alguns casos você não terá escolha.
Alguns dispositivos, como as placas de rede, não
tem entrada no /dev
, ou as entradas
são muito diferentes das esperadas.
devicename
Uso:
Aparência:
sio
é usado para
comunicação serial no FreeBSD.
sio
se manifesta através
de entradas em /dev
, incluindo
/dev/ttyd0
e
/dev/cuaa0
.
Por outro lado, dispositivos de rede, tais como
ed0
não aparecem
/dev
.
No MS-DOS, o primeiro disco flexível é
chamado de a:
. No FreeBSD é
/dev/fd0
.
Estes elementos são parte das extensões do FreeBSD ao DocBook, e não existem no DTD DocBook original.
Você pode marcar a informação sobre
a identificação de computadores em rede
(hosts) de diversas maneiras. Todas elas usam
hostid
como elemento, com o atributo
role
dizendo o tipo da
informação marcada.
role
, ou
role="hostname"
Sem o atributo role
(i.e.,
hostid
.../hostid
)
a informação marcada é
simplesmente o nome do computador, tal como
freefall
ou
wcarchive
. Você pode
especificar explicitamente com
role="hostname"
.
role="domainname"
O texto é um nome de domínio, tal
como FreeBSD.org
ou
ngo.org.uk
. Não há o
componente do nome do computador (hostname).
role="fqdn"
O texto é um nome completo, com o nome do
computador e do domínio. O termo
fqdn
significa “Fully
Qualified Domain Name” - Nome de
Domínio Completamente Qualificado.
role="ipaddr"
O texto é um endereço IP,
provavelmente expresso como dotted
quad
.
role="ip6addr"
O texto é um endereço IPv6.
role="netmask"
O texto é uma máscara de rede, que
pode ser expressa como dotted quad
,
uma string hexadecimal ou como /
seguido de um número.
role="mac"
O texto é um endereço MAC Ethernet, expresso como números hexadecimais de 2 digitos separados por dois pontos (:).
Hostid
e Roles
Use:
Aparência:
A máquina local sempre pode ser referida pelo
nome localhost
, que terá o
endereço IP
127.0.0.1
.
O domínio
FreeBSD.org
contém vários hosts diferentes, incluindo
freefall.FreeBSD.org
e
bento.FreeBSD.org
.
Quando estiver adicionando um apelido para uma
interface (usando ifconfig
)
sempre use a máscara de
rede 255.255.255.255
(que
também pode ser expressa como
0xffffffff
).
O endereço MAC identifica unicamente cada
placa de rede existente. Um endereço MAC
típico se parece com
08:00:20:87:ef:d0
.
Estes elementos são parte das extensões do FreeBSD ao DocBook, e não existem no DTD DocBook original.
Quando precisar se referir a um nome de usuário
específico, tal como root
ou
bin
, use o elemento
username
.
Username
Uso:
Aparência:
Para executar a maioria das funções
administrativas você precisará ser
root
.
Estes elementos são parte das extensões do FreeBSD ao DocBook, e não existem no DTD DocBook original.
Existem dois elementos para descrever partes de
Makefile
s,
maketarget
e makevar
.
O maketarget
identifica uma alvo de
construção exportado por um
Makefile
que pode ser passado como um
parâmetro ao make
. O
makevar
identifica uma variável
que pode ser ajustada (no ambiente, na linha de comando do
make
, ou dentro do
Makefile
) para influenciar o
processo.
Maketarget
e
Makevar
Uso:
Aparência:
Dois alvos comuns em um Makefile
são all
e
clean
.
Tipicamente, usar all
irá refazer a aplicação, usar
clean
irá remover os
arquivos temporários (.o
por exemplo) criados pelo processo de
construção.
O clean
pode ser controlado
por muitas variáveis, incluindo
CLOBBER
e
RECURSE
.
Com frequência você irá precisar incluir texto “literal” na documentação. Este texto que é originado de outro arquivo, ou que deve ser copiado de forma fiel da documentação para outro arquivo.
Às vezes, o programlisting
será suficiente. Mas o
programlisting
nem sempre é
apropriado, particularmente quando você quer incluir
uma parte de um arquivo “in-line” com todos
os parágrafos.
Nestas ocasiões, use literal
.
Literal
Uso:
Aparência:
A linha maxusers 10
no arquivo de
configuração do kernel determina o tamanho
de muitas tabelas do sistema, e diz aproximadamente
quantos logins simultâneos o sistema irá
suportar.
Muitas vezes você irá querer mostrar ao usuário o que fazer, ou precisará se referir a um arquivo, a uma linha de comando ou coisa parecida, na qual ele não poderá simplesmente copiar o exemplo que você forneceu, mas na qual ele terá deve dar alguma informação por ele mesmo.
O elemento replaceable
foi criado para
estas ocasiões. Use ele dentro de outros elementos para
indicar partes do conteúdo do elemento que o
usuário deve substituir.
replaceable
Uso:
Aparência:
%
man comando
O replaceable
pode ser usado em
muitos elementos diferentes, incluindo
literal
. Este exemplo também
mostra que replaceable
só deve
envolver o conteúdo que o usuário
deve fornecer. O outro
conteúdo não deve ser alterado.
Uso:
Aparência:
A linha maxusers
no arquivo de configuração do kernel
determina o tamanho de muitas tabelas do sistema, e diz
aproximadamente quantos logins simultâneos o sistema
irá suportar.n
Para uma estação de trabalho,
32
é um bom valor para
n
.
O suporte a imagem na documentação ainda é extremamente experimental. O mecanismo aqui descrito provavelmente não irá mudar, mas isto não é garantido.
Você precisará instalar o port
graphics/ImageMagick
que é usado para converter entre os diferentes
formatos de imagens. Ele é grande e a sua maior
parte não é necessária. Entretanto,
enquanto nós ainda estamos trabalhando nos
Makefile
s e em outros itens da
infraestrutura, ele torna as coisas mais
fáceis. Este port não
está no meta port
textproc/docproj
,
você deve instalá-lo manualmente.
O melhor exemplo do que acontece na prática
é o documento
doc/en_US.ISO8859-1/articles/vm-design/
. Se você se sentir inseguro na
descrição que segue, dê uma olhada nos
arquivos deste diretório e veja como tudo se
encaixa. Experimente criar versões com diferentes
formatos de saída do documento para ver como a
marcação de imagem aparece no documento final.
Atualmente suportamos dois formatos de imagens. O formato que você deve usar depende da natureza da sua imagem.
Para imagens vetoriais, tais como diagramas de rede,
linhas temporais e similares, use Encapsulated Postscript,
e certifique-se que suas imagens tenham a extensão
.eps
.
Para bitmaps, tais como a captura de uma tela, use o
formato Portable Network Graphic, e certifique-se que suas
imagens tenham a extensão
.png
.
Estes são os únicos formatos de imagem que podem ser gravados no repositório Subversion.
Use o formato correto para a imagem correta. Espera-se
que a sua documentação tenha tanto imagens
EPS quanto PNG. Os Makefile
s
asseguram que o formato correto seja escolhido dependendo
do formato de saída da sua
documentação. Não faça
commit da mesma imagem nos dois formatos diferentes para o
repositório.
É esperado que o projeto de documentação passe a utilizar no futuro o formato Scalable Vector Graphic (SVG) para imagens vetoriais. Entretanto, o atual estado das ferramentas de edição torna isto impraticável.
A marcação para uma imagem é
relativamente simples. Primeiro, marque um
mediaobject
. O
mediaobject
pode conter outros objetos
mais específicos. Estamos interessandos em dois,
o imageobject
e o
textobject
.
Você deve incluir um
imageobject
, e dois elementos
textobject
. O
imageobject
irá apontar para o
nome do arquivo da imagem que será usada
(sem a extensão). Os elementos
textobject
contém a
informação que será apresentada ao
usuário junto, ou não, com a imagem.
Há duas circunstâncias em que isso pode ocorrer.
Quando o leitor estiver vendo a documentação em HTML. Neste caso, cada imagem precisará ter um texto alternativo associado para mostrar ao usuário, tipicamente enquanto a imagem estiver sendo carregada, ou se ele parar o ponteiro do mouse sobre a imagem.
Quando o leitor estiver vendo a documentação em modo texto. Neste caso, cada imagem deve ter uma ASCII art equivalente para mostrar ao usuário.
Um exemplo provavelmente irá tornar as coisas
mais fáceis de se entender. Suponha que você
tenha uma imagem, chamada fig1.png
, que
você queira incluir no documento. Esta imagem
é um retângulo com um A dentro dele. A
marcação para isso será:
Inclua um elemento | |
O primeiro Veja como as primeras e últimas linhas do
conteúdo do elemento | |
O segundo |
Suas imagens devem estar listadas na variável
IMAGES
do Makefile
.
Esta variável deve conter o nome de todos
fontes das suas imagens. Por exemplo,
se você criou três figuras,
fig1.eps
,
fig2.png
,
fig3.png
, então o seu
Makefile
deve ter linhas como estas.
ou
De novo, o Makefile
irá
fazer uma lista completa das imagens necessárias
para criar o seu documento fonte, você precisa
listar apenas as imagens que
você fornece.
Você precisa ser cuidadoso quando separar a sua documentação em arquivos menores (veja Section 3.7.1, “Utilizando entidades gerais para incluir arquivos”) em diretórios diferentes.
Suponha que você tenha um livro com três
capítulos, e os capítulos estão
armazenados cada um no seu próprio diretório,
chamados chapter1/chapter.xml
,
chapter2/chapter.xml
, e
chapter3/chapter.xml
. Se cada
capítulo tiver imagens associadas a eles, é
sugerido que você as coloque dentro do respectivo
subdiretório de cada capítulo
(chapter1/
,
chapter2/
,
chapter3/
).
Entretanto, se você fizer isso você deve
incluir o nome dos diretórios na variável
IMAGES
no Makefile
,
e deve incluir o nome do
diretório no elemento imagedata
do seu documento.
Por exemplo, se você tiver
chapter1/fig1.png
, então
chapter1/chapter.xml
deve
conter:
O Makefile
deve conter:
Desta forma tudo deve funcionar.
Links também são elementos in-line.
Links dentro do mesmo documento exigem que você especifique de onde você esta se ligando (i.e., o texto no qual o usuário irá clicar, ou indicando de outra maneira a origem do link) e para onde você está se ligando (o destino do link).
Cada elemento dentro do DocBook tem um atributo chamado
id
. Você pode por um texto neste
atributo para identificar unicamente o elemento associado
a ele.
Este valor será usado quando você especificar a origem do link.
Normalmente, você irá se ligar apenas a
capítulos ou seções, assim você
irá colocar o atributo id
nestes
elementos.
id
em capítulos
ou seçõesObviamente, você deve usar nomes mais descritivos.
Estes nomes devem ser únicos dentro do documento
(i.e., não apenas no arquivo, mas sim no documento
no qual o arquivo está incluído). Repare como o
id
é construído adicionando-se
texto ao id
do capítulo. Isto
ajuda a garantir que eles sejam únicos.
Se você quiser permitir ao usuário saltar
para uma parte específica do documento
(possivelmente para o meio do parágrafo ou um
exemplo), use o elemento anchor
. Este
elemento não tem conteúdo, mas aceita o atributo
id
.
anchor
Quando você quiser dar ao usuário um link
que possa ser ativado (provavelmente clicando-se) para ir
para outra seção do documento que tenha um
atributo id
, você pode usar
xref
ou link
.
Ambos os elementos têm um atributo
linkend
. O valor deste atributo deve
ser o mesmo usado no atributo id
(não importa se ele ainda não ocorreu no
documento; isto funciona tanto para um link à frente
quanto para trás).
Se você utilizar o xref
então você não terá controle
sobre o texto do link. Ele será gerado para
você.
xref
Assuma que este fragmento apareça em algum
lugar de um documento que inclua o id
do exemplo.
O texto do link será gerado automaticamente, e irá se parecer com (As palavras em itálico indicam o texto que será o link):
Maiores informações podem ser encontradas no Capítulo Um.
Informações mais específicas podem ser encontradas na seção chamada Subseção 1.
Observe como o texto do link é deduzido a partir do título da seção ou do número do capítulo.
Isto significa que você não
pode usar xref
para se
ligar a um atributo id
em um elemento
anchor
. O anchor
não tem conteúdo, desta forma o
xref
não pode gerar o texto
para o link.
Se você quiser controlar o texto do link
você deverá utilizar link
.
Este elemento envolve o conteúdo, e o conteúdo
será usado para o link.
link
Assuma que este fragmento aparece em algum lugar em
um documento que inclui o id
do
exemplo.
Isto irá gerar o seguinte (Palavras em itálico indicam o texto que será o link):
Maiores informações podem ser encontradas no primeiro capítulo .
Informações mais específicas podem ser encontradas nesta seção
Este último é um mau exemplo. Nunca use palavras como “esta” ou “aqui” como origem do link. O leitor terá que procurar no contexto próximo para ver para onde o link o está levando.
Você pode usar o elemento
link
para incluir um link para um
id
em um elemento
anchor
, uma vez que o conteúdo
de link
define o texto que será
usado para o link.
Ligar-se a um documento externo é muito mais
simples, desde que você saiba o URL do documento ao
qual deseja se ligar. Basta utilizar o elemento
ulink
. O atributo url
é o URL da página para o qual
o link aponta, e o conteúdo do elemento é
o texto que será mostrado para o usuário
ativar.
ulink
Uso:
Aparência:
É claro que você pode parar de ler este documento e ir para a Página principal do FreeBSD
[3] Uma pequena história sobre este assunto pode ser encontrada em http://www.oasis-open.org/docbook/intro.shtml#d0e41.
[4] Há outros tipos de elementos de lista no DocBook, mas não vamos nos preocupar com eles no momento.
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>.