Return to README CVS log

Up to [XFree86 CVS] / doctools

doctools 1.3.5

                         doctools version 1.3.5
                         ======================

                   Documentation tools for XFree86
                   -------------------------------

Introduction
------------

This is a collection of documentation tools, based closely on the tools
used by the FreeBSD documentation project (as of early 1998).  The
XFree86-specific customisations are relatively minor.

The SGML parser used is James Clark's sp/nsgmls.  Although the full
jade package is included here, only the sp part is built and used
(for now).

The instant package (from OSF) is used to translate the SGML parser
output into the appropriate format.

The whole lot is driven from a perl script called sgmlfmt, written
by John Fieber <jfieber@FreeBSD.org>.  sgmlfmt also takes care of
a significant amount of the work when producing HTML output.

The SGML document descriptions (DTD) included here are the original
linuxdoc-1.1, two versions with modifications for FreeBSD use, and
one based on the more recent FreeBSD version with a couple of additions
for compatibility of the older tools XFree86 was using.  The DocBook
DTD (from the Davenport Group -- who's work is hosted at O'Reilly's web
site) is also included.

Instant translation descriptions are included (in sgmlformat/transpec)
for translating the linuxdoc formats to [g]roff, latex, html and docbook.
The latter allows a quick conversion from linuxdoc to docbook.  Translation
descriptions for DocBook are include for [g]roff and html, although at
least the [g]roff one appears incomplete and in need of work.


Building
--------

