
README

Version of March 30, 1993 - David Loveman, Digital Equipment Corporation

This README file describes characteristics of the High Performance 
Fortran Report Document.  Specifically it covers:

- the structure of the directory "hpf-report",

- how to add a chapter to the report, 

- the LaTeX labels used in the document, 

- how to distribute the report, and

- documentation on the syntax macro package.



DIRECTORY STRUCTURE

Following is a list of the files in the directory hpf-report, and 
their purposes:

  README - this file
  PRINT-SOURCE-TXT - a script that prints all these files (and 
     doesn't print working files created by LaTeX, backup files, etc.)
  CLEANUP - a script that deletes working files created by LaTeX, 
     backup files, etc., and leaves just the appropriate source files  
  MAKE-HPF-REPORT - a script that runs LaTeX three times to get the 
     table of contents and page numbers correct (the first run may 
     generate LaTeX Warnings that references are undefined - these 
     go away in the second run), then runs dvips to produce a 
     postscript file from the dvi file, xdvi to run an X-windows 
     postscript previewer, and finally prints the postscript file
  MAKE-HPF-JOD - a script like MAKE-HPF-REPORT that generates the 
     Journal of Development
  hpf-report.tex - the LaTeX file that provides the structure for the 
     Language Specification document.  It includes all of the other 
     necessary .tex files
  MAKE-HPF-CHAPTER - a script similar to MAKE-HPF-REPORT. It takes 
     one argument, the filename of the chapter to be produced.  It 
     uses the file chapter-head.tex and a set of 
     temporary files named temp.*
  chapter-head.tex - a file which when followed by 
     a single chapter followed by "\end{document}" is a freestanding 
     LaTeX file that can produce a printout of a single chapter
  syntax-macs.tex - macros for code examples and BNF syntax, created 
     by Guy Steele of Thinking Machines
  credits.tex - the acknowledgements chapter
  overview.tex - the overview chapter
  terms.tex - the terms and concepts chapter
  distribution.tex - the distribution chapter
  statements.tex - the statements chapter
  intrinsics.tex - the intrinsics chapter
  foreign.tex - the chapter on foreign procedures
  sequence.tex - the sequence and storage association chapter
  hpf-subset.tex - the subset chapter
  appendixes.tex - the text of the Journal of Development
  bibliography.tex - the bibliography
  Elemental - a subdirectory of intrinsic procdeure definitions
  Grade - a subdirectory of intrinsic procdeure definitions
  Inquiry - a subdirectory of intrinsic procdeure definitions
  Mapping - a subdirectory of intrinsic procdeure definitions
  Minloc - a subdirectory of intrinsic procdeure definitions
  Prefix - a subdirectory of intrinsic procdeure definitions
  Reduction  - a subdirectory of intrinsic procdeure definitions
  Scatter - a subdirectory of intrinsic procdeure definitions
  bnf.tex - a list of HPF BNF rules generated by glombnf.c
  glombnf.c - the C program that searches the HPF document and generated 
     the list of all of the BNF rules
  hpf-jod.tex - the LaTeX file that provides the structure for the 
     Journal of Development document.  It includes all of the other 
     necessary .tex files
  jod-overview.tex - the overview chapter for the Journal of Development


ADDING A CHAPTER

To add a chapter, create a tex file named foo.tex, where "foo" is 
descriptive of the chapter's contents.  The first few lines of 
the file should look similar to:

  %foo.tex

  %Version of July 14, 1992

  \chapter{Chapter Title\protect\footnote{version of July 14, 1992}}
  \label{foo}

At the appropriate place in the file hpf-document.tex put the line

  \include{foo}


At the appropriate place in the file PRINT_SOURCE_TXT put the 
line 

  cat foo.tex | fmt | lpr -Oportrait -i5

At the apropriate place in the file README (this file) put a brief 
description of the chapter.


LATEX LABELS USED

Following are some of the LaTeX label usages in the various files:

in file appendixes.tex

%\chapter{Examples}
%\label{examples}

\chapter{Journal of Development}
\label{journal}

\section{Nested WHERE statements}
\label{nested-where}

\section{ALLOCATE in FORALL}
\label{forall-allocate}

\section{Generalized Data References}
\label{data-ref}

\section{FORALL with INDEPENDENT Directives}
\label{begin-independent}

\section{EXECUTE-ON-HOME and LOCAL-ACCESS Directives}
\label{on-clause}

\section{Elemental Reference of Pure Procedures}
\label{elem-ref-of-pure-procs}

\section{Parallel I/O}
\label{parallel-io-jod}


in file distribution.tex

\chapter{Data Alignment and Distribution Directives}
\label{distribution}

\section{Allocatable Arrays and Pointers}
\label{ALLOCATABLE-SECTION}


in file foreign.tex

\chapter{Extrinsic Procedures}
\label{foreign}

\subsection{Definition and Invokation of extrinsic procedures}
\label{def-and-call}

\subsection{Information Available to the Local Procedure}
\label{local-info-section}

\subsection{Fortran 90 Local Routine Intrinsics}
\label{f90-intrinsics}

in file hpf-subset.tex

\chapter{Subset High Performance Fortran}
\label{subset}


in file intrinsics.tex

\chapter{Intrinsic Functions}
\label{intrinsics}

\subsection{Parallel Prefix Instrinsics}
\label{parallel-prefix}


in file io.tex

\chapter{Input/Output}
\label{io}


in file overview.tex

\chapter{Overview}
\label{overview}

\section{Goals and Scope of High Performance Fortran}
\label{overview-goals}

\section{Fortran 90 Binding}
\label{overview-f90}

\section{New Features in High Performance Fortran}
\label{overview-new}

\section{Fortran 90 and HPF Subset}
\label{overview-subset}

\section{Notation}
\label{overview-notation}


in file sequence.tex

\chapter{Sequence and Storage Association}
\label{sequence}

\subsection{Definitions}
\label{sequence-defs}

\item \label{seq-var} Variables are either {\it sequential} or {\it
nonsequential}.


in file statements.tex

\chapter{Statements}
\label{statements}

\section{Element Array Assignment - FORALL}
\label{forall-stmt}

\subsection{Interpretation of Element Array Assignments}
\label{forall-interp}  

\section{FORALL Construct}
\label{forall-construct}

\section{Pure Procedures}
\label{forall-pure}

\subsubsection{Pure procedure interfaces}
\label{pure-proc-interface}

\section{The INDEPENDENT Directive}
\label{do-independent}

\caption{Dependences in DO and FORALL without
INDEPENDENT assertions}
\label{fig-dep}
\end{figure}

\caption{Dependences in DO and FORALL with
INDEPENDENT assertions}
\label{fig-indep}
\end{figure}


in file terms

\chapter{High Performance Fortran Terms and Concepts}
\label{terms}

\subsection{Simple Communication Examples}
\label{simple-comm}

\subsection{Aggregate Communication Examples}
\label{agg-comm}


REPORT DISTRIBUTION

The report is distributed electronically by mail as a uuencoded, 
compressesd tar file.  When you are in the directory that contains the 
directory "hpf-report", the command 

  tar cvf hpf-dist.tar hpf-report

will create a tar file named "hpf-dist.tar" from the directory 
"hpf-report".

The command:

  compress hpf-dist.tar

will create a compressed file named "hpf-dist.tar.Z" ready for 
distribution.

The command:

  uuencode hpf-dist.mail < hpf-dist.tar.Z > hpf-dist.mail

will create an ASCII file named "hpf-dist.mail", consisting of 
printing characters only, ready to be mailed.  

An HPF report delivery is a mail message containing a uuencoded, 
compressed tar file.  Copy this mail message to an arbitrarily named 
file "hpf.mail" in an arbitrarily named directory "hpf-stuff".  From 
within the directory "hpf-stuff", execute the following command 
sequence:

  uudecode  < hpf.mail
  mv hpf-dist.mail hpf-dist.tar.Z

  uncompress hpf-dist.tar.Z
  tar xvf hpf-dist.tar

The directory "hpf-stuff" will now have a sub-directory "hpf-report" 
containing all the files necessary to construct the HPFF report.  
Begin by reading the file README.  The files "hpf.mail" and 
"hpf-dist.tar" are no longer needed and may be deleted.

Have fun!


LaTeX MACRO PACKAGE DOCUMENTATION

[1] I have \chapter generating the word "Section" or "Annex"
as appropriate.  Of course, we will have to go through and
correct occurrences of "Chapter" and "Appendix" in the text.


[2] The BNF rules now number themselves automatically.  No change
in the text files is required.  BNF rules automatically generate
labels for themselves of the form "lhs-rule".  For example,
									\BNF
combined-directive         \IS  combined-attribute-list :: hpf-entity-decl-list
									\FNB
defined a LaTeX label "combined-directive-rule" such that
\ref{combined-directive-rule} produces "H301".  In this way
you can refer to any BNF rule from the text.

To make this work properly, it is important that distinct
BNF rules be separated by empty lines.  Thus the source text from
chapter 4
                                                                \BNF
forall-stmt          \IS FORALL forall-header forall-assignment
forall-header        \IS ( forall-triplet-spec-list [ , scalar-mask-expr ] )
forall-triplet-spec  \IS index-name = subscript : subscript  [ : stride ]
forall-assignment    \IS assignment-stmt
                     \OR pointer-assignment-stmt
                                                                \FNB
needs to be changed to
                                                                \BNF
forall-stmt          \IS FORALL forall-header forall-assignment

forall-header        \IS ( forall-triplet-spec-list [ , scalar-mask-expr ] )

forall-triplet-spec  \IS index-name = subscript : subscript  [ : stride ]

forall-assignment    \IS assignment-stmt
                     \OR pointer-assignment-stmt
                                                                \FNB


[3] The line-numbering ruler in the margins now works.  It always sticks
tiny numbers from 1 to 48 in the gutter margin (edge of page nearest
the binding---I thought they would be least obtrusive there).

The usage is to add \withlinenumbers after any \pagestyle command.
Thus:

	\pagestyle{headings}  \withlinenumbers

So you don't have to have line numbers in the table of contents, etc.


[4] There are three new environments: rationale, implementors, and users.

\begin{implementors}
You don't really want to support views.
\end{implementors}

produces something like

	{\it Advice to implementors.}  You don't really want to
	support views.  ({\it End of advice to implementors.})


[5] I have written a little utility in C, called "glombnf".  It
behaves a bit like "cat", but passes through only what is needed for
an annex of collected syntax.  It collects chapter and section
headings, turning them into section and subsection headings in the
style of annex D of the Fortran 90 document.  There is also a switch
that allows one to collect just BNF, without the constraints.
See the comments at the head of file glombnf.c .

To produce the annex for HPF, I executed the command

glombnf overview.tex terms.tex distribution.tex statements.tex intrinsics.tex foreign.tex io.tex sequence.tex hpf-subset.tex > bnf.tex

It was then merely necessary to insert into file  hpf-report.tex  the lines

\cleardoublepage
\include{bnf}

in the appropriate place as if it were any other chapter.


[6] The new version of  syntax-macs.tex  contains the new BNF macros,
environme4nts, etc., as well as revised macros for formatting the
descriptions of intrinsics in the manner of Fortran 90 section 13.

=================================================================

I added BNF cross-reference capability to the BNF glommer.

To get the cross-reference, you must provide the -crossref
switch to glombnf.  I used the command

glombnf -crossref overview.tex terms.tex distribution.tex statements.tex intrinsics.tex foreign.tex io.tex sequence.tex hpf-subset.tex > bnf.tex

to process the entire HPF report.  The result is that the file
bnf.tex  contains *two* annexes.  (I decided to use two separate
annexes rather than nesting the subsection structure as deeply
as in annex D of the Fortran 90 standard.)

In one of the files, I inserted the following block of commands:

\Fortranrule{R710}{add-op}
\Fortranrule{R431}{array-constructor}
\Fortranrule{R512}{array-spec}
\Fortranrule{R735}{assignment-stmt}
\Fortranrule{R1218}{end-function-stmt}
\Fortranrule{R1222}{end-subroutine-stmt}
\Fortranrule{R504}{entity-decl}
\Fortranrule{R208}{execution-part}
\Fortranrule{R513}{explicit-shape-spec}
\Fortranrule{R1216}{function-stmt}
\Fortranrule{R728}{int-expr}
\Fortranrule{R607}{int-variable}
\Fortranrule{R210}{internal-subprogram-part}
\Fortranrule{R741}{mask-expr}
\Fortranrule{R736}{pointer-assignment-stmt}
\Fortranrule{R204}{specification-part}
\Fortranrule{R620}{stride}
\Fortranrule{R1220}{subroutine-stmt}
\Fortranrule{R617}{subscript}
\Fortranrule{R619}{subscript-triplet}
\Fortranrule{R739}{where-construct}
\Fortranrule{R738}{where-stmt}

This tells the cross-referencing mechanism that certain nonterminals
are defined by the Fortran 90 standard rather than by HPF.

I also added the ability to insert prefatory material before
the collected syntax rules and before the cross-reference.
For example, the following can appear in  hpf-report.tex  just
before the \include{bnf}:

\def\crossrefpreface{\label{crossref-annex}
In the following cross references, all occurrences of {\it scalar-xyz}
and {\it xyz-list} are treated as occurrences of {\it xyz}.
Rule labels beginning with ``H'' refer to syntax rules in this
HPF report; rule labels beginning with ``R'' refer to syntax rules in
the Fortran 90 standard.}

One can also define \BNFpreface similarly.
