Documentació d'aplicacions

La documentació de les aplicacions és un aspecte summament important, tant pel que fa al desenvolupament com pel que fa al manteniment de l’aplicació. Hi ha molts programadors que no li donen gaire importància i no s’adonen que perden la possibilitat de reutilitzar part del programa en altres aplicacions, sense necessitat de conèixer el codi fil per randa.

La importància de la documentació es podria comparar amb la importància de tenir una pòlissa d’assegurança; quan tot va bé no es té la precaució de confirmar si la pòlissa d’assegurança és vigent o no.

La documentació d’una aplicació comença en el moment que es comença a construir l’aplicació i finalitza just abans de lliurar-la al client. Així mateix, la documentació que es lliura al client ha de coincidir amb la versió final dels programes que componen l’aplicació.

L’estil de redacció dels manuals de documentació ha de complir aquests requisits:

• Ser concret.
• Ser precís.
• Definir els termes utilitzats.
• Utilitzar paràgrafs curts.
• Utilitzar títols i subtítols.
• Utilitzar formes actives en lloc de passives.
• Evitar frases llargues que presentin fets diferents.
• Evitar referir-se a una informació només amb el número de referència.

Els fitxers d’ajuda contenen la informació per ajudar l’usuari a fer servir l’aplicació.

Ara veureu els formats principals del sistemes operatius següents:

• Microsoft Windows
• Mac OS X
• UNIX - Gnu/Linux

Dins del sistema operatiu Microsoft Windows, veureu el primer format, el Microsoft Compiled HTML Help, que es va crear l’any 1997. També veureu l’evolució d’aquest format, el Microsoft Assistance Markup Language, que incorpora més garanties de seguretat.

El Microsoft Compiled HTML Help és un format desenvolupat per Microsoft que es va llançar el 1997 per als fitxers d’ajuda del sistema. Es va introduir per primera vegada amb el llançament del Windows 98 i encara s’utilitza en les plataformes Windows XP, Windows Vista i Windows 7. El 2002 es va anunciar que hi havia riscos de seguretat associats a aquest format, per la qual cosa es va decidir no continuar utilitzant-lo i crear-ne un de nou, el Microsoft Assistance Markup Language.

Per crear els fitxers d’ajuda HTML (extensió chm) s’utilitzen eines d’autoria d’ajuda. Microsoft proporciona una eina, el Help Workshop, que es pot descarregar gratuïtament. A partir dels arxius amb el text de l’ajuda, un compilador de línia d’ordres (hhc.exe) els compila i crea un arxiu CHM. També hi ha una sèrie d’eines d’autor de tercers disponibles.

Un fitxer amb extensió chm constitueix un conjunt de documents d’HTML i altres dades, com imatges i JavaScript, comprimit en un sol arxiu. Els arxius CHM contenen un nombre de característiques molt útils que ajuden l’usuari a trobar el que busca:

• Taula de contingut
• Índex de paraules clau
• Funcionalitat de cerca amb text complet

El Microsoft Assistance Markup Language (conegut normalment com a MAML) és un llenguatge de marques basat en XML. Aquest llenguatge el va desenvolupar l’equip d’assistència a l’usuari de Microsoft a fi d’oferir ajuda per al sistema operatiu Microsoft Windows Vista. Algunes de les característiques del MAML han estat disponibles en el .NET Framework 2, però s’hi han afegit més opcions amb el llançament del .NET Framework 3.

L’aspecte més significatiu del MAML és que desplaça la producció de l’assistència a l’usuari amb el concepte autoria estructurada (semblant al DocBook). Els documents i els elements que els constitueixen es defineixen pel context en què es troben. L’èmfasi es posa en el contingut i en les tasques que un usuari fa amb l’ordinador, no en les característiques del programari.

L’estructura del MAML es divideix en segments relacionats amb un tipus de contingut:

• Resolució de problemes conceptuals
• Preguntes freqüents
• Glossari
• Procediment de referència
• Contingut reutilitzable
• Tasca
• Tutorial

Quan apareix un tema, es produeixen tres nivells de transformació:

• Estructura
• Presentació
• Representació

La transformació estructural conté contingut reutilitzable. La lògica condicional s’aplica per determinar l’estructura que ha de tenir el contingut quan es mostra i el contingut del text mateix.

La transformació de la presentació permet que el contingut creat en MAML es pugui transformar en molts formats diferents, incloent-hi el DHTML, l’XAML, el format de text enriquit i altre material imprès.

La transformació de la representació aplica fulls d’estil i mostra el contingut final als usuaris.

L’ajuda d’Apple proporciona assistència a l’usuari basada en el format de fitxers HTML.

