Libro de documentos

DocBook es un lenguaje de marcado semántico para documentación técnica . En un principio, estaba pensado para escribir documentos técnicos relacionados con hardware y software informáticos, pero se puede utilizar para cualquier otro tipo de documentación. ^[1]

Como lenguaje semántico, DocBook permite a sus usuarios crear contenido de documentos en un formato neutral en cuanto a la presentación que captura la estructura lógica del contenido; dicho contenido puede luego publicarse en una variedad de formatos, incluidos HTML , XHTML , EPUB , PDF , páginas de manual , WebHelp ^[2] y HTML Help , sin necesidad de que los usuarios realicen cambios en la fuente. En otras palabras, cuando un documento se escribe en formato DocBook, se puede trasladar fácilmente a otros formatos, en lugar de tener que reescribirse.

DocBook es un lenguaje XML . En su versión actual (5.x), el lenguaje de DocBook está definido formalmente por un esquema RELAX NG con reglas Schematron integradas . (También hay versiones del esquema XML + Schematron y Document Type Definition (DTD) del W3C disponibles, pero se consideran no estándar).

Como lenguaje semántico, los documentos DocBook no describen el "aspecto" de sus contenidos, sino el significado de dichos contenidos. Por ejemplo, en lugar de explicar cómo se puede formatear visualmente el resumen de un artículo, DocBook simplemente dice que una sección en particular es un resumen. Depende de una herramienta o aplicación de procesamiento externa decidir en qué parte de una página debe ir el resumen y qué aspecto debe tener o si debe incluirse o no en el resultado final.

DocBook ofrece una gran cantidad de etiquetas de elementos semánticos. Se dividen en tres grandes categorías: estructurales, a nivel de bloque y en línea.

Las etiquetas estructurales especifican características generales de su contenido. El bookelemento, por ejemplo, especifica que sus elementos secundarios representan las partes de un libro. Esto incluye un título, capítulos, glosarios, apéndices, etc. Las etiquetas estructurales de DocBook incluyen, entre otras:

• set: Colección titulada de uno o más books o articles, se puede anidar con otros conjuntos
• book: Colección titulada de chapters, articles y/o parts, con glosarios opcionales, apéndices, etc.
• part: Colección titulada de uno o más chapters—puede estar anidada con otras partes y puede tener un texto introductorio especial
• article: Colección titulada y no numerada de elementos a nivel de bloque
• chapter: Colección numerada y titulada de elementos a nivel de bloque: los capítulos no requieren números explícitos, un número de capítulo es el número de elementos del capítulo anterior en el documento XML más 1
• appendix: Contiene texto que representa un apéndice.
• dedication: El texto representa la dedicación del elemento estructural contenido.

Los elementos estructurales pueden contener otros elementos estructurales. Los elementos estructurales son los únicos elementos de nivel superior permitidos en un documento DocBook.

Las etiquetas a nivel de bloque son elementos como párrafos, listas, etc. No todos estos elementos pueden contener texto directamente. Los elementos secuenciales a nivel de bloque se representan uno "después" de otro. Después, en este caso, puede diferir según el idioma. En la mayoría de los idiomas occidentales, "después" significa debajo: los párrafos de texto se imprimen en la parte inferior de la página. Los sistemas de escritura de otros idiomas pueden tener una direccionalidad diferente ; por ejemplo, en japonés, los párrafos a menudo se imprimen en columnas hacia abajo, con las columnas que van de derecha a izquierda, por lo que "después" en ese caso sería a la izquierda. La semántica de DocBook es completamente neutral a este tipo de conceptos basados ​​en el lenguaje.

Las etiquetas de nivel en línea son elementos como énfasis, hipervínculos, etc. Envuelven el texto dentro de un elemento de nivel de bloque. Estos elementos no hacen que el texto se rompa cuando se representa en un formato de párrafo, pero normalmente hacen que el procesador de documentos aplique algún tipo de tratamiento tipográfico distinto al texto incluido, cambiando la fuente, el tamaño o atributos similares. (La especificación DocBook dice que espera un tratamiento tipográfico diferente, pero no ofrece requisitos específicos sobre cuál puede ser este tratamiento). Es decir, un procesador DocBook no tiene que transformar una emphasisetiqueta en cursiva . Un procesador DocBook basado en lector podría aumentar el tamaño de las palabras o un procesador basado en texto podría usar negrita en lugar de cursiva.

 <?xml version="1.0" encoding="UTF-8"?> <book xml:id= "simple_book" xmlns= "http://docbook.org/ns/docbook" version= "5.0" > <title> Un libro muy sencillo </title> <chapter xml:id= "chapter_1" > <title> Capítulo 1 </title> <para> ¡Hola mundo! </para> <para> ¡ Espero que tu día transcurra <emphasis> espléndidamente </emphasis> ! </para> </chapter> <chapter xml :id= "chapter_2" > <title> Capítulo 2 </title> <para> ¡Hola de nuevo, mundo! </para> </chapter> </book>                               

