Para enfatizar uma palavra ou frase em particular, use emphasis
. Isso pode ser apresentado em itálico ou negrito, ou pode ser falado diferentemente com um sistema de conversão de texto em fala.
Não há uma maneira de mudar a apresentação da ênfase no documento, não existe um equivalente a b
e i
do HTML . Se as informações apresentadas forem importantes, considere apresentá-las em important
em vez de emphasis
.
emphasis
Uso:
<para>
&os; is without doubt<emphasis>
the</emphasis>
premiere &unix;-like operating system for the Intel architecture.</para>
Aparência:
FreeBSD is without doubt the premiere UNIX®-like operating system for the Intel architecture.
Muitos termos de computador são siglas, palavras formadas a partir da primeira letra de cada palavra em uma frase. Os acrônimos são marcados com elementos acronym
. É útil para o leitor quando um acrônimo é definido no primeiro uso, como mostrado no exemplo abaixo.
acronym
Uso:
<para>
Request For Comments (<acronym>
RFC</acronym>
) 1149 defined the use of avian carriers for transmission of Internet Protocol (<acronym>
IP</acronym>
) data. The quantity of<acronym>
IP</acronym>
data currently transmitted in that manner is unknown.</para>
Aparência:
Request For Comments (RFC) 1149 defined the use of avian carriers for transmission of Internet Protocol (IP) data. The quantity of IP data currently transmitted in that manner is unknown.
Para citar texto de outro documento ou fonte, ou para denotar uma frase que é usada de forma figurada, use quote
. A maioria das tags de marcação disponíveis para texto normal também está disponível em quote
.
quote
Uso:
<para>
However, make sure that the search does not go beyond the<quote>
boundary between local and public administration</quote>
, as<acronym>
RFC</acronym>
1535 calls it.</para>
Aparência:
However, make sure that the search does not go beyond the “boundary between local and public administration”, as RFC 1535 calls it.
Para se referir a uma tecla específica no teclado, use keycap
. Para se referir a um botão do mouse, use mousebutton
. E para se referir a combinações de pressionamentos de teclas ou cliques do mouse, coloque todos eles em keycombo
.
keycombo
tem um atributo chamado action
, que pode ser um dos click
, double-click
, other
, press
, seq
, ou simul
. Os dois últimos valores indicam se as teclas ou botões devem ser pressionados em sequência ou simultaneamente.
As folhas de estilo adicionam automaticamente quaisquer símbolos de conexão, como +
, entre os nomes das chaves, quando agrupados em keycombo
.
Uso:
<para>
To switch to the second virtual terminal, press<keycombo action="simul">
<keycap>
Alt</keycap>
<keycap>
F1</keycap>
</keycombo>
.</para>
<para>
To exit<command>
vi</command>
without saving changes, type<keycombo action="seq">
<keycap>
Esc</keycap>
<keycap>
:</keycap>
<keycap>
q</keycap>
<keycap>
!</keycap>
</keycombo>
.</para>
<para>
My window manager is configured so that<keycombo action="simul">
<keycap>
Alt</keycap>
<mousebutton>
right</mousebutton>
</keycombo>
mouse button is used to move windows.</para>
Aparência:
To switch to the second virtual terminal, press Alt+F1.
To exit vi
without saving changes, type Esc : q !.
My window manager is configured so that Alt+ mouse button is used to move windows.
Ambos os aplicativos e comandos são frequentemente utiilzados ao escrever uma documentação. A distinção entre eles é que um aplicativo é o nome de um programa ou conjunto de programas que preenche uma tarefa específica. Um comando é o nome do arquivo de um programa que o usuário pode digitar e executar em uma linha de comando.
Muitas vezes é necessário mostrar algumas das opções que um comando pode ter.
Finalmente, muitas vezes é útil listar um comando com seu número de seção do manual, no formato “command(number)” que é comum em manuais Unix.
Marque nomes de aplicações com application
.
Para listar um comando com seu número de seção do manual (que deve ser utilizado com maior frequência), o elemento DocBook é citerefentry
. Isto irá conter mais dois elementos, refentrytitle
e manvolnum
. O conteúdo de refentrytitle
é o nome do comando, e o conteúdo do manvolnum
é a seção da página de manual.
Isso pode ser trabalhoso para escrever e assim uma série de entidades gerais foram criadas para tornar esse processo mais fácil. Cada entidade assume o formato &man.
.manual-page
.manual-section
;
O arquivo que contém essas entidades está em doc/share/xml/man-refs.ent
e pode ser referenciado usando este FPI:
PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"
Portanto, a introdução à documentação do FreeBSD geralmente incluirá isto:
<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ <!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> %man; … ]>
Use command
para incluir um nome de comando “in-line”, mas mostre como algo que o usuário deve digitar.
Use option
para marcar as opções que serão passadas para um comando.
Ao se referir ao mesmo comando várias vezes nas proximidades, é preferível usar a notação &man.
para marcação a primeira referência e use command
.section
;command
para marcar as referências subsequentes. Isso faz com que a saída gerada, especialmente HTML, apareça visualmente melhor.
Uso:
<para>
<application>
Sendmail</application>
is the most widely used Unix mail application.<para>
<para>
<application>
Sendmail</application>
includes the<citerefentry>
<refentrytitle>
sendmail</refentrytitle>
<manvolnum>
8</manvolnum>
</citerefentry>
, &man.mailq.1;, and &man.newaliases.1; programs.</para>
<para>
One of the command line parameters to<citerefentry>
<refentrytitle>
sendmail</refentrytitle>
<manvolnum>
8</manvolnum>
</citerefentry>
,<option>
-bp</option>
, will display the current status of messages in the mail queue. Check this on the command line by running<command>
sendmail -bp</command>
.</para>
Aparência:
Sendmail é o aplicativo de email Unix mais utilizado.
O Sendmail inclui o os programas sendmail(8), mailq(1), e o newaliases(1).
Um dos parâmetros da linha de comando para o sendmail(8), -bp
, exibirá o status atual das mensagens no fila de email. Verifique isso na linha de comando executando sendmail -bp
.
Observe como a notação &man.
é mais fácil de ser seguida..
section
;
Para se referir ao nome de um arquivo, um diretório, uma extensão de arquivo ou um nome de dispositivo, use filename
.
filename
Uso:
<para>
O código fonte do Handbook em inglês é encontrada em<filename>
/usr/doc/en_US.ISO8859-1/books/handbook/</filename>
. O arquivo principal é chamado<filename>
book.xml</filename>
. Há também um<filename>
Makefile</filename>
e vários arquivos com a extensão<filename>
.ent</filename>
.</para>
<para>
<filename>
kbd0</filename>
é o primeiro teclado detectado pelo sistema e aparece em<filename>
/dev</filename>
.</para>
Aparência:
O código fonte do Handbook em inglês é encontrada em /usr/doc/en_US.ISO8859-1/books/handbook/
. O arquivo principal é chamado book.xml
. Há também um Makefile
e vários arquivos com a extensão .ent
.
kbd0
é o primeiro teclado detectado pelo sistema e aparece em /dev
.
Estes elementos fazem parte da extensão do FreeBSD ao DocBook, e não existem no DocBook DTD original.
Para incluir o nome de um programa da Coleção de Ports do FreeBSD no documento, use a tag package
. Como a Coleção de Ports pode ser instalada em qualquer local, inclua apenas a categoria e o nome do port; não inclua /usr/ports
.
Por padrão, package
refere-se a um pacote binário. Para se referir a um port que será compilado a partir do código fonte, configure o atributo role
para port
.
package
Uso:
<para>
Instale o pacote binário<package>
net/wireshark</package>
para visualizar o tráfego de rede.</para>
<para>
<package role="port">
net/wireshark</package>
também pode ser compilado e instalado pela Coleção de Ports.</para>
Aparência:
Instale o pacote binário net/wireshark para visualizar o tráfego de rede.
O net/wireshark também pode ser compilado e instalado pela Coleção de Ports.
Estes elementos fazem parte da extensão do FreeBSD ao DocBook, e não existem no DocBook DTD original.
Informações para “itens do sistema” estão marcadas com systemitem
. O atributo class
é usado para identificar o tipo específico de informação mostrada.
class="domainname"
O texto é um nome de domínio, como FreeBSD.org
ou ngo.org.uk
. Não há nenhum componente de nome de host.
class="etheraddress"
O texto é um endereço Ethernet MAC, expresso como uma série de números hexadecimais de 2 dígitos separados por dois pontos.
class="fqdomainname"
O texto é um nome de domínio FQDM, com ambos nome de domínio e hostname.
class="ipaddress"
O texto é um endereço de IP.
class="netmask"
O texto é uma máscara de rede, que pode ser expressa igual a um IP, uma sequência hexadecimal ou como um /
seguido por um número (notação CIDR).
class="systemname"
Com class="systemname"
, as informações marcadas são o nome do host simples, como freefall
ou wcarchive
.
class="username"
O texto é um nome de usuário, como root
.
class="groupname"
O texto é um grupo, como wheel
.
systemitem
Uso:
<para>
The local machine can always be referred to by the name<systemitem class="systemname">
localhost</systemitem>
, which will have the IP address<systemitem class="ipaddress">
127.0.0.1</systemitem>
.</para>
<para>
The<systemitem class="domainname">
FreeBSD.org</systemitem>
domain contains a number of different hosts, including<systemitem class="fqdomainname">
freefall.FreeBSD.org</systemitem>
and<systemitem class="fqdomainname">
bento.FreeBSD.org</systemitem>
.</para>
<para>
When adding an<acronym>
IP</acronym>
alias to an interface (using<command>
ifconfig</command>
)<emphasis>
always</emphasis>
use a netmask of<systemitem class="netmask">
255.255.255.255</systemitem>
(which can also be expressed as<systemitem class="netmask">
0xffffffff</systemitem>
).</para>
<para>
The<acronym>
MAC</acronym>
address uniquely identifies every network card in existence. A typical<acronym>
MAC</acronym>
address looks like<systemitem class="etheraddress">
08:00:20:87:ef:d0</systemitem>
.</para>
<para>
To carry out most system administration functions requires logging in as<systemitem class="username">
root</systemitem>
.</para>
Aparência:
A máquina local sempre pode ser referenciada 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
.
Ao adicionar um alias de IP a uma interface (usando ifconfig
) sempre use uma máscara de rede de 255.255.255.255
(que também pode ser expressa como 0xffffffff
).
O endereço MAC identifica exclusivamente todas as placas de rede existentes. Um endereço MAC típico se parece com 08:00:20:87:ef:d0
.
Para executar a maioria das funções de administração do sistema, é necessário efetuar login como root
.
Ocasionalmente, é útil mostrar um Identificador de Recurso Uniforme (URI) sem torná-lo um hiperlink ativo. O elemento uri
torna isso possível:
uri
Uso:
<para>
Esta URL é mostrada apenas como texto:<uri>
https://www.FreeBSD.org</uri>
. Não é criado um link.</para>
Aparência:
Esta URL é mostrada apenas como texto: https://www.FreeBSD.org
. Não é criado um link.
Para criar links, consulte Seção 9.8, “Links”.
Os endereços de email são marcados como elementos email
. No formato de saída HTML, o texto marcado se torna um hiperlink para o endereço de email. Outros formatos de saída que suportam hiperlinks também podem tornar o endereço de email em um link.
email
Uso:
<para>
Um endereço de email que não existe, como<email>
notreal@example.com</email>
, pode ser usado como um exemplo</para>
Aparência:
Um endereço de email que não existe, como <notreal@example.com>
, pode ser usado como exemplo.
Uma extensão específica do FreeBSD permite configurar o atributo role
para nolink
para evitar a criação do hiperlink para o endereço de email.
email
Sem HiperlinkUso:
<para>
Às vezes, o link para um endereço de email como<email role="nolink">
notreal@example.com</email>
não é desejado.</para>
Aparência:
Às vezes, o link para um endereço de email como <notreal@example.com>
não é desejado.
Estes elementos fazem parte da extensão do FreeBSD ao DocBook, e não existem no DocBook DTD original.
Existem dois elementos para descrever partes de Makefile
s, buildtarget
e varname
.
buildtarget
identifica um destino de compilação exportado por um Makefile
que pode ser fornecido como um parâmetro para o make
. varname
identifica uma variável que pode ser definida (no ambiente, na linha de comando com o make
, ou dentro do Makefile
) para influenciar o processo.
buildtarget
e varname
Uso:
<para>
Two common targets in a<filename>
Makefile</filename>
are<buildtarget>
all</buildtarget>
and<buildtarget>
clean</buildtarget>
.</para>
<para>
Typically, invoking<buildtarget>
all</buildtarget>
will rebuild the application, and invoking<buildtarget>
clean</buildtarget>
will remove the temporary files (<filename>
.o</filename>
for example) created by the build process.</para>
<para>
<buildtarget>
clean</buildtarget>
may be controlled by a number of variables, including<varname>
CLOBBER</varname>
and<varname>
RECURSE</varname>
.</para>
Aparência:
Dois targets comuns em um Makefile
são all
e clean
.
Normalmente, invocar all
irá reconstruir o aplicativo, e invocar clean
removerá os arquivos temporários (.o
por exemplo) criados pelo processo de compilação.
clean
pode ser controlado por várias de variáveis, incluindo CLOBBER
e RECURSE
.
O texto literal, ou texto que deve ser inserido na íntegra, é frequentemente necessário na documentação. Este é um texto extraído de outro arquivo ou que deve ser copiado exatamente como mostrado na documentação em um outro arquivo.
Na maioria das vezes, programlisting
será suficiente para denotar este texto. Mas programlisting
nem sempre é apropriado, particularmente quando você quer incluir uma parte de um arquivo “in-line” com o resto do parágrafo.
Nestes casos, use literal
.
literal
Uso:
<para>
The<literal>
maxusers 10</literal>
line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support.</para>
Aparência:
A linha maxusers 10
no arquivo de configuração do kernel determina o tamanho de muitas tabelas do sistema e é um guia aproximado de quantos logins simultâneos o sistema suportará.
Haverá diversos momentos em que o usuário irá ver o que fazer, ou será referenciado a um arquivo ou linha de comando, mas não poderá simplesmente copiar o exemplo fornecido. Em vez disso, eles precisam fornecer algumas informações.
replaceable
é projetado para essa eventualidade. Use isso dentro de outros elementos para indicar partes do conteúdo desse elemento que o usuário deve substituir.
replaceable
Uso:
<screen>
&prompt.user;<userinput>
man<replaceable>
command</replaceable>
</userinput>
</screen>
Aparência:
%
man
command
replaceable
pode ser usado em diversos elementos, incluindo literal
. Este exemplo também mostra que o replaceable
deve estar apenas em torno do conteúdo que o usuário está destinado a fornecer. O outro conteúdo deve ser deixado de lado.
Uso:
<para>
The<literal>
maxusers<replaceable>
n</replaceable>
</literal>
line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support.</para>
<para>
For a desktop workstation,<literal>
32</literal>
is a good value for<replaceable>
n</replaceable>
.</para>
Aparência:
A linha maxusers
no arquivo de configuração do kernel determina o tamanho de muitas tabelas do sistema e é um guia aproximado de quantos logins simultâneos o sistema suportará.n
Para uma estação de trabalho, 32
é um bom valor para n
.
Os botões apresentados por uma interface gráfica do usuário são marcados com guibutton
. Para tornar o texto mais parecido com um botão gráfico, colchetes e espaços não separáveis são adicionados em volta do texto.
guibutton
Uso:
<para>
Edit the file, then click<guibutton>
[ Save ]</guibutton>
to save the changes.</para>
Aparência:
Edite o arquivo e clique em
para salvar as alterações.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>.