L’ajuda d’Apple gestiona i mostra els llibres ajuda. Un llibre d’ajuda és la col·lecció de fitxers HTML que constitueixen l’ajuda a l’usuari d’un producte de programari, a més d’un índex de l’ajuda dels arxius indexats generats. En crear un llibre d’ajuda, els usuaris poden accedir a l’ajuda de la seva interfície d’usuari i veure-ho directament en el visualitzador d’ajuda d’Apple.

L’ajuda en els entorns Linux està lligada a l’ajuda que ofereixen les ordres de sistema de l’UNIX. Per mostrar l’ajuda executarem:

man <nom ordre> 

Cada pàgina és un document independent.

La majoria d’aplicacions gràfiques sobre l’UNIX (sobretot les construïdes amb els entorns de desenvolupament GNOME i KDE) proporcionen a l’usuari final la documentació en HTML i inclouen visors d’HTML incrustats, com el Yelp, el qual s’utilitza per a la lectura de l’ajuda dins de l’aplicació.

A continuació, veureu dues eines gratuïtes per generar fitxers d’ajuda. L’una és el Microsoft HTML Help Workshop, per al Microsoft Windows, que únicament genera fitxers amb extensió chm, i l’altra és el DocBook, que pot generar un rang més ampli de fitxers d’ajuda.

L’ajuda HTML (.chm) és un estàndard de l’ajuda del Windows. Combina la funcionalitat del programari del Windows WinHelp amb la flexibilitat de l’HTML (hypertext markup language) i el poder dels controls ActiveX.

Creareu un arxiu de projecte, el qual permetrà compilar la llista de fitxers (HTML i gràfics) que formaran el sistema d’ajuda. Modificareu l’aspecte de l’arxiu i en definireu unes quantes característiques especials.

Per crear un projecte nou, cal que seguiu els passos següents:

1. Executeu l’aplicació Microsoft HTML Help Workshop. Apareixerà la finestra que es pot veure en la figura.

2. Seleccioneu l’opció File – New. Apareixerà el quadre de diàleg que es mostra en la figura.

3. L’opció Project està seleccionada per defecte. Feu clic al botó OK i s’obrirà el quadre de diàleg New Project (vegeu la figura).

4. Com que creeu un projecte nou, no marqueu l’opció i feu Siguiente. A continuació, apareixerà el quadre de diàleg New Project – Destination (vegeu la figura).

5. Escriviu la ruta i el nom del fitxer en el quadre de text d’entrada. Cliqueu a Siguiente. Apareixerà el quadre de diàleg New Project – Existing Files.

6. Com que creeu un projecte des de zero i no teniu cap fitxer creat, feu Siguiente. Apareixerà l’últim quadre de diàleg, New Project - Finish (vegeu la figura i figura).

7. En prémer el botó Finalizar, apareixerà el quadre de diàleg de l’aplicació, HTML Help Workshop (vegeu la figura).

El pas següent consisteix a establir les característiques que tindrà la finestra d’ajuda.

1. Feu clic a Add/Modify Window Definitions (vegeu la figura).

Llavors apareixerà el quadre de diàleg Add a New Window Type (figura).

Modify Window Definitions

2. Entreu el nom (per exemple, principal) i feu OK. Apareixerà el quadre de diàleg Window Types (figura).

En la finestra es mostren les pestanyes següents:

• Buttons: especifica els botons que apareixeran en la finestra d’ajuda.
• Position: especifica la posició i la mida de la finestra d’ajuda.
• Files: especifica els fitxers que s’utilitzaran en les diverses parts de l’ajuda.
• Navigation Pane: especifica el panell de navegació de la finestra d’ajuda.
• Styles i Extended Styles: especifiquen els estils que s’aplicaran a la finestra d’ajuda.

3. Especifiqueu les característiques que vulgueu a la finestra i feu Aceptar per acabar.

Si se selecciona la cerca de text complet, la llista de paraules d’aturada impedeix que les paraules comunes, com i/o, es mostrin en els resultats de la cerca. Incloure una llista d’aturada redueix la mida de l’índex de cerca de text complet, cosa que significa que l’arxiu que en resultarà també serà més petit.

Les paraules d’aturada es guarden en un fitxer de text amb extensió stp.

Un tema (topic) és un “tros” d’informació que es guarda en un fitxer en un format HTML i amb el qual es treballa per crear l’ajuda.

Per crear un tema nou, cal seguir els passos següents:

1. Seleccioneu l’opció File > New > HTML file.

2. Entreu el títol del tema i feu OK. Apareixerà una finestra nova a la dreta.

3. Modifiqueu el DOCTYPE, perquè el que es genera no és correcte. Poseu-hi l’HTML 4.01 Transitional DOCTYPE:

   <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
     "http://www.w3.org/TR/html4/loose.dtd"> 

4. Entreu el contingut del tema en format HTML.

5. Deseu el fitxer i poseu-li un nom.

