1. Tulostaminen

Dokumenttien tulostamista varten TIMissä on kaksi yleensä käytettävää toimintoa:

• Tulostaminen selaimen tulostustoiminnolla (Browser print -toiminto). Yksinkertainen tulostus. Tätä suositellaan käytettäväksi silloin, kun dokumentti halutaan nopeasti tulostaa sellaisenaan ilman kansilehteä tai sisällysluetteloa.
• Print Document -toiminto. Tämä tulostus mahdollistaa kirjapainotasoisen jäljen sekä kansileden ja/tai sisällysluettelon lisäämisen. Jokaiselle pluginille voi myös määritellä miten ne tulostuvat tai käyttää oletusta.

Näiden vaihtoehtojen lisäksi Print Document -toiminnolla on mahdollista muodostaa TIM-dokumentista LaTeX-tiedosto, jota voi sitten omalla koneellaan muokata ilman rajoitteita haluamallaan editorilla. Tämä toiminto on tarkoitettu edistyneemmille käyttäjille, jotka haluavat enemmän muokattavuutta ja joille LaTeX on tuttua.

Tulostusmenu löytyy TIMistä vasemmasta yläkulmasta ratas-ikonnin takaa:

2. Tulostus selaimen tulostustoiminnolla (Browser print)

2.1 Yleisohje

Browser print -toimintoa voidaan käyttää joko Ctrl + P -näppäinyhdistelmällä tai Browser print -painikkeesta.

Mene haluamaasi dokumenttiin ja paina näppäimistöltä Ctrl + P näppäinyhdistelmää tai klikkaa vasemmassa reunassa olevasta valikosta hammasratas-ikonia ja tämän jälkeen klikkaa Browser print -painiketta.

Tämän jälkeen dokumentti avautuu käyttämäsi selaimen tulostuksen esikatseluun. Tässä esikatselussa voit tarkastaa että dokumentti on ulkoasultaan oikean näköinen. Esikatselussa dokumentin voi tulostaa tai peruuttaa ja palata muokkaamaan dokumenttia.

2.2 Kappaletekstin/pluginin sovittaminen sivulle

Tekstikappaleiden tai dokumentin liitännäisten eli pluginien sisällön katkeamisen ja sijoittumisen eri sivuille voit estää toimimalla näin:

1. Klikkaa sivuvalikosta Customize TIM.
2. Laita rasti ruutuun kohtaan CSSprint_sovitus - Sovita kappaleet sivulle.
3. Palaa selaimessa edelliselle sivulle.
4. Päivitä sivu.
5. Asetus on nyt käytössä.

Asetuksen saa pois käytöstä toimimalla samoin kuin edellä, mutta poistamalla rastin ruudusta kohdasta CSSprint_sovitus - Sovita kappaleet sivulle.

2.3 Kommenttien tulostaminen

Dokumentissa olevat kommentit saa mukaan tulosteeseen seuraavalla tavalla:

1. Klikkaa sivuvalikosta Customize TIM.
2. Laita rasti ruutuun kohtaan CSSprint_kommentit - Näytä kommentit tulosteessa.
3. Palaa selaimessa edelliselle sivulle.
4. Päivitä sivu.
5. Asetus on nyt käytössä.

Kommentit saa pois käytöstä toimimalla samoin kuin edellä, mutta poistamalla rastin ruudusta kohdasta CSSprint_kommentit - Näytä kommentit tulosteessa.

2.4 Asetusten muokkaaminen

Voit halutessasi muokata/lisätä dokumentin ulkoasuun vaikuttavia asetuksia. Tämän ominaisuuden käyttö vaatii osaamista CSS-tyylimäärittelyistä.

Jos haluat muokata asetuksia toimi näin:

1. Klikkaa sivuvalikosta Customize TIM.
2. Klikkaa alareunasta Add Print Settings -painiketta.

Custom CSS -tekstikenttään ilmestyvään media print -lohkoon voi kirjoittaa omia CSS-tyylimäärittelyitä. Nämä määrittelyt vaikuttavat ainoastaan Browser print -toiminnon avulla muodostettavan dokumentin ulkoasuun.

Oletuksena lohkossa näkyvät leipätekstin ja eri otsikkotasojen fonttikoko sekä fonttityyli.

3. TeX- ja PDF-tulostus (Print document -toiminto)

3.1 Yleisohje

Tulostaminen tapahtuu Print Document -toiminnolla. Tällä tavalla muodostettuun tulosteeseen on mahdollista lisätä kansilehti ja/tai sisällysluettelo. Kansilehden ja sisällysluettelon lisääminen ei kuitenkaan ole pakollista, vaan dokumentti voidaan myös tulostaa ilman niitä.

Pluginien ulkoasu on mahdollista määrittää tulosteeseen. Jos pluginille ei itse määritä tulostusmuotoa, se tulostuu oletus ulkoasulla. Pluginien ulkoasun määritys vaikuttaa ainoastaan tulosteeseen eikä ulkoasu näy TIMissä. Pluginien asetuksien säätämistä opastetetaan täällä.

Tällä tulostustavalla saadaan aikaan kirjapainotasoista tulostusjälkeä, mutta usein hyvän tuloksen saaminen vaatii vaivannäköä ja osin jo tekstiä kirjoitettaessa sen miettimistä, miten asiat voidaan tulostaa.

TIMin ulkopuoliset kuvat tulevat tulosteeseen linkkinä tekijänoikeussyistä. Tästä löytyy ohjeet kuinka näiden kanssa tulee toimia.

Tulostaminen tapahtuu näin:

1. Klikkaa vasemman reunan valikosta hammasratas-ikonia.
2. Klikkaa valikosta Print document -painiketta.
3. Tulostusikkuna avautuu

4. Valitse ikkunasta kohdasta Please choose a template vaihtoehto runko
5. Varmista että ikkunan alareunassa kohta PDF on valittuna.
6. Klikkaa Create-painiketta.
7. Odota että dokumentti muodostuu. Kun dokumentti on valmis, ikkunan alareunaan tulee siitä ilmoitus.

8. Jos muodostuksessa tapahtui virhe, ikkunan alareunaan ilmestyy virheviesti. Muussa tapauksessa ilmoituksessa on linkki dokumenttiin.
9. Klikkaa View the document -linkkiä ja dokumentti avautuu uuteen ikkunaan.
10. Voit esikatsella dokumenttiasi ja joko tallentaa sen tietokoneellesi tai tulostaa sen.

Jos muokkaat tekstiä ja sinulla on vielä auki vanha tuloste selaimen toisessa ikkunassa tai välilehdellä, riittää virkistää tämä tulostunäkymä (F5), niin tulostus-PDF muodostetaan uudelleen.

Mikäli dokumentissa ei muuteta mitään, käytettäessä edellä saadun tulostesivun osoitetta, saadaan suoraan välimuistista PDF-tiedosto. Jos dokumenttia muutetaan, niin em. osoitteesta saadaan uusi PDF ja silloin sivun aukeaminen voi kestää.

Jos dokumentti riippuu paljon muista dokumenteista, voi käydä niin, että riippuvuussuhteita ei huomata. Tällöin saadaan sama PDF vaikka sisällön pitäisi olla erilainen.

Tarvittaessa voidaan pakottaa tekemään uusi PDF-dokumentti lisäämällä tulostesivun osoitteen perään teksti

&force=true

Esimerkiksi siis:

https://tim.jyu.fi/print/kurssit/tie/proj/2017/timantti/kayttoohje? (jatkuu seur rivi)
   file_type=pdf&template_doc_id=134613&plugins_user_code=False&force=true

Mikäli tuloste on tehty käyttäjän vastausten perusteella (ruksi ruudussa Use user...), niin vaikka käyttäjä muuttaisi vastauksiaan, ei sivua lasketa uusiksi jos vain virkistetaan tulostesivua. Tällöin uusi laskenta pitää pakottaa joko force-parametrilla tai tekemällä tuloste uusiksi dokumentin kautta.

Käyttäjän vastauksiin perustuva tuloste lasketaan aina uusiksi silloin kun se tehdään dokumentin kautta.

Jos tulostuksen kanssa ilmenee ongelmia, lue kohta haasteita PDF-tulostuksessa.

3.2 Tulosteessa piilotettu ja näkyvä teksti