Semánticamente, este documento es un "libro", con un "título", que contiene dos "capítulos", cada uno con su propio "título". Esos "capítulos" contienen "párrafos" que contienen texto. El marcado es bastante legible en inglés.

En más detalle, el elemento raíz del documento es book. Todos los elementos DocBook están en un espacio de nombres XML , por lo que el elemento raíz tiene un atributo xmlns para establecer el espacio de nombres actual. Además, el elemento raíz de un documento DocBook debe tener una versión que especifique la versión del formato en el que se basa el documento.

(Los documentos XML pueden incluir elementos de varios espacios de nombres a la vez, como los idatributos del ejemplo).

Un bookelemento debe contener un title, o un infoelemento que contenga un title. Esto debe estar antes de cualquier elemento estructural secundario. Después del título están los elementos estructurales secundarios, en este caso, dos chapterelementos. Cada uno de ellos debe tener un title. Contienen paraelementos de bloque, que pueden contener texto libre y otros elementos en línea como el emphasisdel segundo párrafo del primer capítulo.

Las reglas se definen formalmente en el esquema XML de DocBook . Las herramientas de programación adecuadas pueden validar un documento XML (DocBook o de otro tipo) comparándolo con su esquema correspondiente para determinar si el documento no cumple con dicho esquema (y en qué casos). Las herramientas de edición XML también pueden utilizar la información del esquema para evitar la creación de documentos que no cumplan con las normas.

Como DocBook es XML, los documentos se pueden crear y editar con cualquier editor de texto. Un editor XML dedicado es también un editor funcional de DocBook. DocBook proporciona archivos de esquema para los lenguajes de esquema XML más populares, por lo que cualquier editor XML que pueda proporcionar la finalización de contenido en función de un esquema puede hacerlo para DocBook. Muchos editores XML gráficos o WYSIWYG vienen con la capacidad de editar DocBook como un procesador de textos . ^[3]

Las tablas, los elementos de lista y otros contenidos estilizados se pueden copiar y pegar en el editor de DocBook y se conservarán en la salida XML de DocBook. ^[3] Debido a que DocBook se ajusta a un esquema XML bien definido, los documentos se pueden validar y procesar utilizando cualquier herramienta o lenguaje de programación que incluya soporte XML.

DocBook comenzó en 1991 en grupos de discusión en Usenet y eventualmente se convirtió en un proyecto conjunto de HAL Computer Systems y O'Reilly & Associates y finalmente generó su propia organización de mantenimiento (el Grupo Davenport) antes de mudarse en 1998 al consorcio SGML Open , que posteriormente se convirtió en OASIS . DocBook es mantenido actualmente por el Comité Técnico de DocBook en OASIS. ^[4]

DocBook está disponible en formato SGML y XML , como DTD . Están disponibles los formatos RELAX NG y W3C XML Schema de la versión XML. A partir de DocBook 5, la versión RELAX NG es el formato "normativo" a partir del cual se generan los demás formatos.

DocBook comenzó originalmente como una aplicación SGML, pero se desarrolló una aplicación XML equivalente que ahora ha reemplazado a la SGML para la mayoría de los usos. (A partir de la versión 4 de la DTD SGML, la DTD XML continuó con este esquema de numeración de versiones). Inicialmente, un grupo clave de empresas de software usaban DocBook ya que sus representantes estaban involucrados en su diseño inicial. Sin embargo, con el tiempo, DocBook fue adoptado por la comunidad de código abierto donde se ha convertido en un estándar para crear documentación para muchos proyectos, incluidos FreeBSD , KDE , la documentación del escritorio GNOME , las referencias de la API GTK+ , la documentación del kernel de Linux (que, a partir de julio de 2016, está en transición a Sphinx / reStructuredText ^{[5] [6]} ) y el trabajo del Proyecto de Documentación de Linux .

Hasta DocBook 5, DocBook se definía normativamente mediante una definición de tipo de documento (DTD). Dado que DocBook se creó originalmente como una aplicación de SGML , la DTD era el único lenguaje de esquema disponible. Los formatos de DocBook 4.x pueden ser SGML o XML, pero la versión XML no tiene su propio espacio de nombres.

Los formatos DocBook 4.x tenían que vivir dentro de las restricciones de estar definidos por un DTD. La restricción más significativa era que el nombre de un elemento define de forma única su posible contenido. Es decir, un elemento nombrado infodebe contener la misma información sin importar dónde se encuentre en el archivo DocBook. Como tal, hay muchos tipos de elementos de información en DocBook 4.x: bookinfo, chapterinfo, etc. Cada uno tiene un modelo de contenido ligeramente diferente, pero comparten parte de su modelo de contenido. Además, repiten la información de contexto. El infoelemento del libro es que, debido a que es un hijo directo del libro, no necesita ser nombrado especialmente para un lector humano. Sin embargo, debido a que el formato fue definido por un DTD, tuvo que ser nombrado como tal. El elemento raíz no tiene ni necesita una versión , ya que la versión está incorporada en la declaración DTD en la parte superior de un documento anterior a DocBook 5.