6. Incorporeu el fitxer creat com a tema dins l’ajuda. Feu clic a la icona Add/Remove Topic Files (figura).

Remove Topic Files

Apareixerà el quadre de diàleg Topic Files (figura).

7. Premeu el botó Add i seleccioneu el fitxer acabat de crear com a tema nou per a l’ajuda.

El tema d’inici apareix quan els usuaris obren l’arxiu d’ajuda. És la primera informació que els usuaris veuen dins la finestra d’ajuda.

Per definir el tema d’inici, cal seguir els passos següents:

1. Feu clic a Change Project Options (vegeu la figura).

2. S’obrirà el quadre de diàleg d’opcions del projecte, Options, i apareixerà la pestanya General (figura).

3. Seleccioneu, en el menú desplegable Default file, el fitxer amb el tema d’inici que vulgueu.

4. Feu Aceptar.

Com que treballem amb fitxers en format HTML, la navegació entre els diferents temes relacionats es fa per mitjà d’enllaços (hyperlinks).

Un enllaç a HTML està format de la manera següent:

   <a href="URL destinació"> Text explicatiu de l'enllaç</a>

Segons el contingut de l’adreça URL de destinació, es pot indicar una de les possibilitats següents:

• Pàgina a Internet: URL destinació = http://ioc.xtec.cat/
• Enllaç a un tema: URL destinació = Tema.htm”
• Enllaç a un tema dins un projecte d’ajuda diferent: URL destinació = projecte2.chm::/Tema2.htm
• FTP: URL destinació = ftp://ftp.xtec.cat
• Marca dins del text del tema: URL destinació = Tema.htm#Marca
• Adreça correu = mailto:nom@ioc.cat

El procés de compilació agafa tots els fitxers que heu creat en el projecte, els comprimeix i genera un fitxer de sortida en format .chm que conté el sistema d’ajuda muntat.

Abans de compilar el projecte, cal que comproveu les opcions de compilació i que tots els fitxers estan desats en el disc.

Per comprovar les opcions de compilació, cal que seguiu els passos següents:

1. Feu clic a Change Project Options (figura).

2. S’obrirà el quadre de diàleg d’opcions del projecte, Options. Seleccioneu la pestanya Compiler (figura).

En aquesta pestanya es poden especificar les opcions de compilació. Les més significatives són les següents:

• While compiling, display: permet especificar la sortida de l’informe de compilació. Se li pot demanar informació sobre el fitxer que compila o bé que faci un recull dels possibles errors, enllaços trencats, etc.
• Compatibility: permet definir la compatibilitat amb la versió 1.0.
• Don’t include folders in compiled file: permet definir que tots els fitxers s’ubiquin en l’arrel de l’ajuda. Si s’utilitza aquesta opció, s’ha de vigilar que els noms dels fitxers que hi hagi en les diverses carpetes no siguin iguals.
• Compile full-text search information: permet especificar que la cerca dins l’ajuda es faci a tot el text.

Per compilar el projecte, cal seguir els passos següents:

1. Cliqueu, en la barra principal, a la icona Compile HTML File (figura).

2. Apareixerà la finestra prèvia a la compilació.

Es pot marcar que tots els fitxers es desin al disc abans de la compilació, Save all files before compiling, i també que després de la compilació es mostri l’ajuda resultant, Automatically display compiled help file when done (vegeu la figura).

3. Feu Compile.

La taula de continguts constitueix una manera de navegar per la finestra d’ajuda. Presenta la informació d’una manera jeràrquica per mitjà d’encapçalaments i pàgines.

1. Per accedir a la taula de continguts, cal que premeu la pestanya Contents (figura).

2. Com que la taula de continguts encara no està definida, apareixerà un quadre de diàleg que us preguntarà si voleu crear una taula de continguts o bé si en voleu obrir una que ja estigui creada. Per crear-ne una, haureu de mantenir el valor seleccionat per defecte (vegeu la figura).

3. En fer OK, apareixerà el quadre de diàleg Guardar como, en què haureu de posar un nom al fitxer (figura).

A continuació, haureu de definir la taula de continguts, la qual consta d’encapçalaments i pàgines de contingut.

1. Feu clic a la icona Insert a heading per inserir un encapçalament (figura).

Apareixerà el quadre de diàleg d’entrada nova en la taula de continguts, Table of Contents Entry (figura).

2. Entreu el títol i feu clic al botó Aceptar. L’encapçalament es mostra a la part superior de la pestanya Contents.

Per crear un encapçalament nou, feu clic a inserir un encapçalament nou (vegeu la figura). Apareixerà un missatge que us demanarà si voleu inserir aquest encapçalament a la part superior de la jerarquia. Premeu Sí o No.

La posició de les pàgines i els encapçalaments sempre es pot canviar més tard amb les fletxes de posició (figura).

Un encapçalament també pot enllaçar amb un tema. Poseu-hi el nom i premeu el botó Add per introduir el lligam amb el tema que vulgueu.

1. Feu clic a Insert a Page (figura).

La primera vegada que s’insereix una pàgina, apareix un missatge que demana si es vol inserir la pàgina a la part superior de la jerarquia.

2. Premeu Sí o No. Apareixerà el quadre de diàleg d’entrada nova en la taula de continguts, Table of Contents Entry (figura).

3. Escriviu el títol de la pàgina.

4. Feu clic al botó Add. Apareixerà el quadre de diàleg Path or URL per poder escollir el fitxer (figura).

5. Podeu seleccionar un tema de la llista o bé una adreça URL per escollir-ne un que sigui en un fitxer.

6. Feu OK.

1. Cliqueu, en la pestanya Project, a Add/Modify Window Definitions (figura).

Modify Window Definitions

2. Seleccioneu la pestanya Files (figura).

3. Feu clic a la fletxa avall, al costat de TOC, i seleccioneu el contingut del fitxer amb extensió .hhc.

4. Seleccioneu la pestanya Navigation Pane (figura).

5. Seleccioneu la sincronització automàtica, Auto Sync, i modifiqueu la pestanya per defecte, Default tab.

6. Premeu el botó Aceptar.

L’índex està format per un conjunt de paraules clau. Cada paraula clau està associada amb un tema. Fa la mateixa funció que un índex d’un llibre, és a dir, ajuda a trobar el que es busca. L’índex es desa en un fitxer amb extensió .hhk .

1. Per accedir a l’índex, cal que feu clic a la pestanya Index (figura).

2. Com que l’índex encara no està definit, apareixerà un quadre de diàleg que us preguntarà si en voleu crear un o bé si en voleu obrir un que ja estigui creat (vegeu la figura). Per crear-ne un, cal mantenir el valor seleccionat per defecte.

3. En prémer OK, apareixerà el quadre de diàleg Guardar como, en què caldrà introduir un nom per al fitxer (figura).

Per crear una paraula clau, cal seguir els passos següents:

1. Feu clic a inserir una paraula clau, Insert a Keyword (figura).

2. Apareixerà el quadre de diàleg Index Entry (figura).

3. Escriviu la paraula clau en el quadre d’entrada de paraules clau, Keyword. Feu clic a Add. Apareixerà el quadre de diàleg Path or URL (figura).

4. Seleccioneu el tema de la llista de fitxers i feu clic OK.

5. Premeu Aceptar.

Per crear entrades a dos nivells, seguiu els passos anteriors i utilitzeu les fletxes per col·locar l’entrada en el nivell i la posició corresponent (vegeu la figura).

1. Feu clic, en la pestanya Project, a Add/Modify Window Definitions (figura).

Modify Window Definitions

2. Seleccioneu la pestanya Files (figura).

3. Feu clic a la fletxa avall, al costat d’Index, i seleccioneu el contingut del fitxer amb extensió .hhk.

4. Premeu el botó Aceptar.

El programa Microsoft HTML Help Workshop inclou un programa editor d’imatges, l’HTML Help Image Editor, que es pot fer servir per crear captures de pantalla i altres gràfics (figura).

Per iniciar l’editor d’imatges, cal que seleccioneu Tools > HTML Help Image Editor (figura).

En un projecte d’ajuda es poden incloure els tipus de gràfics següents:

• GIF
• JPG
• BMP
• ICO

HAL Computer Systems i O’Reilly & Associates el van crear l’any 1991. Avui dia, però, hi participen empreses com Novell, Sun Microsystems i Hewlett Packard, entre altres. També s’utilitza en la documentació de projectes de programari lliure, com el GNOME, el KDE i el PHP.

Un exemple de text que conté marques té la forma següent:

   <titol> Text de Títol </titol>

   <paragraf>
       Això seria un paràgraf, amb un text en <negreta>cursiva</negreta>
   </paragraf>

Les marques d’inici serien:

<titol>
<paragraf>
<negreta>

i les de final:

</titol>
</paragraf>
</negreta> 

El text que hi ha entre la marca d’inici i la de final està subjecte al significat que es dóna a la marca. El text que hi hagués entre les dues marques (per exemple, en el cas de la marca “títol”) es tractaria com un títol i s’hi podria definir un estil més destacat que el que es donaria a la marca “paragraf”.

L’autor no s’ha de preocupar de l’estil final del document. Mentre crea el text, hi va afegint les marques que donen significat a determinades parts. Un cop creat, s’apliquen els estils, segons el format que es vol crear, a les marques que hi ha i el resultat es guarda en el format seleccionat.

El DocBook permet exportar el text als formats següents:

• HTML, XHTML, Ajuda Java, Ajuda HTML
• PDF, PostScript, RTF, Text
• Format d’ajuda d’UNIX «man pages»