Dokumenttiin on mahdollista lisätä normaalin tekstin lisäksi tekstiä, joka näkyy vain tulosteessa mutta ei TIMissä ja tekstiä joka näkyy vain TIMissä mutta ei tulosteessa. Näitä käytetään samalla tavalla kuin TIMin tyylejä.

Vain TIMissä näkyvä teksti

[Tämä teksti näkyy vain TIMissä, mutta ei tule tulosteeseen]{.hidden-print}

Vain tulosteessa näkyvä teksti

[Tämä teksti tulee vain tulosteessa, mutta ei TIMissä]{.visible-print}

Piilotustyyliä .hidden-print voi käyttää myös esimerkiksi kuvien kanssa. Tulostettaessa tosin pitää silloin huomioida että piilotustyylin käyttäminen saattaa poistaa PDF/LaTeX-tulostuksessa kuvien asetteluun liittyviä asetuksia. Jos kys. asetukset ovat oleellisia, ne saattaa joutua lisäämään käsin joko texmacros-attribuutilla tai kokonaan uutta tulostuspohjaa käyttäen.

3.3 Tulostusasetuksien muokkaaminen

Tulostusasetuksia on mahdollista muokata, lisäämällä dokumenttiin asetuslohko.

Tämä tapahtuu seuraavasti:

1. Klikkaa vasemman reunan valikosta hammasratas-ikonia.

2. Klikkaa valikosta Edit settings -painiketta.

3. Halutut asetukset tulee kirjoittaa settings-lohkoon. Nämä lisätään TIMin texmakrot-lohkoon. Mahdolliset asetukset löytyvät täältä. Perusasetukset voi kopioida tästä:

    texmacros: 
     texfontsize: 12pt
     texauthorname: 'Tekijä'
     texlanguage: 'finnish'
     texpaper: 'a4paper'
     texdocumentclass: 'extarticle'
     texside: 'oneside'
     textitle: 'Otsikko'
     texversion: 'Versio: 0.0.1'
     texdate: '18.7.2017'
     texorganization: 'Organisaatio'
     texsectionstart: 0
     texautonumber: 0
     texcoverpage: 0
     textableofcontents: 0
     texfancyfooter: 0
     texforcetoplevel: ''
     texforcesonlysectionnumber: 0
     texcaption: 1
     texmargins: 'left=20mm, right=20mm, top=20mm, bottom=20mm'
     texfootrulewidth: 0.0pt
     texfancyfooterstyle: ''

4. Asetuksien lisäämisen jälkeen ikkunan tulisi näyttää tältä (paitsi macros: sanan tilalla pitää olla texmacros):

5. Muokkaa asetuksia haluamallasi tavalla.

6. Klikkaa ikkunasta Save-painiketta.

3.3.1 Tyypilliset asetukset

Tyypilliset tulostusasetukset sellaista dkumenttia varten, johon halutaan kansilehti ja automaattinen numeorinti 1. tasosta alkaen:

``` {settings=""}
auto_number_headings: 1
texmacros:
 texauthorname: "Vesa Lappalainen"
 textitle: "Tulostuksen käyttöohje"
 texversion: "Versio: 1.0.1"
 texdate: "1.2.2018"
 texorganization: "Jyväskylän yliopisto"
```

3.4 Kuvat

Tulosteeseen tulee automaattisesti kaikki sellaiset kuvat, jotka on ladattu TIMiin. Tämä tarkoittaa siis sellaisia kuvia, jotka on lisätty käyttämällä Upload file/image-toimintoa.

Ulkopuolisista lähteistä lainatut kuvat eli sellaisin joihin viitataan URL-osoitteella eivät tule tulosteeseen, kun käytetään PDF-tulostusta. Tällöin tulosteeseen tulee ainoastaan linkki kyseiseen kuvaan. Näin toimitaan tekijänoikeussyistä. Jos käyttäjä haluaa kyseisen kuvan/kuvat tulosteeseen, on ne käytävä lataamassa ensin omalle koneelleen ja tämän jälkeen lisättävä uudestaan dokumentiin käyttämällä Edit-näkymästä löytyvää Upload file/image -toimintoa. Tällöin käyttäjä itse on vastuussa siitä, että hänellä on oikeudet käyttää kyseistä kuvaa.

Kuvat on syytä olla .png tai .jpg. LaTeX ei osaa näyttää .gif-kuvia. Jos on linkkejä .gif-kuviin, on ne konvertoitava tunnettuun formaattiin ja vaihdettava osoite tai käytettävä niiden kohdalla vaihtoehtoista tulostuskuvaa.

Mikäli kuvien ei haluta "kelluvan", kannattaa sijoittaa texmacros listan kohtaan texmacros komento tätä varten:

texmacros: 
  texmacros: |!!
\floatplacement{figure}{H}
!!

3.5 Templaten eli tulostuspohjan luominen

Kehittyneemmät käyttäjät voivat luoda myös omia Template -tiedostoja eli tulostuspohjia. Näiden avulla dokumentin tulostetta voi hienosäätää hieman tarkemmin. Näiden tiedostojen muokkaaminen kuitenkin vaatii osaamista LaTeXista. Tässä ohjeessa siis opastetaan ainoastaan kuinka näitä pohjia luodaan ja minne ne tulee sijoittaa. Ohjeessa ei neuvota LaTeXia koskevia asioita.

Tulostuspohjia voi luoda joko omaan henkilökohtaiseen käyttöön tai esimerkiksi oman kurssin käyttöön. Voit luoda tulostuspohjia ainoastaan sellaiseen hakemistoon johon sinulla on muokkausoikeudet.

3.6 Template-tiedostojen sijoittaminen

Template-tiedostoja voi luoda mihin tahansa hakemistoon, johon käyttäjällä on muokkausoikeudet. Template-tiedostot tulee aina sijoittaa haluamansa hakemiston Templates/Printing-hakemistoon. Jos template on sijoitettu väärään paikkaan, se ei näy tulostusikkunassa.

Yllä olevassa kuvassa on esimerkki template-tiedostojen sijoittamisesta. Tulostusikkunassa näkymiseen vaikuttaa myös oikean hakemiston lisäksi minkä hakemiston Templates/Printing-hakemisto on kyseessä.

Yllä olevassa esimerkissä tulostettaessa dokumenttia Demo_1 tulostus ikkunassa näkyy sekä Template_1 että Template_2. Näiden lisäksi näkyy myös kaikki Esimerkkikurssi-hakemiston yläpuolella olevat templatet juurihakemistoon saakka.

Tulostettaesa Luento_1 dokumenttia tulostusikkunassa näkyy ainoastaan Template_1 ja Esimerkkikurssi-hakemiston yläpuolella olevat templatet.

Tulostusikkunassa näkyy siis ainoastaan kaikki ne template-tiedostot jotka ovat hakemistorakenteessa kyseisessä hakemistossa tai sen yläpuolella.

3.7 Kurssin tulostuspohjan luominen

1. Klikkaa vasemman reunan valikosta hammasratas-ikonia.
2. Klikkaa Print document -painiketta.
3. Tulostusikkuna avautuu.

4. Klikkaa ikkunan alareunasta rasti ruutuun kohtaan Show advanced options.
5. Klikkaa haluamasi templaten perässä olevaa kynä-ikonia.
6. Mene avautuvat dokumentin Manage-välilehteen.
7. Selaa sivua alaspäin kohtaan Translations and copies.

8. Klikkaa kohdasta Create a copy.
9. Anna templatelle nimi kohtaan Title, tällä nimellä template näkyy tulostusikkunan listassa.
10. Aseta Location kohtaan haluamsi sijainti, esimerkiksi näin:
    kurssit/tietotekniikka/ohj1/Templates/Printing
11. Klikkaa Create-painiketta.
12. Nyt template-tiedoston tulisi näkyä tulostusikkunassa, kun tulostetaan dokumentteja kyseisestä hakemistosta.

3.8 Henkilökohtaisen tulostuspohjan luominen

Voit luoda käyttöösi myös henkilökohtaisia tulostuspohjia, jotka eivät näy muille käyttäjille. Nämä luodaan samalla tavalla kuin yläpuolella olevassa ohjeessa. Ainoastaan kohtaan Location syötetään oma henkilökohtainen hakemisto. Esimerkiksi
users/meikalainen-maija-maarit/Templates/Printing.

Henkilökohtaiset template-tiedostot näkyvät tulostusikkunassa aina, tulostettiin sitten mistä hakemistosta tahansa.

