GitBookin käyttäminen

Overview

Organization

GitBookin käyttäjäsisältö on aina organisaation omistuksessa. Meidän tapauksessamme se on MuseScore.

Space

Organisaation sisällä voit luoda Tiloja erilaiselle sisällölle. Meillä on tällä hetkellä yksi tila nimeltä Englanti (US), 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 (eli 'sivustolle'). Meillä on tällä hetkellä yksi sivusto nimeltä MuseScore Studio Handbook. 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/ (alias, koska se on asetettu organisaation oletussivustoksi)

• https://handbook.musescore.org/ (koska loimme mukautetun verkkotunnuksen)

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

Tilan sisältö voidaan synkronoida 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.

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.

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

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)

Voit piilottaa **yhteenvedon** tai **sivun jäsennyksen** sivupalkin valitsemalla **Sivutoiminnot (⋮) > Asetukset**.

Yhteenveto ja sivun jäsennys pysyvät näkyvissä muilla sivuilla.

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.

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.

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.

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.

Editing

Live edits

GitBookissa on reaaliaikainen muokkaustila, 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öä.

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.

Change request (CR)

Vaikka reaaliaikaiset muokkaukset on poistettu käytöstä, ainoa tapa tehdä muutoksia on muutospyynnön 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ö...".

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.

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.

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.

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.

Creating new pages and groups

Jos viet hiiren osoittimen 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.

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

Kun viet hiiren osoittimen 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 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

• Otsikko

• Luettelon kohde

• Taulukon rivi

• Jne.

Expand me

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

Jos viet osoittimen 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.