Com que la informació no té format visual, és més fàcil reutilitzar-la en altres documents.

El DocBook és un estàndard, és de codi obert (open source) i té una gran base de desenvolupadors i una comunitat de suport important.

• L’aprenentatge del llenguatge de marques és una mica lent.
• Hi ha moltes marques, més de quatre-centes etiquetes diferents.
• No totes les eines “bones” per crear algun tipus de format són lliures.

Els documents necessiten un diccionari. En aquest diccionari es descriu la sintaxi i l’estructura que han de tenir els documents escrits amb llenguatge de marques perquè siguin correctes. Aquesta definició del tipus de document s’anomena DTD (document type definition, definició de tipus de document).

El DocBook pot treballar amb dos llenguatges de marques diferents, l’XML (extensible markup language, llenguatge d’etiquetatge extensible) o l’SGML (standard generalised markup language, llenguatge d’etiquetatge generalitzat estàndard). Així, els documents es poden crear utilitzant la sintaxi de l’XML o l’SGML. Quan un document segueix les normes i l’estructura definides en el diccionari, es pot considerar vàlid.

L’article correspon a documents més petits que un llibre, com els articles de revista, els llibres blancs o les notes tècniques. Sovint és el punt de partida més lògic.

Un llibre típic (en anglès, si més no) conté entre les etiquetes

<bookinfo> i </bookinfo>

informació del llibre mateix sobre el títol, l’autor i el copyright. També inclou un o diversos prefacis entre les etiquetes

<preface> i </preface>

així com capítols varis entre les etiquetes

<chapter> i </chapter> 

i, a vegades, un apèndix entre les etiquetes

<appendix> i </appendix>

A més, pot contenir bibliografia, glossaris, índexs i un colofó.

Estructura d’un llibre:

   <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

   <book>

   <bookinfo>
     <title>El meu primer llibre</title>
     <author><firstname>Nom</firstname><surname>Cognom</surname></author>
     <copyright><year>Any</year><holder>Nom Cognom</holder></copyright>
   </bookinfo>

   <preface><title>Títol prefaci</title> ... </preface>

   <chapter> ... </chapter>
   <chapter> ... </chapter>
   <chapter> ... </chapter>

   <appendix> ... </appendix>
   <appendix> ... </appendix>

   <index> ... </index>

   </book>

Els capítols

<chapter> i </chapter>

així com els pròlegs

<preface> i </preface> 

i els apèndixs

<appendix> i </appendix>

tenen una estructura semblant. Es componen d’un títol, d’informació addicional, si escau, i d’un nombre qualsevol d’elements a escala de bloc, seguit per un nombre qualsevol de seccions de nivell superior.

Una secció es una divisió lògica del contingut del document. Les seccions es defineixen per mitjà de marques:

de <sect1> a <sect5>

La marca “section” només es pot utilitzar en documents de tipus article. Cada secció, al seu torn, pot contenir un nombre qualsevol d’elements a escala de bloc seguit per un nombre qualsevol de seccions, com es mostra en l’exemple següent.

  <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

  <chapter>
   <title>My Chapter</title>

   <para> ... </para>

   <sect1 id="seccio_1">
    <title>Títol secció 1</title>
    <para>Paràgrag secció 1</para>
   </sect1>

   <sect1 id="seccio_2">
    <title>Títol secció 2</surname>
    <para>Paràgrag secció 2</para>
    <sect2 id="seccio_2.1>
      <title>Títol secció 2.1</email>
      <para>...</para>
    </sect2>
   </sect1>

  </chapter>

Essencialment, el cos d’un article és el mateix que el d’un capítol, o que el de qualsevol altre element a escala de component. Es mostra en l’exemple següent.

  <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
 <article>
 
  <artheader>
    <title>El meu Article</title>
    <author><honorific>Dr</honorific><firstname>Eduard</firstname>
            <surname>Jarder</surname></author>
  </artheader>
 
  <para> ... </para>
 
  <sect1>
    <title>Títol secció 1</title> 
    <para> ... </para>
  </sect1>

  <bibliography> ... </bibliography>

 </article>

Quan l’autor del contingut acaba de crear un fitxer XML amb el format del DocBook, comença el procés de transformació. Cal aplicar un estil identificat segons uns patrons a cada marca. Aquests estils es desen en uns arxius d’extensió xsl, anomenats fulls d’estil, que defineixen les transformacions que cal aplicar a cada element DocBook.

Per aplicar els estils es fa servir un processador XSL, programari que s’encarrega d’aplicar les transformacions, definides per les fulles d’estil, a cada element DocBook de l’arxiu que processa. El resultat de la transformació conté la mateixa informació que ha creat l’autor del contingut, però presenta un altre format que permet veure-la com a PDF o HTML (vegeu la figura).

Característiques generals:

