DOCSLIB.ORG

Get Going with Docbook

Total Page：16

File Type：pdf, Size：1020Kb

Download full-text PDF Read full-text
Get Going with Docbook Get Going With DocBook Notes for Hackers Mark Galassi Cygnus Solutions Get Going With DocBook: Notes for Hackers by Mark Galassi Copyright © 1998 by Mark Galassi This document can be freely redistributed according to the terms of the GNU General Public License. Revision History Revision 0.01997-10-11Revised by: [email protected] Initial revision; mostly just an outline Revision 0.11997-11-01Revised by: [email protected] Firmed up the outline, based on the evolution of Cygnus’s DocBook effort Revision 0.21997-11-09Revised by: [email protected] Have enough meat in there that I have announced it. Revision 0.31997-12-31Revised by: [email protected] Separated the tutorial (this document) from the style guide for my project at Cygnus. This tutorial can now be distributed on its own. Revision 0.41998-02-14Revised by: [email protected] Added some blurbs on descriptions and made the first web release of this document. Revision 0.51998-06-12Revised by: [email protected] Added Sara Mitchell’s brief essay on SGML marked sections as its own chapter. Revision 0.61998-10-19Revised by: [email protected] Mentioned that this document is GPLed, did a bit of cleanup, and added mention of my FrameMaker+SGML EDD. Table of Contents 1. What is this?......................................................................................................... -999 1.1. A tutorial for hacker–writers ...................................................................... -999 1.2. An example of how to use DocBook structure........................................... -999 1.3. Not an example for all situations ................................................................ -999 2. Get going............................................................................................................... -999 2.1. Hello, world ................................................................................................ -999 2.2. A slightly more complex example.............................................................. -999 2.3. From here on............................................................................................... -999 3. A tour of some DocBook features....................................................................... -999 3.1. Global markups........................................................................................... -999 3.1.1. Books ............................................................................................... -999 3.1.2. Articles............................................................................................. -999 3.2. Examples and screen snapshots.................................................................. -999 3.2.1. Examples involving plain text ......................................................... -999 3.2.2. Describing GUIs .............................................................................. -999 3.2.3. Code samples................................................................................... -999 3.3. Describing an API ...................................................................................... -999 3.4. Tables.......................................................................................................... -999 3.5. Reference things ......................................................................................... -999 4. Concepts ............................................................................................................... -999 4.1. Your world view.......................................................................................... -999 4.2. Markup based on content............................................................................ -999 4.3. Explanation of SGML–related terms.......................................................... -999 4.3.1. SGML — a framework for defining markup languages.................. -999 4.3.2. What about the appearnace on output media? ................................. -999 5. How you should structure your documents....................................................... -999 5.1. Structure of a book ..................................................................................... -999 5.2. Structure of a chapter.................................................................................. -999 5.3. Structure of sections ................................................................................... -999 6. DocBook Resources ............................................................................................. -999 3 7. SGML entities ...................................................................................................... -999 7.1. BASIC STRUCTURE OF AN SGML DOCUMENT................................ -999 7.2. USING ENTITIES TO CONNECT OTHER FILES.................................. -999 7.3. IDENTIFYING FILES WITH FORMAL PUBLIC IDS ........................... -999 7.4. USING ENTITIES FOR SHARED TEXT ................................................ -999 7.5. USING MARKED SECTIONS TO HANDLE CONDITIONAL CONTENT -999 8. Emacs PSGML mode tips ................................................................................... -999 A. Obtaining and installing DocBook tools ........................................................... -999 A.1. UNIX ......................................................................................................... -999 A.2. Win32......................................................................................................... -999 A.3. FrameMaker+SGML ................................................................................. -999 Glossary .................................................................................................................... -999 4 List of Tables 3-1. Convergence of dynamical equations and constraints for various choices of constrained edges............................................................................................... -999 List of Examples 2-1. Bare bones DocBook document — the source................................................... -999 2-2. Fleshier DocBook document — the source........................................................ -999 3-1. Documenting a typical ftp session ..................................................................... -999 3-2. Program listings in DocBook ............................................................................. -999 3-3. A simple C program ........................................................................................... -999 3-4. Describing a function in a C library API............................................................ -999 3-5. A simple informal table (no title)....................................................................... -999 3-6. A more complex table ........................................................................................ -999 5 Chapter 1. What is this? 1.1. A tutorial for hacker–writers This booklet has two main goals: The first is present a tutorial on writing documentation that will be used in a particular project at Cygnus. The second is for me to clarify my thoughts on how I think the books we ship with should be structured. A third goal, which is not as pressing, is that this booklet should become a tutorial for all people at Cygnus (and elsewhere; the GNOME project, for example is using DocBook) who will be writing notes for future incorporation into Cygnus documentation. If you just want the tutorial with no further background information, please jump right to Chapter 2. 1.2. An example of how to use DocBook structure This booklet is a valid demonstration of how to use DocBook elements for writing Cygnus documentation. As the Cygnus tag team refines the Cygnus style and typical tag usage, this document will be updated to reflect that style and usage. Whenever I mention Cygnus, please note that the Cygnus stylesheets and all the tools we use are being made available to the world at large, so projects outside of Cygnus can also use these stylesheets, our tools, and this tutorial. If you are a hacker working on a project and you need to write an essay, or if you would like to document your portion of the project, you can use this booklet as an example of 6 Chapter 1. What is this? how to structure your document and what DocBook elements you should use to mark up your text. 1.3. Not an example for all situations This booklet is a tutorial written in quasi–slapstick style — I use the words I and you liberally. You should not treat it as an example of how to write a reference manual, or as an example of how to write a more stuffy tutorial. 7 Chapter 2. Get going Here is a brutal sequence of steps that will get you started writing DocBook documents. If you actually want to understand what is going on, you might want to read Chapter 4 first and then come back to this chapter. This chapter will not tell you how to get the tools installed — it is assumed that your system administrator has done that for you. If she or he has not done so, there is an appendix that gives instructions to get DocBook editing and processing tools. There are sections for Section A.1 (with free tools), Section A.2 (with free tools) and Section A.3. 2.1. Hello, world Here’s a simple DocBook document to get going. I will show you how to write this document using explicit element tags, but if you are using an authoring tool that provides a high level interface, just choose the same tags using that interface. Example 2-1. Bare bones DocBook document — the source <!doctype book PUBLIC
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]
  • 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]
  • 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]
  • Rdieharder: an R Interface to the Dieharder Suite of Random Number Generator Tests
    RDieHarder: An R interface to the DieHarder suite of Random Number Generator Tests Dirk Eddelbuettel Robert G. Brown Debian Physics, Duke University [email protected] [email protected] May 2007 1 Introduction Random number generators are critically important for computational statistics. Simulation methods are becoming ever more common for estimation; Monte Carlo Markov Chain is but one approach. Also, simulation methods such as the Bootstrap have long been used in inference and are becoming a standard part of a rigorous analysis. As random number generators are at the heart of the simulation-based methods used throughout statistical com- puting, `good' random numbers are therefore a crucial aspect of a statistical, or quantitative, computing environment. However, there are very few tools that allow us to separate `good' from `bad' random number generators. Based on work that started with the random package (Eddelbuettel, 2007) (which pro- vides functions that access a non-deterministic random number generator (NDRNG) based on a physical source of randomness), we wanted to compare the particular NDRNG to the RNGs implemented in GNU R (R Development Core Team, 2007) itself, as well as to sev- eral RNGs from the GNU GSL (Galassi et al., 2007), a general-purpose scientific computing library. Such a comparison is possible with the DieHarder test suite by Brown(2007) which extends the DieHard test suite by Marsaglia. From this work, we became interested in mak- ing DieHarder directly accessible from GNU R. The RDieHarder package presented here allows such access. This paper is organized as follows. Section 2 describes the history and design of the DieHarder suite.
    [Show full text]
  • Universidad Nacional Autónoma De México
    Universidad Nacional Aut´onoma de M´exico Instituto de Investigaciones en Matem´aticas Aplicadas y en Sistemas Facultad de Ingenier´ıa Laboratorio de Biorob´otica ocalizaci´on y seguimiento de objetos a trav´es de sus caracter´ısticas principales Ing� Rommel S´anchez Verdejo [email protected] 2008 a UNAM – Dirección General de Bibliotecas Tesis Digitales Restricciones de uso DERECHOS RESERVADOS © PROHIBIDA SU REPRODUCCIÓN TOTAL O PARCIAL Todo el material contenido en esta tesis esta protegido por la Ley Federal del Derecho de Autor (LFDA) de los Estados Unidos Mexicanos (México). El uso de imágenes, fragmentos de videos, y demás material que sea objeto de protección de los derechos de autor, será exclusivamente para fines educativos e informativos y deberá citar la fuente donde la obtuvo mencionando el autor o autores. Cualquier uso distinto como el lucro, reproducción, edición o modificación, será perseguido y sancionado por el respectivo titular de los Derechos de Autor. Resumen El objetivo de este trabajo es proporcionar al Laboratorio de Biorob´otica del Posgrado de la Facultad de Ingenier´ıa de la Universidad Nacional Aut´onoma de M´exico un sistema de visi´on !ue sea "´acil de modi#car para "uturas generaciones de un conjunto de $erramientas en mantenimiento constante as´ı como per"ectamente documentadas utili%ando implementaciones con su respectivo c´odigo anteriormente propuesto evaluando & mejorando su rendimiento a trav´es de t´ecnicas de optimi%aci´on por $ard'are & una t´ecnica te´orica en este caso( la cuanti%aci´on vectorial)
    [Show full text]
  • The Journal of AUUG Inc. Volume 22 ¯ Number 3 November 2001
    The Journal of AUUG Inc. Volume 22 ¯ Number 3 November 2001 Features: Doing Damage with DocBook 14 AUUGN CD: Mandrake 8.1 16 Linux as a Replacement for Windows 2000 17 Interview with Ben Collins, DPL 27 Old Kernels Never Die 29 Rune for Linux 30 Testing a Firewall or Router 33 Caldera Open Linux Workstation 3.1 37 Wasabi Systems ships update to NetBSD 44 DVD Players for Linux 44 Using XML and XSLT 53 Logical Volume Managers 57 Psionic Portsentry, the defender of the ports 59 The State of Corporate IT: The case for Linux 62 Installing Debian on a 4MB RAM System 66 wxPython for Newbies 67 Debian Conference, Australia 72 AUUG2001: The Conference Photos 72 Shell Programming 78 News: Public Notices 10 AUUG2002: Call for Papers 6 LUV Installfest 2001 12 AUUG Security Symposium 2001 86 AUUG: Chapter Meetings and Contact Details 9O Regulars: President’s Column 3 /var/spool/mail/auugn 4 My Home Network 10 ISSN 1035-7521 Print post approved by Australia Post - PP2391500002 , AUUG Membership and General Correspondence The AUUG Secretary PO Box 366 Editorial Kensington NSW 2033 Con Zymaris Telephone: 02 8824 9511 [email protected] or 1800 625 655 (Toll-Free) Facsimile: 02 8824 9522 Email: [email protected] I often begin issues of AUUGN with a snippet of recent news which relates to our segment of the IT industry. AUUG Management Committee Now, what do I define as our segment of the IT Email: [email protected] industry? Well, to be blunt, and at the risk of President inflaming opposing opinions, I define it as that area David Purdue bounded by switched-on people doing interesting iPlanet e-commerce solutions The Tea House things with advanced computing platforms.
    [Show full text]
  • Performance and Availability Characterization for Linux Servers
    Performance and Availability Characterization for Linux Servers Vasily Linkov Oleg Koryakovskiy Motorola Software Group Motorola Software Group [email protected] [email protected] Abstract software solutions that were very expensive and in many cases posed a lock-in with specific vendors. In the cur- The performance of Linux servers running in mission- rent business environment, many players have come to critical environments such as telecommunication net- the market with variety of cost-effective telecommuni- works is a critical attribute. Its importance is growing cation technologies including packed data technologies due to incorporated high availability approaches, espe- such as VoIP, creating server-competitive conditions for cially for servers requiring five and six nines availability. traditional providers of wireless types of voice commu- With the growing number of requirements that Linux nications. To be effective in this new business environ- servers must meet in areas of performance, security, re- ment, the vendors and carriers are looking for ways to liability, and serviceability, it is becoming a difficult task decrease development and maintenance costs, and de- to optimize all the architecture layers and parameters to crease time to market for their solutions. meet the user needs. Since 2000, we have witnessed the creation of several industry bodies and forums such as the Service Avail- Other Linux servers, those not operating in a mission- ability Forum, Communications Platforms Trade As- critical environment, also require different approaches sociation, Linux Foundation Carrier Grade Linux Ini- to optimization to meet specific constraints of their op- tiative, PCI Industrial Computer Manufacturers Group, erating environment, such as traffic type and intensity, SCOPE Alliance, and many others.
    [Show full text]
  • Modern Software Engineering and Research a Pandemic-Adapted Professional Development Workshop
    Modern Software Engineering and Research A pandemic-adapted professional development workshop Mark Galassi Space Science and Applications group Los Alamos National Laboratory 2020-05-16, 2021-01-20 Last built 2021-01-27T13:19:44 (You may redistribute these slides with their LATEX source code under the terms of the Creative Commons Attribution-ShareAlike 4.0 public license) Outline Goals Outline Goals Goals and path In the educational industrial complex we are required to state our goals before we start. It might even be a good idea. Goals The meandering path I Have a broad view of University I My path is largely historical because of curriculum, successes and limitations, my personal inclination to use history state of industry. to give perspective. I Awareness of grand challenges I We need perspective so we are not tossed in software engineering. about by the short-term interest of I Awareness of current approaches industry. to address those challenges. Style I Slides are placeholders for me to then tell stories. I hope you will talk and tell stories too. I But also: I join the modern quest to give a seminar made entirely of xkcd slides. Outline Curriculum Programming Languages Stories of programming languages Tour of languages Insights on languages The Computer Science Curriculum From https://teachyourselfcs.com/ Computer programming Computer Architecture Algorithms and Data Structures Discrete Math Operating Systems Networking Computer security Databases Compilers and Languages Artificial Intelligence Graphics The Software Engineering curriculum Most of the computer science department courses. Less math. Process and management classes. ISO’s “Software Engineering Body of Knowledge” Margaret Hamilton, who led the MIT team that wrote the Apollo on-board software in the 1960s, is one of the coiners of the term (SWEBOK).
    [Show full text]
  • Our Form 1023 with the USA
    Application for Recognition of Exemption OMS No. 1545-0056 Form 1023 Note: If exempt status is (Rev. October 2004) Under Section 501{c)(3) of the Internal Revenue Code approved, this Department of the Treasury application will be open Internal Revenue Service for public inspection. Use the instructions to complete this application and for a definition of all bold items. For additional help, call IRS Exempt Organizations Customer Account Services toll-free at 1-877-829-5500. Visit our website at www.irs.gov for forms and publications. If the required information and documents are not submitted with payment of the appropriate user fee, the application may be returned to you. Attach additional sheets to this application if you need more space to answer fully. Put your name and EIN on each sheet and identify each answer by Part and line number. Complete Parts I - XI of Form 1023 and submit only those Schedules (A through H) that apply to you. Identification of Applicant 1 Full name of organization (exactly as it appears in your organizing document) 2 c/o Name (if applicable) Software Freedom ConseNancy, Inc. 3 Mailing address (Number and street) (see instructions) Room/Suite 4 EmployerIdentificationNumber(EIN) 17th 1995 Broadway 41-2203632 Floor City or town, state or country, and ZIP + 4 5 Monththeannualaccountingperiodends(01 -12) New York, NY 10023 12 6 Primary contact (officer, director, trustee, or authorized representative) a Name: Karen M. Sandler b Phone: (212)461-1908 Secretary c Fax: (optional) (212)580-0898 7 Are you represented by an authorized representative, such as an attorney or accountant? If "Yes," 0 Yes [KJ No provide the authorized representative's name, and the name and address of the authorized representative's firm.
    [Show full text]
  • How to Run a Successful Free Software Project
    Producing Open Source Software How to Run a Successful Free Software Project Karl Fogel Producing Open Source Software: How to Run a Successful Free Software Project by Karl Fogel Copyright © 2005-2021 Karl Fogel, under the CreativeCommons Attribution-ShareAlike (4.0) license. Version: 2.3214 Home site: https://producingoss.com/ Dedication This book is dedicated to two dear friends without whom it would not have been possible: Karen Underhill and Jim Blandy. i Table of Contents Preface ........................................................................................................................................................... vi Why Write This Book? ............................................................................................................................. vi Who Should Read This Book? ................................................................................................................... vi Sources .................................................................................................................................................. vii Acknowledgements ................................................................................................................................. viii For the first edition (2005) .............................................................................................................. viii For the second edition (2021) ............................................................................................................ ix Disclaimer .............................................................................................................................................
    [Show 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 ...............................................................................................................................
    [Show full text]
  • Persistence for the Masses: RRB-Vectors in a Systems Language
    Persistence for the Masses: RRB-Vectors in a Systems Language JUAN PEDRO BOLÍVAR PUENTE Relaxed Radix Balanced Trees (RRB-Trees) is one of the latest members in a family of persistent tree based data-structures that combine wide branching factors with simple and relatively flat structures. Like the battle- tested immutable sequences of Clojure and Scala, they have effectively constant lookup and updates, good cache utilization, but also logarithmic concatenation and slicing. Our goal is to bring the benefits of func- tional data structures to the discipline of systems programming via generic yet efficient immutable vectors supporting transient batch updates. We describe a C++ implementation that can be integrated in the runtime of higher level languages with a C core (Lisps like Guile or Racket, but also Python or Ruby), thus widening the access to these persistent data structures. In this work we propose (1) an Embedding RRB-Tree (ERRB-Tree) data structure that efficiently stores arbitrary unboxed types, (2) a technique for implementing tree operations independent of optimizations for a more compact representation of the tree, (3) a policy-based design to support multiple memory management and reclamation mechanisms (including automatic garbage collection and reference counting), (4) a model of transience based on move-semantics and reference counting, and (5) a definition of transience for confluent meld operations. Combining these techniques a performance comparable to that of mutable arrays can be achieved in many situations, while using the data structure in a functional way. CCS Concepts: • Software and its engineering → Data types and structures; Functional languages; • General and reference → Performance; Additional Key Words and Phrases: Data Structures, Immutable, Confluently, Persistent, Vectors, Radix-Balanced, Transients, Memory Management, Garbage Collection, Reference Counting, Design Patterns, Policy-Based Design, Move Semantics, C++ ACM Reference Format: Juan Pedro Bolívar Puente.
    [Show full text]