Tutoriais Mini-Book em fortran-lang.org#

Este guia cobrirá como escrever tutoriais mini-book para a seção Aprenda do site https://fortran-lang.org.

Ver orientações para contribuições para um guia geral de como contribuir para o https://fortran-lang.org.

0. Mini-book formats#

Mini-books são feitos para ser os tutoriais mais concisos de um recurso particular da linguagem Fortran.

Há dois tipos de formatos para os mini-books:

  • Página Única: todo conteúdo é escrito dentro de um único ficheiro markdown e mostrado em uma única página web;

  • Várias Páginas: o conteúdo do tutorial é escrito ao longo de vários ficheiros markdown e mostrado como uma coleção de páginas web.

A escolha do tipo de livro depende do tamanho de seu conteúdo e como você pretende estruturá-lo.

Leve em conta o tipo de sumário que será produzido:

  • Livros de única página possuem um nível de navegação: um link para cada seção do tutorial no sumário na mesma página (que se localiza à direita).

  • Livros de várias páginas possuem dois níveis de navegação: um link para cada seção no sumário do tutorial (que se encontra à direita) e um sumário lateral (à esquerda) mostrando as diferentes páginas do diretório.

Mini-books de página única são mais simples de fazer e devem ser usados para tópicos curtos ou tutoriais que eventualmente podem ser reaproveitados em um livro de múltiplas páginas mais abrangente.

Livros multi-página são recomendados para tutoriais mais abrangentes que podem ser estruturados com um sub-tópico por página.

O resto deste guia está dividido em duas seções, uma para cada tipo de mini-book.

1. Single-page mini-book#

Os passos necessários para a publicação de um mini-book de página única são:

  • Crie um novo documento markdown no diretório ./learn

  • Escreva o conteúdo do seu tutorial

  • Adicione uma entrada no data/learning.yml para o seu novo mini-book

  • Abra um PR

1.1 Escrevendo seu mini-book em markdown#

Para mini-books de página única seu tutorial será completamente contido dentro de um único documento escrito em markdown.

Primeiro crie um novo documento markdown no diretório ./learn/{{nome_do_minibook}}/ com a extensão .md e um nome curto que descreva bem o tópico do seu tutorial, Ex: ./learn/{{nome_do_minibook}}/file_io.md.

Abra seu novo ficheiro markdown e adicione uma entrada no TOC do learn.md, no seguinte formato:

:::{toctree}
:hidden:

learn/quickstart/index
learn/best_practices/index
learn/os_setup/index
learn/building_programs/index
learn/intrinsics/index
learn/{{book-filename}}
:::

Troque {{book-filename}} pelo nome do seu ficheiro markdown, porém não inclua a extensão .md. Além disso, não deve haver separador de ficheiro ao final da linha.

Exemplo: cabeçalho

:::{toctree}
:hidden:

learn/quickstart/index
learn/best_practices/index
learn/os_setup/index
learn/building_programs/index
learn/intrinsics/index
learn/file_io
:::

NÃO FAÇA: permalink: /learn/file_io.md

NÃO FAÇA: permalink: /learn/file_io/

Você agora é capaz de preencher o restante do seu ficheiro com o conteúdo do seu tutorial escrito em markdown; veja Kramdown syntax para uma documentação a respeito da implementação markdown usada aqui.

1.2 Estruturando seu mini-book com seções#

Você deve usar cabeçalhos para quebrar seu mini-book de única página em uma estrutura lógica. Cada cabeçalho vai aparecer lincado na tabela-de-conteúdo (TOC).

Em markdown, seções podem ser escritas com:

# Heading level 1

## Heading level 2

### Heading level 3

#### Heading level 4

##### Heading level 5

###### Heading level 6

Nota: tenha certeza de incluir uma linha em branco antes de seu cabeçalho.

1.3 Adicione seu mini-book na página Aprenda#

Para adicionar seu novo mini-book à página Aprenda, você deve adicionar uma nova entrada no ficheiro de dados data/learning.yml.

Abra este ficheiro e crie uma nova entrada abaixo do campo books:, no seguinte formato:

- title: {{book-title}}
  description: {{book-description}}
  category: {{book-category}}
  link: /learn/{{book-filename}}

O campo title é o que será mostrado na página Learn de seu mini-book e geralmente deve ser o mesmo que o campo title em seu ficheiro markdown, porém isso não é obrigatório.

Os conteúdos do campo description também é mostrado na página Learn e deve descrever brevemente o conteúdo de seu tutorial mini-book.

O campo category deve bater com uma das categorias listadas no topo do ficheiro de dados (abaixo do campo categories:) e usado para agrupar tutoriais na página Aprenda.

O campo link deve ser o mesmo que o campo permalink em seu documento markdown.

Exemplo: entrada de livro no learning.yml

- title: File input and output
  description: A tutorial on reading and writing files in Fortran
  category: Getting started
  link: /learn/file/file_io

Salve o ficheiro de dados modificado learning.yml, rode o script fortran_package.py e recompile o site na sua máquina para checar os resultados. Se tudo correr bem, um novo link deve aparecer na página _Aprenda*com o título de seu novo mini-book.

Uma vez terminado seu mini-book e adicionado uma entrada no ficheiro learning.yml, abra um PR em fortran-lang/webpage (veja CONTRIBUTING).

2. Multi-page mini-books#

Os passos necessários para a publicação de um mini-book de múltiplas páginas são:

  • Crie uma nova pasta no diretório ./learn/

  • Crie um ficheiro index.md em sua nova pasta

  • Escreva o conteúdo de seu tutorial em ficheiros markdown na sua nova pasta

  • Adicione uma entrada no data/learning.yml para o seu novo mini-book

  • Abra um PR

2.1 Crie uma nova pasta para seu mini-book#

Crie uma nova pasta no diretório ./learn/ com um nome curto que descreva o tópico de seu tutorial, Ex: ./learn/coarrays/. Todas as páginas de seu mini-book devem estar contidas dentro desta pasta.

A primeira página do seu mini-book deve ser chamada index.md, então crie um ficheiro markdown na pasta do seu mini-book chamado index.md e adicione um cabeçalho no seguinte formato em todos os ficheiros markdown:

:::{toctree}
:hidden:

file1
file2
:::

Não pode ter barra no final.

Exemplo: cabeçalho para o arquivo index.md

:::{toctree}
:hidden:

learn/quickstart/index
learn/best_practices/index
learn/os_setup/index
learn/building_programs/index
learn/intrinsics/index
:::

NÃO FAÇA: permalink: /learn/coarrays/

você deve preencher o restante do arquivo index.md com uma introdução ao seu tutorial, o que pode incluir: um resumo dos conceitos, quaisquer pre-requisitos e qualquer referência a outros mini-books relacionados ou recursos úteis de terceiros.

2.2 Adicione páginas a seu mini-book#

Para cada nova página no seu mini-book, crie um novo arquivo markdown no seu diretório mini-book.

Como em mini-books de uma página, você deve usar títulos para dividir cada página em uma estrutura lógica. Cada título na página atual aparecerá no sumário.

2.3 Adicione seu mini-livro à página Aprenda#

Para adicionar seu novo mini-book à página Aprenda, você deve adicionar uma nova entrada no ficheiro de dados data/learning.yml.

Abra este ficheiro e crie uma nova entrada abaixo do campo books:, no seguinte formato:

- title: {{book-title}}
  description: {{book-description}}
  category: {{book-category}}
  link: /learn/{{book-folder}}
  pages:
    - link: /learn/{{book-folder}}/{{page1-filename}}
    - link: /learn/{{book-folder}}/{{page2-filename}}
    - link: /learn/{{book-folder}}/{{page3-filename}}

O campo título é o que ficará exibido na página Aprenda do seu mini-livro e deveria geralmente ser o mesmo do campo título no seu arquivo markdown index.md, mas isto não é necessário.

Os conteúdos do campo description também é mostrado na página Learn e deve descrever brevemente o conteúdo de seu tutorial mini-book.

O campo category deve bater com uma das categorias listadas no topo do ficheiro de dados (abaixo do campo categories:) e usado para agrupar tutoriais na página Aprenda.

o campo link deve corresponder exatamente ao campo permalink no seu arquivo index.md.

Cada campo link em pages deve corresponder exatamente ao campo permalink em cada página subsequente do seu mini-book.

Exemplo: entrada de livro no learning.yml

- title: Parallel programming with Coarrays
  description: A tutorial on parallel programming using coarrays
  category: Parallel programming
  link: /learn/coarrays
  pages:
    - link: /learn/coarrays/background
    - link: /learn/coarrays/codimension
    - link: /learn/coarrays/examples

Salve o arquivo modificado learning.yml e use o comando fortranpackage.py e refaça o build do website na sua máquina local para verificar os resultados. Se bem sucedido, um novo link deverá aparecer na página _Learn com o título do seu novo mini-book.

Uma vez finalizado seu mini-book e adicionado ao ficheiro de dados learning.yml, abra um PR em fortran-lang/fortran-lang.org (veja CONTRIBUTING para mais informações).