1. Dokumentointikäytännöt
Tämä opas käyttää useita käytäntöjä tiettyjen sanojen ja lauseiden korostamiseksi sekä huomion kiinnittämiseksi joihinkin dokumentin osiin.
1.1. Typografiset käytännöt
Tiettyjen sanojen ja lauseiden korostamiseksi käytetään neljää typograafista käytäntöä. Nämä käytännöt ja niihin liittyvät tilanteet ovat seuraavat.
Tasavälinen lihavoitu
Käytetään järjestelmälle annettavan syötteen korostamiseen, mukaan lukien komentokehotteen komennot, tiedostonimet ja polut. Käytetään myös korostamaan näppäinten nimiä ja näppäinyhdistelmiä. Esimerkiksi:
Nykyisessä työhakemistossa olevan tiedoston seuraava_menestysromaanini sisällön katselemiseksi syötä komento cat seuraava_menestysromaanini komentokehotteeseen ja paina Enter komennon suorittamiseksi.
Yllä oleva esimerkki sisältää tiedostonimen, komentokehotekomennon ja näppäimen nimen, kaikki esitettynä tasavälisellä lihavoidulla kirjasimella.
Näppäinyhdistelmät voi erottaa näppäinten nimistä näppäinyhdistelmän osia yhdistävän väliviivan ansiosta. Esimerkiksi:
Paina Enter-näppäintä komennon suorittamiseksi.
Paina Ctrl+Alt+F1 ensimmäiseen virtuaalipäätteeseen siirtymiseksi. Paina Ctrl+Alt+F7 X-ikkunointi-istuntoon palaamiseksi.
Ensimmäinen lause korostaa painettavan näppäimen nimeä. Toinen korostaa kahta kolmen näppäimen sarjaa, jotka on tarkoitettu painettavaksi yhtä aikaa.
Jos käsitellään lähdekoodia, kappaleen sisällä mainitut luokkanimet, metodit, funktiot, muuttujien nimet ja palautusarvot esitetään kuten yllä, tasavälisellä lihavoidulla kirjasimella. Esimerkiksi:
Tiedostoihin liittyviä luokkia ovat filesystem tiedostojärjestelmiä varten, file tiedostoja varten sekä dir hakemistoja varten. Jokaisella luokalla on omat oikeutensa.
Suhteellinen lihavoitu
Tämä merkitsee järjestelmään liittyviä sanoja tai lauseita, mukaan lukien ohjelmien nimet, valintaikkunoiden tekstit, painikkeiden nimet, valintaruutujen ja -nappien nimet sekä valikkokohdat. Esimerkiksi:
Valitse valikkopalkista Hiiriasetukset-ohjelman käynnistämiseksi. Napsauta Näppäimet-välilehdessä Vasenkätinen hiiri -valintaruutua ja napsauta Sulje. Näin saat vaihdettua hiiren ensisijaisen näppäimen vasemmalta oikealle, jolloin hiirtä on helpompi käyttää vasemmalla kädellä.
Erikoismerkin lisäämiseksi gedit-tiedostoon valitse valikkopalkista. Valitse seuraavaksi Merkkikartta-ohjelman valikkopalkista, kirjoita merkin nimi Etsi-kenttään ja napsauta Seuraava. Etsimäsi merkki korostetaan Merkkikartassa. Kaksoisnapsauta korostettua merkkiä, jolloin se siirtyy Kopioitava teksti -kenttään ja napsauta sitten Kopioi-painiketta. Vaihda nyt takaisin asiakirjaan ja valitse geditin valikkopalkista.
Yllä oleva teksti sisältää ohjelmien nimiä, valikkonimiä sekä graafisen käyttöliittymän painikkeita ja tekstiä, kaikki esitettynä suhteellisella lihavoidulla kirjasimella.
Huomaa kuinka -merkkiä käytetään ilmaisemaan valikoissa liikkumista. Näin tehdään hankalasti seurattavan ”Valitse valikkopalkin -valikon -alivalikosta” -ilmaisutavan välttämiseksi.
Tasavälinen lihavoitu kursiiviSuhteellinen lihavoitu kursiivi
Tasavälisen lihavoidun tai suhteellisen lihavoidun kirjasimen kursivointi ilmaisee korvattavaa tai vaihtuvaa tekstiä. Kursivointi ilmaisee tekstiä, jota ei syötetä sellaisenaan tai näytettävää tekstiä, joka muuttuu tilanteesta riippuen. Esimerkiksi:
Kirjoita ssh käyttäjätunnus@verkko.osoite komentokehotteeseen etäkoneelle yhdistämiseksi ssh:ta käyttäen. Jos etäkone on esimerkki.com ja käyttäjätunnuksesi tuolla koneella on jussi, kirjoita ssh jussi@esimerkki.com.
Komento mount -o remount tiedostojärjestelmä liittää nimetyn tiedostojärjestelmän uudelleen. Esimerkiksi /home-tiedostojärjestelmän uudelleenliittämiseen tarvittava komento on mount -o remount /home.
Asennetun paketin version näkee komennolla rpm -q paketti. Se palauttaa tuloksen seuraavassa muodossa: paketti-versio-julkaisu
Huomaa yllä olevat lihavoidulla kursiivilla kirjoitetut sanat: käyttäjätunnus, verkko.osoite, tiedostojärjestelmä, paketti, versio ja julkaisu. Jokainen sana on niin sanottu paikkamerkki, joka merkitsee joko paikkaa, johon tekstiä syötetään komentoa annettaessa tai järjestelmän näyttämää tekstiä.
Työn nimen lisäksi kursiivilla esitetään uuden ja tärkeän käsitteen ensimmäinen käyttökerta. Esimerkiksi:
Kun Apache-HTTP-palvelin hyväksyy pyyntöjä, se käynnistää lapsiprosesseja tai säikeitä niiden käsittelyä varten. Tämä lapsiprosessien tai säikeiden joukko tunnetaan nimellä server-pool. Apache-HTTP-palvelimen versiossa 2.0 näiden server-poolien luonti ja ylläpito on annettu moduuliryhmälle nimeltä Multi-Processing Modules (MPM). Muista moduuleista poiketen Apache-HTTP-palvelin voi ladata vain yhden moduulin MPM-ryhmästä.
Kaksi yleensä monirivistä tietotyyppiä erotetaan visuaalisesti ympäröivästä tekstistä.
Päätteelle lähetettävä tuloste esitetään tasavälisellä pystykirjasimella seuraavasti:
kirjat Työpöytä dokumentaatio vedokset mss kuvat juttuja svn
kirjat_testit Työpöytä1 lataukset kuvat muistiinpanot skriptit svgt
Lähdekoodilistauksissa käytetään myös tasavälistä pystykirjasinta mutta ne esitetään seuraavasti:
package org.jboss.book.jca.ex1;
import javax.naming.InitialContext;
public class ExClient
{
public static void main(String args[])
throws Exception
{
InitialContext iniCtx = new InitialContext();
Object ref = iniCtx.lookup("EchoBean");
EchoHome home = (EchoHome) ref;
Echo echo = home.create();
System.out.println("Created Echo");
System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
}
}
1.3. Huomautukset ja varoitukset
Kolmea visuaalista tyyliä käytetään kiinnittämään lukijan huomio tietoon, joka muuten saattaisi jäädä huomaamatta.
Huomautus
Huomautus on vinkki, oikopolku tai erilainen lähestymistapa kyseiseen tehtävään. Huomautuksen ohittamisella ei pitäisi olla ikäviä seurauksia, mutta silloin saattaa ohittaa elämää helpottavan tempun.
Tärkeää
Tärkeää-laatikot kertovat tarkkoja tietoja asioista, jotka on helppoa ohittaa, esimerkiksi vain nykyiseen istuntoon liittyvät asetusmuutokset tai palvelut jotka on käynnistettävä uudelleen päivityksen jälkeen. Tärkeää-laatikoiden ohittaminen ei aiheuta tietojen katoamista, mutta saattaa aiheuttaa ärsyyntymistä ja turhautumista.
Varoitus
Varoitusta ei pitäisi ohittaa. Varoitusten ohittaminen aiheuttaa todennäköisesti tietojen katoamista.