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