Los documentos DocBook 4.x no son compatibles con DocBook 5, pero se pueden convertir en documentos DocBook 5 mediante una hoja de estilo XSLT. db4-upgrade.xslSe proporciona una ( ) como parte de la distribución del paquete de esquema y especificación DocBook 5. ^[7]

Los archivos DocBook se utilizan para preparar archivos de salida en una amplia variedad de formatos. Casi siempre, esto se logra utilizando hojas de estilo XSL de DocBook . Se trata de hojas de estilo XSLT que transforman los documentos DocBook en varios formatos ( HTML , XSL-FO para su posterior conversión a PDF , etc.). Estas hojas de estilo pueden ser lo suficientemente sofisticadas como para generar tablas de contenido, glosarios e índices. Pueden supervisar la selección de partes designadas particulares de un documento maestro para producir diferentes versiones del mismo documento (como un "tutorial" o una "guía de referencia rápida", donde cada una de ellas consiste en un subconjunto del material). Los usuarios pueden escribir sus propias hojas de estilo personalizadas o incluso un programa completo para procesar el DocBook en un formato de salida apropiado según lo dicten sus necesidades.

Norman Walsh y el equipo de desarrollo del Proyecto DocBook mantienen la aplicación clave para producir resultados a partir de los documentos fuente de DocBook: un conjunto de hojas de estilo XSLT (así como un conjunto heredado de hojas de estilo DSSSL ) que pueden generar resultados HTML y de impresión ( FO / PDF ) de alta calidad , así como resultados en otros formatos, incluidos RTF , páginas de manual y Ayuda HTML.

La ayuda web ^[2] es un formato de salida HTML fragmentado en las hojas de estilo DocBook XSL que se introdujo en la versión 1.76.1. La documentación de la ayuda web ^[8] también proporciona un ejemplo de ayuda web y forma parte de la distribución DocBook XSL.

Las principales características son su diseño de página totalmente basado en CSS, búsqueda de contenido de ayuda y una tabla de contenidos en forma de árbol plegable. La búsqueda tiene función de derivación , resaltado de coincidencias, puntuación explícita de páginas y el tokenizador multilingüe estándar . La búsqueda y la tabla de contenidos se encuentran en un panel que aparece como un conjunto de marcos , pero en realidad se implementa con etiquetas div y cookies (para que sea progresivo).

DocBook ofrece una gran cantidad de funciones que pueden resultar abrumadoras para un usuario nuevo. Para aquellos que desean la comodidad de DocBook sin una curva de aprendizaje pronunciada, se diseñó Simplified DocBook . Es un pequeño subconjunto de DocBook diseñado para documentos individuales, como artículos o libros blancos (es decir, no se admiten "libros"). La DTD de Simplified DocBook se encuentra actualmente en la versión 1.1. ^[9]

Ingo Schwarze, el autor de mandoc de OpenBSD , considera que DocBook es inferior a la macro semántica mdoc para páginas man . En un intento de escribir un conversor de DocBook a mdoc (los conversores anteriores como docbook-to-man no cubren elementos semánticos), encuentra que las partes semánticas son "infladas, redundantes e incompletas al mismo tiempo" en comparación con los elementos cubiertos en mdoc. Además, Schwarze considera que la especificación de DocBook no es lo suficientemente específica sobre el uso de etiquetas, que el lenguaje no es portable entre versiones, que los detalles son ásperos y que, en general, son inconsistentes. ^[10]

• Lista de lenguajes de marcado de documentos
• Comparación de lenguajes de marcado de documentos
• DocBook XSL
• Arquitectura de tipificación de información de Darwin
• LinuxDoc
• Látex

Norman Walsh es el autor principal del libro DocBook: The Definitive Guide, la documentación oficial de DocBook. Este libro está disponible en línea bajo la licencia GFDL y también como publicación impresa.

• DocBook.org - Colección de información de DocBook, incluida una versión 4.x y 5.0 de DocBook: The Definitive Guide y todas las versiones de los esquemas/DTD de DocBook.
• Repositorio DocBook en OASIS: hogar normativo del esquema/DTD de DocBook.
• Página del proyecto DocBook XSL en SourceForge.net , hojas de estilo XSLT 1.0 para DocBook en GitHub
• CÓMO DESMITIFICAR DOCBook
• DocBook: La guía definitiva, 1.ª edición, v. 2.0.6 - PDF totalmente marcado de la Guía para DocBook 3.x y 4.x.
• Escribir con elementos DocBook.