\input texinfo @c -*-texinfo-*-
@c $Id: readme.texi,v 1.6 2002/03/11 14:07:22 wsnyder Exp $
@c %**start of header
@setfilename readme.info
@settitle Perl SystemC::Vregs Installation
@c %**end of header

@c DESCRIPTION: TexInfo: DOCUMENT source run through texinfo to produce README file
@c Use 'make README' to produce the output file

@node Top, Copyright, (dir), (dir)

This is the SystemC Vregs Package, aka Vregs.

@menu
* Copyright::                   
* Summary::                     
* Description::                 
* SystemPerl Example::          
* Obtaining Distribution::      
* Supported Systems::           
* Installation::                
@end menu

@node Copyright, Summary, Top, Top
@section Copyright

This package is Copyright 2001 by Wilson Snyder @email{wsnyder@@wsnyder.org}.

You may distribute under the terms of either the GNU General Public License
or the Artistic License, as specified in the Perl README file, with the
exception that it cannot be placed on a CD-ROM or similar media for commercial
distribution without the prior approval of the author.

This code is provided with no warranty of any kind, and is used entirely at
your own risk.

@node Summary, Description, Copyright, Top
@section Summary

The publicly licensed Vregs package provides a means for extracting
registers, classes, enumerations, and defines from documentation.  Vregs
then extracts header files for C++, Verilog, and Perl.

Being very object oriented, the program can easily be extended to
support additional output languages and output files.  You can download
Vregs from the link off of http://www.veripool.com/vregs.html

Vregs does not require SystemC or C++ to be useful, though some of the
generated header files are only useful in object oriented languages like
C++.

@node Description, SystemPerl Example, Summary, Top
@section Description

Vregs converts documentation to C++, Verilog, and perl headers.

First, you write your specification using the example documentation in
Microsoft Word format in vregs_spec.doc, or using any editor that can
produce HTML code.  Vregs only cares about the general table layout, not
style and font issues; almost any program will do, both Microsoft Word
and Adobe Framemaker have been used in the past.

When the document is ready for conversion, save the document as HTML. 
Microsoft Word annoyingly opens the HTML after saving; be sure to exit
the HTML version immediately.

You then run Vregs, which reads the HTML code and writes out a .vspec
file, which contains a summary of the extracted information.  This file
can be examined for errors, or edited standalone.  Vregs also produces
header fields with #defines for all of the constants and magic numbers in
the spec.  

Vregs can be customized to change the code it creates using templates;
see 'man vregs' for details.

@node Obtaining Distribution, Supported Systems, SystemPerl Example, Top
@section Obtaining Distribution

The latest version is available at 
@uref{http://www.perl.org/CPAN/}

Download the latest package from that site, and decompress.
@samp{gunzip SystemC-Vregs_version.tar.gz ; tar xvf SystemC-Vregs_version.tar}

You will also need to have installed Bit::Vector, HTML::TableExtract,
and Verilog::Language from CPAN.  If you wish, simply try and install
Vregs and it will tell you what prerequisites are missing.

@node Supported Systems, Installation, Obtaining Distribution, Top
@section Supported Systems

This version of Vregs has been built and tested on:

@itemize @bullet
@item i386-linux
@end itemize

It should run on any system with Perl.

@node Installation,  , Supported Systems, Top
@section Installation

@enumerate
@item
@code{cd} to the directory containing this README notice.

@item
Type @samp{perl Makefile.PL} to configure Vregs for your system.

@item
Type @samp{make} to compile.

@item
Type @samp{make test} to check the compilation.  Note that
vregs_spec.doc with this distribution is converted into the files in the
test_dir directory.

@item
Type @samp{make install} to install the programs and any data files and
documentation.

@item
Install @samp{vregs-mode.el} in your Emacs site-lisp directory.

@item
Add the @samp{include} directory to your project's build path, if you
wish to use the register information classes produced by Vregs.

@item
Examine the example document under vregs_spec.doc and vregs_spec.html.

@end enumerate


