\input texinfo

@comment %**start of header
@settitle FullSWOF-utils Reference Manual
@syncodeindex pg cp
@comment %**end of header

@copying
This document describes FullSWOF-utils, a set of utility scripts to be
used with the FullSWOF shallow flow solver.

Copyright @copyright{} 2019 Paul Garlick.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying



@titlepage
@title FullSWOF-utils Reference Manual
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top FullSWOF-utils

Utility scripts for the FullSWOF shallow flow solver
@end ifnottex


@menu
* Installation::                Installing FullSWOF-utils.
* Usage::
* GNU Free Documentation License::  The license of this manual.
* Index::                       Complete Index.
@end menu

@node Installation, Usage, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Installation

@cindex chapter, installation

The @emph{fullSWOF-utils} package comprises a single top-level directory
and several sub-directories.  The package may be installed in the same
location as @emph{FullSWOF} itself or any other convenient location.

@menu
* Requirements::
* Cloning::
* Uninstalling::
@end menu

@node Requirements, Cloning, Installation, Installation
@comment  node-name,  next,  previous,  up
@section Requirements

To install @emph{fullSWOF-utils} the following packages are required:

@itemize
@item
@url{https://git-scm.com/, Git}, the version control system.

@item
@url{https://www.gnu.org/software/texinfo/, Texinfo}, the GNU
documentation system.
@end itemize


@node Cloning, Uninstalling, Requirements, Installation
@comment  node-name,  next,  previous,  up
@section Cloning

FullSWOF-utils is maintained using git, the version control system.  A
simple way to install the package is to clone the git repository.  To do so,
first open a terminal window on a system that has git installed.  Then,
from within a suitable working directory, execute the command:

@example
git clone http://cgit.tourbillion-technology.com/fullSWOF-utils
@end example

A directory named @emph{fullSWOF-utils} will be created.  To complete
the installation first change directory to the new @emph{fullSWOF-utils}
directory.  Then execute the command:

@example
make
@end example

This command will create the documentation for the package.  The
documentation is available in two formats; GNU Info format and html.
The info file is located in the doc directory.  The html files are
located in the manual directory.  There are two versions.
@emph{fullswof-utils.html} contains the complete documentation set out
on one page.  The subdirectory @emph{html_node} contains a top-level
@emph{index.html} file and a separate page for each node.

The info file may be read using the @command{info} program.  The html
files may be read using any web browser.

@node Uninstalling,  , Cloning, Installation
@comment  node-name,  next,  previous,  up
@section Uninstalling

All the files in the @emph{fullSWOF-utils} package are installed under a
single directory.  To uninstall the package it is sufficient to remove
that directory.  For example, to remove a clone of the repository, first
navigate to the directory on the system where the clone is located.
Then execute the command:

@example
rm -rf fullSWOF-utils
@end example

@node Usage, GNU Free Documentation License, Installation, Top
@comment  node-name,  next,  previous,  up
@chapter Usage

The programs provided in the @emph{fullSWOF-utils} package are written
in the @emph{python} programming language.  Python version 3.0 or above
is recommended.  @xref{Runtime Dependencies} for the python packages
that are required by each program.

To run an individual program it is convenient to create a symbolic link
to the corresponding file in the installation directory.  For example,
from a suitable working directory, execute the following command to
create a link to the @emph{makeBoundary} program:

@example
ln -s /path/to/installation/directory/python/makeBoundary
@end example

@menu
* Runtime Dependencies::
@end menu

@node Runtime Dependencies,  , Usage, Usage
@comment  node-name,  next,  previous,  up
@section Runtime Dependencies


@node GNU Free Documentation License, Index, Usage, Top
@appendix GNU Free Documentation License
@include fdl-1.3.texi

@node Index,  , GNU Free Documentation License, Top
@unnumbered Index
@printindex cp

@bye

Local Variables:
mode: texinfo
TeX-master: t
End: