# Uso de GitBook ## Overview ### Organization El contenido de usuario en GitBook siempre es propiedad de una [Organización](https://docs.gitbook.com/account-management/organization-management). En nuestro caso, esa es [MuseScore.](https://app.gitbook.com/o/ZDAbKoO7AzkLkkLRGvQP) ### Space Dentro de una organización, se pueden crear [Espacios](https://docs.gitbook.com/content-editor/editor/content-structure/what-is-a-space) para diferentes contenidos. Actualmente tenemos un espacio llamado [English (US)](https://handbook.musescore.org/), 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](https://docs.gitbook.com/published-documentation/publish-a-docs-site) (también conocido como 'sitio'). Actualmente tenemos un sitio llamado [MuseScore Studio Handbook](https://app.gitbook.com/o/ZDAbKoO7AzkLkkLRGvQP/sites/site_Jnu8t). Este sitio se utilizará para el espacio de origen y todas las traducciones. Ahora que el sitio del manual está publicado, está disponible en: * (URL canónica del sitio) * [https://musescore.gitbook.io/](https://musescore.gitbook.io/musescore-studio-handbook) (alias porque está configurado como el sitio predeterminado para esta organización) * (porque hemos configurado un [dominio personalizado](https://docs.gitbook.com/publishing-documentation/custom-domain)) {% hint style="warning" %} 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). {% endhint %} ### GitHub sync El contenido dentro de un espacio se puede [sincronizar](https://docs.gitbook.com/integrations/git-sync/enabling-github-sync) 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á: 1. Editar el texto de origen en Gitbook o GitHub. 2. Subir cadenas de Github a Transifex. 3. Descargar traducciones de Transifex a Github. 4. Sincronizar traducciones de vuelta a Gitbook. {% hint style="warning" %} 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. {% endhint %} ## 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. {% hint style="info" %} Para evitar que una página específica aparezca en el \*\*sumario\*\*, vaya a las \*\*Acciones de la página (⋮)> Ocultar la página\*\*. La página aún aparecerá en los resultados de búsqueda y será accesible para cualquier persona con la URL. {% endhint %} ### 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) {% hint style="info" %} Para ocultar la barra lateral del \*\*sumario\*\* o el \*\*esquema de la página\*\*, vaya a \*\*Acciones de página (⋮)>Opciones\*\*. El sumario y el esquema de la página permanecerán visibles en otras páginas. {% endhint %} ### Pages You're viewing a page now. This page is actually a *subpage* of the [main page](https://github.com/shoogle/Handbook/blob/es/docs/about-the-handbook/broken-reference/README.md). It's also possible to have *subsubpages*, and so on. {% hint style="info" %} Por defecto, las páginas principales están \_colapsadas\_ en el \*\*sumario\*\*, por lo que no puede ver sus subpáginas. Las subpáginas se hacen visibles cuando ve la página principal o hace clic en la flecha de expansión al lado en el sumario. {% endhint %} ### 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. {% hint style="info" %} Los grupos no son páginas y, por lo tanto, no pueden contener su propio contenido. Si intenta visitar una URL grupal, Gitbook lo redirigirá a la primera página del grupo. {% endhint %} ## Editing ### Live edits Gitbook tiene un modo de [edición en vivo](https://docs.gitbook.com/content-editor/editing-content/live-edits) 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. {% hint style="warning" %} 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**. {% endhint %} ### 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 ..."*.
Example CR nameRatingComment
"shoogle's Nov 21 changes"1Default CR name. It's not descriptive enough.
"Metric modulations"2Bare minimum.
"Added images of metric modulations"3Better, but not in imperative mood.
"Add images of metric modulations"4This is in the imperative mode.
"Tempos: Add images of metric modulations"5In imperative mood and identifies the topic being edited.
{% hint style="info" %} En general, cada solicitud de cambio solo debe hacer una cosa. Esa cosa podría ser: * *"Añadir página: Ritmo"* * *"Renombrar la página 'Medida' a 'Indicación de compás '"* * *"Instalación en Linux: Eliminar detalles innecesarios"* * *"Reemplazar 'MuseScore 4' con 'MuseScore Studio' en todas las páginas"* Si al nombrar su CR, no puede evitar usar la palabra "y" (como en *"Hacer esto* **y** *hacer aquello"*), eso es una pista de que debe considerar dividir sus ediciones en múltiples CRs. {% endhint %} ### 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. {% hint style="info" %} Cada solicitud de cambio debe centrarse en un solo tema. Esto hace que sea más fácil revisar y fusionarse rápidamente, lo que reduce la probabilidad de que ocurran conflictos, y facilita la resolución de conflictos si ocurren. {% endhint %} ### 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. {% hint style="info" %} If GitHub sync is enabled and you create a new subfolder or Markdown file in the repository, you must manually add it to \`SUMMARY.md\` for GitBook to become aware of it. {% endhint %} ### 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: 1. Visite una página del [antiguo manual](https://musescore.org/en/handbook/4) y use la opción de Editar. 2. Copie el título y el texto de la fuente y péguelos en . 3. 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 \

se importan incorrectamente como encabezado 2. (\

y \

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: * [Párrafo](https://docs.gitbook.com/content-editor/blocks/paragraph) * [Encabezado](https://docs.gitbook.com/content-editor/blocks/heading) * [Lista de artículos](https://docs.gitbook.com/content-editor/blocks/unordered-list) * [Fila de tabla](https://docs.gitbook.com/content-editor/blocks/table) * Etc.
Expand me Algunos bloques pueden estar anidados dentro de otros bloques, como este párrafo, que está anidado dentro de una sección expandible.
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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://handbook.musescore.org/es/about-the-handbook/using-gitbook.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.