Opinto-oppaan pikaohje Miika Nurminen, 28.2.2008 (minurmin@jyu.fi) Dokumentin osoite: http://opinto-opas.jyu.fi/dokumentit/pikaohje.doc (+pdf) Sovelluksen rakenne ja toiminta Julkaisuprosessi (Kokako-projekti): Julkaisujärjestelmä on jaettu projekteihin (esim. it/2008, science/2008), jotka on edelleen jaettu variantteihin (esim. it/2008/opas, science/2008/opas, it/2008/puhlu) Kooste.xml variantin omassa hakemistossa määrittää käytettävät tiedostot (lukutasolla) ja kansitiedot Varsinainen sisältö on varianteille (mutta ei projekteille) yhteisessä xml-hakemistossa esim it/2008/xml
Käyttöympäristö Verkkolevy Verkkolevyn mappaus windowsin komentorivillä esim: net use l: \\sovpa3.cc.jyu.fi\opinto-opas /user:tunnus Tai: explorerissa päävalikosta tools->map network drive Verkkolevyä voi käyttää kotikoneellakin, kunhan jyu:n vpn-yhteys on päällä - [ http://ww.jyu.fi/erillis/thk/ohjeet/verkko/vpn ] Verkkolevyn juurihakemisto vastaa www-osoitetta http://opinto-opas.jyu.fi/ - alihakemistot varattu eri opasprojekteille (esim. it, science, testit) Kukin projekti voi edelleen sisältää omia opasvariantteja - esim. it:llä op_opas, ov_opas, puhlu ja kurssit
Toimii myös linux-pääteyhteydellä (esim. charra- ja jalava-koneet) - näkyy hakemistona /var/www/virtual.hosts/opinto-opas.jyu.fi/ Huom. tammikuusta 2008 eteenpäin eppu- ja sovpa1-koneilla olleet verkkolevyt eivät ole enää käytössä! Web-hallintakäyttöliittymä Osoitteen https://opinto-opas.jyu.fi/hallinta/-alla eri versioille ja varianteille omat alihakemistonsa, https://opintoopas.jyu.fi/hallinta/it/2007/ jne Myös ohjaukset vanhoista osoitteista http://opinto-opas.jyu.fi/hallinta/, http://opintoopas.jyu.fi/it/2007/hallinta/ jne käytössä Kirjautuminen Korppi-käyttäjätunnuksen avulla Kirjautuessa selain voi varoittaa sertifikaattien puutteesta ja siitä, etteivät osoitteet opinto-opas.jyu.fi ja sovpa3.cc.jyu.fi täsmää. Tässä tapauksessa tästä ei tarvitse välittää, vaan hyväksyä varoitukset.
Sisältää kaikki keskeiset loppukäyttäjän koostamis- julkaisu ja esikatselutoiminnot tiedostokohtaisesti. Lisäksi kurssien haku. Mahdollista myös muokata xml-tiedostoja - editointikäyttöliittymänä tavallinen webtekstieditorikomponentti
XML-editori Kaikki laajemmat muokkaukset tiedostoihin kannattaa tehdä erillisellä, paikallisella koneella ajettavalla xml-editorilla Esim. XML Spy (kaupallinen), Exchanger, mikä tahansa tekstieditori tai monet sovelluskehittimet (esim. NetBeans, Eclipse) Muokkauprosessi: tiedostoja muokataan suoraan verkkolevyltä (huom. riskit monen käyttäjän editoidessa) ja ajetaan hallintakäyttöliittymällä esikatselutoimintoa Hakemistot htmlwork ja pdfwork päivittyvät myös automaattisesti selainta refreshatessa, jos tiedostoja on muuttunut (päivitys helpointa hallintakäyttöliittymällä) Mozillaa, IE:tä tai muuta xslt:llä varustettua selainta käytettäessä voi myös avata suoraan xml-tiedoston selaimeen, jolloin näkee karkean html-esikatselun Xml-editorit Exchanger - [ www.freexmleditor.com ] ilmainen ei-kaupalliseen käyttöön, ominaisuuksiltaan lähellä xml spyta + Editori osaa itse ehdottaa käyttäjälle elementtejä ja attribuutteja editoidessa ja ilmoittaa virheistä + Editoriin voi tehdä omia "projekteja", jonka avulla sisältötiedostoihin pääsee helposti käsiksi + Puumaisesti "laskostettava" xml-näkymä - Ajoittain hidas - Editorissa voisi olla vieläkin enemmän avustavia toimintoja Editoinnista kooste.xml tai hallintakäyttöliittymän puu kannattaa pitää jatkuvasti avoinna "maalaamalla" exchangerissa kooste.xml:ssä olevan tiedostonimen (esim.../xml/18_jatkokoulutus.xml), tiedoston voi avata ponnahdusvalikon avulla lukutiedostojen nimissä kannattaa pitää juokseva numerointi, joka liittyy lukujen suhteelliseen järjestykseen
jos luvun validiudesta on epäilyksiä, ponnahdusvalikossa on validointitoiminto. lisäksi dokumentti validoidaan automaattisesti tallennettaessa. jos xml-dokumentti sisältää leveyssuunnassa pitkiä rivejä, automaattisen rivityksen saa päävalikosta: View->Editor Properties->Soft wrapping aktiivista dokumenttia voi vaihtaa alt-1:llä. huom. välilehdet: xml-puurakenne - huomaa attribuuttien laittaminen näkyviin (esim. opasvariantit erottuvat selkeämmin) ohjelma osaa varoittaa, jos dokumenttia on muokattu toisaalla. tällöin on syytä olla varovainen muutosten kanssa. Pikanäppäimiä ctrl-w sulkee tämänhetkisen (xml)-tiedoston ctrl+enter "avaa" tai "sulkee" kursorin kohdalla olevan xml-alipuun (marginaalissa olevat +/- -merkit) ctrl-ylös/alas - menee tämänhetkisen elementin alku/lopputagiin F7 validoi dokumentin Harjoitus: käynnistä exchanger start-valikosta (voi kestää hetken) Joillakin koneilla ei käynnisty suoraan - tällöin komentoriviltä ohjelman omasta hakemistosta java -jar lib\xngr-loader.jar Tee opasprojekti: Project->New project (nimeksi esim. opas), Add virtual folder L (opinto-opas on sovpa.cc.jyu.fi -levy \testit\xml) (huom. voi toimia hitaasti) Projektiin hakemistoksi esim. testit, jokin sen variantti (jos tarkoitus editoida kooste.xml:ää) tai testit\xml (jos tarkoitus editoida vain lukuja) - mielellään tässä vaiheessa ei mitään it- tai science-hakemistojen alta testit-projektin alla olevaa sisältöä (kopioitu sekä it- että mltk-oppaista + muita testejä) voi editoida ja kokeilla vapaasti tuotantokäytössä hakemistot it\2008\xml, science\2008\xml jne muut projektipuussa olevat projektit voi selkeyden vuoksi tuhota (voi lisätä myöhemmin uudelleen tarvittaessa, löytyvät exchangerin omasta hakemistosta) käyttöliittymän ulkoasun vaihto windows-tyyliseksi (vaatii uudelleenkäynnistyksen): file- >preferences->system->look and feel
Xml Spy - [ http://ww.altova.com/products/xmlspy/xml_editor.html ] Kaupallinen, lisenssejä saatavilla rajoitetusti Tab-merkit kannattaa vaihtaa max. 2 välilyönniksi ja rivnvaihdot cr/lf-muotoon - helpottaa editointia selaimessa valikosta tools -> options ja file-välilehti, ks. kuva Html Kit - [ www.htmlkit.com ] Shareware, suuniteltu html:n editointiin Xml:ää editoitaessa värikoodaa elementit, mutta ei osaa ehdottaa elementtien/attribuuttien nimiä
Kooste.xml:n rakenne Kansitiedot Oppaan + variantin nimi, julkaisija, julkaisuvuosi jne Työryhmätiedot Muita alkuun tulevia huomautuksia Oppaan "osat" Esiluvut: ei numeroida Tekstiluvut: numeroidaan normaalisti Liitteet: luetellaan kirjaimilla Takaluvut: ei numeroida Jokainen osa voi sisältää lukuja, jotka annetaan tiedostoviittauksella xml-hakemiston käyttö on vain käytäntö - muuttamalla hakemistoviittausta tiedostoja voisi periaatteessa käyttää muualtakin Luvut voivat edelleen sisältää alalukuja tasoon 3 saakka Alalukujen erottaminen yksittäisistä lukutiedoista on hyödyllistä, jos tietoja generoidaan automaattisesti (esim. osa mltk:n kurssitiedoista) tai eri variantit käyttävät eri palasia luvuista (esim. it-tutkintovaatimukset) Alalukurakenne voidaan merkitä kooste.xml:ään (mltk-variantti) tai sisältötiedostoihin (opas- ja fuksiopas-variantit) - molemmissa tapauksissa hallintakäyttöliittymä näyttää koko tiedostorakenteen Koosteen rakennemääritys: opas.dtd, luku.dtd, kansi.dtd jne [ http://pinto-opas.jyu.fi/testit/skriptit/opas.dtd ]
Oppaan lukujen editointi Luku.dtd on perusrakenteeltaan lähellä html:ää, mutta elementit on nimetty suomeksi Rakenteellisesti lähellä html:ää: listat, kappaleet, taulukot, korostukset, viittaukset Rakenteellisia eroja luvut ja aliluvut "ympäröivät" sisältönsä (vs. html:ssä h-elementeillä merkataan vain otsikot metatiedot suunniteltu oppaan julkaisuprosessia ajatellen joissakin elementeissä lisätietoja tai käytäntöjä, joita ei ole html:ssä, esim. kuvatekstit, taulukoiden ja sarakkeiden tyypit Yleisesti: luku.dtd on huomattavasti html:ää yksinkertaisempaa - esim. suurinta osaa html:ssä määriteltyjä inline-tason muotoiluelementtejä ei ole Taulukoista Html-taulukoiden tyylisiä jopa niin pitkälle, että monesti on mahdollista tehdä taulukko aluksi html-editorilla ja korvata elementtien ja attribuuttien nimet luku.dtd:n vastaavilla - saraketyypit pitää silti säätää käsin Sisäisen toteutuksensa (LaTeX) takia taulukoissa on jonkin verran rajoitteita, jotka voivat olla vaikeasti hahmotettavissa - [ opinto-opas.jyu.fi/testit/testit/pdf ] Helpointa on sopia organisaation sisällä esim. tutkintovaatimusten kuvaamiseen yksi pohja ja kopioida siitä taulukot Taulukkotyypit tavallinen: taulukko ilmestyy juuri samaan kohtaan tekstissä ilmaistun kanssa kelluva: LaTeX päättää taulukon asettelusta "parhaaseen" paikkaan. taulukon mahduttava yhdelle sivulle riviyli & sarakeyli -attribuutit: solu voi mennä monen rivin tai sarakkeen yli (mutta ei samanaikaisesti) Sarakkeen tasaustyypit (määritellään ensimmäisellä rivillä) vasen - oletus tiivistetty - vasemmalle tasaus, joka jättää tavallista enemmän tilaa oikeaan reunaan
keskitetty oikea tasattu - tasaus molempiin reunoihin Saraketyypit (määriteltävä ensimmäisellä rivillä, ei voi muuttaa): tavallinen: saraketta ei rivitetä, voi mennä tekstin leveyden yli monirivi: sarake yritetään rivittää automaattisesti Monirivisten sarakkeiden leveys määritetään automaattisesti tavallisista ja kapeista sarakkeista ylijäävästä tilasta niin, että leveys on kaikilla taulukon monirivisarakkeilla sama. Helpoin tapa muotoilla taulukko niin, että kaikki solut vähintään näkyvät on tehdä kaikista sarakkeista monirivisiä. Laadultaan paras tulos saadaan kuitenkin säätämällä sarakkeiden tyyppiä (ja jopa yksittäisten solujen asettelua) niiden todellisuudessa vaatiman tilan mukaan. monen sarakkeen yli menevän solun tasaus määräytyy siihen kuuluvan vasemmanpuolimmaisimman sarakkeen mukaan Huom! monen sarakkeen yli menevää solua ei rivitetä automaattisesti, ellei mene koko taulukon yli. kapea: kiinteä, "kapea" leveys Kapeilla sarakkeilla on vakioleveys, joka on n. 2 cm. Kapeat sarakkeet rivitetään automaattisesti. Solut tasataan pystysuunnassa ylös Viitteistä <viite>-elementillä voidaan viitata mihin tahansa oppaan lukuun, taulukkoon tai kuvaan - kohteen id:n täytyy täsmätä myös www-linkkeihin tai sähköpostiosoitteisiin voidaan viitata valitsemalla viitteen tyyppi Kuvalle annettava leveys pdf-käsittelyä varten (esim. 10.5cm) Luvun rakennemääritys: luku.dtd, meta.dtd, kappale.dtd jne [ http://opinto-opas.jyu.fi/testit/skriptit/luku.dtd ]
Varianttien ja koostettujen lukujen käsittely Kooste.xml:n lisäksi myös sisältötiedostot voivat sisältää tiedostoviittauksia - merkintätapa on sama kuin kooste.xml:ssä Lukutason täytyy olla järkevä: esim. aliluku2-tason sisälle ei voi sisällyttää "luku"- tasoista tiedostoa Poikkeus: "ylemmän tason" tiedoston voi sisällyttää yhtä tasoa alemmaksi, jos ylimmällä tasolla ei ole otsikkoa - tällöin vain alempi taso huomioidaan Hyötynä on, että näin saadaan kierrettyä xml:n rajoitus vain yhdesstä juurielementistä ja pakattua samaan asiaan liittyvät tiedot yhteen lukuun Käytetty esim. kurssikuvauksissa Viitatuille luvuille ja usemmille muillekin elementeille voidaan lisäksi merkitä opasvariantti-attribuutilla, mihin varianttiin se otetaan mukaan Variantin määritely kiinteästi dtd:ssä (ei mltk): nyt op_opas, ov_opas, puhlu ja kurssit Esim. voidaan merkitä samaan tiedostoon kahteen kertaan "sama" kappale suunnattuna eri variantteihin Vähentää merkittävästi copy/pastetustarvetta tai tiedostoja