DocBook es un lenguaje de marcado semántico para documentación técnica . Originalmente estaba destinado a la redacción de documentos técnicos relacionados con hardware y software informáticos, pero se puede utilizar para cualquier otro tipo de documentación. [1]
Extensión de nombre de archivo | .dbk, .xml |
---|---|
Tipo de medio de Internet | aplicación / docbook + xml |
Desarrollado por | OASIS |
Tipo de formato | lenguaje de marcado |
Extendido desde | SGML , XML |
Estándar | 5.1 (noviembre de 2016) , 4.5 (octubre de 2006) |
¿ Formato abierto ? | sí |
Como lenguaje semántico, DocBook permite a sus usuarios crear contenido de documentos en una forma de presentación neutra que captura la estructura lógica del contenido; ese contenido se puede publicar en una variedad de formatos, incluidos HTML , XHTML , EPUB , PDF , páginas de manual , ayuda web [2] y ayuda HTML , sin necesidad de que los usuarios realicen cambios en la fuente. En otras palabras, cuando un documento se escribe en formato DocBook, se puede transportar fácilmente a otros formatos, en lugar de tener que reescribirlo.
Diseño
DocBook es un lenguaje XML . En su versión actual (5.x), el lenguaje de DocBook está formalmente definido por un esquema RELAX NG con reglas Schematron integradas . (También hay versiones del esquema W3C XML Schema + Schematron y Document Type Definition (DTD) disponibles, pero se consideran no estándar).
Como lenguaje semántico, los documentos DocBook no describen cómo "se ven" sus contenidos, sino más bien el significado de esos 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 proporciona una gran cantidad de etiquetas de elementos semánticos. Se dividen en tres categorías amplias, a saber, estructural, a nivel de bloque e integrado.
Las etiquetas estructurales especifican amplias características de su contenido. El book
elemento, 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
: Titulado colección de uno o másbook
s oarticles
s, puede ser anidado con otros conjuntosbook
: Colección titulada dechapter
s,article
s y / opart
s, con glosarios opcionales, apéndices, etc.part
: Colección titulada de uno o máschapter
mensajes de correo electrónico : se puede anidar con otras partes y puede tener un texto introductorio especialarticle
: Colección titulada y sin numerar de elementos a nivel de bloquechapter
: Colección titulada y numerada 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 de capítulo anterior en el documento XML más 1appendix
: Contiene texto que representa un apéndicededication
: El texto representa la dedicatoria 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 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 abajo: los párrafos de texto se imprimen en la página. Los sistemas de escritura de otros idiomas pueden tener diferente direccionalidad ; por ejemplo, en japonés, los párrafos a menudo se imprimen en columnas hacia abajo, con las columnas de derecha a izquierda, por lo que "después" en ese caso estaría a la izquierda. La semántica de DocBook es completamente neutral para 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 por lo general hacen que el procesador de documentos aplique algún tipo de tratamiento tipográfico distinto al texto adjunto, cambiando la fuente, el tamaño o atributos similares. (La especificación DocBook no decir que se espera que el tratamiento tipográfico diferente, pero no ofrecer requisitos específicos en cuanto a lo que puede ser este tratamiento.) Es decir, un procesador de DocBook no tiene que transformar una emphasis
etiqueta 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.
Documento de muestra
xml version = "1.0" encoding = "UTF-8"?> xml: id = "simple_book" xmlns = "http://docbook.org/ns/docbook" version = "5.0" > Libro muy simple ítulo> xml: id = "capítulo_1" > ítulo> Capítulo 1 ¡Hola mundo! ¡Espero que su día transcurra espléndidamente ! xml: id = "chapter_2" > Capítulo 2 ¡Hola de nuevo, mundo!
Semánticamente, este documento es un "libro", con un "título", que contiene dos "capítulos" cada uno con sus propios "títulos". Esos "capítulos" contienen "párrafos" que contienen texto. El marcado es bastante legible en inglés.
Más detalladamente, el elemento raíz del documento es book
. Todos los elementos de 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. Para simplificar, el ejemplo no ilustra esto).
Un book
elemento debe contener a title
, o un info
elemento que contenga a title
. Debe estar antes de cualquier elemento estructural secundario. A continuación del título están los hijos estructurales, en este caso, dos chapter
elementos. Cada uno de estos debe tener un title
. Contienen para
elementos de bloque, que pueden contener texto libre y otros elementos en línea como emphasis
en el segundo párrafo del primer capítulo.
Esquemas y validación
Las reglas se definen formalmente en el esquema DocBook XML . Las herramientas de programación adecuadas pueden validar un documento XML (DocBook o de otro tipo), contra su esquema correspondiente, para determinar si (y dónde) el documento no se ajusta a ese esquema. Las herramientas de edición XML también pueden usar información de esquema para evitar la creación de documentos no conformes en primer lugar.
Autorización y procesamiento
Dado que DocBook es XML, los documentos se pueden crear y editar con cualquier editor de texto. Un editor XML dedicado es también un editor de DocBook funcional. DocBook proporciona archivos de esquema para lenguajes de esquema XML populares, por lo que cualquier editor XML que pueda proporcionar la finalización de contenido basada en un esquema puede hacerlo para DocBook. Muchos editores XML gráficos o WYSIWYG vienen con la capacidad de editar DocBook como un procesador de texto . [ cita requerida ]
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.
Historia
DocBook comenzó en 1991 en grupos de discusión sobre Usenet y finalmente 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 pasar 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. [3]
DocBook está disponible en formatos SGML y XML , como DTD . Los formularios RELAX NG y W3C XML Schema de la versión XML están disponibles. A partir de DocBook 5, la versión RELAX NG es la forma "normativa" a partir de la cual se generan los otros formatos.
DocBook comenzó originalmente como una aplicación SGML, pero se desarrolló una aplicación XML equivalente y ahora ha reemplazado a SGML para la mayoría de los usos. (A partir de la versión 4 de SGML DTD, XML DTD continuó con este esquema de numeración de versiones). Inicialmente, un grupo clave de empresas de software utilizaba DocBook ya que sus representantes participaron en su diseño inicial. Eventualmente, sin embargo, 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, incluyendo FreeBSD , KDE , documentación de escritorio GNOME , las referencias de la API GTK + , la documentación del kernel de Linux y el trabajo de Linux. Proyecto de documentación .
Pre DocBook v5.0
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 , DTD era el único lenguaje de esquema disponible. Los formatos 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 una DTD. La restricción más significativa fue que el nombre de un elemento define de forma única sus posibles contenidos. Es decir, un elemento nombrado info
debe 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 diferentes, pero comparten una parte de su modelo de contenido. Además, repiten información de contexto. El info
elemento del libro es que, porque es un hijo directo del libro; no necesita un nombre especial 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á integrada 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. Se db4-upgrade.xsl
proporciona uno ( ) como parte de la distribución del esquema y el paquete de especificaciones de DocBook 5. [4]
Formatos de salida
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 DocBook XSL . 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 específicas designadas 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 documentos fuente DocBook: un conjunto de hojas de estilo XSL (así como un conjunto heredado de hojas de estilo DSSSL ) que pueden generar HTML e impresión ( FO / PDF ) de alta calidad salida, así como salida 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 para la ayuda web [5] también proporciona un ejemplo de ayuda web y es parte de la distribución DocBook XSL.
Las características principales son su diseño de página totalmente basado en CSS, búsqueda del contenido de ayuda y una tabla de contenido en forma de árbol plegable. La búsqueda tiene derivación , resaltado de coincidencias, puntuación de página explícita y el tokenizador multilingüe estándar . La búsqueda y la tabla de contenido 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 simplificado
DocBook ofrece una gran cantidad de funciones que pueden resultar abrumadoras para un nuevo usuario. Para aquellos que desean la conveniencia de DocBook sin una curva de aprendizaje empinada, se diseñó DocBook simplificado . Es un pequeño subconjunto de DocBook diseñado para documentos individuales como artículos o informes técnicos (es decir, los "libros" no son compatibles). El DocBook DTD simplificado se encuentra actualmente en la versión 1.1. [6]
Crítica
Ingo Schwarze, el autor de OpenBSD 's mandoc , considera DocBook inferior a la semántica mdoc macro para páginas man . En un intento de escribir un convertidor de DocBook a mdoc (convertidores anteriores como docbook-to-man no cubren elementos semánticos), encuentra las partes semánticas "infladas, redundantes e incompletas al mismo tiempo" en comparación con los elementos cubiertos en mdoc. Además, Schwarze encuentra que la especificación DocBook no es lo suficientemente específica sobre el uso de etiquetas, el lenguaje no es portátil entre versiones, es tosco en detalles y en general inconsistente. [7]
Ver también
- 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
- Mumasy
- SilkPage
Referencias
- ^ ¿Qué es DocBook?
- ^ a b Proyecto DocBook WebHelp
- ^ Introducción a DocBook
- ^ Jirka Kosek, Norman Walsh, Dick Hamilton y Michael Smith, DocBook V5.0: The Transition Guide , 16 de junio de 2009, Conversión de documentos DocBook V4.x a DocBook V5.0
- ^ Documentación de ayuda web
- ^ DocBook simplificado
- ^ Schwarze, Igor (19 de abril de 2019). "docbook2mdoc-1.0.0 publicado" . Diario de OpenBSD .
Otras lecturas
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 GFDL y también como publicación impresa.
- Norman Walsh (junio de 2010). DocBook 5: La guía definitiva (2ª ed.). Asociados O'Reilly. ISBN 978-0-596-80502-9.
- Bob Stayton (2005). DocBook XSL: La guía completa (3ª ed.). Empresas Sagehill. ISBN 0-9741521-2-9.
- Joe Brockmeier (2001). Publicación de DocBook: una mejor forma de crear documentos profesionales . Serie Linux de Prima Tech. ISBN 0-7615-3331-1.
enlaces externos
- DocBook.org : recopilación de información de DocBook, incluida una versión 4.xy 5.0 de DocBook: la guía definitiva y todas las versiones de los esquemas / DTD de DocBook.
- Repositorio DocBook en OASIS - Hogar normativo del esquema DocBook / DTD.
- Página del proyecto DocBook XSL en SourceForge.net , XSLT 1.0 Stylesheets para DocBook en GitHub
- CÓMO de desmitificación de DocBook
- DocBook: The Definitive Guide, 1.ª edición, v. 2.0.6 - PDF de la Guía con marcadores completos para DocBook 3.xy 4.x.
- Escribir con elementos de DocBook .