Usando o GitBook

Overview

Organization

O conteúdo do usuário no GitBook sempre pertence a uma organização. No nosso caso, é o MuseScore.

Space

Dentro de uma organização, você pode criar Espaços para diferentes conteúdos. Atualmente, temos um espaço chamado Inglês (EUA), 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 (também conhecido como "site"). Atualmente, temos um site chamado Manual do MuseScore Studio. 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/ (alias porque é definido como o site padrão para esta organização)

• https://handbook.musescore.org/ (porque configuramos um domínio 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

O conteúdo dentro de um espaço pode ser sincronizado 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.

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.

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.

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)

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.

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.

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.

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.

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.

Editing

Live edits

O GitBook possui um modo de edição ativa, 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.

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.

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, 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 1“Esta solicitação de mudança irá...”.

Example CR name	Rating	Comment
"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.

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.

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.

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.

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.

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.

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

• Título

• Item de lista

• Linha de tabela

• Etc.

Expand me

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

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.