T6 DocumentacionSoftware

Tema 6.
Documentacin del software

DocBook [1] http://www.docbook.org/
Introduccin
DocBook
Es una DTD pensada para la escritura de toda clase de

libros y manuales
Contiene la mayor parte de los elementos lgicos que

pueden aparecer en un libro: captulos, secciones,
ejemplos, grficos, ...
La documentacin de un programa se puede entender

como un libro (informe, manual) en el que se pueden
intercalar texto y cdigo
Programacin letrada
Introduccin
DocBook [1] http://www.docbook.org/
No se refiere a tcnicas de documentacin

orientadas a una determinada metodologa de
ingeniera del software
DocBook XML V5.0 http://www.oasis-open.org/docbook/xml/5.0a1/
XML Schema para DocBook (versin 4.1.2.1)
Versin simplificada de DocBook para XML (DTD)
Se refiere a:
z
Uso de XML para documentar programas
Presentacin de la programacin letrada
Enlazar la programacin letrada con XML
ltima versin de DocBook para XML (DTD)
http://www.oasis-open.org/docbook/xml/simple/
Documentacin sobre la DTD DocBook simplificada:

http://www.docbook.org/tdg/simple/en/

DocBook. Tipos de elementos. Libros
DocBook. Tipos de elementos
Conjuntos
Libros
Divisiones (de libros en partes)
DocBook
Componentes (de libros o divisiones en captulos)
Secciones (de componentes)
Metainformacin
Elementos de bloques
Elementos de lnea
book es el elemento de alto nivel ms comn en
Se corresponde con la idea de libro en el sentido ms

amplio
DocBook. Tipos de elementos. Conjuntos
DocBook. Tipos de elementos. Libros
Se compone de:
Es el elemento raz de DocBook
Dedicatorias
Un elemento set contiene dos o ms elementos book
Ejemplos de uso:
Componentes de navegacin: ndice, listas de: tablas,

figuras, ejemplos, ...
Divisiones:
Toda la documentacin de un lenguaje

programacin que puede constar de varios libros
de
Todos los manuales de asociados a una determinada

maquinaria
z
Primer nivel jerrquico por debajo de libro
Contiene partes, part, y referencias, reference.
Las partes contienen componentes
Las referencias contienen refEntry
Componentes: captulos, ...
DocBook. Tipos de elementos. Componentes
DocBook. Tipos de elementos. Secciones
Elementos dentro de book, part o article
Por ejemplo: preface, chapter,

glossary, bibliography
Hay diferentes tipos de secciones:

z
Elementos RefSect1... RefSect3: dentro de refEntry,

slo 3 niveles de secciones numeradas
appendix,
z
Elementos
divisiones
GlossDiv,
dentro
de
BiblioDiv,
glossary,
IndexDiv:
bibliography
index sin posibilidad de anidamiento
DocBook. Tipos de elementos. Secciones
DocBook. Tipos de elementos. Metainformacin
Hay diferentes tipos de secciones:

z
Elementos
Sect1
...Sect5
(nmero=
nivel
de
anidamiento: Sect3 dentro de Sect2, mximo 5 niveles)

z
Se refiere a informacin bibliogrfica sobre el contenido
Por ejemplo: elemento bookInfo
Elemento Section: no hay restricciones de n de niveles

(se introdujo posteriormente a Sect1...)
Elemento SimpleSect: seccin sin anidamientos
Elemento
BrigdeHead:
seccin
con
ttulo
pero
sin
contenido

DocBook. Tipos de elementos. Elementos de lnea
DocBook. Tipos de elementos. Elementos de

bloques
Ocurren dentro de los componentes y las secciones
Son de diferentes categoras:

z
Listas: ItemizedList, OrderedList, ...
Advertencias: caution, important, note, warning,
Tablas, figuras, ejemplos: example, table, figure
Entornos especficos de lnea: mantienen los espacios en

blanco y saltos de lnea del texto fuente (ProgramListing,
screen (captura de pantalla en modo texto))
produzcan un pequeo cambio tipogrfico (tipo de letra)

sin producir cambios de lnea o cambios mayores
Prrafos: para, FormalPara (con ttulos), ...
Ecuaciones: ecuation ...
Grficos: MediaObject
imagen ...
Preguntas y respuestas: QandAset para FAQs y colecciones

de elementos question y answer
...
Tradicionales: Abbrev, Emphasis, Footnote, Quote, ...
Referencias cruzadas: link, CiteRefEntry, ...
Interfaces de usuario: GUIIcon, GUIButton, ...
Constructores y elementos de programacin: Classname,

