# GitBookin käyttäminen

## Overview

### Organization

GitBookin käyttäjäsisältö on aina [organisaation](https://docs.gitbook.com/account-management/organization-management) omistuksessa. Meidän tapauksessamme se on [MuseScore](https://app.gitbook.com/o/ZDAbKoO7AzkLkkLRGvQP).

### Space

Organisaation sisällä voit luoda [Tiloja](https://docs.gitbook.com/content-editor/editor/content-structure/what-is-a-space) erilaiselle sisällölle. Meillä on tällä hetkellä yksi tila nimeltä [Englanti (US)](https://handbook.musescore.org/), joka on käsikirjan englanninkieliselle lähdetekstille. Lisäämme lisää tiloja myöhemmin; yhden jokaiselle käännökselle, mukaan lukien englanti (GB), jos haluamme (tai voimme nimetä päätilan uudelleen "Englanti").

### Site / Docs site

Jotta tila olisi julkisesti nähtävissä, se on lisättävä [Docs-sivustolle](https://docs.gitbook.com/published-documentation/publish-a-docs-site) (eli 'sivustolle'). Meillä on tällä hetkellä yksi sivusto nimeltä [MuseScore Studio Handbook](https://app.gitbook.com/o/ZDAbKoO7AzkLkkLRGvQP/sites/site_Jnu8t). Tätä sivustoa käytetään lähdekooditilaan ja kaikkiin käännöksiin.

Nyt kun käsikirjan verkkosivusto on julkaistu, se on saatavilla osoitteessa:

* <https://musescore.gitbook.io/musescore-studio-handbook> (kanoninen sivuston URL-osoite)
* [https://musescore.gitbook.io/](https://musescore.gitbook.io/musescore-studio-handbook) (alias, koska se on asetettu organisaation oletussivustoksi)
* <https://handbook.musescore.org/> (koska loimme [mukautetun verkkotunnuksen](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

Tilan sisältö voidaan [synkronoida](https://docs.gitbook.com/integrations/git-sync/enabling-github-sync) GitHub-arkiston kanssa. Arkistossa sisältö tallennetaan Markdown-tiedostoina, ja jokaisella **pääsivulla** tai **ryhmällä** on alakansiot.

Synkronointi on kaksisuuntainen, joten kummassakin paikassa tehdyt muokkaukset näkyvät toisessa. Tämä mahdollistaa seuraavat:

1. Muokkaa lähdetekstiä GitBookissa tai GitHubissa.
2. Lataa merkkijonoja GitHubista Transifexiin.
3. Lataa käännöksiä Transifexistä GitHubiin.
4. Synkronoi käännökset takaisin GitBookiin.

{% 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" %}
Jos haluat estää tietyn sivun näkymisen \*\*yhteenvedossa\*\*, siirry kohtaan \*\*Sivutoiminnot (⋮) > Piilota sivu\*\*.

Sivu näkyy edelleen hakutuloksissa ja on kaikkien URL-osoitteen tietävien käytettävissä.
{% endhint %}

### Page outine / On this page

Näytön oikealla puolella, "TÄLLÄ SIVULLA" -otsikon alla, on luettelo nykyisen sivun otsikoista. Tämä on **sivun jäsennys**. Jäsennyksessä näkyvät vain Otsikko 1 ja Otsikko 2 -otsikot.

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

{% hint style="info" %}
Voit piilottaa \*\*yhteenvedon\*\* tai \*\*sivun jäsennyksen\*\* sivupalkin valitsemalla \*\*Sivutoiminnot (⋮) > Asetukset\*\*.

Yhteenveto ja sivun jäsennys pysyvät näkyvissä muilla sivuilla.
{% endhint %}

### Pages

You're viewing a page now. This page is actually a *subpage* of the [main page](https://github.com/shoogle/Handbook/blob/fi/docs/about-the-handbook/broken-reference/README.md). It's also possible to have *subsubpages*, and so on.

{% hint style="info" %}
Pääsivut on oletuksena \_kutistettu\_ \*\*yhteenvedossa\*\*, joten niiden alasivuja ei näy. Alasivut tulevat näkyviin, kun tarkastelet pääsivua tai napsautat sen vieressä olevaa laajennusnuolta yhteenvedossa.
{% endhint %}

### Groups

Sivuja voidaan myös sijoittaa sisäkkäin ryhmien alle. Ryhmien nimet näkyvät yhteenvedossa ISOILLA KIRJAIMILLA.

Toisin kuin pääsivut, ryhmät *laajennetaan* aina yhteenvedossa, eikä niitä voida kutistaa. Ryhmiä ei myöskään voi sijoittaa sisäkkäin muiden ryhmien tai sivujen alle.

{% hint style="info" %}
Ryhmät eivät ole sivuja, joten ne eivät voi sisältää omaa sisältöä. Jos yrität käydä ryhmän URL-osoitteessa, GitBook ohjaa sinut ryhmän ensimmäiselle sivulle.
{% endhint %}

## Editing

### Live edits

GitBookissa on [reaaliaikainen muokkaustila](https://docs.gitbook.com/content-editor/editing-content/live-edits), jossa voit muokata sisältöä suoraan luomatta ensin "haaraa". Tässä tilassa voit lisätä, siirtää, nimetä uudelleen ja poistaa sivuja sekä muokata nykyisten sivujen sisältöä.

{% hint style="warning" %}
Live-muokkaukset \_eivät ole käytössä\_, kun sivusto on julkaistu tai GitHub-synkronointi on käytössä.

Jos muokkaus on poistettu käytöstä, monet tällä sivulla mainituista **valikoista (⋮)**, **vaihtoehdoista (⠿)** ja **painikkeista (+)** eivät ole käytettävissä, ennen kuin aloitat **muutospyynnön** tekemisen.
{% endhint %}

### Change request (CR)

Vaikka reaaliaikaiset muokkaukset on poistettu käytöstä, ainoa tapa tehdä muutoksia on [muutospyynnön](https://docs.gitbook.com/collaboration/change-requests) eli 'CR' kautta. Tämä luo henkilökohtaisen 'haaran', jossa muokkaus on käytössä. CR-haarasi kattaa koko tilan, joten useita tiedostoja voi muokata yhdessä CR:ssä tarvittaessa, mutta tämä tulisi tehdä vain, jos muutokset liittyvät toisiinsa.

Kun olet muokannut tiedoston valmiiksi, voit lähettää muutospyynnön tarkistettavaksi GitHub-pull-pyynnön (PR) tavoin. Kuten PR-pyynnöille, muutospyynnöille tulisi aina antaa merkityksellinen otsikko, joka kuvaa tehtyä muutosta. Ihannetapauksessa otsikko tulisi kirjoittaa käskymuodossa, mikä tarkoittaa, että sen tulisi täydentää lause *"Tämä muutospyyntö..."*.

<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" %}
Yleisesti ottaen jokaisen muutospyynnön tulisi tehdä vain yksi asia. Se asia voi olla:

* *"Lisää sivu: Rytmi"*
* *"Nimeä 'Mitat'-sivu uudelleen 'Tahtilajit'-sivuksi"*
* *"Asennus Linuxiin: Poista tarpeettomat yksityiskohdat"*
* *"Korvaa 'MuseScore 4' tekstillä 'MuseScore Studio' kaikilla sivuilla"*

Jos et voi välttää sanan "ja" käyttöä CR:n nimeämisessä (kuten *"Tee näin* **ja** *tee noin"*), se on vihje siitä, että harkitse muokkausten jakamista sen sijaan useisiin CR:iin.
{% endhint %}

### Resolving conflicts

Odottaessasi muutospyyntösi (CR) yhdistämistä, sen perustana oleva sisältö voi muuttua ensisijaisessa tilassa (esim. jos jonkun toisen CR yhdistetään ennen sinun pyyntöäsi). Jos näin tapahtuu, GitBook kehottaa sinua **päivittämään muutospyyntösi** vastaamaan uutta ensisijaista sisältöä.

Kun napsautat **Päivitä**-painiketta CR:ssäsi, GitBook ilmoittaa sinulle ristiriidoista, joita se ei pysty ratkaisemaan automaattisesti. Näin tapahtuu, jos olet muuttanut **lohkoa** (eli kappaletta), jota on muutettu myös ensisijaisessa tilassa. Tässä tapauksessa GitBook näyttää lohkon kaksi versiota rinnakkain ja pyytää sinua valitsemaan toisen säilytettäväksi: ensisijaisen version tai muutetun version. Voit tarvittaessa muokata lohkoa manuaalisesti sisällyttääksesi molempien versioiden elementtejä.

GitBook ei tunnista joitakin ristiriitatyyppejä. Jos esimerkiksi muokkauksesi viittaa muuhun sisältöön, kuten sivulla ylempänä olevaan kuvaan tai määritelmään, sinun tulee tarkistaa, että tämä sisältö on edelleen olemassa CR:n päivittämisen jälkeen. Jos muokkaamasi sivu on nimetty uudelleen ensisijaisessa tilassa, saatat CR:ää päivittäessäsi huomata, että sinulle jää sivusta kaksi kopiota, joilla molemmilla on eri nimi ja eri sisältö. Jos näin käy, sinun on poistettava toinen kopio sivusta ja mahdollisesti siirrettävä osa sen sisällöstä toiseen kopioon.

{% hint style="info" %}
Jokaisen muutospyynnön tulisi keskittyä yhteen aiheeseen. Tämä helpottaa niiden tarkistamista ja yhdistämistä nopeasti, mikä vähentää ristiriitojen esiintymisen todennäköisyyttä ja helpottaa niiden ratkaisemista, jos niitä ilmenee.
{% endhint %}

### Creating new pages and groups

Jos viet hiiren kohdistimen **yhteenvedossa** olevan sivun tai ryhmän päälle, näkyviin tulee **Lisää toimintoja (⋮)** -painike, joka paljastaa valikon, jossa on **Lisää alasivu** -vaihtoehto. Tämä luo uuden tyhjän sivun pääsivun tai ryhmän alle. Vastaavasti, jos viet hiiren osoittimen yhteenvedon sivujen *välillä*, näkyviin tulee **Lisää (+)** -painike, jonka avulla voit lisätä uuden sivun viereisten sivujen väliin.

Luodaksesi ryhmän, käytä yhteenvedon alareunassa olevaa **Lisää uusi** -vaihtoehtoa. Tätä painiketta voidaan käyttää myös ylemmän tason sivujen luomiseen (eli sivujen, jotka eivät ole toisen sivun tai ryhmän alasivuja). Kun uusi sivu tai ryhmä on luotu, voit vetää sen oikeaan paikkaan yhteenvedossa.

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

Kun viet hiiren kohdistimen yhteenvedossa olevan sivun tai ryhmän päälle, näkyviin tuleva **Lisää toimintoja (⋮)** -valikkopainike sisältää myös vaihtoehdon **Tuo alasivut**. Tämän vaihtoehdon avulla voit valita tietokoneeltasi Markdown- tai HTML-tiedoston ladattavaksi ja muuttamiseksi uudeksi alasivuksi.

Markdown- tai HTML-tiedoston luominen:

1. Siirry [vanhan käsikirjan](https://musescore.org/en/handbook/4) sivulle ja käytä Muokkaa-vaihtoehtoa.
2. Kopioi otsikko ja lähdeteksti ja liitä ne osoitteeseen <https://shoogle.github.io/gitbookify/>.
3. Klikkaa "Muunna" ja tallenna tuloksena oleva tiedosto jonnekin koneellesi.

Kun sivu on GitBookissa, sillä on todennäköisesti ongelmia, kuten:

* Linkit muille käsikirjan sivuille ovat rikki.
* Kuvat on "pikalinkitty" MuseScore.orgista sen sijaan, että ne olisi ladattu GitBookiin.
* Jos tuot HTML:ää Markdownin sijaan:
  * \<h1>-elementit on tuotu virheellisesti Otsikkona 2. (\<h2> ja \<h3> on tuotu oikein.)

Nämä ongelmat täytyy korjata manuaalisesti, mutta meidän ei tarvitse tehdä sitä vielä, koska teemme uuden tuonnin myöhemmin, kun vanha käsikirja on jäädytetty. Ennen sitä meidän on itse totuteltava GitBookiin ja tiedotettava sitten yhteisölle siirtymisestä.

### Editing a page

GitBook käyttää lohkopohjaista editoria, joka on hieman samanlainen kuin Squarespace ja WordPressin uudemmat versiot.

#### Content blocks

Uusi lohko luodaan jokaiselle:

* [Kappale](https://docs.gitbook.com/content-editor/blocks/paragraph)
* [Otsikko](https://docs.gitbook.com/content-editor/blocks/heading)
* [Luettelon kohde](https://docs.gitbook.com/content-editor/blocks/unordered-list)
* [Taulukon rivi](https://docs.gitbook.com/content-editor/blocks/table)
* Jne.

<details>

<summary>Expand me</summary>

Jotkin lohkot voidaan sijoittaa sisäkkäin toisten lohkojen sisään, kuten tämä kappale, joka on sisäkkäin laajennettavan osan sisällä.

</details>

Jos viet kohdistimen nykyisen lohkon päälle, näkyviin tulee **plus (+)** -painike uuden lohkon lisäämiseksi sekä **asetuspainike (⠿)**, jossa on nykyisen lohkon asetukset. Asetuspainiketta voi myös vetää lohkon siirtämiseksi sivulla.

Toinen tapa luoda lohko on muokata nykyistä lohkoa ja painaa **Enter-** tai **Return-näppäintä**. Tämä luo yleensä uuden kappalelohkon ensimmäisen lohkon alle, mutta se saattaa luoda myös jotain muuta, kuten uuden luettelokohdan tai taulukkorivin. Jos kyseessä on luettelokohta, voit painaa **Tab-** ja **Shift+Tab-näppäinyhdistelmää** muuttaaksesi sisäkkäisyyden tasoa ja **Enter-** tai **Return-näppäinyhdistelmää** muuntaaksesi sen normaaliksi kappaleeksi (tämä toimii vain, kun lohko on tyhjä).

Kun muokkaat tyhjää lohkoa, voit **kirjoittaa vinoviivan (/)** muuntaaksesi sen nopeasti erityyppiseksi lohkoksi. Jos lohko ei ole tyhjä, **vinoviivan (/)** kirjoittaminen näyttää vaihtoehtoja tekstinsisäisen sisällön lisäämiseksi.


---

# 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/fi/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.