<!--
     The FreeBSD Italian Documentation Project
-->

<chapter id="docproj">
  <title>Lavorare con la documentazione</title>

  <sect1 id="docproj-intro">
    <title>Preambolo</title>

    <para>Questo documento, il <emphasis>Linux Documentation Project</emphasis>,
      il <emphasis>FreeBSD Documentation Project</emphasis> ed altri progetti
      per lo pi&ugrave; sviluppati a codice aperto, vengono gestiti e sono
      realizzati grazie una serie di strumenti, tali strumenti consentono agli
      utenti di scrivere e di mantenere aggiornata la propria documentazione
      utilizzando il linguaggio standard <emphasis>SGML</emphasis>.</para>

    <para>Lo <emphasis>Standard Generalized Markup Language</emphasis> (SGML)
      &egrave; il linguaggio standard ISO ufficiale per la creazione dei
      documenti in <emphasis>MRF</emphasis>, l'SGML &egrave; oggi il linguaggio
      maggiormente utilizzato in ambito informatico ed umanistico.
      L'<emphasis>SGML</emphasis> nasce con l'obiettivo di imporsi come schema
      linguistico standard nell'ambito della codifica dei testi o dei documenti,
      l'<emphasis>SGML</emphasis> consente quindi di superare tutti i limiti
      imposti dai tutti sistemi di codifica proprietari che sono stati
      sviluppati negli ultimi venti anni.</para>

    <para>Uno degli obiettivi primari raggiunti dallo standard SGML &egrave;
      quello di aver consentito l'interscambio dei documenti in formato
      elettronico tra sistemi hardware e software diversi,
      l'<emphasis>SGML</emphasis> ha garantito agli sviluppatori di documenti
      l'assoluta portabilit&agrave;.</para>
  </sect1>

  <sect1 id="docproj-src">
    <title>Lavorare con i sorgenti del Progetto di Documentazione di
      &os;</title>

    <para>L'utilizzo proficuo di un sistema operativo dipende essenzialmente
      dalla lettura, pi&ugrave; o meno approfondita, della documentazione, i
      testi documentali possono essere forniti acclusi direttamente con il
      sistema operativo stesso oppure possono anche fare parte di progetti
      diversi e separati dallo sviluppo del sistema operativo stesso.</para>

    <para>Ciascuno di noi pu&ograve; contribuire con al &os; Documentation
      Project che pu&ograve; essere gestita utilizzando direttamente il
      sistema del CVSup.  Per scaricare e mantenere i sorgenti scritti in SGML
      sempre aggiornati o per partecipare direttamente alla realizzazione della
      documentazione &egrave;, secondo il parere di chi scrive, una buona
      norma servirsi di alcuni script di shell che, se inseriti nelle procedure
      periodiche di sistema, si occuperanno direttamente di mantenere l'albero
      documentale del FreeBSD Documentation Projet sempre il linea con i server
      di origine</para>

    <programlisting>#! /usr/local/bin/bash
# mantieni aggiornata la documentazione
#
/usr/local/bin/cvsup -g -L 2 /usr/local/etc/cvsup/doc-supfile</programlisting>

    <para>Abbiamo visto nei capitoli precedenti molto dettagliatamente il
      sistema di aggiornamento tramite <application>CVSup</application> e a
      riguardo non riteniamo di dover fornire ulteriori dettagli.</para>
  </sect1>

  <sect1 id="docproj-tools">
    <title>Quali software installare</title>

    <para>La prima cosa da fare &egrave; installare il metaport di
      <application>docproj</application>, questo package &egrave; stato
      studiato dagli sviluppatori di &os; per risolvere automaticamente tutte
      le dipendenze ed installare tutti quei pacchetti software necessari a
      manutenere e a lavorare con la <emphasis>FreeBSD Documentation
        Project</emphasis>.  Se si vuole conoscere l'elenco completo delle
      applicazioni installate da <application>docproj</application> &egrave;
      bene consultare il <emphasis>FreeBSD Documentation Project Primer for
        New Contributor</emphasis>: <ulink
          url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/tools.html#TOOLS-MANDATORY">http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/tools.html#TOOLS-MANDATORY</ulink></para>

    <screen>&prompt.root; <userinput>cd /usr/ports/textproc/docproj</userinput></screen>

    <screen>&prompt.root; <userinput>make JADETEX=no install</userinput></screen>

    <para>Con questo comando si compilano e si installano i pacchetti che
      compongono il metaport, per contribuire direttamente con il progetto
      &os; Documentation Project vi consiglio di fare riferimento al
      <emphasis>FreeBSD Documentation Project Primer for New
        Contributors</emphasis> alla URLs <ulink
          url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/index.html">http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/index.html</ulink>.</para>
  </sect1>

  <sect1 id="docproj-working">
    <title>Lavorare con la documentazione</title>

    <para>Grazie alle procedure di aggiornamento via
      <application>CVSup</application>, i sorgenti dei documenti in SGML,
      vengono memorizzati direttamente sul disco locale nella directory
      <filename>/usr/doc</filename>.  Vediamo ora una serie di comandi che ci
      consentiranno di compilare in diversi formati i documenti.  Per modificare
      i sorgenti SGML vi consiglio di utilizzare il vostro miglior processore
      di testi, ora scorriamo il contenuto della directory
      <filename>/usr/doc</filename>.</para>

    <screen>&prompt.root; <userinput>cd /usr/doc/</userinput></screen>

    <screen>&prompt.root; <userinput>ls</userinput>
