Scribble ja Github - ohjeita

Mikä ihmeen Scribble ja mikä ihmeen Github?

Aloitin tekemään Koodausta kouluun - käsikirjasivustoa. Etsin työkalua, jolla tehdä nettisivut, joihin upottaa koodiesimerkkejä Racket-kielellä. Pitkään ei tarvinnut etsiä, sillä sellainen oli jo asennettuna koneelleni: DrRacket. Olin koodannut Racket-ohjelmia jo hyvän tovin, kunnes ymmärsin että DrRacket:iin on sisäänrakennettu oma HTML-dokumenttien kuvauskieli: Scribble. Eikä mikä tahansa kieli, se on yhteensopiva Racket-koodin kanssa, voin kirjoittaa Racket-koodia Scribble-koodin sekaan ja käännettäessä, se ajaa myös Racket-koodin eli voin samalla koodata kuvituksen tekstiini! Koodiesimerkit myös väritetään (varatut sanat jne omilla väreillään) ja Racket-kielen varatut sanat linkitetään varsinaiseen Racket-dokumentaatioon. Scribble-kääntäjälle annetaan komentorivillä parametrit, joiden kautta sille voi antaa mm. css-määrittelyt, eli sivustosta tulee juuri sellainen kuin itse haluat. Huimaa!

Tätä näyttää Scribblellä, Racketillä ja css:llä koodattu web-sivu

No, miten Github tähän liittyy? Github:in kautta voi hallita ja jakaa koodia, ja luonnollisesti siis myös Scribble, css- ja html-tiedostoja. Mutta en tiennyt ennen tätä harjoitusta, että se voi toimia myös webbiserverinä sivustolleni. Tein uuden repositoryn githubini juureen nimellä: tyynetyyne.github.io ja tallensin sinne Scribbellä tekemäni html-tiedostot sekä projektiin liittyvät css-tiedostot. Tarmo Toikkanen loi minulle ystävällisesti "racket.koodiaapinen.fi" alidomainin ja ohjasi sen osoittamaan em. Github-repoon. Minun piti vain lisätä tyynetyyne.github.io:n masterhaaraan yksi CNAME-niminen tiedosto, jonka sisällä lukee "racket.koodiaapinen.fi" ja varmistua, että siellä oli yksi index.html niminen tiedosto. 

Löysin Githubista jopa Latex-tuen Scribblelle (pr-math), joten voin kirjoittaa matemaattisia merkintöjä Scribble-koodin sekaan ja sivu näyttää sen oikein!

No, ei tämä nyt aivan noin yksinkertaista ollut. Ensinnäkin Scribblen käyttö vaatii hieman harjoittelua  ja konffaamista. Scribble.exe tulee kyllä koneellesi DrRacket:in mukana mutta, koska se toimii komentoriviltä, joudut asettamaan sen sijainnin PATH-ympäristömuuttujaan. Windows 7:ssa se tehdään näin. Path - muutujan pitkän listaan perään lisätään siis: "; c:\Program Files\Racket" (ilman hipsuja).

Komentorivin käynnistyksen jälkeen siirrytään siihen hakemistoon, jossa Scribble - koodi sijaitsee, ja sitten komentoriville kirjoitetaan sopiva komento. Scribblen komennot (flagit) on kuvattu täällä ja melkoisen testaamisen ja kokeilun jälkeen itselleni toimivin rimpsu oli lopulta tämä:

> scribble --html ++main-xref-in --style manual-style-koko.css --dest generoitu --redirect-main http://docs.racket-lang.org koodausta_kouluun_aloita_tasta.scrbl

Nämä punaisella merkityt ovat projektini css-tiedosto, sekä aloitussivun Scribble-tiedosto. Lopuksi tallensin rimpsun "koko.cmd" tiedostoon ja ajelin sitä sieltä. Ajon jälkeen hakemistoon ilmestyi  kansio, jonka nimi on "generoitu" ja sen sisällä on "koodausta_kouluun_aloita_tasta.html" sekä erinäinen määrä muita html-tiedostoja, jpg-tiedostoja, pari JavaScript-tiedostoa ja css-tiedostoja, jotka muodostavat sivustoni. Jos kaikki toimii ok, voin päivittää sekä source-tiedostot, että target-tiedostot Githubiin käyttämällä tätä Github - Windows clientia.

Hankalinta kaikessa oli saada linkit ohjautumaan oikeaan dokumentaatioon. Se vaati .scrbl tiedostoon merkinnät mihin linkataan:
@(require (for-label lang/htdp-beginner))
@(require (for-label (except-in 2htdp/image image?)))

Lisäksi linkkien ohjaaminen käyttämään Racket-serveriä vaati --redirect-main -flagin. Ja jotta linkitys ylipäätään tehtäisiin piti käyttää ++main-xref-in -flagiä.

Source-tiedostot

Target-tiedostot (generoitu)

Voisi sanoa, että on pieni ihme, että olen saanut Githubiin tehtyä nettisivut, koodaamalla ne Scribblellä, Racketilla, css:lla ja Latexilla. Kukapa olisi uskonut! Tästä on hyvä jatkaa.

Voit testata sivujani osoitteessa: http://racket.koodiaapinen.fi