Pe a2 perl-documentazione

577 views

Published on

Published in: Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
577
On SlideShare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
5
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Pe a2 perl-documentazione

  1. 1. Parte 3 Documentazione in Perl Linguaggi dinamici – A.A. 2009/2010 1
  2. 2. Introduzione Il formato messo a disposizione dal Perl per la documentazione dei sorgenti prende il nome di POD (Plain Old Format) Antesignano di tutti i sistemi di documentazione “on-line” (integrati nel codice sorgente): JavaDoc, RubyDoc, pydoc Per una guida completa: perldoc perlpod Linguaggi dinamici – A.A. 2009/2010 2
  3. 3. Obiettivi di design Il formato POD è progettato per essere scarno ed efficiente nella rappresentazione della documentazione allegata Caratteristiche E' semplice da analizzare lessicamente (parse) E' semplice da convertire in altri linguaggi di markup (HTML, TeX) E' semplice documentare codice di esempio E' semplice da leggere senza l'uso di un formattatore POD E' semplice da scrivere Linguaggi dinamici – A.A. 2009/2010 3
  4. 4. Tag di descrizione Il formato POD fa uso di tag di descrizione che marcano alcune aree del documento sorgente come documentazione Proprio come nel formato HTML, alcuni tag necessitano di apertura e chiusura, altri solo di apertura Il carattere di demarcazione di un tag è il simbolo = Linguaggi dinamici – A.A. 2009/2010 4
  5. 5. Formattazione La documentazione è tipicamente suddivisa in paragrafi, delineati da righe vuote Un paragrafo che inizia con un carattere di spazio viene considerato “verbatim” (non viene applicata la formattazione di POD) Un paragrafo che inizia con il carattere = introduce un tag di descrizione All'interno di un paragrafo, può essere applicata una formattazione su porzioni arbitrarie (formattazione di carattere) Linguaggi dinamici – A.A. 2009/2010 5
  6. 6. Formattazione Alcuni esempi di tag (formattazione paragrafo): =head1: titolo di primo livello =head2: titolo di secondo livello =over n: indentazione di n caratteri a destra =back n: indentazione di n caratteri a sinistra =begin format: inizio area di documentazione gestita da un formattatore per il formato format =end format: fine area di documentazione gestita da un formattatore per il formato format =item: elenco puntato =item n: elenco numerato =cut: termina una sezione di documentazione Linguaggi dinamici – A.A. 2009/2010 6
  7. 7. Formattazione Alcuni esempi di tag (formattazione carattere): Btesto: testo in neretto Itesto: testo in corsivo Utesto: testo sottolineato Ctesto: codice Lvoce: link a voce Linguaggi dinamici – A.A. 2009/2010 7
  8. 8. Uso dello strumento di formattazione Si utilizza il comando perldoc (perldoc perldoc) Scansione del file sorgente Individuazione delle aree di documentazione Estrazione e formattazione Produzione di un flusso formattato su STDOUT Stampa e paginazione (less) del flusso Linguaggi dinamici – A.A. 2009/2010 8
  9. 9. Produzione di documentazione Sezioni da includere nella documentazione di un qualunque modulo o programma Perl =head1 NAME: nome del programma/modulo ed una sua breve spiegazione (1 riga) =head1 SYNOPSIS: una porzione di codice che spiega l'uso del programma/modulo =head1 DESCRIPTION: una descrizione succinta (4-5 righe max.) del programma/ modulo Linguaggi dinamici – A.A. 2009/2010 9
  10. 10. Produzione di documentazione Sezioni da includere nella documentazione di un qualunque modulo o programma Perl =head2 Methods: descrizione dei singoli metodi del modulo =over 12 =item Cmetodo Descrizione del metodo ... =back Linguaggi dinamici – A.A. 2009/2010 10
  11. 11. Produzione di documentazione Sezioni da includere nella documentazione di un qualunque modulo o programma Perl =head1 LICENSE: descrizione della licenza di uso del programma/modulo =head1 AUTHOR: nome, cognome ed indirizzo di posta elettronica/home page dell'autore =head1 SEE ALSO: collegamenti ad eventuali altre pagine di documentazione Linguaggi dinamici – A.A. 2009/2010 11
  12. 12. ESEMPI: doc1.pl Documentazione in HTML doc2.pl doc3.pl Il modulo Pod::Html permette di convertire agevolmente la documentazione dal formato POD al formato HTML Comando pod2html file.pl Genera documentazione in formato POD a partire dai tag di file.pl Individua le porzioni begin HTML … end HTML e le include direttamente Produce e stampa su STDOUT il flusso finale Linguaggi dinamici – A.A. 2009/2010 12

×