DOCSLIB.ORG

Writing Documentation Using Docbook

Total Page：16

File Type：pdf, Size：1020Kb

Download full-text PDF Read full-text
Writing Documentation Using Docbook Writing Documentation Using DocBook A Crash Course David Rugge [email protected] Mark Galassi [email protected] Éric Bischoff [email protected] Writing Documentation Using DocBook: A Crash Course by David Rugge, Mark Galassi, and Éric Bischoff Copyright © 1997-2006 David Rugge, Mark Galassi, Éric Bischoff This document is a first tutorial on how to write documentation in DocBook. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". Table of Contents 1. Introduction..................................................................................................................................... 1 1.1. About this Booklet ............................................................................................................... 1 1.2. Why DocBook?.................................................................................................................... 2 1.3. Your World View.................................................................................................................. 3 1.4. Markup based on content ..................................................................................................... 4 2. Getting started ................................................................................................................................ 5 2.1. Presentation of the Tools...................................................................................................... 5 2.2. The Old Way: the DocBook-tools........................................................................................ 5 2.3. The New Way: XSLTProc and FOP..................................................................................... 7 2.4. My First DocBook File ........................................................................................................ 8 2.5. Introducing the Style Sheets ................................................................................................ 9 3. Basic notions..................................................................................................................................11 3.1. Anatomy of a DocBook Tag ..............................................................................................11 3.2. The Structure of a DocBook File .......................................................................................11 4. The Document Type Declaration.................................................................................................14 4.1. Using Entities for Shared Text ...........................................................................................14 4.2. Using Entities to Include Other files ..................................................................................15 4.3. Identifying files with formal public IDs.............................................................................15 4.4. Using Marked Sections to Handle Conditional Content....................................................17 5. Meta Information..........................................................................................................................19 6. Lists ................................................................................................................................................21 6.1. The simplelist.....................................................................................................................21 6.2. The itemizedlist..................................................................................................................22 6.3. The orderedlist ...................................................................................................................22 6.4. The variablelist...................................................................................................................23 6.5. The segmentedlist...............................................................................................................24 6.6. qandaset..............................................................................................................................25 6.7. Procedures..........................................................................................................................25 7. Tables .............................................................................................................................................27 8. Graphics.........................................................................................................................................29 9. Links...............................................................................................................................................32 10. Describing the Application’s Interface .....................................................................................33 10.1. Examples..........................................................................................................................33 10.2. GUI Interface Elements....................................................................................................34 10.3. Command Line Elements.................................................................................................36 10.4. Describing an API............................................................................................................38 11. Miscellaneous Useful Tags..........................................................................................................40 11.1. Labelling Tags..................................................................................................................40 11.2. Formatting Tags................................................................................................................40 11.3. Warnings, Tips, and Notes ...............................................................................................40 12. Where to Go Next .......................................................................................................................41 12.1. DocBook Resources.........................................................................................................41 A. Licence ..........................................................................................................................................42 A.1. Free Documentation Licence ............................................................................................42 iii B. Emacs PSGML mode tips............................................................................................................50 Glossary .............................................................................................................................................52 iv List of Tables 7-1. Mouse Mileage............................................................................................................................28 v Chapter 1. Introduction 1.1. About this Booklet This booklet was meant as a tutorial that can give you an introduction on how to use all the power and effectiveness of DocBook. It aims at getting you introduced to this matter in the shortest delay, hence then name of "Crash-course to DocBook". Even if you have never used either DocBook or other markup languages (like LinuxDoc) before, you should be able to become proficient in it just by reading through this guide and using the online (http://www.oasis-open.org/docbook/documentation/reference/html/docbook.html) or the paper (http://www.oreilly.com/catalog/docbook/index.html) version of [DocBook - The Definitive Guide] published by O’Reilly & Associates. Note: Please note that this crash course is designed to be used along with, not instead of, the DocBook Reference. There are a number of cases where it is much easier to refer to the reference rather than trying to rehash what it already covers. Use this guide to understand what DocBook is about and to have a general overview on how to use those tags. This tutorial will teach you enough DocBook to write basic documentation. You will learn: • What DocBook is about • How to get the DocBook-Tools up and running • The format of a DocBook tag • How to structure your documents properly • How to use lists and tables to organize data • How to describe GUI elements and Unix Commands • How to include graphics in your documentation • How to link to URL’s and create cross-references In appendix, one can find a short description of the Emacs psgml mode. This material comes from the fusion of three documents: • the "Introduction to DocBook" by Mark Galassi • the "KDE crash-course to DocBook" by David Rugge • parts of Eric Bischoff’s tutorial about DocBook Many parts of this document were borrowed from the "DocBook 3.0 Reference" by Eve Maler of ArborText, Inc. and Terry Allen of Fujitsu Software Corporation. The parts of this document that 1 Chapter 1. Introduction were borrowed from the Reference are Copyright © 1992, 1993, 1994, 1995, 1996, 1997 by HaL Computer Systems, Inc., O’Reilly & Associates, Inc., Fujitsu Software Corporation, and ArborText, Inc. 1.2. Why DocBook? The DocBook format was designed by OASIS consortium specifically for technical documentation. It provides a rich set of tags to describe the content of
Load more