total 16
drwxr-xr-x   6 root  wheel   512 Jun  9 11:06 ./
drwxr-xr-x  19 root  wheel   512 Jun  9 11:05 ../
-rw-r--r--   1 root  wheel  1550 Mar  9 23:20 Makefile
-rw-r--r--   1 root  wheel   392 Oct 13  2001 README
drwxr-xr-x   5 root  wheel   512 Jun  9 11:06 en_US.ISO8859-1/
drwxr-xr-x   5 root  wheel   512 Jun  9 11:06 it_IT.ISO8859-15/
drwxr-xr-x   3 root  wheel   512 Jun  9 11:06 release/
drwxr-xr-x  10 root  wheel   512 Jun  9 11:06 share/</screen>

    <para>Generiamo la documentazione in formato html</para>

    <screen>&prompt.root; <userinput>cd it_IT.ISO8859-15/articles/euro/</userinput></screen>
    <screen>&prompt.root; <userinput>ls</userinput>
total 22
drwxr-xr-x  2 root  wheel    512 Jun  9 11:06 ./
drwxr-xr-x  9 root  wheel    512 Aug 15 23:58 ../
-rw-r--r--  1 root  wheel    282 Sep 22  2002 Makefile
-rw-r--r--  1 root  wheel  15200 Mar 19 19:54 article.sgml</screen>

    <screen>&prompt.root; <userinput>make FORMATS=html</userinput></screen>

    <para>Generiamo la documentazione in formato <emphasis>html-split</emphasis>
      (pagina multipla)</para>

    <screen>&prompt.root; <userinput>make FORMATS=html-split</userinput></screen>

    <para>Generiamo la documentazione in formato <emphasis>txt</emphasis></para>

    <screen>&prompt.root; <userinput>make FORMATS=txt</userinput></screen>
  </sect1>

  <sect1 id="docproj-italian">
    <title>La nostra documentazione</title>

    <para>Per lavorare direttamente anche con la nostra documentazione
      pu&ograve; essere consigliabile lavorare all'interno della home
      directory utilizzando gli stessi file di make che abbiamo utilizzato
      per lavorare con la FreeBSD Documentation Project</para>

    <screen>&prompt.root; <userinput>ls /home/user1/Books/Unix/</userinput>
total 56
drwxr-xr-x  2 user1  syseng    512 Aug 16 17:20 ./
drwxr-xr-x  4 user1  syseng    512 Aug 16 00:17 ../
-rw-r--r--  1 user1  syseng    302 Aug 16 00:09 Makefile
-rw-r--r--  1 user1  syseng  51175 Aug 15 22:10 article.sgml</screen>

    <para>Come vedete il contenuto di questa directory personale &egrave;
      praticamente uguale a quello della <emphasis>FreeBSD Documentation
        Project</emphasis></para>

    <screen>&prompt.root; <userinput>ls /usr/doc/it_IT.ISO8859-15/articles/new-users/</userinput>
total 52
drwxr-xr-x  2 root  wheel    512 Jul 12 04:24 ./
drwxr-xr-x  9 root  wheel    512 Aug 15 23:58 ../
-rw-r--r--  1 root  wheel    287 Sep 22  2002 Makefile
-rw-r--r--  1 root  wheel  46764 Jul 12 04:24 article.sgml</screen>

    <para>Nella compilazione della documentazione personale e di sistema,
      &egrave; fondamentale non modificare il contenuto della directory
      <filename>/usr/doc/share/mk/</filename>, in questa directory infatti,
      sono contenuti tutti i file di <application>make</application> veri e
      propri.  A questo punto abbiamo la necessit&agrave; di creare dei
      <emphasis>template</emphasis> per differenziare nella sostanza dal
      formato della documentazione di <emphasis>FreeBSD Documentation
        Project</emphasis></para>

    <screen>&prompt.root; <userinput>cp doc.project.mk doc.myproject.mk</userinput></screen>

    <para>Ora modifichiamo il Makefile per consentire una corretta compilazione
      dei formati documentali</para>

    <programlisting># Makefile
]# $FreeBSD: doc/it_IT.ISO8859-15/articles/multi-os/Makefile,v 1.1 2002/09/22 10:47:32 blackend Exp $
DOC?= article
FORMATS?= html
INSTALL_COMPRESSED?=gz
INSTALL_ONLY_COMPRESSED?=
SRCS= article.sgml
DOC_PREFIX?= ${.CURDIR}/../../../../../usr/doc
.include "${DOC_PREFIX}/share/mk/doc.myproject.mk"</programlisting>

    <para>Nel Makefile viene definita la variabile DOC_PREFIX, inoltre
      c'&egrave; una <literal>include</literal> che richiama direttamente il
      file <filename>/usr/doc/share/mk/doc.myproject.mk</filename>.  Nella
      variabile DOC_PREFIX viene indicato il percorso, partendo dalla posizione
      del Makefile, che consentir&agrave; di richiamare correttamente il nostro
      <emphasis>template</emphasis> personale.  Che dire.....a questo punto
      non ci resta solo che scrivere la nostra documentazione nel linguaggio
      SGML utilizzando gli strumenti che ci sono pi&ugrave; familiari.</para>
  </sect1>
</chapter>

<!--
     Local Variables:
     mode: sgml
     sgml-indent-data: t
     sgml-omittag: nil
     sgml-always-quote-attributes: t
     sgml-parent-document: ("../book.sgml" "book" "chapter")
     End:
-->