• Totes les marques s’han d’escriure en minúscules
• Tota marca que s’obri s’ha de tancar
• Els identificadors de capítols, seccions i taules, entre altres, han de ser únics.

<application>

S’usa per referir-se a una aplicació gràfica o text.

Per exemple:

   Per treballar amb arxius Zip comprimits, pot utilitzar el programa 
   <application> File Roller </ application>
   en mode gràfic o el programa <application> Zip </application>
   des de la línia d'ordres.

<citetitle>

Es fa servir per citar una referència externa.

Per exemple:

   Si voleu obtenir una descripció detallada del procés d'instal·lació, 
   vegeu la <citetitle> Guia oficial d'instal·lació 
   per a Intel x86 </citetitle>.

<command>

Es fa servir per fer referència al codi executable d’una aplicació, una ordre o una directriu de configuració.

Per exemple:

   Per configurar la xarxa amb el Linux Red Hat, pot utilitzar
   l'ordre <command> netconfig </command>. <command> DocumentRoot </command>
   Aquesta directriu de configuració indica la ubicació al servidor Apache.

<computeroutput>

Es fa servir per mostrar missatges que apareixen a la pantalla.

Per exemple:

   <computeroutput> rm: esborrar el fitxer normal «Makefile»? (S/N) </computeroutput>

El contingut s’ha de posar immediatament després de la marca. Com en la marca “screen”, es respecten els espais i les línies extres.

<emphasis>

Es fa servir per posar èmfasi en una frase.

Per exemple:

   Si s'utilitza <command> /sbin/mke2fs </command> sobre un sistema d'arxius,
   es perdrà <emphasis> tota </emphasis> la informació que hi hagi.

<example>

Es fa servir per mostrar exemples acompanyats d’un títol.

Típicament són seccions de codi o de fitxers de configuració.

Per exemple:

   <example id="ej-resolv">
   <title> Domini i servidor DNS a utilitzar </title>
   <screen>
   <computeroutput> domain unsitio.com
   nameserver 192.168.1.4; </computeroutput>
   </screen>
   </example>

<filename>

Es fa servir per fer referència a noms de fitxers o directoris.

Si es tracta d’un directori, és preferible incloure / al final per aclarir el text.

Per exemple:

   L'arxiu <filename> /etc/passwd </filename> conté diverses 
   peces d'informació d'un compte d'usuari.

<figure>

S’utilitza si es vol incloure una figura que tingui un títol i una descripció breu.

Per exemple:

   <figure id="f-pref-mozilla">
   <title> Preferències del Mozilla </title>
   <mediaobject>
   <imageobject>
   <imagedata fileref="./figs/mozpref.eps" format="EPS"/>
   </imageobject>
   <imageobject>
   <imagedata fileref="./figs/mozpref.png" format="PNG"/>
   </imageobject>
   <textobject>
   <phrase> La figura mostra les preferències...</phrase>
   </textobject>
   </mediaobject>
   </figure>

<footnote>

S’utilitza per inserir una nota a peu de pàgina.

Per exemple:

   Hi ha, per defecte, la partició assignada a <filename> /boot </filename>.
   <footnote>
   <para> En alguns sistemes, a causa de problemes amb discos grans, s'acostuma
    a crear aquesta partició
   dins els primers 1.024 cilindres. </para>
   </footnote> Requerirà un espai de 60 a 100 MiB.

<foreignphrase>

S’usa per mostrar una paraula o una frase en una llengua diferent a la del document.

Per exemple:

   Les ordres següents s'han d'escriure des de l'indicador (<foreignphrase> indicador
   </foreignphrase>).

<itemizedlist>

S’usa per mostrar informació breu que no requereix un ordre específic.

Per exemple:

  <itemizedlist>

   <listitem>
   <para> Revisar ús d'espai lliure en disc. </para>
   </listitem>

   <listitem>
   <para> Monitorar i gestionar processos. </para>
   </listitem>

   <listitem>
   <para> Mantenir programes al dia. </para>
   </listitem>

  </itemizedlist>

<orderedlist>

S’usa per mostrar una llista d’elements en què l’ordre és important.

Per exemple:

  <orderedlist>

   <listimtem>
   <para> Instal·lar el paquet. </para>
   </listimtem>

   <listimtem>
   <para> Modificar el fitxer de configuració. </para>
   </listimtem>

   <listimtem>
   <para> Iniciar el servei. </para>
   </listimtem>

  </orderedlist>

<variablelist>

S’usa per mostrar una llista de termes i definicions amb les descripcions corresponents.

Per exemple:

  <variablelist>

   <varlistentry>
   <term> Servidor X </term>

   <listimtem>
   <para> Ofereix les operacions bàsiques de...</para>
   </listimtem>

  </varlistentry>
  
  <varlistentry>

   <term> Servidor de lletres X </term>

   <listimtem>
   <para> Proveeix els tipus de lletres... </para>
   </listimtem>

   </varlistentry>
   ...
  </variablelist>

