demo/neatstart.ms

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