constant, Function, Literal, Type, VarName, ...
Sistemas operativos: command, filename, option, ...
DocBook. Un esqueleto bsico de un libro:

<!DOCTYPE book PUBLIC ...>
<book>
<bookinfo> <title> Documentacin del software </title>
<author><firstname>Fulano</firstname> <surname>Montes</surname>
<copyright> <year>2004</year> <holder> Fulano Montes </holder>
</copyright>
</bookinfo>
<preface> <title> Prlogo </title> </preface>
<chapter> ... </chapter>
<chapter> ... </chapter>
<appendix> ... </appendix>
<index> ... </index>
</book>
Son de diferentes categoras:

z
Hay diversos tipos
DocBook. Tipos de elementos. Elementos de

bloques
Anotan elementos textuales que podemos querer que
pueden contener video, audio,
El elemento raz es article

DocBook. Un esqueleto bsico de un captulo:
<chapter>
<title> DTD DocBook
</title>
<para> ...
</para>
<section> <title> ... </title>
<para> ...
</para>
<example> ...
</example>
</section>
</chapter>

DocBook. Un esqueleto bsico de un artculo:
<article>
<artheader>
<author><firstname> ...</firstname> <surname> ...</surname>
</artheader>
<para> ...
</para>
<section> <title> ... </title>
<para> ...
</para>
</section>
<bibliography> ... </bibliography>
</article>
10
11
12

DocBook. Conversiones a formatos de
presentacin
docbook2html para SGML

http://gd.tuwien.ac.at/linuxcommand.org/man_pages/docbook2html1.ht
ml
Hojas de estilo paraXML docBook
docbook2html para XML
http://sourceforge.net/project/showfiles.php?group_id=21935
http://ccm.redhat.com/doc/core-platform/5.0/engineeringstandards/docbook-publishing.html#adpub

Programacin Letrada (Literate Programming)
Concepto inventado por Donald Knuth
Cambio en la actitud: el programador enfoca la
escritura de programas no slo al ordenador sino
tambin a un humano
Mejorar la legibilidad y comprensibilidad de un
programa tiene como principales beneficios facilitar el
mantenimiento y reutilizacin del cdigo
13
14
Documentacin usual:
WEB: primer sistema de la programacin letrada
Un programa fuente consiste en un fichero de texto con
(Universidad de Stanford)
el cdigo del programa que incorpora comentarios que

describen dicho cdigo
Consta de 2 lenguajes:
Programacin letrada
un lenguaje para formatear documentos (originalmente Tex)
El programador escribe documentos que contienen
un lenguaje de programacin (originalmente Pascal)
cdigo
Definicin:
Mtodo de desarrollo de programas basado en la
combinacin del cdigo fuente de un programa y de su
documentacin en un nico documento
WEB: el programador escribe un nico programa

fuente que se procesar con dos objetivos:
obtener un documento consistente en el programa fuente

documentado
La obtencin de la documentacin y del cdigo fuente

de forma separada se realiza a travs de un software
especfico
obtener el programa ejecutable asociado
Tanto el programa como su documentacin se generan

al partir del mismo fuente: consistencia
15
16

Funcionalidades bsicas en un sistema de PL:
WEB
Weave
Reordenacin de cdigo
Tangle
TeX
Weave: software que produce la documentacin y
el que debern aparecer en el programa fuente
Tangle: software que produce el programa fuente
Funcionalidades bsicas deseables en un sistema

Pretty-printing y variedad tipofrfica
de PL:
Reordenacin de cdigo
Pretty-printing y variedad tipofrfica
Referencias cruzadas
Las herramientas deben permitir independizar el orden en el

que partes del cdigo aparecen en el documento, del orden en
resuelve las referencias cruzadas
El programador es libre para presentar el cdigo del programa

en el orden que considere conveniente
Pascal
Una mejor calidad en la presentacin ya que puede utilizar todo

el poder tipogrfico del lenguaje de representacin
17
Si la herramienta es sensible al lenguaje de programacin,

puede aplicar ciertas caractersticas de estilo (negrita,
enfatizado) para mostrar palabras reservadas, identificadores,
etc, (pretty-printing)
18
Ejemplo: Sistema CWEB
Referencias cruzadas
similar a WEB pero para C y C++ y Java

