usr/src/cmd/troff/troff.d/README

   1 #
   2 # CDDL HEADER START
   3 #
   4 # The contents of this file are subject to the terms of the
   5 # Common Development and Distribution License, Version 1.0 only
   6 # (the "License").  You may not use this file except in compliance
   7 # with the License.
   8 #
   9 # You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  10 # or http://www.opensolaris.org/os/licensing.
  11 # See the License for the specific language governing permissions
  12 # and limitations under the License.
  13 #
  14 # When distributing Covered Code, include this CDDL HEADER in each
  15 # file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  16 # If applicable, add the following below this CDDL HEADER, with the
  17 # fields enclosed by brackets "[]" replaced with your own identifying
  18 # information: Portions Copyright [yyyy] [name of copyright owner]
  19 #
  20 # CDDL HEADER END
  21 #
  22 #
  23 # Copyright 1989 Sun Microsystems, Inc.  All rights reserved.
  24 # Use is subject to license terms.
  25 #
  26
  27 #ident  "%Z%%M% %I%     %E% SMI"
  28
  29 #
  30 # University Copyright- Copyright (c) 1982, 1986, 1988
  31 # The Regents of the University of California
  32 # All Rights Reserved
  33 #
  34 # University Acknowledgment- Portions of this document are derived from
  35 # software developed by the University of California, Berkeley, and its
  36 # contributors.
  37 #
  38
  39 The troff in this directory
  40 is a troff that produces machine-independent output.
  41 It requires a file of descriptive information about
  42 the particular typesetter you have in mind, and produces
  43 output parameterized for that device.
  44
  45 Thus:
  46         troff -Taps ...
  47 produces output for the Autologic APS-5.
  48 (This is the default.)
  49
  50 To make this work, you need two things.
  51 First, you need to create a set of
  52 device and font descriptions in the directory
  53         /usr/doctools/font/devxxx
  54 where "xxx" is your device name.
  55 Currently supported device is
  56         aps     Autologic APS-5 phototypesetter
  57 Source for this device is found in the subdirectory
  58 devaps of this directory.
  59
  60 The file "DESC" contains information about the
  61 device itself and the character set.  (See devaps/DESC.)
  62
  63 In addition, each font needs a file describing its
  64 characters, width and device-driving codes;
  65 see R and S for typical examples.
  66
  67 The program "makedev" will convert these text
  68 descriptions into a binary form that the troff can
  69 slurp up in a single gulp during initialization;
  70 these wind up in DESC.out (which includes
  71 default font info) and XX.out for info about font XX.
  72
  73 The second half of the job is to write a post-processor
  74 that converts the more or less machine-independent troff
  75 output into specific codes for your favorite typesetter.
  76 daps.c is the driver for the APS-5;
  77 it will serve as a useful prototype.  In particular,
  78 it contains a precise description of the output language.
  79         ta      prints ascii on ordinary terminals (crudely)
  80
  81 One can always simply run
  82         troff
  83 and look at the output; it is guaranteed to be ascii text
  84 and thus safe to edit, grep, etc.
  85 (Since it is ascii, it is also guaranteed to be quite voluminous.)
  86
  87 The recommended way to create the necessary files to make troff
  88 able to communicate with a new output device
  89 is to pick the most similar device for which this software
  90 already exists, and modify it to suit the new device.
  91
  92 This release contains prototype software for one
  93 type of device -- a phototypesetter (devaps)
  94 The devaps subtree contains
  95 profusely-commented programs and strategically placed README
  96 files to help guide the experienced user in making
  97 modifications to these files.
  98
  99 Two other source of information for users who wish to delve
 100 deeply into this software are the manual pages
 101 troff(5), which describes the output language produced by troff,
 102 and font(5), which describes the format of the device
 103 and font description files.
 104
 105 -----------------------------------------------------------------------------
 106
 107 Changes since the original release:
 108
 109 January, 1985:
 110
 111 Added optional 3rd argument to .fp command:
 112         .fp 3 xx longishname
 113 causes font to be called xx but data is loaded
 114 from longishname.out instead of xx.out.
 115 The intent is to deal with the proliferation of fonts.
 116
 117 Turned NBLIST up to 2048 so can handle really big
 118 diversions.  Tends to blow various systems.
 119
 120 December 1984:
 121
 122 Nroff modified to read ascii tables for various devices
 123 instead of the compiled C code nonsense.  Only a few
 124 tables converted;  details of language still subject to
 125 change.
 126
 127 September 1984:
 128
 129 Added Molly Wagner's code to prevent side effects
 130 during scanning of false branch of an if.
 131
 132 Added test warning when one removes a macro during
 133 its execution (more precisely, warning when a macro
 134 evaluation has encountered a freed block).
 135 [Disabled Nov 84;  it seemed to cause troubles]
 136
 137 NS = 128;  devname[] is bigger;  turned off the -t
 138 argument (it could be a synonym for -T but that's
 139 probably just as risky.)
 140
 141 July, 1984:
 142
 143 Added TYPESETTER environment variable
 144
 145 Added \X'...' command:  ... comes out as
 146         x X ...\n in proper place. (doesn't nest)
 147
 148 In \D comands, unrecognized command letters are passed through
 149 untouched.  This makes it possible to define things like other
 150 splines, filled polygons, etc.
 151
 152 \s(dd, \s(+dd, \s(-dd size commands.
 153
 154 Added .lf line filename to set current line number & filename
 155
 156 Added Dan Berry's fixes to handle horizontal resolution properly.
 157
 158 New, March 1984:
 159
 160 Dennis Ritchie's hashed macro and number register tables;
 161 cached width computations, general cleanup.
 162 Minor work on de-linting.
 163
 164 New comments 9/16/83
 165
 166 This version is the current evolution of 8th Edition troff.
 167 The only changes of substance since the export version are
 168
 169         the end of a sentence is more general; things like
 170         ." .!'' etc are recognized and padded
 171
 172         the "font too big for position n" error can no longer arise.
 173         makedev has a new parameter called biggestfont that
 174         ensures that all font positions are at least that big.
 175         this eliminates the "font X too big for position Y" message
 176
 177         some minor bugs fixes have been made:
 178                 doesn't look for ligatures in \nf
 179                 doesn't put out WORDSP in -a
 180
 181         troff no longer produces \^ and \| on output,
 182         but this hasn't been tested much since it takes
 183         character set changes too.
 184