Tutoriales de mini-libros en fortran-lang.org#

Esta guía cubrirá cómo escribir tutoriales de minilibros para la sección Aprender de https://fortran-lang.org.

See contributing guidelines for general guidance on contributing to https://fortran-lang.org.

0. Mini-book formats#

Los minilibros están diseñados para ser en su mayoría tutoriales autónomos sobre una característica particular del lenguaje Fortran.

Hay dos tipos de formato de minilibro:

  • Página única: todo el contenido se escribe en un solo archivo markdown y se muestra en una sola página web;

  • Multipágina: el contenido del tutorial se escribe en varios archivos Markdown y se muestra como una colección de páginas web.

La elección del tipo de libro depende de la extensión de su contenido y de cómo pretenda estructurarlo.

Considere la tabla de contenido que se producirá:

  • Los libros de una sola página tienen un nivel de navegación: un enlace para cada encabezado en el tutorial en inpage-toc (toc en el lado derecho de la página).

  • Los libros de varias páginas tienen dos niveles de navegación: un enlace para cada encabezado del tutorial en inpage-toc (toc en el lado derecho de la página) y sidebar-toc (toc en el lado izquierdo del página que muestra diferentes páginas en el directorio).

Los minilibros de una sola página son más simples de producir y deben usarse para temas breves o tutoriales breves que eventualmente se incluirán en un libro de varias páginas más completo.

Se recomiendan libros de varias páginas para tutoriales más completos que se pueden estructurar con un subtema por página.

El resto de esta guía se divide en dos secciones, una para los tipos de libros de una sola página y de varias páginas.

1. Single-page mini-book#

Los pasos necesarios para publicar un minilibro de una sola página son:

  • Crear un nuevo documento en markdown en el directorio ./learn

  • Escriba el contenido de su tutorial

  • Agregue una entrada a data/learning.yml para su nuevo minilibro

  • Abrir una solicitud de integración

1.1 Escribiendo tu mini-libro en markdown#

En mini-libros de una sola página, su tutorial estará enteramente en un solo documento de markdown.

Primero, cree un nuevo documento en markdown en el directorio ./learn/{{nombre_del_mini_libro}} con la extensión .md y un nombre corta que describa el tema de su tutorial de manera concisa, por ejemplo: ./learn/{{nombre_del_mini_libro}}/rutinas_input_output.md.

Abra el nuevo archivo markdown y añada una entrada en el índice de contenidos en aprender.md utilizando el siguiente formato:

:::{toctree}
:hidden:

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

Reemplace {{nombre-del-libro}} con el nombre de su archivo markdown excluyendo la extensión .md. No debe de haber una diagonal (/) al final .

Ejemplo: encabezado

:::{toctree}
:hidden:

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

INCORRECTO: permalink: /aprender/es_datos.md

INCORRECTO: permalink: /aprender/es_datos/

Ya puede escribir el resto del tutorial en markdown; vea cómo implementar el estilo markdown en Sintaxis Kramdown.

1.2 Estructurando tu minilibro con encabezados#

Debe usar encabezados para dividir su minilibro de una sola página en una estructura lógica. Cada encabezado aparecerá en la tabla de contenido con hipervínculos.

En markdown, los encabezados se pueden escribir:

# Heading level 1

## Heading level 2

### Heading level 3

#### Heading level 4

##### Heading level 5

###### Heading level 6

Nota: asegúrese de incluir una línea en blanco antes de su título.

1.3 Agregue su mini libro a la página de aprendizaje#

Para agregar su nuevo minilibro a la página Learn, debe agregar una nueva entrada en el archivo de datos data/learning.yml.

Abra este archivo y cree una nueva entrada en el campo books: con el siguiente formato:

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

El campo de título es lo que será mostrado en la página Aprende en su mini-libro y, normalmente, debería ser el mismo que el campo de título en su archivo de Markdown, sin embargo esto no es obligatorio.

El contenido del campo descripción también se muestra en la página Aprender y debe resumir brevemente el contenido del tutorial de su mini libro.

El campo categoría debe coincidir con una de las categorías enumeradas en la parte superior del archivo de datos (bajo el campo categorías:) y se usa para agrupar tutoriales en la página de aprendizaje.

El campo link debe de corresponder exactamente con el campo permalink en su documento de Markdown.

Ejemplo: entrada de libro 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

Guarde el archivo de datos learning.yml modificado y ejecute fortran_package.py y reconstruya el sitio web en su máquina local para verificar los resultados. Si tiene éxito, debería aparecer un nuevo enlace en la página _Learn* con el título de su nuevo mini-libro.

Once you have completed your mini-book and added an entry to the learning.yml data file, open a pull request at fortran-lang/webpage (see CONTRIBUTING).

2. Multi-page mini-books#

Los pasos necesarios para publicar un mini-libro de varias páginas son:

  • Crear un nuevo fólder en el directorio ./learn/

  • Cree un archivo index.md en el fólder nuevo

  • Escriba el contenido de su tutorial en archivos markdown en el fólder nuevo

  • Agregue una entrada a data/learning.yml para su nuevo minilibro

  • Abrir una solicitud de integración

2.1 Crear un nuevo fólder para su mini-libro#

Create a new folder in the ./learn/ directory with a short name that concisely describes the topic of your tutorial, e.g. ./learn/coarrays/. All pages of your mini-book will be contained within this folder.

The first page of your mini-book should be called index.md, so create a new markdown file in your mini-book folder called index.md, and add a toc in the following format in all the markdown files:

:::{toctree}
:hidden:

file1
file2
:::

There should be no trailing slash.

Example: toc for index.md

:::{toctree}
:hidden:

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

NOT: permalink: /learn/coarrays/

you should populate the remainder of index.md with an introduction to your mini-book tutorial which may include: a summary of the concepts covered; any prerequisites; and any references to other related mini-books or useful third-party resources.

2.2 Add pages to your mini-book#

For each new page in your mini-book, create a new markdown file in your mini-book folder.

As with single-page mini-books, you should use headings to break-up each page into a logical structure. Each heading on the current page will show up in the inpage table-of-contents.

2.3 Add your mini-book to the Learn page#

Para agregar su nuevo minilibro a la página Learn, debe agregar una nueva entrada en el archivo de datos data/learning.yml.

Abra este archivo y cree una nueva entrada en el campo books: con el siguiente 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}}

The title field is what will be displayed on the Learn page for your mini-book and should generally be the same as the title field in your index.md markdown file, but this isn’t required.

El contenido del campo descripción también se muestra en la página Aprender y debe resumir brevemente el contenido del tutorial de su mini libro.

El campo categoría debe coincidir con una de las categorías enumeradas en la parte superior del archivo de datos (bajo el campo categorías:) y se usa para agrupar tutoriales en la página de aprendizaje.

The top-level link field should exactly match the permalink field in your index.md file.

Each link field under pages should exactly match the permalink field in each of your subsequent mini-book pages.

Ejemplo: entrada de libro 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

Save the modified learning.yml data file and run fortranpackage.py and rebuild the website on your local machine to check the results. If successful, a new link should appear on the _Learn page with the title of your new mini-book.

Once you have completed your mini-book and added an entry to the learning.yml data file, open a pull request at fortran-lang/fortran-lang.org (see CONTRIBUTING).