O suporte de imagem na documentação é um pouco experimental. Os mecanismos descritos aqui provavelmente não mudarão, mas isso não é garantido.
Para fornecer conversão entre diferentes formatos de imagem, o port graphics/ImageMagick deve estar instalado. Esse port não está incluído no meta port textproc/docproj e deve ser instalado separadamente.
Um bom exemplo do uso de imagens é o documento graphics/ImageMagick
. Examine os arquivos nesse diretório para ver como esses elementos são usados juntos. Crie formatos de saída diferentes para ver como o formato determina quais imagens são mostradas no documento renderizado.
Os seguintes formatos de imagem são suportados atualmente. Um arquivo de imagem será automaticamente convertido em bitmap ou imagem vetorial, dependendo do formato do documento de saída.
Estes são os formatos somente nos quais as imagens devem ser enviadas para o repositório de documentação.
Imagens com base principalmente em vetores, como diagramas de rede, linhas de tempo e similares, devem estar nesse formato. Estas imagens têm uma extensão .eps
.
Para bitmaps, como capturas de tela, use este formato. Essas imagens têm a extensão .png
.
PIC é uma linguagem para desenhar figuras baseadas em vetor simples usadas no utilitário pic(1). Essas imagens têm a extensão .pic
.
Este formato é específico para capturas de tela da saída do console. O seguinte comando gera um arquivo SCR shot.scr
do buffer de vídeo /dev/ttyv0
:
#
vidcontrol -p
<>
/dev/ttyv0
shot.scr
É preferível o formato PNG para capturas de tela porque o arquivo SCR contém texto sem formatação das linhas de comando para que possa ser convertido em uma imagem PNG ou um texto simples, dependendo do formato do documento de saída.
Use o formato apropriado para cada imagem. A documentação geralmente tem uma mistura de imagens EPS e PNG. O Makefile
assegura que a imagem de formato correta seja escolhida dependendo do formato de saída usado. Não envie a mesma imagem ao repositório em dois formatos diferentes.
O Projeto de Documentação pode eventualmente mudar para o formato SVG (Scalable Vector Graphic) para imagens vetoriais. No entanto, o estado atual das ferramentas de edição compatíveis com SVG torna isso inviável.
As imagens podem ser armazenados em um dos diversos locais abaixo, dependendo do documento e da imagem:
No mesmo diretório do documento em si, geralmente feito para artigos e pequenos livros que mantêm todos os arquivos em um único diretório.
Em um subdiretório do documento principal. Geralmente feito quando um livro grande usa subdiretórios separados para organizar capítulos individuais.
Quando as imagens são armazenadas em um subdiretório do diretório do documento principal, o nome do subdiretório deve ser incluído em seus caminhos no Makefile
e no elemento imagedata
.
Em um subdiretório de doc/share/images
nomeado após o documento. Por exemplo, as imagens do Handbook estão armazenadas em doc/share/images/books/handbook
. Imagens que funcionam para várias traduções são armazenadas neste nível superior da árvore de arquivos da documentação. Geralmente, estas são imagens que podem ser usadas inalteradas em traduções não inglesas do documento.
As imagens são incluídas como parte de um mediaobject
. O mediaobject
pode conter outros objetos mais específicos. Estamos preocupados com dois, o imageobject
e o textobject
.
Inclua um imageobject
e dois elementos textobject
. O imageobject
apontará para o nome do arquivo de imagem sem a extensão. Os elementos textobject
contêm informações que serão apresentadas ao usuário, bem como, ou em vez da própria imagem.
Elementos de texto são mostrados ao leitor em várias situações. Quando o documento é exibido em HTML, elementos de texto são mostrados enquanto a imagem está sendo carregada ou se o ponteiro do mouse estiver sobre a imagem ou se um navegador somente texto estiver sendo usado. Em formatos como texto simples, onde os gráficos não são possíveis, os elementos de texto são mostrados em vez dos gráficos.
Este exemplo mostra como incluir uma imagem chamada fig1.png
em um documento. A imagem é um retângulo com um A dentro dela:
<mediaobject>
<imageobject>
<imagedata fileref="fig1"/>
![]()
</imageobject>
<textobject>
<literallayout class="monospaced">
+---------------+| A | +---------------+
</literallayout>
</textobject>
<textobject>
<phrase>
A picture</phrase>
![]()
</textobject>
</mediaobject>
Inclua um elemento | |
O primeiro Observe como a primeira e a última linha do conteúdo do elemento | |
O segundo |
As imagens devem estar listadas no Makefile
na variável IMAGES
. Esta variável deve conter os nomes de todas as imagens source. Por exemplo, se houver três figuras, fig1.eps
, fig2.png
, fig3.png
, então o Makefile
deve ter linhas como esta.
… IMAGES= fig1.eps fig2.png fig3.png …
ou
… IMAGES= fig1.eps IMAGES+= fig2.png IMAGES+= fig3.png …
Novamente, o Makefile
irá elaborar a lista completa de imagens necessárias para compilar o documento, você só precisa listar os arquivos de imagem que você forneceu.
Tenha cuidado ao separar a documentação em arquivos menores em diretórios diferentes (consulte Seção 7.7.1, “Usando Entidades Gerais para Incluir Arquivos”).
Imagine que haja um livro com três capítulos e os capítulos sejam armazenados em seus próprios diretórios, chamados chapter1/chapter.xml
, chapter2/chapter.xml
e chapter3/chapter.xml
. Se cada capítulo tiver imagens associadas, coloque essas imagens no subdiretório de cada capítulo (chapter1/
, chapter2/
, e chapter3/
).
No entanto, fazer isso requer a inclusão dos nomes de diretório na variável IMAGES
no Makefile
, e a inclusão do nome do diretório no elemento imagedata
no documento.
Por exemplo, se o livro tiver chapter1/fig1.png
, então chapter1/chapter.xml
deve conter:
<mediaobject>
<imageobject>
<imagedata fileref="chapter1/fig1"/>
![]()
</imageobject>
…</mediaobject>
O Makefile
deve conter:
… IMAGES= chapter1/fig1.png …
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>.