Preparando Documentos com o Adessowiki

Um documento AdessoWiki é feito por texto estruturado, código de programação e instruções para compilação, execução e formatação da informação. A estrutura base é herdada do reStructuredText, parte do projeto Docutils para formatação de texto.

A documentação do reStructuredText pode ser acessada em http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html.

Extensões

O AdessoWiki acrescenta algumas extensões ao reStructuredText. As principais são diretivas que permitem a interpretação de scripts com geração de imagens e inserção no documento.

As extensões ao reStructuredText são:

  • Inserção de código executável
  • Inserção de links wiki
  • Inserção de equações no texto

Inserção de Código

O modelo básico é o seguinte. O script é executado em um ambiente onde toda escrita em stdout é capturada e chamadas a algumas funções especiais são sobrecarregadas para que elas retornem gráficos e imagens que são inseridas no próprio documento.

  • Inserção de código Python

A inserção de trecho de programa Python é feito usando:

.. code:: python

   print sys.version

O resultado de sua execução aparecerá no documento:

1. print sys.version
2.7.3 (default, Apr 10 2013, 06:20:15) 
[GCC 4.6.3]

A função que gera imagem é a adshow:

  • adshow

Todas as outras funções de visualizações mais complexas e de plotagem são feitas no final através do adshow.

adshow tem um parâmetro title que permite especificar uma legenda (caption) para a imagem inserida no documento.

  • Inserção de código MATLAB

    Infelizmente o termo de licença do MATLAB não permite que seu acesso seja feito via web, assim, esta opção não é disponível. Entretanto o uso do Python junto com o pacote numérico NumPy substitui com vantagens as funções do MATLAB.

A inserção de imagens e texto ao documento é controlada pelos parâmetros da diretiva (veja o exemplo mais à frente). Os seguintes parâmetros são suportados atualmente:

  • show_code: yes/no. Insere o código do script no documento. Default: yes.
  • show_output: yes/no. Insere conteúdo capturado de stdout no documento. Default: yes.
  • show_images: yes/no. Insere imagens geradas no documento. Default: yes.
  • img_width: Largura máxima de cada imagem no documento. Default: 320.
  • img_cols: Número de colunas de imagens no documento. Default: 2.
  • img_texdpi: Resolução das imagens no documento (apenas para PDF). Default: 120.
  • tex_pos: Posição da figura (apenas para PDF), código LaTeX: btph (bottom, top, page ou here, seguido ou não de !)
  • col_span: Span de cada coluna da tabela de imagens (sequencia de inteiros).
  • title: Título do quadro inteiro.

Vejamos um exemplo:

.. code:: python
      :show_code: yes
      :show_output: yes
      :show_images: yes
      :img_width: 320
      :img_cols: 2
      :img_texdpi: 120
      :title: Imagens: (a) original e (b) invertida.
1. import ia636
2. f = adreadgray('cameraman.tif')
3. 
4. adshow( f, title='(a)')
5. adshow(ia636.ianeg( f), title='(b)')
6. 
7. print 'Image shape is', f.shape
Image shape is (256, 256)

(a)

(b)

Imagens: (a) original e (b) invertida.

Inserção de Ligações Wiki

Para que o AdessoWiki permita a criação de uma web colaborativa como uma wiki, é possível criar novos arquivos e ligá-lo usando os símbolos ` . A primeira palavra dentro do string é o novo arquivo a ser ligado e as palavras seguintes formam o texto que aparecerá sobre a ligação:

Exemplos:

`MainPage Página de Entrada do AdessoWiki

Inserção de Equações

Em sua modalidade latex, permite a inserção de equações através de sua definição em LaTeX. Existe ainda um markup in-line para a inserção de equações in-line. Um exemplo:

Esta é uma equação in-line: :eq:`\Omega = \Psi`. A diretiva é usada a seguir.

.. equation:: latex
    :dpi: 100

    f \ is \ lower \ complete  \Leftrightarrow \forall p \in \mathcal{D}_f,
    \forall p' \in N_\mathcal{G}(p), f(p') \geq f(p) \Rightarrow p \in RMIN(f)

Esta é uma equação in-line: . A diretiva é usada a seguir.