README

   1            SGMLS.PM: A PERL5 CLASS LIBRARY FOR USE WITH THE
   2                        SGMLS AND NSGMLS PARSERS
   3
   4                              Version 1.03ii
   5
   6
   7                            David Megginson,
   8                          University of Ottawa
   9
  10
  11 [This is the fourth public release.  See "CHANGES", below, for a
  12 summary of the most important changes since version 1.02.  For
  13 detailed changes, see ChangeLog and DOC/ChangeLog; for known bugs, see
  14 BUGS.]
  15
  16
  17 This distribution contains SGMLS.pm, a perl5 class library for parsing
  18 the output from James Clark's SGMLS and NSGMLS parsers.  This is a
  19 free package, but it is _not_ Public-Domain software -- please see the
  20 file COPYING in this directory for the terms of use.
  21
  22 Full documentation is available in SGML format the DOC directory, and
  23 in Postscript, LaTeX, and HTML format in the various subdirectories of
  24 the DOC directory.  Documentation in POD format is also included
  25 within each of the modules, and once they are installed, you can view
  26 them with perldoc (SGMLS, SGMLS::Ouptut, or SGMLS::Refs) -- there is
  27 no POD documentation in sgmlspl yet.
  28
  29 Take a look in the elisp/ subdirectory for a special package for Gnu
  30 Emacs -- it will allow you to run (n)sgmls and sgmlspl from within an
  31 Emacs buffer containing an SGML file, displaying the output (LaTeX,
  32 for example) in another Emacs buffer.
  33
  34 I have included a Unix Makefile for installing the package on Unix and
  35 Unix-like systems.  Make any necessary changes at the top of the
  36 Makefile, then type
  37
  38   make install
  39
  40 to install the perl5 scripts on your system.  If you want to test the
  41 installation, change to the DOC subdirectory, read the comments at the
  42 top of the make file there, then type
  43
  44   make clean; make all
  45
  46 to regenerate the LaTeX and HTML documentation using the scripts which
  47 you have just installed (you will have to have the SGMLS or NSGMLS
  48 parser, the Docbook 2.2.1 DTD and SGML declaration, and the ISOpub and
  49 ISOnum entity sets available on your system -- copies are included in
  50 the DOC/Extras subdirectory).  You may also type
  51
  52   make dvi
  53
  54 or
  55
  56   make ps
  57
  58 to produce DVI or Postscript versions of the documentation for
  59 printing.
  60
  61
  62 ** nb: Effective with v.1.02, SGMLS.pm supports the new output from
  63 NSGMLS 0.4.13 with the -h option.
  64
  65
  66 CHANGES
  67
  68 There have been some major changes since version 1.02.  File handles
  69 passed as arguments to SGMLS::new should be qualified in the correct
  70 package now.  The Output.pm module has been moved, so you should now
  71 type
  72
  73   use SGMLS::Output;
  74
  75 instead of
  76
  77   use Output;
  78
  79 in all of your scripts.  There is also a new package, SGMLS::Refs, to
  80 maintain a database of forward references from one processing pass to
  81 another, like the LaTeX .aux files.  Once you have installed SGMLS.pm,
  82 you can type
  83
  84   perldoc SGMLS::Refs
  85
  86 at the shell prompt for more information, or you can read the new
  87 section in the SGML documentation for sgmlspl.  All of the
  88 documentation for this package is available online through my home
  89 page, listed below.
  90
  91 As mentioned above, there is also a convenient package for Gnu Emacs
  92 19 in the elisp/ directory.
  93
  94
  95 Enjoy!
  96
  97 David Megginson
  98
  99
 100 EMAIL: dmeggins@aix1.uottawa.ca
 101 WWW: http://www.uottawa.ca/~dmeggins
 102 Canada Post: Department of English,
 103              University of Ottawa,
 104              Ottawa, CANADA
 105