demo/neatstart.ms

   1 .\" PSTITLE: Getting Started with Neatroff
   2 .so neat__.ms
   3 .ps.info "Getting Started with Neatroff" "Ali Gholami Rudi"
   4 .de MH
   5 .       sp
   6 .       LP
   7 .       ne 1.5
   8 \m[#237]\fI\\$1\fP\m[]
   9 .       IP
  10 ..
  11 .ds en.cl "#39a
  12 .HD
  13 .TL
  14 \f(HD\s+8Getting Started with Neatroff\m0\s-8\fP
  15 .AU
  16 \fIA. G. Rudi\fP
  17 .sp 3
  18 The present document explains the steps necessary for setting up and
  19 using Neatroff.  It uses neatroff_make Git repository, which contains
  20 a set of standard macro packages and a top-level makefile to obtain
  21 and build Neatroff and its helper programs, which are referred to as
  22 Neat* throughout this document.  More details about Neatroff and the
  23 programs that accompany it are available in its homepage at
  24 \*[ps.url http://litcave.rudi.ir/].
  25
  26 .SH "Using Neatroff Without Installation"
  27 To use Neatroff without installing it, neatroff_make can be retrieved
  28 as follows:
  29
  30 .cc.beg
  31 $ git clone git://repo.or.cz/neatroff_make.git
  32 .cc.end
  33
  34 .LP
  35 This branch assumes that the resulting directory will not be removed
  36 and shall contain Neatroff fonts, macros, and binaries when using
  37 Neatroff.  The \(lqinit\(rq make target, clones the necessary Git
  38 repositories and obtains Ghostscript fonts.  The \(lqneat\(rq target
  39 compiles the programs and generates Neatroff font descriptions.
  40 Finally, the demo/ subdirectory contains small examples and a Makefile
  41 to demonstrate how to use Neatroff.
  42
  43 .cc.beg
  44 $ make init
  45 $ make neat
  46 $ cd demo && make
  47 .cc.end
  48
  49 .LP
  50 To add new fonts, simply place them in the fonts/ subdirectory and
  51 re-make the \(lqneat\(rq target.  To use the new font in Neatroff, the
  52 file name without its extension may be mounted.  For instance, if the
  53 name of the font is NewFont.ttf, the following Troff code mounts and
  54 uses this font.
  55
  56 .cc.beg
  57 \&.fp - F1 NewFont
  58 \&.ft F1
  59 Text in NewFont
  60 .cc.end
  61
  62 .SH "Installing Neatroff"
  63 This section describes how to install Neatroff in system directories.
  64 The following commands fetch neatroff_make and
  65 obtain the latest versions of Neat*:
  66
  67 .cc.beg
  68 $ git clone -b install git://repo.or.cz/neatroff_make.git
  69 $ cd neatroff_make/
  70 $ make pull
  71 .cc.end
  72
  73 .LP
  74 This obtains Neatroff, Neatpost, Neateqn, Neatrefer, and a port of
  75 Plan 9 troff to use its pic and tbl preprocessors (sadly there is no
  76 Neatpic and Neattbl!).
  77
  78 To build Neat*, neatroff_make/makefile should be modified to set the
  79 values of \s-1GSFONTS\s+1 and \s-1PREFIX\s+1 macros.  \s-1GSFONTS\s+1
  80 should point to the directory containing the standard Ghostscript
  81 fonts (ghostscript-fonts package, containing files such as
  82 n021003l.afm).  In most environments these files are installed in
  83 /usr/\:share/\:ghostscript/\:fonts or
  84 /usr/\:share/\:fonts/\:type1/\:gsfonts; you can manually obtain the
  85 ghostscript-fonts package and extract it to a temporary directory, if
  86 they are missing.  Also \s-1PREFIX\s+1 specifies the installation
  87 prefix.  The following commands build and install Neat*.
  88
  89 .cc.beg
  90 $ make
  91 $ make install
  92 .cc.end
  93
  94 .LP
  95 Note that the second command may need to be executed by a superuser
  96 depending on the directory specified as \s-1PREFIX\s+1.
  97
  98 At this point Neat* should be installed.  If Neatroff is set up
  99 properly, the following command should create test.pdf from the input
 100 troff source test.tr (you need to add other preprocessors if you use
 101 them).
 102
 103 .cc.beg
 104 $ echo "Hello Neatroff!" >test.tr
 105 $ cat test.tr | neatroff | neatpost | ps2pdf - test.pdf
 106 .cc.end
 107
 108 .LP
 109 \fBAdding Fonts\fP:
 110 A remarkable design decision in troff was the separation of
 111 output devices, for instance for Postscript, from the troff
 112 typesetting program.  This separation requires generating
 113 device-independent font descriptions, listing available glyphs for
 114 each font and their metrics.
 115 Neatroff's font descriptions can be generated with the Neatmkfn
 116 program as follows:
 117 .LP
 118 .cc.beg
 119 $ neatmkfn -b -a <fontpath.afm \\
 120 \&      >PREFIX/share/neatroff/font/devutf/fontname
 121 $ neatmkfn -b -o <fontpath.ttf \\
 122 \&      >PREFIX/share/neatroff/font/devutf/fontname
 123 .cc.end
 124
 125 .LP
 126 After generating font description, the new font can be mounted in
 127 troff just as other fonts with \&.fp request:
 128
 129 .cc.beg
 130 \&.fp 12 F2 fontname
 131 .cc.end
 132
 133 .LP
 134 Alternatively, you can place your fonts in the directory specified as
 135 \s-1GSFONTS\s+1 when building neatroff_make; the makefile generates
 136 and installs font descriptions for all fonts in that directory
 137 automatically.  This is specially convenient when the number of fonts
 138 is large.
 139
 140 There is another method of using fonts in Neatroff that creates
 141 the font descriptions on the fly.  Despite its overhead, this
 142 method may be convenient when testing new fonts.  It uses the
 143 fp macro package, which is included in neatroff_make.
 144 Assuming that the new fonts are in /path/to/fonts, the following
 145 command informs the macros defined in this package and Ghostscript
 146 about the location of the fonts (note that -mfp is passed to
 147 Neatroff to read this package).
 148
 149 .cc.beg
 150 $ cat test.tr | neatroff -dfp.src=/path/to/fonts -mfp | \\
 151 \&      neatpost | ps2pdf -sFONTPATH=/path/to/fonts - test.pdf
 152 .cc.end
 153
 154 .LP
 155 The package defines \&.fp.ttf, \&.fp.otf, and \&.fp.afm macros, whose
 156 behaviour is quite similar to the standard \&.fp request, except that
 157 the third argument should be the name of the font file without its
 158 extension.  Thus, for mounting /path/\:to/\:fonts/\:NewFont.ttf,
 159 test.tr can contain:
 160
 161 .cc.beg
 162 \&.fp.ttf - F3 NewFont
 163 \&.ft FN
 164 Testing the new font...
 165 .cc.end
 166
 167 .SH "More Information"
 168
 169 .MH "Neatroff Introduction
 170 Explains the differences between Neatroff and other
 171 troff implementations.  Available at http:/\h'-.3n'/litcave.rudi.ir/neatroff.pdf.
 172
 173 .MH "Typesetting Mathematics with Neateqn"
 174 Introduces the Neateqn preprocessor for typesetting mathematical equations.
 175 Available at http:/\h'-.3n'/litcave.rudi.ir/neateqn.pdf.
 176
 177 .MH "Neatroff Introduction in Farsi
 178 Explains specifying text direction in right-to-left languages and
 179 Keshideh adjustment in Farsi.
 180 Available at http:/\h'-.3n'/litcave.rudi.ir/neatfarsi.pdf.