<simplelist>

S’usa principalment per crear una llista dins una taula.

Per exemple:

  <simplelist>
   <member> Processador Intel </member>
   <member> Pentium IV 02/04 Ghz </member>
   <member> 512 MIB RAM </member>
   <member> 80 GIB Disc </member>
   <member> CDWR / DVD </member>
  </simplelist>

<option>

S’usa per indicar una opció d’una determinada ordre.

Per exemple:

   L'ordre <command> uname </command> seguida de l'opció
   <option> r </option> mostra la versió de nucli que està
   executant el seu sistema.

<para>

S’utilitza al voltant de qualsevol paràgraf simple.

Per exemple:

   <para>
   L'ordre <command> uname </command> seguida de l'opció
   <option> r </option> mostra la versió de nucli que
   està executant el seu sistema.
   </para>

Només heu d’utilitzar marques “para” al voltant de paràgrafs simples.

Concretament, no heu de fer servir “para” al voltant de les marques següents:

<itemizedlist>
<orderedlist>
<variablelist>
<screen>
<table>

<prompt>

S’usa per mostrar un indicador.

Per exemple:

   Per iniciar el sistema, cal que escriviu //linux// 
   en l'indicador <prompt> LILO: </prompt>.
   L'indicador <prompt> # </prompt> es reserva a l'usuari
   primari.

<replaceable>

Es fa servir per indicar que el lector ha de substituir el text que hi ha entre les marques per la informació més adequada, segons el seu cas concret.

Per exemple:

   Els mòduls del nucli es troben al directori
   <filename> /lib/modules/ <replaceable> versió de
   nucli </replace> / </filename>.

<screen>

S’usa per mostrar una llista de programes, arxius o qualsevol resultat mostrat a la pantalla.

Per exemple:

   <para> Per veure la versió del nucli, heu d'escriure el següent: </para>

   <screen>
    <userinput> uname-r </userinput>
   </screen>

   <para> Mostrarà un resultat semblant a aquesta línia: </para>

   <screen>
    <computeroutput> 2.4.29-686 </computeroutput>
   </screen>

La marca i el contingut han d’estar justificats a l’esquerra.

Qualsevol espai dins la marca “screen” es conserva.

Aquesta marca en pot contenir d’altres:

<computeroutput>
<userinput>
<replaceable>

Per definició, no és necessari incloure altres marques dins de “screen”.

<table>

S’usa per mostrar una taula.

Per exemple:

 <table id="tb­pop­imap">
 
  <title>Característiques del POP i l'IMAP</title>

   <tgroup cols="3">

     <colspec colnum="1" colname="carac" colwidth="120pt"/>
     <colspec colnum="2" colname="pop" colwidth="30pt"/>
     <colspec colnum="3" colname="imap" colwidth="30pt"/>

     <thead>
       <row>
         <entry>Característica</entry>
         <entry>POP</entry>
         <entry>IMAP</entry>
       </row>
     </thead>

     <tbody>
       <row>
         <entry>Treballa en línia (//on­line//)</entry>
         <entry>Sí</entry>
         <entry>Sí</entry>
       </row>
     </tbody>

   </tgroup>

 </table>

<userinput>

S’utilitza per indicar el que l’usuari ha d’escriure.

Per exemple:

   En l'indicador del sistema, cal que escriviu el següent:
   <userinput> fdformat / dev/fd0 </ userinput>

<xref>

S’usa per fer referència a una altra secció o capítol del document.

Per exemple:

   Per obtenir més informació sobre les particions de disc
   en Linux, vegeu <xref linkend="secparticions" />.

1. Instal·leu els fulls d’estil XSL per generar els documents HTML, XHTML, HTML Help, etc.
   • apt-get install docbook-xsl
2. Instal·leu els fulls d’estil XSL per generar documents PDF
   • apt-get install fop docbook-xsl-doc-pdf
3. Instal·leu el processador per fer les transformacions XSL
   • apt-get install xsltproc
4. Instal·leu el Bluefish, processador de textos que ajuda a treballar amb fitxers XML i DocBook.
   • apt-get install bluefish

Un cop instal·lat el programari necessari, començareu a escriure el vostre primer document amb el DocBook.

Obriu l’editor Bluefish i creeu el fitxer test.xml amb el contingut següent:

   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
"http://docbook.org/xml/4.2/docbookx.dtd">

   <article>

     <title>El meu primer article amb el DocBook </title>

     <sect1>
        <title>Benvinguda</title>
        <para>
          Hola, IOC
        </para>
     </sect1>

   </article>

Executeu la instrucció següent en un terminal. Transformeu el fitxer XML que acabeu de crear en un fitxer amb format HTML.

   xsltproc -o test.html /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl 
test.xml

Explicació de la sentència:

• xsltproc és l’aplicació que fa la conversió.
• -o test.html estableix el fitxer de sortida.
• …/docbook.xsl és el full d’estil que s’ha utilitzat per fer la conversió (converteix XML a XHTML).
• test.xml diu a l’aplicació xsltproc on és el fitxer d’entrada.

El resultat és un fitxer en format HTML. El podeu veure, en la figura següent, obert amb el navegador Firefox (vegeu la figura).

Convertir el fitxer XML a PDF és un procés de dos passos:

En primer lloc, cal transformar el fitxer XML en un fitxer amb format intermig FO amb l’aplicació xsltproc.

   xsltproc -o test.fo /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl 
test.xml

Explicació de la sentència:

• xsltproc és l’aplicació que fa la conversió.
• -o test.fo estableix el fitxer de sortida en el format intermig.
• …/docbook.xsl és el full d’estil que s’utilitza per fer la conversió (converteix XML a FO).
• test.xml diu a l’aplicació xsltproc on és el fitxer d’entrada.

En segon lloc, cal convertir el fitxer FO a PDF amb l’aplicació FOP.

   fop -pdf test.pdf -fo test.fo

Explicació de la sentència:

• FOP és l’aplicació que fa la conversió a PDF.
• -pdf test.pdf estableix el fitxer de sortida en el format PDF.
• test.fo diu a l’aplicació xsltproc on és el fitxer d’entrada.

El resultat és un fitxer en format PDF. El podeu veure, en la figura, obert amb un visualitzador de PDF.

L’organització de la informació es fa en temes i subtemes. Per tal de diferenciar aquests dos elements de manera visual, es poden fer servir icones. Així, s’ajuda l’usuari a trobar més ràpidament el contingut que busca.

Les paraules que els usuaris consideren clau han de constar en el contingut de l’índex. Aquestes paraules es poden adreçar a diferents tipus d’usuaris. Poden ser específiques, generals o sinònims de termes que es fan servir en l’aplicació.

L’objectiu de l’índex és ajudar l’usuari a trobar el que busca. Per tant, l’índex ha d’intentar que l’usuari pugui arribar a la informació de moltes maneres, perquè així la probabilitat que trobi alguna paraula que li resulti útil serà més gran.

Normalment un índex es dissenya perquè tingui dos nivells. Les entrades del primer nivell descriuen un tema general, mentre que les del segon corresponen a temes específics dins del tema més general del primer nivell.

Hi ha diversos tipus de documentació. Aquests documents abracen des del desenvolupament fins a la implementació, l’operació i el manteniment de l’aplicació.

El manual d’usuari conté la informació necessària perquè els usuaris puguin utilitzar correctament l’aplicació. Ha de servir com a manual d’aprenentatge. Permet que els usuaris sàpiguen de manera detallada quines activitats poden desenvolupar en l’aplicació i quines dades o documents en poden obtenir.

Reuneix la informació, les normes i la documentació necessària perquè l’usuari conegui i utilitzi adequadament l’aplicació desenvolupada. Ha de definir les funcions que l’usuari hi pot dur a terme i l’ha d’informar sobre la resposta que ha de donar a cada missatge d’error.

En elaborar el manual d’usuari, cal tenir en compte a qui es dirigeix, ja que el manual el pot utilitzar des del director d’una empresa fins a la persona que introdueix dades. Per tant, s’ha de redactar de manera clara i senzilla perquè qualsevol tipus d’usuari en pugui comprendre el contingut.

La guia de referència és el document definitiu per a l’usuari i ha de ser completa i exhaustiva.

Descriu amb detall les qualitats i les possibilitats del sistema i l’ús, els informes d’error generats i les situacions en què sorgeixen aquests errors.

La guia ràpida constitueix un subconjunt de la guia d’usuari.

En un espai molt més reduït, inclou l’explicació de les accions principals que l’aplicació permet dur a terme per tal de poder-la començar a utilitzar sense haver de llegir tot el manual d’usuari.

El manual d’instal·lació és la guia que conté la informació necessària per implementar l’aplicació en un ambient particular.

Dins d’aquest document hi ha les instruccions per posar en marxa el sistema. També inclou les normes d’utilització, entre les quals hi ha les de seguretat (físiques i d’accés a la informació).

En aquest manual s’explica com iniciar-se en el sistema i com utilitzar les qualitats comunes que té. Aquesta documentació ha de dir a l’usuari com sortir d’un problema quan les coses funcionen malament.

El manual de configuració conté una explicació detallada de tots els paràmetres de configuració disponibles en l’aplicació.

L’objectiu d’aquest manual és explicar tot el que un usuari administrador ha de saber per dur a terme l’administració de l’aplicació.