Recommended publications
  • An Improved Parallel Hashed Oct-Tree N-Body Algorithm for Cosmological Simulation 1
    Scientific Programming 22 (2014) 109–124 109 DOI 10.3233/SPR-140385 IOS Press 2HOT: An improved parallel hashed oct-tree N-body algorithm for cosmological simulation 1 Michael S. Warren Theoretical Division, Los Alamos National Laboratory, Los Alamos, NM, USA E-mail: [email protected] Abstract. We report on improvements made over the past two decades to our adaptive treecode N-body method (HOT). A math- ematical and computational approach to the cosmological N-body problem is described, with performance and scalability mea- sured up to 256k (218) processors. We present error analysis and scientific application results from a series of more than ten 69 billion (40963) particle cosmological simulations, accounting for 4×1020 floating point operations. These results include the first simulations using the new constraints on the standard model of cosmology from the Planck satellite. Our simulations set a new standard for accuracy and scientific throughput, while meeting or exceeding the computational efficiency of the latest generation of hybrid TreePM N-body methods. Keywords: Computational cosmology, N-body, fast multipole method 1. Introduction mological parameters, modeling the growth of struc- ture, and then comparing the model to the observations We first reported on our parallel N-body algorithm (Fig. 1). (HOT) 20 years ago [67] (hereafter WS93). Over the Computer simulations are playing an increasingly same timescale, cosmology has been transformed from important role in the modern scientific method, yet a qualitative to a quantitative science. Constrained by a the exponential pace of growth in the size of calcu- diverse suite of observations [39,44,47,49,53], the pa- lations does not necessarily translate into better tests rameters describing the large-scale Universe are now of our scientific models or increased understanding of known to near 1% precision.
    [Show full text]
  • Multiple Outputs Why Single-Source?
    Sagehill Enterprises Single-source Publishing with What is Single-source DocBook XSL Publishing? ►Multiple outputs from single source file. ►Reusable content. Bob Stayton ►Modular writing. ►Assembled documents. Sagehill Enterprises ►“Write once, publish many”. DocBook Consulting http://www.sagehill.net email: [email protected] 831-566-8239 17 August 2005 Single-source Publishing with DocBook XSL 1 17 August 2005 Single-source Publishing with DocBook XSL 2 Multiple outputs Why Single-source? ►Print, PDF, HTML, slides, Help files. ►Reduce redundant writing. ►Different product versions. ►Writers can specialize. ►Different user levels. ►Update in a single place. ►Sight-impaired, WML, text-only. ►Users get more accurate information. ►Fewer words to translate. 17 August 2005 Single-source Publishing with DocBook XSL 3 17 August 2005 Single-source Publishing with DocBook XSL 4 What is DocBook? Why use DocBook? ►DTD for technical documentation. ►Designed for technical documentation. ►Related stylesheets and tools. ►Content kept separate from format. ►Started in 1991 as SGML, now XML. ►Open to computer processing. ►OASIS standard since 1998. ►Choose your publishing tools. ►Cross platform ►Automate your processing. 17 August 2005 Single-source Publishing with DocBook XSL 5 17 August 2005 Single-source Publishing with DocBook XSL 6 Copyright 2005 Bob Stayton 1 Sagehill Enterprises What’s the downside? Best for … ►XML learning curve. ►Multiple output formats. ►Investment in setup. ►Multiple releases over time. ►Technical staff needed. ►Large documentation sets. ►Batch processing environment. ►Shared authoring. 17 August 2005 Single-source Publishing with DocBook XSL 7 17 August 2005 Single-source Publishing with DocBook XSL 8 Who uses DocBook? What do you need? ► Sun ►DocBook DTD (XML version).
    [Show full text]
  • C-C++ Beautifier HOW-TO
    C-C++ Beautifier HOW-TO Al Dev (Alavoor Vasudevan) < alavoor[AT]yahoo.com > v16.7, 2 Nov 2003 Abstract This document will help you to format (beautify) the C/C++ programs so that it is more readable and confirms to your site C/C++ coding standards. The information in this document applies to all the operating sytems that is - Lin- ux, MS DOS, Apple Macintosh, Windows 95/NT/2000, BeOS, OS/2, IBM OSes, all flavors of Unix like Solaris, HPUX, AIX, SCO, Sinix, BSD, UnixWare, etc.. and to all other operating systems which support "C" compiler (it means almost all the operating systems on this planet!). Table of Contents Introduction ...................................................................................................................... 1 Installing BCPP ................................................................................................................. 2 How can I trust Beautifier programs??!! ................................................................................ 3 Method 1: Verfication Program for C++/C ..................................................................... 3 Method 2: Verfication Program for C++/C ..................................................................... 3 Method 3: Verfication Program for Java/C++/Others ........................................................ 4 Method 4: Shell script: Verfication Program for C++/C .................................................... 5 HTML Beautifier ..............................................................................................................
    [Show full text]
  • OASIS Response to NSTC Request for Feedback on Standard Practices
    OASIS RESPONSE TO NSTC REQUEST FOR FEEDBACK ON STANDARDS PRACTICES OASIS (Organization for the Advancement of Structured Information Standards) is pleased to respond to the request from the National Science and Technology Council's Sub-Committee on Standards published at 75 FR 76397 (2010), and extended by 76 FR 3877 (2011), for feedback and observations regarding the effectiveness of Federal agencies' participation in the development and implementation of standards and conformity assessment activities and programs. We have advised our own members about the Federal Register inquiry, in case they wish to respond. Of course, their opinions are their own, and this response does not represent the views of any members, but only the observations of OASIS professional staff. I. RESPONDENT'S BACKGROUND OASIS is one of the largest and oldest global open data standards consortia, founded in 1993 as SGML Open. OASIS has over 5000 active participants representing about 600 member organizations and individual members in over 80 countries. We host widely-used standards in multiple fields including • cybersecurity & access control (such as WS-Security, SAML, XACML, KMIP, DSS & XSPA) [/1], • office documents and smart semantic documents (such as OpenDocument, DITA, DocBook & CMIS) [/2], and • electronic commerce (including SOA and web services, such as BPEL, ebXML, WS-ReliableMessaging & the WS-Transaction standards) [/3] among other areas. Various specific vertical industries also fulfill their open standards requirements by initiating OASIS projects, resulting in mission-specific standards such as • UBL and Business Document Exchange (for e-procurement) [/4], • CAP and EDML (for emergency first-responder notifications) [/5], and • LegalXML (for electronic court filing data)[/6].
    [Show full text]
  • Automated Software System for Checking the Structure and Format of Acm Sig Documents
    AUTOMATED SOFTWARE SYSTEM FOR CHECKING THE STRUCTURE AND FORMAT OF ACM SIG DOCUMENTS A THESIS SUBMITTED TO THE GRADUATE SCHOOL OF APPLIED SCIENCES OF NEAR EAST UNIVERSITY By ARSALAN RAHMAN MIRZA In Partial Fulfillment of the Requirements for The Degree of Master of Science in Software Engineering NICOSIA, 2015 ACKNOWLEDGEMENTS This thesis would not have been possible without the help, support and patience of my principal supervisor, my deepest gratitude goes to Assist. Prof. Dr. Melike Şah Direkoglu, for her constant encouragement and guidance. She has walked me through all the stages of my research and writing thesis. Without her consistent and illuminating instruction, this thesis could not have reached its present from. Above all, my unlimited thanks and heartfelt love would be dedicated to my dearest family for their loyalty and their great confidence in me. I would like to thank my parents for giving me a support, encouragement and constant love have sustained me throughout my life. I would also like to thank the lecturers in software/computer engineering department for giving me the opportunity to be a member in such university and such department. Their help and supervision concerning taking courses were unlimited. Eventually, I would like to thank a man who showed me a document with wrong format, and told me “it will be very good if we have a program for checking the documents”, however I don’t know his name, but he hired me to start my thesis based on this idea. ii To Alan Kurdi To my Nephews Sina & Nima iii ABSTRACT Microsoft office (MS) word is one of the most commonly used software tools for creating documents.
    [Show full text]
  • Editing Docbook V5.0
    DocBook V5.0 The Transition Guide 27 October 2005 This version: http://docbook.org/docs/howto/2005-10-27/ Latest version: http://docbook.org/docs/howto/ Authors: Jirka Kosek, <[email protected]> Norman Walsh, <[email protected]> Table of Contents Introduction ........................................................................................................................................ 1 Finally in a namespace .................................................................................................................. 2 Relaxing with DocBook ................................................................................................................ 2 Why switch to DocBook V5.0? ...................................................................................................... 3 Schema jungle ............................................................................................................................ 3 Toolchain ........................................................................................................................................... 4 Editing DocBook V5.0 .................................................................................................................. 4 Validating DocBook V5.0 .............................................................................................................. 9 Processing DocBook V5.0 ........................................................................................................... 10 Markup changes ...............................................................................................................................
    [Show full text]
  • Howtos with Linuxdoc
    HOWTOs with LinuxDoc David S. Lawyer v0.09, November 2007 Questo testo tratta di come scrivere gli HOWTO usando il semplice linguaggio a marcatori (markup) LinuxDoc. È rivolto principalmente agli autori del Linux Documentation Project (e ad autori futuri alle prime armi che vogliono iniziare rapidamente). Se si vuole usare DocBook, il linguaggio a marcatori più completo e dicile, (incluso XML), vedere la LDP Authoring Guide (Guida per gli autori di LDP). Traduzione ed adattamenti in italiano a cura di Beatrice Torracca, beatricet (at) libero (dot) it, e Hugh Hartmann, hhartmann (at) libero (dot) it, revisione a cura di Vieri Giugni, v.giugni (at) gmail (dot) com). Per versioni aggiornate di questo documento, e per trovare altra documentazione in italiano sul software libero, visitare il sito dell' ILDP <http://it.ildp.org> Indice 1 Introduzione 2 1.1 Per partire immediatamente.....................................2 1.2 Copyright e licenza..........................................3 1.3 Perché si dovrebbe scrivere un HOWTO?.............................3 1.4 Perché ho scritto questo documento................................3 2 Informazioni sulla scrittura di un HOWTO3 2.1 Copyright...............................................3 2.2 Scegliere un argomento........................................3 3 Il formato degli HOWTO4 3.1 Introduzione..............................................4 4 LinuxDoc e DocBook a confronto4 5 Imparare LinuxDoc 6 5.1 Introduzione..............................................6 5.2 Esempio 1 (nome le: esempio1.sgml)...............................6 5.3 Esempio 2 (nome le: esempio2.sgml)...............................7 5.4 Esempio 3 (nome le: esempio3.sgml)...............................9 5.5 Guida di consultazione rapida di LinuxDoc............................ 11 5.5.1 Intestazione.......................................... 11 5.5.2 Impaginazione del corpo................................... 12 5.5.3 Tipi di carattere....................................... 12 1.
    [Show full text]
  • Open-Source Documentation
    Open-Source Documentation: In Search of User-Driven, Just-in-Time Writing Erik Berglund Michael Priestley Linköping University IBM Toronto Lab S-581 83, Linköping, Canada Sweden [email protected] + 46 13 28 24 93 [email protected] ABSTRACT Keywords Iterative development models allow developers to respond quickly Open source documentation, just-in-time, user-driven. to changing user requirements, but place increasing demands on writers who must handle increasing amounts of change with ever- 1. THE PROBLEM decreasing resources. In the software development world, one Over the years, the software industry has accepted that changing solution to this problem is open-source development: allowing the requirements are simply part of the software development process. users to set requirements and priorities by actually contributing to An allowance for client requirements change, even an expectation the development of the software. This results in just-in-time of change, is at the foundation of most software development software improvements that are explicitly user-driven, since they methodologies. The Rational Unified Process (RUP) illustrates are actually developed by users. this, and Extreme Programming (XP) exemplifies it. Taken to the In this article we will discuss how the open source model can be extreme, as it often is in open-source development, the extended to the development of documentation. In many open- functionality of the product may not be determined until the day it source projects, the role of writer has remained unchanged: is completed. documentation development remains a specialized activity, owned Continuous requirements change makes traditional methods of by a single writer or group of writers, who work as best they can software documentation difficult.
    [Show full text]
  • A Self-Referential HOWTO on Release Engineering∗
    A self-referential HOWTO on release engineering∗ Mark Galassi† Space Science and Applications group Los Alamos National Laboratory‡ February 1, 2018 Abstract Release engineering is a fundamental part of the software development cycle: it is the point at which quality control is exercised and bug fixes are integrated. The way in which software is released gives the end user her first experience of a software package, while in scientific computing release engineering can guarantee reproducibility. For these reasons and others the release process is a good indicator of the maturity and organization of a development team. Software teams often do not put in place a release process at the beginning. This is unfortunate because the team does not have early and continuous execution of test suites, and it does not exercise the software in the same conditions as the end users. I describe an approach to release engineering based on the software tools developed and used by the GNU project, together with several specific proposals related to packaging and distribution. I do this in a step-by-step manner, demonstrating how this very paper is written and built using proper release engineering methods. Because many aspects of release engineering are not exercised in the building of the paper, the accompanying software repository also contains examples of software libraries. ∗For use with software version 1.0.0plus †[email protected] ‡LA-UR-14-21151 1 4 Introducing a library, and release 0.5.0 15 4.1 A simple library, built and installed by hand 15 4.2 Building and installing that simple library with automake .
    [Show full text]
  • Xmlmind XSL Utility - Online Help
    XMLmind XSL Utility - Online Help Hussein Shafie, XMLmind Software <[email protected]> February 23, 2021 Table of Contents 1. Overview ................................................................................................................................ 1 2. Running XMLmind XSL Utility ............................................................................................... 3 2.1. System requirements ..................................................................................................... 3 2.2. Installation ................................................................................................................... 3 2.3. Contents of the installation directory .............................................................................. 3 2.4. Starting XMLmind XSL Utility ..................................................................................... 4 2.5. XMLmind XSL Utility as a command-line tool .............................................................. 5 3. Converting an XML document to another format ....................................................................... 6 3.1. Canceling the current conversion process ....................................................................... 7 4. Changing the parameters of a conversion .................................................................................. 8 5. Specifying a conversion ......................................................................................................... 10 5.1. Specifying the conversion
    [Show full text]
  • JSON Application Programming Interface for Discrete Event Simulation Data Exchange
    JSON Application Programming Interface for Discrete Event Simulation data exchange Ioannis Papagiannopoulos Enterprise Research Centre Faculty of Science and Engineering Design and Manufacturing Technology University of Limerick Submitted to the University of Limerick for the degree of Master of Engineering 2015 1. Supervisor: Prof. Cathal Heavey Enterprise Research Centre University of Limerick Ireland ii Abstract This research is conducted as part of a project that has the overall aim to develop an open source discrete event simulation (DES) platform that is expandable, and modular aiming to support the use of DES at multi-levels of manufacturing com- panies. The current work focuses on DES data exchange within this platform. The goal of this thesis is to develop a DES exchange interface between three different modules: (i) ManPy an open source discrete event simulation engine developed in Python on the SimPy library; (ii) A Knowledge Extraction (KE) tool used to populate the ManPy simulation engine from shop-floor data stored within an Enterprise Requirements Planning (ERP) or a Manufacturing Execution System (MES) to allow the potential for real-time simulation. The development of the tool is based on R scripting language, and different Python libraries; (iii) A Graphical User Interface (GUI) developed in JavaScript used to provide an interface in a similar manner to Commercial off-the-shelf (COTS) DES tools. In the literature review the main standards that could be used are reviewed. Based on this review and the requirements above, the data exchange format standard JavaScript Object Notation (JSON) was selected. The proposed solution accom- plishes interoperability between different modules using an open source, expand- able, and easy to adopt and maintain, in an all inclusive JSON file.
    [Show full text]
  • Reconnaissance Structurelle De Formules Mathématiques : État De L’Art 9
    CORE Metadata, citation and similar papers at core.ac.uk Provided by HAL-UNICE Reconnaissance Structurelle de Formules Math´ematiques Typographi´eeset Manuscrites St´ephaneLavirotte To cite this version: St´ephaneLavirotte. Reconnaissance Structurelle de Formules Math´ematiques Typographi´ees et Manuscrites. Interface homme-machine [cs.HC]. Universit´eNice Sophia Antipolis, 2000. Fran¸cais. <tel-00523373> HAL Id: tel-00523373 https://tel.archives-ouvertes.fr/tel-00523373 Submitted on 5 Oct 2010 HAL is a multi-disciplinary open access L'archive ouverte pluridisciplinaire HAL, est archive for the deposit and dissemination of sci- destin´eeau d´ep^otet `ala diffusion de documents entific research documents, whether they are pub- scientifiques de niveau recherche, publi´esou non, lished or not. The documents may come from ´emanant des ´etablissements d'enseignement et de teaching and research institutions in France or recherche fran¸caisou ´etrangers,des laboratoires abroad, or from public or private research centers. publics ou priv´es. UNIVERSITEDENICE–SOPHIAANTIPOLIS´ Ecole´ Doctorale des Sciences et Technologies de l’Information et de la Communication Reconnaissance structurelle de formules math´ematiques typographi´ees et manuscrites THESE` de doctorat pour obtenir le titre de Docteur en Sciences Discipline : Informatique par St´ephane LAVIROTTE Soutenue le 14 juin 2000 a` l’ESSI (Sophia-Antipolis) Composition du jury Pr´esident : Jean-Marc FEDOU Professeur `a l’Universit´e de Nice Sophia-Antipolis Rapporteurs : Karl TOMBRE Professeural’ ` Ecole´ des Mines de Nancy Guy LORETTE Professeura ` l’Universit´e de Rennes I Examinateurs : Lo¨ıc POTTIER Charg´e de Recherche `a l’INRIA Sophia-Antipolis Peter SANDER Professeura ` l’Universit´e de Nice Sophia-Antipolis Marc BERTHOD Directeur de Recherchea ` l’INRIA Sophia-Antipolis Universit´e de Nice Sophia-Antipolis / Institut National de Recherche en Informatique et Automatique Mis en page avec la classe thloria.
    [Show full text]