puede utilizarse LaTeX
El sistema de PL ve el cdigo y la documentacin como un
http://packages.debian.org/testing/devel/cweb-latex
todo, por lo que debe ser posible relacionar diversas partes del
documento.
Javadoc es una herramienta que generar documentacin de

referencia a partir de comentarios embebidos en cdigo Java
Sistema CWEB. Ejemplo de plantilla.
Sin embargo Javadoc NO ES una herramienta de Programacin

Letrada
\documentclass{cweb}
\begin{document}
\title{...}
\author{...}
\maketitle
\tableofcontents % si es necesario
@* A PSPACE solucin del problema
< insertar el programa >
Las herramientas de PL permiten generar documentacin ms

detallada
...
@
\end{document}
Javadoc es una buena herramienta para documentar mtodos y

clases en una API java
19
20

Bibliografa:
[1] N. Wals, L. Muellner. DocBook. The definitive guide. O`Reilly,

1999.
[2] D. E. Knuth. Literate Programming, CSLI Lecture Notes, 1992.
Direcciones de inters:
http://www.literateprogramming.com/
FAQ The Literate Programming
http://shelob.ce.ttu.edu/daves/lpfaq/faq.html
Documentacin, sistemas de PL, bibliografa
http://tex.loria.fr/english/litte.html

Programacin Letrada y XML
http://www.oasis-open.org/cover/xmlLitProg.html
XML-Lit: A Simple XML-Based Literate
Programming System
http://xml-lit.sourceforge.net/
Se puede utilizar con DocBook
xmLP Herramienta de PL para XML escrita en

XSLT http://xmlp.sourceforge.net/
21
22

T6 DocumentacionSoftware

Cargado por

Información del documento

Título original

Derechos de autor

Formatos disponibles

Compartir este documento

Compartir o incrustar documentos

Opciones para compartir

¿Le pareció útil este documento?

¿Este contenido es inapropiado?

Copyright:

Formatos disponibles

T6 DocumentacionSoftware

Cargado por

Copyright:

Formatos disponibles

Tema 6.

Documentacin del software

Documentacin del software

Es una DTD pensada para la escritura de toda clase de

Contiene la mayor parte de los elementos lgicos que

La documentacin de un programa se puede entender

Documentacin del software

Documentacin del software

DocBook [1] http://www.docbook.org/

No se refiere a tcnicas de documentacin

DocBook XML V5.0 http://www.oasis-open.org/docbook/xml/5.0a1/

XML Schema para DocBook (versin 4.1.2.1)

Versin simplificada de DocBook para XML (DTD)

Uso de XML para documentar programas

Presentacin de la programacin letrada

Enlazar la programacin letrada con XML

ltima versin de DocBook para XML (DTD)

Documentacin sobre la DTD DocBook simplificada:

Documentacin del software

Documentacin del software

DocBook. Tipos de elementos

Divisiones (de libros en partes)

Componentes (de libros o divisiones en captulos)

Secciones (de componentes)

book es el elemento de alto nivel ms comn en

Documentacin del software

Se corresponde con la idea de libro en el sentido ms

Documentacin del software

DocBook. Tipos de elementos. Conjuntos

DocBook. Tipos de elementos. Libros

Es el elemento raz de DocBook

Un elemento set contiene dos o ms elementos book

Componentes de navegacin: ndice, listas de: tablas,

Toda la documentacin de un lenguaje

Todos los manuales de asociados a una determinada

Primer nivel jerrquico por debajo de libro

Contiene partes, part, y referencias, reference.

Las partes contienen componentes

Las referencias contienen refEntry

Componentes: captulos, ...

Documentacin del software

Documentacin del software

DocBook. Tipos de elementos. Componentes

DocBook. Tipos de elementos. Secciones

Elementos dentro de book, part o article

Por ejemplo: preface, chapter,

Hay diferentes tipos de secciones:

Elementos RefSect1... RefSect3: dentro de refEntry,

index sin posibilidad de anidamiento

Documentacin del software

Documentacin del software

DocBook. Tipos de elementos. Secciones

DocBook. Tipos de elementos. Metainformacin

Hay diferentes tipos de secciones:

anidamiento: Sect3 dentro de Sect2, mximo 5 niveles)

Se refiere a informacin bibliogrfica sobre el contenido

Por ejemplo: elemento bookInfo

Elemento Section: no hay restricciones de n de niveles

Elemento SimpleSect: seccin sin anidamientos

Documentacin del software

Documentacin del software

DocBook. Tipos de elementos. Elementos de

Ocurren dentro de los componentes y las secciones