# Usando o GitBook

## Overview

### Organization

O conteúdo do usuário no GitBook sempre pertence a uma [organização](https://docs.gitbook.com/account-management/organization-management). No nosso caso, é o [MuseScore](https://app.gitbook.com/o/ZDAbKoO7AzkLkkLRGvQP).

### Space

Dentro de uma organização, você pode criar [Espaços](https://docs.gitbook.com/content-editor/editor/content-structure/what-is-a-space) para diferentes conteúdos. Atualmente, temos um espaço chamado [Inglês (EUA)](https://handbook.musescore.org/), que é para o texto original em inglês do manual. Adicionaremos mais espaços posteriormente; um para cada tradução, incluindo Inglês (GB), se desejarmos (ou podemos renomear o principal para "Inglês").

### Site / Docs site

Para tornar um espaço visível ao público, ele deve ser adicionado a um site [Docs](https://docs.gitbook.com/published-documentation/publish-a-docs-site) (também conhecido como "site"). Atualmente, temos um site chamado [Manual do MuseScore Studio](https://app.gitbook.com/o/ZDAbKoO7AzkLkkLRGvQP/sites/site_Jnu8t). Este site será usado para o espaço de origem e todas as traduções.

Agora que o site do manual foi publicado, ele está disponível em:

* <https://musescore.gitbook.io/musescore-studio-handbook> (URL do site canônico)
* [https://musescore.gitbook.io/](https://musescore.gitbook.io/musescore-studio-handbook) (alias porque é definido como o site padrão para esta organização)
* <https://handbook.musescore.org/> (porque configuramos um [domínio 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

O conteúdo dentro de um espaço pode ser [sincronizado](https://docs.gitbook.com/integrations/git-sync/enabling-github-sync) com um repositório do GitHub. No repositório, o conteúdo é armazenado como arquivos Markdown, com subpastas para cada **página** pai ou **grupo** .

A sincronização é bidirecional; então as edições feitas em qualquer um dos lugares serão refletidas no outro. Isso nos permitirá:

1. Editar o texto fonte no GitBook ou GitHub.
2. Carregar strings do GitHub para o Transifex.
3. Baixar traduções do Transifex para o GitHub.
4. Sincronizar as traduções de volta para o 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 uma página específica apareça no \*\*resumo\*\*, acesse \*\*Ações da página (⋮) > Ocultar página\*\*.

A página continuará aparecendo nos resultados da pesquisa e poderá ser acessada por qualquer pessoa com a URL.
{% endhint %}

### Page outine / On this page

No lado direito da tela, sob o rótulo "NESTE PÁGINA", há uma lista de títulos da página atual. Este é o **esboço da página**. Apenas os títulos de nível 1 e 2 são exibidos no esboço.

#### Heading 3 (not shown in page outline)

{% hint style="info" %}
Para ocultar a barra lateral do \*\*resumo\*\* ou do \*\*esboço da página\*\*, acesse \*\*Ações da página (⋮) > Opções\*\*.

O resumo e o esboço da página permanecerão visíveis nas outras 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/pt_BR/docs/about-the-handbook/broken-reference/README.md). It's also possible to have *subsubpages*, and so on.

{% hint style="info" %}
Por padrão, as páginas principais são \_recolhidas\_ no \*\*resumo\*\*. Portanto, você não pode ver suas subpáginas. As subpáginas ficam visíveis quando você visualiza a página principal ou clica na seta de expansão ao lado dela no resumo.
{% endhint %}

### Groups

As páginas também podem ser aninhadas em grupos. Os nomes dos grupos aparecem em LETRAS MAIÚSCULAS no resumo.

Ao contrário das páginas principais, os grupos são sempre *expandidos* no resumo e não podem ser recolhidos. Além disso, os grupos não podem ser aninhados em outros grupos ou páginas.

{% hint style="info" %}
Grupos não são páginas e, portanto, não podem conter conteúdo próprio. Se você tentar visitar a URL de um grupo, o GitBook o redirecionará para a primeira página do grupo.
{% endhint %}

## Editing

### Live edits

O GitBook possui um modo de [edição ativa](https://docs.gitbook.com/content-editor/editing-content/live-edits), onde você pode editar o conteúdo diretamente, sem precisar criar uma "ramificação" primeiro. Nesse modo, você pode adicionar, mover, renomear e excluir páginas, além de editar o conteúdo de páginas existentes.

{% hint style="warning" %}
As edições ativas ficam \_desabilitadas\_ enquanto um site estiver publicado ou enquanto a sincronização do GitHub estiver ativada.

Se a edição estiver desabilitada, muitos dos **menus (⋮)**, **opções (⠿)** e **botões (+)** mencionados nesta página não estarão disponíveis até que você comece a fazer uma **solicitação de alteração**.
{% endhint %}

### Change request (CR)

Enquanto as edições ativas estejam desabilitadas, a única maneira de fazer alterações é por meio de uma [solicitação de alteração](https://docs.gitbook.com/collaboration/change-requests), ou "CR". Isso cria uma "ramificação" pessoal na qual a edição é habilitada. Sua ramificação de CR abrange todo o espaço. Portanto, é possível editar vários arquivos em uma única CR, se necessário, mas isso só deve ser feito se as alterações forem relacionadas.

Após terminar a edição, você pode enviar sua CR para revisão, como uma solicitação de pull request (PR) do GitHub. Assim como as PRs, as solicitações de mudança devem sempre receber um título significativo que descreva a alteração realizada. O ideal é que o título seja escrito no modo imperativo, o que significa que deve completar a frase &#x31;*“Esta solicitação de mudança irá...”*.

<table><thead><tr><th>Example CR name</th><th data-type="rating" data-max="5">Rating</th><th>Comment</th></tr></thead><tbody><tr><td>"<em>shoogle's Nov 21 changes"</em></td><td>1</td><td>Default CR name. It's not descriptive enough.</td></tr><tr><td>"<em>Metric modulations"</em></td><td>2</td><td>Bare minimum.</td></tr><tr><td>"<em>Added images of metric modulations"</em></td><td>3</td><td>Better, but not in imperative mood.</td></tr><tr><td>"<em>Add images of metric modulations"</em></td><td>4</td><td>This is in the imperative mode.</td></tr><tr><td>"<em>Tempos: Add images of metric modulations"</em></td><td>5</td><td>In imperative mood and identifies the topic being edited.</td></tr></tbody></table>

{% hint style="info" %}
Em geral, cada solicitação de mudança deve fazer apenas uma coisa. Essa coisa pode ser:

* *"Adicionar página: Ritmo"*
* *"Renomear página 'Métricas' para 'Fórmulas de compasso'"*
* *"Instação no Linux: Remover detalhes desnecessários"*
* *"Substituir 'MuseScore 4' por 'MuseScore Studio' em todas as páginas"*

Ao nomear sua CR, se você não puder evitar o uso da palavra "e" (como em *"Faça isso* **e** *faça aquilo"*), isso é um sinal de que você deve considerar dividir suas edições em várias CRs.
{% endhint %}

### Resolving conflicts

Enquanto você aguarda a mesclagem da sua solicitação de alteração (CR), o conteúdo em que ela se baseia pode mudar no espaço primário (e.g. se a CR de outra pessoa for mesclada antes da sua). Se isso acontecer, o GitBook solicitará que você **atualize sua solicitação de alteração** para refletir o novo conteúdo primário.

Ao clicar no botão **Update** na sua resposta de resposta, o GitBook alertará sobre quaisquer conflitos que não consiga resolver automaticamente. Isso acontece se você alterou um **bloco** (i.e. um parágrafo) que também foi alterado no espaço primário. Nesse caso, o GitBook exibe as duas versões do bloco lado a lado e solicita que você escolha uma para manter: a versão primária ou a versão alterada. Se necessário, você pode editar o bloco manualmente para incorporar elementos de ambas as versões.

Alguns tipos de conflito não são identificados pelo GitBook. Por exemplo, se a sua edição fizer referência a outro conteúdo, como uma imagem ou definição existente em um nível superior da página, você deve verificar se esse conteúdo ainda existe após atualizar a sua CR. Além disso, se uma página editada foi renomeada no espaço primário, ao atualizar a CR, você poderá descobrir que restam duas cópias da página, cada uma com um nome e conteúdo diferentes. Se isso acontecer, você terá que excluir uma cópia da página e, potencialmente, transferir parte do seu conteúdo para a outra cópia.

{% hint style="info" %}
Cada solicitação de alteração deve se concentrar em um único tópico. Isso facilita a revisão e a fusão rápidas, o que reduz a probabilidade de conflitos e facilita a resolução de conflitos, caso ocorram.
{% endhint %}

### Creating new pages and groups

Se você passar o cursor sobre uma página ou grupo existente no **resumo**, um botão **Mais ações (⋮)** aparecerá, revelando um menu com a opção **Inserir subpágina**. Isso cria uma nova página vazia aninhada sob a página ou grupo pai. Da mesma forma, se você passar o cursor *entre* páginas no resumo, um botão **Adicionar (+)** aparecerá, permitindo inserir uma nova página entre páginas vizinhas.

Para criar um grupo, use a opção **Adicionar novo** na parte inferior do resumo. Este botão também pode ser usado para criar páginas de nível superior (ou seja, páginas que não são subpáginas ou grupo). Após a criação, você pode arrastar a nova página ou grupo para a posição correta no resumo.

{% 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

Ao passar o cursor sobre uma página ou grupo existente no resumo, o botão de menu **Mais ações (⋮)** que aparece também contém uma opção para **Importar subpáginas**. Usando esta opção, você pode escolher um arquivo Markdown ou HTML no seu computador para carregar e transformar em uma nova subpágina.

Para criar o arquivo Markdown ou HTML:

1. Visite uma página do [antigo manual](https://musescore.org/en/handbook/4) e use a opção Editar.
2. Copie o título e o texto fonte e cole-os em <https://shoogle.github.io/gitbookify/>.
3. Clique em "Converter" e salve o arquivo resultante em algum lugar da sua máquina.

Uma vez no GitBook, a página provavelmente terá problemas, como:

* Links para outras páginas do manual quebrados.
* As imagens estão "linkadas" do MuseScore.org em vez de enviadas para o GitBook.
* Se estiver importando HTML em vez de Markdown:
  * Os elementos \<h1> são importados incorretamente como Título 2. (\<h2> e \<h3> são importados corretamente.)

Esses problemas precisam ser corrigidos manualmente, mas não precisamos fazer isso ainda, pois faremos outra importação mais tarde, depois que o manual antigo for congelado. Antes disso, precisamos nos acostumar com o GitBook e, então, informar a comunidade sobre a migração.

### Editing a page

O GitBook usa um editor baseado em blocos semelhante ao Squarespace e versões recentes do Wordpress.

#### Content blocks

Um novo bloco é criado para cada:

* [Parágrafo](https://docs.gitbook.com/content-editor/blocks/paragraph)
* [Título](https://docs.gitbook.com/content-editor/blocks/heading)
* [Item de lista](https://docs.gitbook.com/content-editor/blocks/unordered-list)
* [Linha de tabela](https://docs.gitbook.com/content-editor/blocks/table)
* Etc.

<details>

<summary>Expand me</summary>

Alguns blocos podem ser aninhados dentro de outros blocos, como este parágrafo, que está aninhado dentro de uma seção expansível.

</details>

Ao passar o cursor sobre um bloco existente, será exibido um botão **mais (+)** para adicionar um novo bloco, bem como um botão **opções (⠿)** com opções para o bloco atual. O botão de opções também pode ser arrastado para reposicionar o bloco na página.

Outra maneira de criar um bloco é editar um bloco existente e pressionar **Enter** ou **Return**. Isso geralmente cria um novo bloco de parágrafo abaixo do primeiro, mas pode criar algo diferente, como um novo item de lista ou linha de tabela. Se for um item de lista, você pode pressionar **Tab** e **Shift+Tab** para alterar o nível de aninhamento e **Enter** ou **Return** para convertê-lo em um parágrafo normal (isso só funciona enquanto o bloco estiver vazio).

Ao editar um bloco vazio, você pode **digitar uma barra (/)** para convertê-lo rapidamente em um tipo diferente de bloco. Se o bloco não estiver vazio, digitar uma **barra (/)** revelará opções para inserir conteúdo em linha.


---

# 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/pt_br/about-the-handbook/using-gitbook.md?ask=<question>
```

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.