3.9 Huomioita tulostuspohjan kirjoittamisesta

Tulostuspohjassa ei saa olla yhteen kirjoitettuna merkkiyhdistelmiä

• {% tämä on TIMin makrokorvausjärjestelmän merkki
• %% tämä saa olla vai jos se TIMin makrossa mukana, esim.
  %%texauthor%%
• myös $-merkin kanssa on oltava varovainen koska se on TIMin käyttämän markdown -> LaTex muuntimen eli Pandocin makromerkki.

3.10 LaTeX

Käyttäjät joille LaTeX on tuttu voivat muodostaa dokumentistaan LaTeX-tiedoston, jota voi muokata omalla tietokoneellaan. Tällöin dokumenttia pystyy hienosäätämään vieläkin tarkemmin.

LaTeX-tiedoston muodostaminen tapahtuu samalla tavalla kuin PDF:n muodostaminen. Ainoana erona on että tulostusikkunan alareunasta valitaan vaihtoehto LaTeX.

LaTeX-tiedoston tapauksessa tulee huomioida, että kaikki dokumentissa olevat kuvat tulee ladata omalle koneelle käsin vastaavaan hakemistoon, mistä TIM etsisi niitä. Jos kuvat laittaa muuhun hakemistoon, pitää niiden osoite vaihtaa LaTex-tiedostossa.

Toinen vaihtoehto on jatkaa TeX-koodin työstämistä TIMissä, jolloin alkuperäiset kuvaosoitteet toimivat, eikä omalle koneelle tarvitse asentaa mitään uutta.

Jatkomuokkamista varten pärjää alla olevilla ohjeilla kun tekee ensin tulosteen PDF:än sijaan LaTeX-muotoon ja sitten kopioi kaiken tekstin talteen ja laittaa sen alla olevien ohjeiden mukaan uudeksi texplain-dokumentiksi.

Pitää kuitenkin muistaa että tämän tavan haittapuoli on se, että syntyy kokonaan uusi haara dokumentista ja varsinaiseen TIM-dokumenttiin tehdyt muutokset eivät enää heijastu tähän TeX-dokumenttiin.

Jos suinkin mahdollista, niin asetuksia kannattaa mieluummin yrittää muokata alkuperäisessä TIM-dokumentissa tai vastaavissa templateissa ja saada tulostusta näin automatisoitua jatkoa varten.

Toiminnon suurin hyöty onkin oikeastaan tehdä kokeita siitä, miten joku asetus pitää saada TeXiä varten ja kun oikeat asetukset ovat löytyneet, palataan normaaliin TIM-tulostamiseen suoran PDF:ksi.

3.11 LaTeXin kirjoittaminen suoraan TIMissä

TIMillä voi tehdä myös suoraan LaTex dokumentteja. Toimintoja ei ole vielä automatisoitu, mutta tarvittavat asiat onnistuu aika helposti manuaalisesti.

Toiminnon suurin hyöty on lähinnä siinä, että kun dokumentista tuotetaan PDF-tulostusta, niin moni asia voi mennä syntyneessä TeX-koodissa vikaan. Vikoja voi olla helpompi tutkia kun tällöin ottaakin tulosteen LaTeX-muodossa ja tekee syntyneestä LaTeX dokukmentista tällaisen TIM-TeX dokumentin, jossa muokkailee koodia ja selvittää virheitä.

Erona TIMissä tehtävässä TeX kirjoittamisessa on se, että mikäli lähdekoodi on otettu kuvia sisältävän TIM-dokumentin LaTeX-tulosteesta, niin silloin kuvat toimivat. Mikäli lähdekoodi siirretään omaan koneeseen, niin silloin kaikki kuvat pitäisi myös saada siirrettyä omaan koneeseen.

3.11.1 Uuden LaTeX-dokumentin luominen

1. Luo normaalisti uusi dokumentti

2. Mene dokumentin asetuksiin (Rattaankuva/Edit settings)

3. Kirjoita asetuksiin:

    ``` {settings=""}
    texplain: true
    ```

4. Kirjoita haluamaasi TeX koodia yhteen tai useampaan lohkoon.

5. Jos kirjoitat kaiken yhteen tiedostoon, homma onkin valmis ja voit tulostaa

6. Avaa rattaan kuvasta Print document.

Esimerkki LateX lohkosta joka on kirjoitettu TIMiin

\documentclass[oneside, 12pt,a4paper,finnish]{extarticle}
\usepackage{graphicx}
\usepackage[utf8]{inputenc}
\begin{document}
  \begin{center}
  \includegraphics{/service/timApp/static/images/tim-logo_42height.png}
  \end{center}
  
  Tervetuloa kirjoittamaan TeXiä TIMillä!
\end{document}

Dokumenttiin voi kirjoittaa useitakin LaTex-lohkoja em. tavalla. Niiden väliin voi kirjoittaa tavallista tulotumatonta TIM-tekstiä, mikäli merkitsee ko lohkot tyylillä hidden-print, eli aloittaa "kommenttilohkot" rivillä

#- {.hidden-print}

Aaltosulkujen sisään voi vielä toki laittaa halutessaan hyppypaikan, jolloin on helppoa antaa kaverille URL-osoite josta löytää ko. kohtaan, esim:

#- {.hidden-print #fermaanlauseentodistus}

Mikäli käytät otsikoita (eli rivi alkaa #), niin myös ne toimivat kommentteina, eli eivät tulostu. Toki voit käyttää myös TeXin kommenttimerkkiä % kommentoimaan tekstiä jonka et halua tulostuvan.

Eli otsikoita käyttämällä em voisi tehdä myös:

## Fermaan suuren lauseen todistus {#fermaanlauseentodistus}

ja sitten kirjoittaa tämän perään TeX-koodia, jossa lause todistetaan.

3.11.2 TIM makrojen suorittaminen texplain dokumenteissa

Oletuksena TIM-makroja ei suoriteta texplain dokumneteissa. Mikäli makrot halutaan suorittaa, pitää lisätä asetus:

``` {settings=""}
texplain: true
nomacros: false
```

Tästä on se haittapuoli, että merkintä:

{%

jota käytetään yleisesti TeXissä, on ristiriidassa Jinja2 TIMiin valitun makrojen lohkon aloituksen kanssa. Jos ei ole haittaa, tätä voi kiertää laittamalla välilyönnin sulun ja prosentin väliin:

{ %

mutta joskus tämä aiheuttaa ylimääräisen välilyönnin ja silloin ratkaisu ei auta.

Toinen tapa on tuottaa Jinja2 makroilla tuo merkintä väkisin:

%%"{%"%%

Seuraava tapa on sulkea koe ongelman aiheuttava kohta raw-lohkoon:

{% raw %}
jotakin {%
{% endraw %}

Jos dokumentin jakaa pienemmiksi TIM-lohkoiksi, voi lohkolle antaa kiellon makrojen suorittamisesta:

#- {nomacros="true"}
jotakin {%

Vielä yksi mahdollisuus että dokumentin asetukset antaa alla ilman makrojen julistusta, mutta sanoo kussakin makroja tarvitsevassa lohkossa erikseen:

#- {nomacros="false"}
jotakin %%makro%%

3.12 Korjaa ja katsele -sykli

Kun tulostus on valmis ja painat View the document aukeaa tulostus uuteen välilehteen. Korjaa ja katsele-sykliä voit nopeuttaa seuraavasti:

1. Siirrä syntynyt tulosteen välilehti omaksi selaimen sivukseen ja laita se näytöllä sopivaan kohtaan.
2. Korjaa TeX-tekstiä ja tallenna.
3. Mene tulosteen välilehdelle ja paina Refesh (F5)
4. Jatka kohdasta 2. kunnes olet tyytyväinen.

3.13 Kuvat

Dokumentissa voi käyttää vain TIMiin ladattuja (upload) kuvia. Niiden osoitteen saa selville seuraavasti:

Kuva joka Timiin lataamisen jälkeen on osoitteessa:

https://tim.jyu.fi/images/134961/timtex.png

on TeX-koodissa käytettävissä osoitteesta:

/tim_files/blocks/images/134961/timtex.png

Eli tuo em. osoite kirjoitetaan TeXissä vaikkapa makron \includegraphics parametriksi.

Lyhyesti sanottuna osoitteissa vaihdetaan

https://tim.jyu.fi/

tilalle

/tim_files/blocks/

3.14 Pohdintaa LaTex-tekstin kirjoittamisesta TIMissä

Mitä hyötyä olisi kirjoittaa TeXiä TIMIssä?

• yhteiskirjoittaminen (tämän toki tarjoaa muutkin alustat)
• ei tarvitse asentaa mitään omalle koneelle (tämäkin toimii jossakin muussa)
• kommentit
• Velpit
• täydellinen versiohistoria
• aloittelevampi voi kirjoittaa tekstiä ensin perusTIMinä ja sitten tulostaa sen TeXiksi ja tehdä hienosäädön siinä
• dokumentin sekaan voi upottaa tulostumattomia lohkoja, joissa voi olla esimerkiksi dokumenttia varten tehtyjä apulaskuja vaikka erilaisissa interaktiivissa komponenteissa tai jopa ohjelmakoodeja joita on testattu

Miinusta (vielä, kun vasta keksin tuon ominaisuuden eikä sitä ole hiottu)

• muokkausikkuna menee kiinni aina tallennuksesa ja pitää avata uudelleen
• ei automaattisesti refreshaa PDF näkymää
• kirjallisuusjuttu ei vielä toimi

4. Haasteita TeX- ja PDF-tulostuksessa

Taustalla käytettävä LaTEX on hyvin tarkka eri asioista ja moitteetonkin TIM-dokumentti voi vaati muutoksia jotta se kääntyy LaTeX-dokumentiksi.

Seuraavaan on koottu vastaan tulleita esimerkkitapauksia muutostarpeista.

Mikäli tulostuksen kanssa ilmenee ongelma, joihin ei löydy vastausta näistä ohjeista, ota yhteyttä TIM-järjestelmän ylläpitoon tim@jyu.fi.

4.1 Tuntemattomia Unicode-merkkejä

TIM-dokumentissa voi olla esimerkiksi Wordistä kopioituja UTF8 merkkejä, jota taustalla oleva LaTeX ei tunne. Tätäs tulee virheilmoitus, esimerkiksi:

Pandoc died with exitcode "43" during conversion: b'! Package inputenc 
Error: Unicode char \xef\xac\x81 (U+FB01)
(inputenc) not set up for use with LaTeX.

Kun etsitään Googlesta hakusanalla unicode fb01 nähdään että tämä on lähekkäin kirjoitettu fi. Tällöin voidaan lisätä TIMin asetuslohkoon

texmacros:
 texmacros: |!!
   \DeclareUnicodeCharacter{FB01}{fi}
 !!

Määrityksiä voi katsoa myös: http://wiki.neo-layout.org/browser/latex/unicode.sty?rev=231

4.2 Liikaa matematiikkamoodeja

TIMin käyttämä MathJax ei ole yhtä tarkka matematiikasta kuin PDF tulostuksen käyttämä LaTeX. Yksi esimerkki on sellainen missä TIMissä kelpaa yhdistelmä:

$$\begin(eqnarray)

LaTeXin kannalta tuossa on kaksi matematiikkamoodin aloitusta ja siksi tuollaisten komentojen edestä (vastaavasti endin jälkeen) pitää poistaa tuo $$.

4.3 Liikaa rivejä eqnaling ympäristössä

Ympäristön eqnarray sisällä ei saa olla tyhjiä rivejä. TIM näyttää siitä huolimatta kaavan, mutta LaTeX ei tykkää.

4.4 array tarvitsee matematiikkamoodin

Vastaavasti array pitää kirjoittaa $-merkkien sisään.

$$\begin{array}...\end{array}$$

4.5 Verbatim-ympäristö LaTeX-makron sisällä

Jos tulee virheilmoitus:

Error!
Pandoc died with exitcode "43" during conversion: b'! 
Paragraph ended before \\FV@BeginScanning was complete.

\\par 
l.9340 }

niin kyseessä voi olla se, että on tehty makro (esim. väri), jonka sisälle joutuu Verbatim tyyliä ja nämä eivät saa olla sisäkkäin. Ratkaisu: Tulosta LaTeX-koodi ja avaa se jossakin editorissa ja katso mitä on rivistä 9340 yläpuolella. Jos on esim:

\red{
...
begin(\Verbatim)
...
end(\Verbatim)
...
}

niin etsi alkuperäisestä dokumentista vastaava kohta ja merkitse Verbatimiksi muuttunut lohko jollakin toisella tavalla.

4.6 Tyylien nimissä muita merkkejä kuin kirjaimia

LaTeX ei tykkää makrojen nimistä, joissa on muuta kuin kirjaimia. Siten esim tyyli .termi2 johtaa tilanteeseen, jossa joko syntynyt LaTeX koodi pn epävalidia tai ylimääräinen merkki 2 ilmestyy joka paikkaan.

Korjaus: nimeä tyyli vaikka .termiB ja tee vastaava LateX-makro dokumentin settings-osaan

texmacros:
 texmacros: |!!
   \definecommand{\termiB}[1]{\blue{#1}}
 !!

4.7 Keskelle sivua sijoitettava kuva samalla rivillä muun tekstin kanssa

Esimerkiksi listoja kirjoitettaessa käy helposti niin, että listaan laitettu kuva jää samalle riville tekstin kanssa (kun rivitys ladotaan uudelleen) ja tällöin kuva lähtee tekstin mukana menemään oikealle.

Tällöin pitää tehdä niin, että ennen kuvaa kirjoitettu teksti lopetetaan \-merkkiin ja kuvan ![kuvan nimi](kuvan osoite) -koodin jälkeen laitetaan myös yksi \-merkki.

Eli lista jonka sisään halutaan kuva, kirjoitetaan seuraavasti:

- tästä alkaa asia joka jatkuu kuvalla\
  ![](kuvan osoite)\
  ja jatkuu sitten taas tekstillä
- uusi listan alkio

4.8 Kalvon vaihdot

Jos tehdään kalvon vaihtoja (---) niiden on oletava omissa kappaleissaan.

4.9 Display kaavat kysymykissä

Monivalinnoissa mcq yms ei saa olla displaykaavoja ($$).

4.10 Tyhjä Verbatim-lohko

TIMissä käytetään ```-merkkejä rajaamaan verbatim (=sanatarkka) lohkoja. Näitä käytettäessä pitää tuon kolmentakahipsun yhdistelmän olla omalla rivillän ja sen tulee olla rivin alussa. Muuten käytettynä tuo voi aiheuttaa ongelmia, josta tulostettaesa tulee virheilmoitus tyyliin:

Error!
Pandoc died with exitcode "43" during conversion: 
! FancyVerb Error:
  Empty verbatim environment
.
\FV@Error ... {FancyVerb Error:
\space \space #1
}
                                                  
l.576 \end{verbatim}

pandoc: Error producing PDF

Tällöin siis pitää alla olevilla ohjeilla etsiä missä kohti LaTeX-tiedostoa tuo virhe on (eli em esimerkissä rivi 576) ja sen perusteella paikantaa virhe alkuperäisesti TIM-dokumentista.

Virheen voi aiheuttaa myös se, että on kirjoitettu kolmea takahipsua käyttäen lohko jossa ei ole mitään sisällä.

4.11 Verbatim-lohko on sijoitettu toisen lohkon sisälle

Joskus juuri mitään sanomaton virheilmoitus:

Pandoc died with exitcode "43" during conversion: 
! Paragraph ended before \FV@BeginScanning was complete.
 
                   \par 
l.585 }

pandoc: Error producing PDF

johtuu siitä, että ``` lohko on kirjoitettu jonkun toisen lohkon sisällä, esimerkiksi:

#- {.huomautus}
Huomaa että

```
tulostuu tasavälisellä kirjasimella
```

ja hipsujen ulkopuolella oleva toisenlaisella kirjasimella.

Noiden ``` lohkojen täytyy muodostaa TIMIssä oma lohkonsa joka ei saa olla toisen lohkon sisällä. Jos edellä esimerkiksi huomautukseen halutaan tasvälistä kirjasinta, voidaan tätä yrittää kiertää:

#- {.huomautus}
Huomaa että

>`tulostuu tasavälisellä kirjasimella`

ja hipsujen ulkopuolella oleva toisenlaisella kirjasimella.

4.12 Mitä teen jos tulee ongelmia?

Latex ei ole ihan verbaalisin virheilmoituksissaan.

Jos tulee virheilmoituksia, kannattaa ne yrittää lukea ja sitten painaa

View erroneous LaTeX line

ja katsoa siitä vastaavat rivit (ensimmäinen virhe on merkitty punaisella) ja yrittää etsiä ne myös alkuperäisestä TIM-dokumentista ja sitten korjata siellä.

Mikäli virhettä ei ilmoituksen pohjalta pysty selvittämään tai löytämään sen kohtaa, niin kannattaa valita LaTeX-tulostuskohteeksi PDF:n sijaan.

Sitten syntynyt LaTeX-tiedosto otetaan johonkin editoriin, mikä näyttää rivinumerot. Hätätilassa vaikkapa TIMiin luomalla sinne uusi texplain-dokumentti. Ks seuraava luku. Sitten etsitään tästä tiedostosta se rivi, johon LaTeX virheilmoitus viittasi (LaTeX virheilmoituksessa esimerkiksi l.609 tarkoittaa että virhe on rivillä 609. Tämän kohdan ympäröivän tekstin perusteella etsitään alkuperäisestä TIM-dokumentista mikä aiheuttaa virheen ja korjataan ongelma.

Toinen hyvä vaihtoehto on ShareLaTeX, johon voi luoda itselleen (jos ensin tekee tunnuksen) uuden projektin, jonne pudottaa syntyneen LaTeX koodin ja katsoo siellä tarkemmin virheilmoituksia ja korjaa ongelmia siellä esim määrittelemällä uusia makroja tai Unicode-korvauksia. Sitten kun saa toimimaan, tekee vastaavat korjaukset TIM-dokumenttiin tai sen settings-osaan tai hätätilassa omaan Template-tiedostoon.

SharedLaTeXin hyvä puoli on siinä, että vaika tulee virheitä, se jatkaa eteenpäin ja esimerkiki puuttuvat kuvat eivät haittaa jonkinlaiset dokumentin muodistumista. Jos dokumentti muodostuu, niin sitten kannattaa klikata Recompile-painikkeen vieressä olevaa dokumentin kuvaa, jonka päällä yleensä lukee virheiden määrä. Sieltä aukeaa parempi selustu virheistä ja niihin pääsee paremmin käsiksi.

Mikäli LaTeX-koodia yrittää ajaa jossakin toisessa ympäristössä, puuttuu tietysti kaikki kuvat. JOtta tästä ei valitettaisi, voi omaan LaTeX-tiedostoon lisätä tilapäisesti rivin:

\renewcommand{\includegraphics}[2][]{}

jolla saa kuvat poistumaan.

5. TeX- ja PDF-tulostuksen tulostusasetukset

Haluttaessa muokata asetuksia, kopioidaan tämän ohjeen mukaisesti perusasetukset dokumenttiin. Näiden lisäksi on olemassa myös muita asetuksia, joita voi dokumenttiin lisätä. On myös asetuksia, joita voi lisätä plugininen määrittelyyn ja ne vaikuttavat ainoastaan kyseiseen pluginiin. Alempana nämä kaikki asetukset käydään läpi.

Nämä asetukset vaikuttavat ainoastaan dokumentin tulosteeseen, ei TIMissä olevaan dokumenttiin.

5.1 Asetuslohkot macros ja texmacros

TIMssä on kaksi makrolohkoa jonka alle alla olevia määrityksiä voidaan kirjoittaa.

• macros: normaalit TIMin makrot, jossa lohkossa määriteillyillä arvoilla korvataan kaikki näyettäessä sivun html:ää ja tulostettaessa
• texmacros: vain TeX-tulostusta varten olevat makrot
• Tavallisessa käytössä siis texmacros-lista ohitetaan kokonaan. Tulostettaessa tehdään kokonaan uusi makrolista, johon luetaan ensin kaikki macros-listassa olevat makrot ja sitten sen jälkeen lisätään/päällekirjoitetaan texmacros-listasta löytyvät makrot. Näin TeX-tulostuksessa texmacros-listan makrot ovat määräävämpiä.

Yleensä kannattaa kirjoittaa kaikki makrolistaan tulevat tex-alkuistet makrot nimenomaan texmacros-listaan. Näin niiden käsittely ei turhaan hidasta normaalia sivun tuottamista selainta varten. Toki jos jotakin arvoa tarvitaan näytettävässä tekstissä, vastaava makro kannattaa sijoittaa macros-listaan. Esimerkiksi texauthor voisi olla tällainen makro jos sen arvoa käytetään selaimelle tulevassa tekstissä.

Tällä ominaisuudella saadaan esimerkiksi se, että voisi olla eri kuvaikoni, joka näytetään selaimessa ja tulostuksessa.

Eli esim jollekin vakiona toistuvalle ikonille voisi olla

macros:
  kynankuva: '![](/.../pienikyna.png)'
texmacros:
  kynankuva: '![](/.../isokyna.png)'

Tällöin selaimeen tulostuu aina pienen kynän kuva ja tulostuksiin isonkynän kuva jos koodissa on muistettu viitata:

  Tässä sinulla %%kynankuva%% tuoreeltaan.

5.2 Yleiset asetukset (texmacros-lohkoon kirjoitettavat asetukset)

Nämä ovat tulosteen ulkoasuun vaikuttavat perusasetukset. Kansilehteen vaikuttavat asetukset kuten otsikon ja tekijän nimen voi kirjoittaa haluamallaan tavalla lainausmerkkien sisään eikä niiden sisältöä ole rajoitettu. Muiden asetusten kohdalla tulee olla tarkkana että ne ovat oikeassa muodossa.

Tämä asetus määrittää tulostettavan dokumentin leipätekstin fonttikoon. Fonttikokoa ei voi valita täysin mielivaltaisesti. Hyväksyttäviä fonttikokoja ovat seuraavat:

• 8pt, 9pt, 10pt, 11pt, 12pt, 14pt, 17pt, 20pt

Tällä asetuksella voidaan asettaa käytettävä fontti. Oletuksena tyhjä, eli tulee oletusfontti. Esimerkiksi

texmacros: 
    texfont: \usepackage[default]{sourcesanspro}

tai

texmacros: 
    texfont: \usepackage[default]{lato}  

voidaan myös skaalta samalla:

texmacros: 
    texfont: \usepackage[sfdefault,scale=0.95]{noto}

Tämä asetus määrittää tulosteen kansilehteen tulevan tekijän nimen. Jos tulosteeseen ei laita kansilehteä, tällä asetuksella ei ole vaikutusta. Jos dokumentin kansilehteen ei halua tekijän nimeä ollenkaan tulee asetus jättää tyhjäksi eli:

texmacros: 
    texauthor: ""

Tämä asetus määrittää tulostettavan dokumentin kielen. Kieliasetus vaikuttaa esimerkiksi sisällysluettelon otsikon kieleen sekä tavutukseen. Tähän voi syöttää yleisimpiä kieliä kuten esimerkiksi:

• finnish, english, swedish

Tämä asetus määrittää tulosteen paperikoon. Mahdollisia arvoja ovat:

• a0paper, a1paper, a2paper, a3paper, a4paper, a5paper, a6paper, b0paper, b1paper, b2paper, b3paper, b4paper, b5paper, b6paper, c0paper, c1paper, c2paper, c3paper, c4paper, c5paper, c6paper, ansiapaper, ansibpaper, ansicpaper, ansidpaper, ansiepaper, letterpaper, executivepaper, legalpaper

Tämä asetus määrittää tulosteen dokumentin tyypin. Asetus vaikuttaa tulosteen ulkoasuun. Suositeltavaa on käyttää oletuksena asetettua dokumenttityyppiä (extarticle) mutta halutessaan voi kokeilla myös muita vaihtoehtoa. Mahdolliset arvot ovat:

• extarticle, extbook, extreport

Esimerkiksi:

texmacros: 
 texdocumentclass: 'extbook'
 texautonumber: 1

vaihtaa sivua ennen jokaista 1. tason otsikkoa ja tulostaa sen eteen oletusasetuksilla sanan Luku.

Tämä asetus vaikuttaa tulosteeseen tulevan kansilehden otsikkoon sekä mahdolliseen alareunan otsikkoon. Jos dokumenttiin ei tule kansilehteä tai ei ole vallinnut alaotsikoita, tällä asetuksella ei ole vaikutusta. Jos dokumentin kansilehteen ei haluta otsikkoa ollenkaan tulee tämä asetus jättää tyhjäksi eli:

texmacros: 
    textitle: ""

Tämä asetus määrittää kansilehteen tulevan versio numeron. Jos tulosteeseen ei laita kansilehteä tällä asetuksella ei ole vaikutusta. Jos kansilehteen ei halua versionumeroa ollenkaan, tämä asetus tulee jättää tyhjäksi eli:

texmacros: 
    texversion: ""

Tämä asetus vaikuttaa kansilehdessä olevaan päivämäärään. Päivämäärän voi kirjoittaa haluamassaan muodossa, esimerkiksi:

texmacros: 
    texdate: "1.1.2017"

    texdate: "11. tammikuuta 2017"

    texdate: "01/01/2017"

Jos dokumenttiin ei tule kansilehteä, tällä asetuksella ei ole vaikutusta. Jos dokumentin kansilehteen ei halua päivämäärää ollenkaan tulee tämä asetus jättää tyhjäksi eli:

texmacros: 
    texdate: ""

Tämä asetus vaikuttaa kansilehteen tulevan organisaation nimeen, esimerkiksi:

texmacros: 
    texorganization: "Jyväskylän yliopisto"

Jos dokumenttiin ei tule kansilehteä, tällä asetuksella ei ole vaikutusta. Jos dokumentin kansilehteen ei halua organisaatiota ollenkaan tulee tämä asetus jättää tyhjäksi eli:

texmacros: 
    texorganization: ""

Tämä asetus määrittelee mistä numerosta otsikoiden numerointi alkaa. Oletuksena tässä on 0, jolloin ensimmäisen otsikon numero on 1. Jos tämän asetuksetn kohdalle laittaa

texmacros: 
    texsectionstart: 1

tulosteen ensimmäisen otsikon numero on 2. Tällä asetuksella ei ole vaikutusta jos asetus texautonumber ei ole käytössä.

Tämä asetus määrittää tuleeko tulostettavaan dokumenttiin otsikoille numerointi. Oletuksena numerointi on pois päältä eli asetuksen arvo on 0. Jos numeroinnin haluaa päälle, tulee asetuksen arvoksi asettaa 1.

Jos asetus ei ole päällä, käytetään TIMin autonumeroinin asetusta. Eli käytännössä tätä ei useinkaan tarvitse laittaa päälle. Kuitenkin esimerkiksi Gradu-tyylin kanssa sitä kannattaa käyttää.

Esimerkki, jolla h2 taso on ensimmäinen numeroitu taso:

``` {settings=""}
auto_number_headings: 2
texmacros: 
    texdocumentclass: 'extbook'
    texautonumber: 1
    texforcetoplevel: 'chapter'
    texforcesonlysectionnumber: 1
```

Tosin tällöin pitää myös mahdollisiin H1 otsikoihin laittaa

# Numeroimaton teksti {.nonumber}

Mikäli numeroitavia tasoja halutaan vaan esimerkiksi korkeintaan kolme, laitetaan asetuksiin:

texmacros:
...
    texmacros: |!!
\setcounter{secnumdepth}{3}
!!

Mikäli on texautonumber: 0 (tai asetusta ei ole) ja on laitettu tuo \setcounter, niin silloin numerot voivat tulla kahteen kertaan, eli TIMin numerointi ja LaTeXin numerointi. Eli tätäkään asetusta ei kannata käyttää mikäli dokumentti on TIMin puolella jo numeroitu.

Tämä asetus määrittää tuleeko tulosteeseen kansilehti vai ei. Oletuksena kansilehteä ei tule, eli asetuksen arvo on 0. Jos tulosteeseen haluaa kansilehden, tulee asetuksen arvoksi asettaa 1.

Tämä asetus määrittää tuleeko tulosteeseen sisällysluettelo vai ei. Oletuksena sisällysluetteloa ei tule eli asetuksen arvo on 0. Jos tulosteeseen haluaa sisällysluettelon, tulee asetuksen arvoksi asettaa 1.

TIMiin on mahdollista lisätä omia tyylejä. Jos nämä omat tyylit haluaa mukaan myös dokumentin tulosteeseen, tulee tyylit määritellä LaTeX-makroina.

Tämän asetuksen kohdalle määritellään omien lisättyjen TIM-tyylien LaTeX-versiot. Esimerkiksi jos TIMiin on määritellyt tyylin[]{.suuripunainenteksi}, tulee vastaava merkitä tex-makrolistaan näin:

texmacros:
 texmacros: |
    \newcommand{\suuripunainenteksti}[1]{{\Huge{\color{red}{#1}}}}

Jos määriteltylä makroja on useita, tulee ne listata allekkain eli näin:

texmacros:
 texmacros: |
    \newcommand{\suuripunainenteksti}[1]{{\Huge{\color{red}{#1}}}}
    \newcommand{\pienisininenteksti}[1]{{\tiny{\color{blue}{#1}}}}

Jos omien LaTeX-makrojen määritys ei ole tuttua, voi siihen tutustua esimerkiksi täällä. Tulee kuitenkin huomioida että makrojen määritys vaatii osaamista LaTeXista.

Mikäli tyyliasetuksissa tarvitaan esimerkiksi TeXin parametria #1, pitää # kahdentaa eli kirjoittaa ##1.

Kuvien kellumisen saa pois:

texmacros:
 texmacros: |!!
\floatplacement{figure}{H} 
!!

5.3 Käyttöesimerkkejä asetuksista

5.3.1 Oman TeX-makron määritys

Oletetaan että dokumentin tekijä kirjoittaa TIM dokumenttiinsa "paljon" kappaleita, jotka alkava keltaisella sanalla Extratietoa: tyyliin:

[Tiesithän että $\pi$ on enemmän kuin kolme.]{.lisatietoa}

joka sitten näkyisi muodossa:

Tiesithän että \(\pi\) on enemmän kuin kolme.

Tätä varten tehdään asetuksiin css-osioon määritys tyylille lisatietoa. Jos dokumentti halutaan tulostaa TeXin kautta, niin tällöin pitää tehdä myös vastaava määritys TeXin tyylehin. Tämä onnistuu makrolla texmacros joka sijoitetaan makro-osion texmacros alle.

Asetuslohko näyttäisi silloin (minimaalisena, lisäesimerkkinä on kuvien kellumisen kieltäminen) tältä:

``` {settings=""}
css: |!!
.lisatietoa::before {
    content: "Extratietoa:  ";
    background-color: #ecec2b;
    /* color: red; */
    font-weight: bold;    
}

!!
texmacros:
    texmacros: |!!
\floatplacement{figure}{H}  % kuvat eivät saa kellua
\raggedbottom               % sivuja ei pakoteta täyteen pituuteen
\newcommand{\lisatietoa}[1]{\bgyellow{Extratietoa:} #1}
!!
```

5.3.2 Oma ympäristö

Jos koko dokumentti on esimerkiksi:

``` {settings=""}
auto_number_headings: 1
texmacros:
    texmacros: |!!
\newcounter{chapter}[section]
\newtheorem{tlause}{Lause}[chapter]
\newcommand{\lause}[1]{\begin{tlause}{#1} \end{tlause}}
!!
css: |!!
body {
  counter-reset: lause;
}

.lause {
   display: flex;
   align-items: baseline;
   
    &::before {
        counter-increment: lause;
        content: "Lause " counter(lause) ":  ";
        /*
          background-color: #ecec2b;
          color: red; */
        font-weight: bold;    
        display: inline-block;
        margin-right: 0.4em;
    }
    
    .parContent {
      flex-grow: 1;
      font-style: italic;
    }
}
!!
```

# Lauseita

## Vertailut

#- {.lause}
Jos $a < b$, niin $b > a$.

#- {.lause}
Jos $a = b$, niin $b = a$.

Näyttäisi dokumentti TIMissä lauseiden osalta seuraavalta:

Vastaavasti tulostetussa LaTexissa tämä olisi:

Oikeassa käytössä chapter arvo tulisi lukunumeroista ja vastaisi silloin lukua.

5.3.3 Fontin vaihto

Yliopiston uusi suositusfontti lato saadaan käyttöön lisäämällä seuraavat rivit kohdan texmacros alle:

\usepackage[default]{lato}
\renewcommand*\rmdefault{lato} 

vastaavasti entinen suositus Palatino saadaan käyttöön lisäämällä texmacros-kohtaan:

texmacros: 
    texmacros: |
        \renewcommand*\rmdefault{ppl}
        \linespread{1.05}        % Palatino needs more leading

Sama onnistuu myös lisäyksellä:

texmacros: 
    texmacros: |
        \usepackage{palatino}
        \linespread{1.05}        % Palatino needs more leading

Lisää fonteista:

• http://www.tug.org/mactex/fonts/LaTeX_Preamble-Font_Choices.html
• http://www.icl.utk.edu/~mgates3/docs/latex-fonts.pdf
• https://www.sharelatex.com/learn/Font_typefaces
• https://en.wikibooks.org/wiki/LaTeX/Fonts
• http://www.tug.dk/FontCatalogue/

5.3.4 Automaattinen kuvan nimeäminen pois

texmacros: 
  texmacros: |!!
\usepackage[labelformat=empty]{caption}
!!

5.4 Plugineja koskevat asetukset

Plugineille on olemassa omia tulostusasetuksia. Osa asetuksista on mahdollista määritellä kaikille plugineille ja osa asetuksista on vain tietyn tyyppisille plugineille.

Haluttaessa tulostaa plugineista käyttäjän vastaukset esimerkiksi monivalintakysymyksen tapauksessa, tulee tulostusikkunassa laittaa rasti ruutuun kohtaan Use user code for plugins.

Mikäli pluginien attribuutteihin joutuu kirjoittamaan #-merkin, pitää ko attribuutti merkitä md: muunoksella, eli esimerkiksi:

header: 'md:Opetellaan C#-kieltä'

Tämän määrityksen avulla voi määrittää mitä pluginin kohdalle haluaa tulostuvan, jos ei halua käyttää pluginin oletus tulostusmuotoa.

Tämä määritys tulee sijoittaa pluginin määrittelyyn eli alapuolella esimerkkinä csPluginin määrittely:

type: java
texprint:
fullprogram: |!!
//
// BYCODEBEGIN
public class HelloWorld {
    public static void main(String args[]) {
        System.out.println("Hello World!");
    }
}
// BYCODEEND
!!

Tähän texprint osioon haluttu tulostus tulee kirjoittaa noudattaen normaaleja TIMin YAML-kirjoittamisen sääntöjä. Usein on varminta käyttää lainausmerkkejä tai pitkän tulostuksen tapauksessa muotoa joka alkaa |!! ja lopuu rivin alussa olevaan !!-yhdistelmään. Tulostusmuodon voi kirjoittaa joko markdown- tai LaTeX-muodossa.

Jos pluginia ei haluta tulosteeseen tulee texprint-lohko jättää tyhjäksi eli:

texprint: ''

tai

texprint: 

Pluginin tilalle haluttaessa tekstiä:

texprint: 'Tämä teksti tulostuu pluginin tilalle.'

Pluginin tilalle haluttaessa pitkää tekstiä:

texprint: |!!
   Tämä teksti tulostuu pluginin tilalle.
   ja tämä myös.
!!

Pluginin tilalle voi myös laittaa kuvan TIMin Upload file/image -toiminnolla:

texprint: '![Kuvateksti](/images/133602/esimerkki.png)'

Tämä toimii samalla tavalla kuin texprint mutta tämän sisään kirjoitetut määritykset tulostuvat ennen pluginia. Tämä tulostetaan riippumatta siitä mikä asetuksen texprint-arvo. Jos texprint on tyhjä, tulostuu tämä ja sen jälkeen pluginin normaalisti tulostuva sisältö. Jos texprint sisältää jotakin, se tulostuu tämän perään.

Tämä toimii samalla tavalla kuin texprint mutta tämän sisään kirjoitetut määritykset tulostuvat pluginin jälkeen. Yleisin käyttötapaus on esimerkiksi lisätä ohjelmakoodin perään malli siitä, mitä ohjelman ajaminen tulostaisi. TIMissähän tämän näkee kun ajaa ohjelman, mutta jos paperille halutaan samanlainen näkymä, on tämä kerrottava erikseen.

Useimmiten tätä attribuuttia käytetään kun on jokin plugin, joka piirtää vaikka Javascriptillä kuvan jota ei TeX ajossa voida käyttää hyväkseen. Silloin otetaan ruudulta kuvasta kuvakaappaus ja uploadataan se TIMiin ja lisätään sitten pluginiin attribuutti:

texafterprint: '![Toisen asteen polynomi](/images/12342/poly2.png)'

Vastaavasti voidaa lisätä myös muotoiltua tekstiä. Esimerkiksi ohjelmalistauksen jälkeen halutaan tulostaa miltä näyttäisi konsoliin tulostettuna kun ohjelma ajetaan.

``` {plugin="csPlugin" #helloeka}
byCode: |!!
public class HelloWorld
{
 public static void Main()
 {
     System.Console.WriteLine("Hello World!");
 }
}
!!
texafterprint: \console{Hello World!}
```

Komento console on käytetävissä vain silloin, kun tehdään lyhyitä esimerkkejä.

Pidempiä esimerkkejä varten on käytettävä ympäristöä consoleenv tyyliin:

\begin{consoleenv} \begin{Verbatim}
Kissa istuu
puussa ja
naukuu
\end{Verbatim}
\end{consoleenv}

Huomaa että \end{Verbatim} kanssa samalle riville ei saa kirjoittaa muuta.

Jotta tämä ei olisi nuin työlästä kirjoittaa, voidaan tehdä TIMin makrot:

``` {settings=""}
texmacros:
  cb: \begin{consoleenv} \begin{Verbatim}
  ce: |
   \end{Verbatim} 
   \end{consoleenv}
```

jolloin vastaava tuloste saadaan:

texafterprint: |!!
%%cb%%
Kissa istuu
puussa ja
naukuu
%%ce%%
!!

5.5 Monivalinta-pluginin asetukset

Nämä asetukset on mahdollista määritellä Monivalinta-pluginille. Nämä asetukset tulee määrittää dokumentin asetuksiin global_plugin_attrs-lohkon sisälle esimerkiksi näin:

global_plugin_attrs:
  mmcq:
    texcorrectText: "Oikein"

Tämä asetus määrittää monivalinta-pluginin oikein merkinnän tapauksessa, jossa tulostetaan käyttäjän vastaukset. Tulostettaessa pluginin yleinen muoto, tällä ei ole vaikutusta. Esimerkiksi voidaan määrittää:

texcorrectText: "Oikein"

Tämä asetus määrittää monivalinta-pluginin väärin merkinnän tapauksessa, jossa tulostetaan käyttäjän vastaukset. Tulostettaessa pluginin yleinen muoto, tällä ei ole vaikutusta. Esimerkiksi voidaan määrittää:

texwrongText: "Väärin"

Tämä asetus määrittää monivalinta-pluginin tulostus muodon sarakkeiden tasauksen. Jokaiselle sarakkeelle on mahdollisuus määrittää oma tasauksensa, l = vasen, r = oikea ja c = keskitetty. Laittamalle näiden kirjaimien väliin pystyviivan eli | saa sarakkeiden väliin pystyviivan. Tämä asetus vaikuttaa pluginiin kun tulostetaan sen yleinen muoto eli ei käyttäjän vastauksia. Esimerkiksi kaikkien tasaus oikealla ja pystyviiva kahden ensimmäisen sarakkeen väliin menee näin:

texcolumns: "|r|r r|"

Tämä asetus määrittää monivalinta-pluginin tulostusmuodon sarakkaiden tasauksen tulostettaessa käyttäjän vastauksia. Jokaiselle sarakkeelle on mahdollisuus määrittää oma tasauksensa, l = vasen, r = oikea ja c = keskitetty. Laittamalle näiden kirjaimien väliin pystyviivan eli | saa sarakkeiden väliin pystyviivan. Esimerkiksi kaikkien tasaus oikealla ja kahden ensimmäisen sarakkeen väliin pystyviiva menee näin:

texcolumns: "|r|r r r r|"

Tällä asetuksella voi määrittää tuleeko kysymys pluginin vaihtoehtojen välille vaakaviiva tulosteeseen. Oletuksen vaihtoehtojen väliin tulee viiva, mutta jos sitä ei haluta tulee asetus määrittää näin:

texhline: ""

5.6 Yksi monesta -pluginin asetukset

Yksi monesta -pluginille voi määritellä myös samat asetukset kuin Monivalinta-pluginille Nämä asetukset tulee määrittää dokumentin asetuksiin global_plugin_attrs-lohkon sisälle esimerkiksi näin:

global_plugin_attrs:
  mcq:
    texcorrectText: Kissa

texcolumns ja texusercolumns asetuksia määritettäessä Yksi monesta -pluginille tulee huomioida sarakkeiden määrä. Määritettäessä asetuksissa tulee olla oikea määrä sarakkeita eli:

texcolumns: |c c|

texusercolumns: |c c c c|

5.7 Viivakoodin tulostaminen

Lisäämällä asetuksiin viivakoodipaketti:

texmacros:
  texpackages: |
    \usepackage[code=Code39,X=.5mm,ratio=2.25,H=1cm]{makebarcode}

voidaan tulostaa viivakoodeja esimerkiksi:

\barcode{12345}

Huomaa että esimerkissä käytettävä viivakoodi on code39 jossa on vain isot kirjaimet ja numerot.

Lisää viivakodista:

• ftp://ftp.funet.fi/pub/TeX/CTAN/macros/latex/contrib/makebarcode/doc/latex/makebarcode/makebarcode.pdf

6. TeX makrojen käyttäminen

Jonkin verran voi käyttää myös TeX-makroja vaikka tämä ei suorituskyvyn takia olekkaan suositeltavin vaihtoehto.

Tarvittavat TeX-makrot kirjoitetaan dokumentin Settings-osaan tyyliin:

``` {settings=""}
doctexmacros: |!!
\newcommand{\water}{H_{2}O}
!!
``` 

Sitten makroja voi käyttää koodissa kirjoittamalla esim:

$\water$

Suorituskyvyn kannalta on parempi käyttää TIMin omia makroja, eli vastaava tehtäisiin:

``` {settings=""}
macros:
    water: '$H_2O$'
!!
``` 

ja käyttötilantessa kirjoitetaan:

%%water%%

7. Puhtaan sisällön tulostaminen

Jos TIMiin ladataan esimerkiksi ohjelmatiedostoja upload toiminnolla, niin ladatun tiedoston osoite muuttuu kun ladataan uusi versio.

Joskus voi olla tarve pitää yhtä osoite samana, jotta joka muutoksen jälkeen sitä ei tarvitse päivittää siellä missä tiedostoon viitataan. Toki usein tämä saadaan laittamalla tiedosto gitiin ja julkaisemalla se osoite. Jos kuitenkin tiedoston muokkausoikeuksia halutaan ylläpitää TIMissä ja kaikki "kurssiin" kuuluva pitää samassa paikassa voi seuraavasta olla hyötyä.

Tehdään "puhdas tekstitiedosto", jota ylläpidetään suoraan TIMissä. Vaiheet tähän ovat:

1. Luo uusi TIM-dokumenti, jonka nimi kuvaa tarvetta, esimerkiksi Hello.java.
   Jos nimen pitää alkaa isolla kirjaimella, voi sisäisen nimen vielä vaihtaa,

2. Lisää dokumentin asetuksiin

   textplain: true

   Tämän ansiosta kaikki teksti mitä kirjoitetaan, näkyy puhtaana tekstinä ilman mitään muotoiluja.

3. Jos haluat että tiedoston voi hakea esimerkiksi wgetillä, niin anna Anonymous lukuoikeudet sille.

4. Kirjoita tiedoston sisältö, esimerkiksi:

   public class Hello {
       public static void main(String args[]) {
           System.out.println("Hello World!");
       }
   }

5. Nyt tiedoston saa "raakana" ulos osoitteella (huomaa view tilalla print):

   • https://tim.jyu.fi/print/tim/koe/tulostus/Hello.java
     
     

6. Tiedoston tekstisisällön voi hakea esim wget-ohjelmalla komennolla:

   wget https://tim.jyu.fi/print/tim/koe/tulostus/Hello.java

8. Yleisiä virheitä ja kiertoteitä niiden korjaamiseksi

Seuraavassa miten joitakin LaTeX käännöksessä tulevia virheitä voisi yrittää korjata

8.1 ! LaTeX Error: Not in outer par mode.

Esimerkiksi jos yrittää saada .huomautus -tyyliseen "laatikkoon" kuvatekstillä olevan kuvan:

#- {.huomautus}
**Kochin lumihiutale**

Kyseisen fraktaalin kehittäjä on nimensä mukaisesti Helge van Koch.
Kuvion rakentaminen aloitetaan pohjajanasta.

![Taso 0.](/images/229434/Nayttokuva_2020-4-7_kello_11.12.03.png)

tulee LaTeX-käännöksessä virheilmoitus:

! LaTeX Error: Not in outer par mode.

Tästä lisää texfaq.org FAQ:ssa. Ongelmana on se, että box sisälle yritetään "liikkuvaa".

Alkeellinen korjaus tähän on että jätetään kuvateksti pois, jolloin \figure-ympäristöä ei tule, eli:

#- {.huomautus}
**Kochin lumihiutale**

Kyseisen fraktaalin kehittäjä on nimensä mukaisesti Helge van Koch.
Kuvion rakentaminen aloitetaan pohjajanasta.

![](/images/229434/Nayttokuva_2020-4-7_kello_11.12.03.png)

Kuvateksti voidaan sitten "manuaalisesti" lisätä kuvan ylä tai alapuolelle, eli joko:

![](/images/229434/Nayttokuva_2020-4-7_kello_11.12.03.png)
>Taso 0.

tai:

>Taso 0:\
![](/images/229434/Nayttokuva_2020-4-7_kello_11.12.03.png)

Edellä väkänen on laitettu jotta teksti sisentyisi hieman.

9. Jekkuja

9.1 Tavuviiva sanassa estää muiden sanan osien tavuttamisen

Esimerkiksi

Toring-täydellinen

ei tavutu LaTeXissa muualta kuin tuon -merkin kohdalta. Tällöin rivistä voi helposti tulla ylipitkä. Tätä voi kiertää niin, että korvataan tuo merkki sellaisella joka sallii tavuttamisen. Tämä vaatii että lisätään paketti

texpackages: |
  \usepackage{hyphenat}

Sitten kirjoitetaan:

Turing\hyp{}täydellinen

Tämä ei kuitenkaan näytä TIMin HTML-näkymässä hyvältä. Lisätään siksi dokumentin asetuksiin globaali ehdollinen makro:

globalmacros:
  _: {% if tex %}\hyp{}{% else %}-{% endif %}

Nyt voidaan kirjoittaa:

Turing%%_%%täydellinen

Tätä on tylsä kirjoittaa, joten jos haluaa päästä vähemmällä, voi määritellä kirjainmakron:

charmacros:
 __: "%%_%%"

Yhdistelmän 2 x alleviiva tilalle voi valita minkä tahansa kirjainyhdistelmän jota ei esiinny itse dokumentissa.

Nyt voidaan kirjoittaa:

Turing__täydellinen

joka on kohtuullisen helppo kirjoittaa ja kääntyy sitten TIM-koodissa pelkäksi tavuviivaksi ja LaTeX-koodissa \hyp{}.

10. Ylläpitäjän toimintoja

10.1 whitelist

Tiedostolla

/opt/tim/.printing_whitelist.config

voi säätää sitä, mitä ulkoisia kuvapolkuja suostutaan lataamaan lokaalille koneelle TeXiä varten. Tiedostossa säännöt ovat regexp muodossa ja kullakin rivillä on yksi sääntö.

Yksinkertaisin vaihtoehto on sallia kuvan hakeminen mistä tahansa osoitteesta, jolloin whitelist tiedosto on:

^.*$

Jos haluttaisiin sallia osoitteet, joissa on jyu jossakin kohti, voisi muoto olla

^.*jyu.*$

10.2 Linkkejä

• Ohjelmalistausten muotoilu

Esim TeXiin sisennys ja vasen viiva highligt-tyyleihin

texmacros:
    texmacros: |!!
\RecustomVerbatimEnvironment {Highlighting}{Verbatim}{frame=leftline, framerule=0.05mm, rulecolor=\color{lightgray}, xleftmargin=2em,commandchars=\\\{\}} 
!!

10.3 Tilapäiset tiedostot

TeX-tiedosto syntyvät hakemistoon tyyliin:

 sudo ls -la /var/lib/docker/volumes/tim_cache/_data/printed_documents/225658/134613/