Uso de GitBook
Overview
Organization
El contenido de usuario en GitBook siempre es propiedad de una Organización. En nuestro caso, esa es MuseScore.
Space
Dentro de una organización, se pueden crear Espacios para diferentes contenidos. Actualmente tenemos un espacio llamado English (US), que es para el texto de origen del manual en inglés. Agregaremos más espacios más tarde; uno para cada traducción, incluido el English (GB) si queremos (o podríamos cambiar el nombre del principal a "English").
Site / Docs site
Para hacer un espacio visible para el público, debe agregarse a un Sitio de Docs (también conocido como 'sitio'). Actualmente tenemos un sitio llamado MuseScore Studio Handbook. Este sitio se utilizará para el espacio de origen y todas las traducciones.
Ahora que el sitio del manual está publicado, está disponible en:
https://musescore.gitbook.io/musescore-studio-handbook (URL canónica del sitio)
https://musescore.gitbook.io/ (alias porque está configurado como el sitio predeterminado para esta organización)
https://handbook.musescore.org/ (porque hemos configurado un dominio personalizado)
While a site is published, [**live edits**](using-gitbook.md#live-edits) on its spaces are disabled, so all changes must be made through [**change requests**](using-gitbook.md#change-request) (or on GitHub if GitHub sync is enabled).
GitHub sync
El contenido dentro de un espacio se puede sincronizar con un repositorio de GitHub. En el repositorio, el contenido se almacena como archivos de Markdown, con subcarpetas para cada página o grupo principal.
La sincronización es de dos vías, por lo que las ediciones realizadas en cualquier lugar se reflejarán en el otro. Esto nos permitirá:
Editar el texto de origen en Gitbook o GitHub.
Subir cadenas de Github a Transifex.
Descargar traducciones de Transifex a Github.
Sincronizar traducciones de vuelta a Gitbook.
While GitHub sync is enabled, [**live edits**](using-gitbook.md#live-edits) are disabled, so all changes must be made through [**change requests**](using-gitbook.md#change-request), or on GitHub via pull requests or direct commits to the repository.
Navigation
Summary / Table of contents
On the left side of the screen is a list of groups, pages and subpages in the current space. This list is the summary or table of contents. If GitHub sync is enabled, the summary appears in a file called SUMMARY.md at the root of the space.
Page outine / On this page
En el lado derecho de la pantalla, debajo de la etiqueta "EN ESTA PÁGINA", hay una lista de encabezados de la página actual. Este es el esquema de la página. Solo los encabezados Encabezado 1 y encabezados 2 se muestran en el esquema.
Heading 3 (not shown in page outline)
Pages
You're viewing a page now. This page is actually a subpage of the main page. It's also possible to have subsubpages, and so on.
Groups
Las páginas también pueden ser anidadas bajo grupos. Los nombres de grupo aparecen en LETRAS MAYÚSCULAS en el sumario.
A diferencia de las páginas principales, los grupos siempre están expandidos en el sumario y no se pueden colapsar. Además, los grupos no pueden estar anidados bajo otros grupos o páginas.
Editing
Live edits
Gitbook tiene un modo de edición en vivo donde puede editar contenido directamente sin crear una "rama" primero. En este modo, puede agregar, mover, cambiar el nombre y eliminar páginas, así como editar contenido en las páginas existentes.
Las ediciones en vivo _se deshabilitan_ mientras se publica un sitio, o mientras GitHub Sync está habilitado.
Si la edición está deshabilitada, muchos de los menús (⋮), opciones (⠿) y botones (+) mencionados en esta página no estarán disponibles hasta que comience a hacer una solicitud de cambio.
Change request (CR)
Mientras las ediciones en vivo están deshabilitadas, la única forma de realizar cambios es a través de una solicitud de cambio o "CR" o Change Request. Esto crea una "rama" personal en la que se habilita la edición. Su rama CR cubre todo el espacio, por lo que es posible editar varios archivos en un solo CR si es necesario, pero esto solo debe hacerse si los cambios están relacionados.
Cuando haya terminado de editar, puede enviar su CR para su revisión, como una solicitud de extracción de GitHub (PR). Al igual que las PRs, las solicitudes de cambio siempre deben recibir un título significativo que describe el cambio realizado. Idealmente, el título debe escribirse en el estado de ánimo imperativo, lo que significa que debería completar la oración "Esta solicitud de cambio ...".
"shoogle's Nov 21 changes"
Default CR name. It's not descriptive enough.
"Metric modulations"
Bare minimum.
"Added images of metric modulations"
Better, but not in imperative mood.
"Add images of metric modulations"
This is in the imperative mode.
"Tempos: Add images of metric modulations"
In imperative mood and identifies the topic being edited.
Resolving conflicts
Mientras espera a que se fusione su solicitud de cambio (CR), el contenido en el que se basa podría cambiar en el espacio primario (por ejemplo, si el CR de otra persona se fusiona antes que el suyo). Si esto sucede, Gitbook le pedirá que actualice su solicitud de cambio para reflejar el nuevo contenido primario.
Cuando haga clic en el botón Actualizar en su CR, Gitbook le alertará de cualquier conflicto que no pueda resolver automáticamente. Esto sucede si usted modificó un bloque (es decir, un párrafo) que también se cambió en el espacio primario. En este caso, Gitbook muestra las dos versiones del bloque lado a lado y le pide que elija uno para mantener: la versión principal o su versión modificada. Si es necesario, puede editar el bloque manualmente para incorporar elementos de ambas versiones.
Gitbook no identifica algunos tipos de conflictos. Por ejemplo, si su edición se refiere a otro contenido, como una imagen o definición existente, más arriba en la página, debe verificar que este contenido todavía exista después de actualizar su CR. Además, si una página que usted editó fue renombrada en el espacio principal, cuando actualiza el CR, puede encontrar que tiene dos copias de la página, cada una con un nombre diferente y un contenido diferente. Si esto sucede, deberá eliminar una copia de la página y potencialmente transferir parte de su contenido a la otra copia.
Creating new pages and groups
Si pasas el cursor sobre una página o grupo existente en el sumario, aparece un botón de Más acciones (⋮), que revela un menú con la opción de Insertar subpágina. Esto crea una nueva página vacía anidada en la página o grupo principal. Del mismo modo, si se pasas entre páginas en el sumario, aparece un botón Add (+), que le permite insertar una nueva página entre las páginas vecinas.
Para crear un grupo, use la opción Añadir nuevo en la parte inferior del sumario. Este botón también se puede usar para crear páginas de nivel superior (es decir, páginas que no son subpáginas de otra página o grupo). Una vez creada, puede arrastrar la nueva página o grupo a la posición correcta en el sumario.
Importing pages from the old handbook
Cuando pasas el cursor sobre una página o grupo existente en el sumario, el botón de menú Más acciones (⋮) que aparece también contiene una opción para Importar subpáginas. Usando esta opción, se puede elegir un archivo Markdown o HTML en su computadora para subir y convertir en una nueva subpágina.
Para crear el archivo Markdown o HTML:
Visite una página del antiguo manual y use la opción de Editar.
Copie el título y el texto de la fuente y péguelos en https://shoogle.github.io/gitbookify/.
Haga clic en "Convertir" y guarde el archivo resultante en algún lugar de su máquina.
Una vez en Gitbook, la página probablemente tendrá problemas, como:
Los enlaces a las páginas de otros manuales están rotas.
Las imágenes están "enlazadas directamente" de MuseScore.org en lugar de cargarse en Gitbook.
Si importa HTML en lugar de Markdown:
Los elementos <h1> se importan incorrectamente como encabezado 2. (<H2> y <H3> se importan correctamente).
Estos problemas deben solucionarse manualmente, pero aún no necesitamos hacerlo porque haremos otra importación más tarde, después de que el antiguo manual haya sido congelado. Antes de eso, necesitamos acostumbrarnos a GitBook nosotros mismos y luego informar a la comunidad sobre la migración.
Editing a page
GitBook utiliza un editor basado en bloques algo similar a Squarespace o versiones recientes de WordPress.
Content blocks
Se crea un nuevo bloque para cada:
Etc.
Si pasa el cursor sobre un bloque existente, esto revela un botón más (+) para agregar un nuevo bloque, así como un botón de opciones (⠿) con opciones para el bloque actual. El botón Opciones también se puede arrastrar para reposicionar el bloque en la página.
Otra forma de crear un bloque es editar un bloque existente y presionar Enter o Return. Esto generalmente crea un nuevo bloque de párrafos debajo del primero, pero podría crear algo más, como un nuevo elemento lista o fila de tabla. Si es un elemento de lista, puede presionar Tab y Mayús.+Tab para cambiar el nivel de anidación, y Enter o Return. para convertirlo a un párrafo normal (esto solo funciona mientras el bloque está vacío).
Mientras se edita un bloque vacío, se puede escribir una barra inclinada (/) para convertirlo rápidamente en un tipo diferente de bloque. Si el bloque no está vacío, la escritura de la barra (/) revela opciones para insertar contenido en línea.
Last updated
Was this helpful?