demo/neatstart.ms

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