Typically (modulo any portability problems), the whole lot can be built
by editing the top level Makefile, and running 'make'.  To install, run
'make install'.  By default everything is installed under /usr/local.
To install in a different location, change the setting of PREFIX in the
top level Makefile.  The `instant' code has been modified to use a POSIX
regex.  For those OSs that don't come with that (like SVR4.0) a copy of
Henry Spencer's regex source is included here.  To use that just uncomment
the appropriate lines in the top level Makefile.  Check the comments in
the Makefile for further details.

Note: the top level Makefile passes lots of settings to those in the
subdirs, so building/installing from within the subdirs needs to be done
with care and isn't advised unless you know what you're doing.

The installation process installs the required runtime data files in
$(PREFIX)/share/sgml/ and the binaries in $(PREFIX)/bin.

If you already have the FreeBSD ports collection of all of this stuff
installed, you will need to update/add the following files:

   /usr/local/bin/sgmlfmt
   /usr/local/share/sgml/linuxdoc/catalog
   /usr/local/share/sgml/linuxdoc/xfree86.dtd
   /usr/local/share/sgml/transpec/linuxdoc-roff.ts
   /usr/local/share/sgml/transpec/docbook-roff.ts
   /usr/local/share/sgml/tmac/*

Alternatively, if you have the FreeBSD ports version installed, and want
to avoid a clash between that version and this one, set PREFIX to some
other value, and make sure that path is set appropriately when doing
an XFree86 build.

Note, that where possible, it is intended that changes made here be fed
back to the maintainers of the various software, and the FreeBSD ports
maintainers.

Groff is required to generate the text and PostScript output format.
The initial testing was done with groff 1.10, so it is probably best to
use 1.10 or later.  Some (slightly) customised tmac files are included
here, and get installed in /usr/local/share/sgml/tmac/ (so that they
can coexist with any standard versions).

As of doctools version 1.1.2 there is support for processing Japanese
documentation into text.  This requires the Japanese-aware version of
groff (jgroff).


Running
-------

To use these utilities from within a normal XFree86 build, add the following
lines to your xc/config/cf/host.def file:

#define HasSgmlFmt              YES
#define BuildAllDocs            YES


If you want to disable building either of the text of PostScript formats
(if, for example, you don't have groff installed), it can be done adding
one or both of the following lines to your host.def file:

#define BuildLinuxDocText       NO
#define BuildLinuxDocPS         NO


You can also disable the building of HTML files with:

#define BuildLinuxDocHtml       NO



SGML/Linuxdoc notes
-------------------

The entities "&tm" and "&dquot" which were present in the original
linuxdoc are deprecated.  Definitions for them are included in the
XFree86 version of the linuxdoc dtd included here for compatibility
reasons, but for future work, "&tm" should be replaced by "&trade", and
"&dquot" should simply be replaced by a '"' character.  Note: there
seems to be some uncertainty as to whether the standard "&quot" entity
is intended to represent a single or double quote character.


Future directions
-----------------

The FreeBSD documentation project is moving towards using the DocBook
dtd, and using jade and DSSSL style sheets for the translation into
final formats instead of instant/transpec.  That is currently work in
progress, and we'll move to that approach once it has progressed a little
further.


TODO
----

Man pages are not installed yet, but should be.



LICENSES
--------

DocBook DTD:

     Copyright 1992, 1993, 1994, 1995, 1996 HaL Computer Systems, Inc.,
     O'Reilly & Associates, Inc., ArborText, Inc., and Fujitsu Software
     Corporation.

     Permission to use, copy, modify and distribute the DocBook DTD and
     its accompanying documentation for any purpose and without fee is
     hereby granted in perpetuity, provided that the above copyright
     notice and this paragraph appear in all copies.  The copyright
     holders make no representation about the suitability of the DTD for
     any purpose.  It is provided "as is" without expressed or implied
     warranty.

     If you modify the DocBook DTD in any way, except for declaring and
     referencing additional sets of general entities and declaring
     additional notations, label your DTD as a variant of DocBook.  See
     the maintenance documentation for more information.

ISO8879 entities:

     (C) International Organization for Standardization 1986
     Permission to copy in any form is granted for use with
     conforming SGML systems and applications as defined in
     ISO 8879, provided this notice is included in all copies.

jade:

    Copyright (c) 1994, 1995, 1996 James Clark

    Permission is hereby granted, free of charge, to any person obtaining
    a copy of this software and associated documentation files (the
    ``Software''), to deal in the Software without restriction, including
    without limitation the rights to use, copy, modify, merge, publish,
    distribute, sublicense, and/or sell copies of the Software, and to
    permit persons to whom the Software is furnished to do so, subject to
    the following conditions:

    The above copyright notice and this permission notice shall be included
    in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND, EXPRESS
    OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    IN NO EVENT SHALL JAMES CLARK BE LIABLE FOR ANY CLAIM, DAMAGES OR
    OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
    ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
    OTHER DEALINGS IN THE SOFTWARE.

    Except as contained in this notice, the name of James Clark shall
    not be used in advertising or otherwise to promote the sale, use or
    other dealings in this Software without prior written authorization
    from James Clark.

regex:

    Copyright 1992, 1993, 1994, 1997 Henry Spencer.  All rights reserved.
    This software is not subject to any license of the American Telephone
    and Telegraph Company or of the Regents of the University of California.

    Permission is granted to anyone to use this software for any purpose on
    any computer system, and to alter it and redistribute it, subject
    to the following restrictions:

    1. The author is not responsible for the consequences of use of this
       software, no matter how awful, even if they arise from flaws in it.

    2. The origin of this software must not be misrepresented, either by
       explicit claim or by omission.  Since few users ever read sources,
       credits must appear in the documentation.

    3. Altered versions must be plainly marked as such, and must not be
       misrepresented as being the original software.  Since few users
       ever read sources, credits must appear in the documentation.

    4. This notice may not be removed or altered.

sgmlfmt:

     Copyright (C) 1996
          John R. Fieber.  All rights reserved.
   
     Redistribution and use in source and binary forms, with or without
     modification, are permitted provided that the following conditions
     are met:
     1. Redistributions of source code must retain the above copyright
        notice, this list of conditions and the following disclaimer.
     2. Redistributions in binary form must reproduce the above copyright
        notice, this list of conditions and the following disclaimer in the
        documentation and/or other materials provided with the distribution.
   
     THIS SOFTWARE IS PROVIDED BY JOHN R. FIEBER AND CONTRIBUTORS ``AS IS'' AND
     ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
     IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
     ARE DISCLAIMED.  IN NO EVENT SHALL JOHN R. FIEBER OR CONTRIBUTORS BE LIABLE
     FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
     DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
     OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
     HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
     LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
     OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
     SUCH DAMAGE.

groff mm macros:

    Copyright (C) 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc.
    mgm is written by Jörgen Hägg <jh@axis.se>

    mgm is free software; you can redistribute it and/or modify it under
    the terms of the GNU General Public License as published by the Free
    Software Foundation; either version 2, or (at your option) any later
    version.

    mgm is distributed in the hope that it will be useful, but WITHOUT ANY
    WARRANTY; without even the implied warranty of MERCHANTABILITY or
    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
    for more details.

    You should have received a copy of the GNU General Public License along
    with groff; see the file COPYING.  If not, write to the Free Software
    Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

instant:

    Copyright (c) 1994
    Open Software Foundation, Inc.

    Permission is hereby granted to use, copy, modify and freely distribute
    the software in this file and its documentation for any purpose without
    fee, provided that the above copyright notice appears in all copies and
    that both the copyright notice and this permission notice appear in
    supporting documentation.  Further, provided that the name of Open
    Software Foundation, Inc. ("OSF") not be used in advertising or
    publicity pertaining to distribution of the software without prior
    written permission from OSF.  OSF makes no representations about the
    suitability of this software for any purpose.  It is provided "as is"
    without express or implied warranty.


All modifications are covered by the following license:

    Copyright (C) 1998 The XFree86 Project, Inc.  All Rights Reserved.

    Permission is hereby granted, free of charge, to any person obtaining
    a copy of this software and associated documentation files (the
    "Software"), to deal in the Software without restriction, including
    without limitation the rights to use, copy, modify, merge, publish,
    distribute, sublicense, and/or sell copies of the Software, and to
    permit persons to whom the Software is furnished to do so, subject
    to the following conditions:

    The above copyright notice and this permission notice shall be
    included in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    IN NO EVENT SHALL THE XFREE86 PROJECT BE LIABLE FOR ANY CLAIM,
    DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
    OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
    OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

    Except as contained in this notice, the name of the XFree86 Project
    shall not be used in advertising or otherwise to promote the sale,
    use or other dealings in this Software without prior written
    authorization from the XFree86 Project.




$XFree86: doctools/README,v 1.12 2001/12/19 22:56:46 dawes Exp $