Subject: hpff-doc: Progress! New version installed

From: Chuck Koelbel <[email-masked]>
Date: Tue, 31 Dec 1996 11:44:15 -0600

---------------------------------------------------------------------------
[email-masked] is a mailing list for HPF 2.0 language specification
authors and editors.  Instructions for adding or deleting yourself from this
list appear at the bottom of this message.
---------------------------------------------------------------------------
By the time this message reaches you, a new version of the HPF 2.0 spec
will be installed.  For those of you who are counting, we are now at
version 2.0.mu.

You can retrieve the document from "the usual place":

	ftp://titan.cs.rice.edu/public/HPFF/work-in-progress

The file "work-in-progress.tar.gz" is the GZIP'ed, TAR'ed collection of
everything else in the directory.

There have been significant changes to the mechanics of the document.  For
most of you, the bottom line is this:

If you are running LaTeX 2.09, you can format the document by saying
	cp hpf-report-header-latex209.tex hpf-report-header.tex
	latex hpf-report

If you are running LaTeX2e, you can format the document by saying
	cp hpf-report-header-latexe.tex hpf-report-header.tex
	latex hpf-report

If you want the whole story, here it is...

>From: [email-masked] (Carl Offner)
>Date: Tue, 24 Dec 1996 12:49:49 -0500
>To: [email-masked], [email-masked]
>Subject: HPF doc
>Cc: [email-masked]
>
>Guy and Chuck--
>
>        I'm following this with the file hpf-report.tar.gz.uue
>containing all the source files for the report.  Carol Munroe
>(due to problems moving offices to Sun) hasn't been quite able
>to finish her chapters, so I have suggested she send them directly
>to Guy when she is done.  I will be out of the office for the
>rest of the week, but I'll be back on Monday, and I can help sort
>out any confusion caused by this then -- it should not be difficult.
>[ed. note - Carol's chapter has since been integrated without trouble]
>
>Here is what I have done:
>
>1.  There is now only one syntax-macs.tex; it is the same for LaTeX
>209 and LaTeX 2e.  On the other hand, there are now two files
>
>        hpf-report-header-latex209.tex
>        hpf-report-header-latex2e.tex
>
>one of which should be linked or copied to hpf-report-header.tex, as
>appropriate.  These files are the only ones in which a distinction
>between the two versions of LaTeX is made.
>
>(I tried to find a way to have LaTeX choose between these two files,
>based on which version of LaTeX was running.  There seems to be no way
>to do this without using some LaTeX internals, however, which I am
>reluctant to do.  Reading the LaTeX2e documentation, I get the
>impression that this was a conscious decision on the part of the LaTeX
>developers -- they don't want to make it easy to continue to maintain
>LaTeX 209 documents, because they feel such documents should either be
>frozen or be upgraded to LaTeX 2e.  In any case, I assume that any
>future versions of the HPF language document will just be created for
>the current version of LaTeX, whatever it is called at that time.)
>
>2.  In hpf-report.tex the variable \libheaders is set to \FALSE.  This
>inhibits making entries in the table of contents for each individual
>library function.  To make such entries, set \libheaders to \TRUE (and
>rerun LaTeX 3 times).  I also changed the form of such entries (if
>made) so that they only reflect the name of the library function and
>not the parameter list -- this prevents the lines from getting too
>long.
>
>Actually, putting these entries in the table of contents really
>doesn't make much sense, because the corresponding local routine
>library functions don't make it into the table of contents in any case
>-- they are one level farther down in the section hierarchy.  Also,
>the Fortran 95 document doesn't have its library functions listed
>individually in the table of contents.
>
>This still does not make the document look exactly like the Fortran 95
>document, however, because the Fortran standard does have a section
>number for each intrinsic function, even though no entry appears in
>the table of contents.  I don't see how to achieve this in LaTeX
>easily.  Also, I don't see what the point is anyway -- why have
>section numbers (at that level) if they don't appear in the table of
>contents?  This is really an inconsistency in the formatting of the
>Fortran standard.
>
>3.  I fixed things so that the explanatory paragraph for the Part
>pages is set on the same page as the Part title itself rather than on
>its own separate page.  The paragraphs came out in bold face.  I kind
>of like that, but it can be changed -- see the notes in each such
>file.
>
>4.  Each Section now starts on an odd-numbered page.  This can be
>changed back to the way we were formerly doing it (i.e., each Section
>starting on the "next" page) by commenting out the \cleardoublepage
>commands in hpf-report.tex that occur before the \include commands for
>each Section.
>
>5.  The copyright notice appears on the back of the title page.  The
>table of contents starts on the next page.  That is, the page sequence
>looks like this:
>
>  title page
>  copyright page
>  table of contents (page i) ...
>
>To change things so that the back of the title page is blank (this is
>the way the handout at the meeting looked), comment out (LINE B) in
>hfp-report.tex and uncomment (LINE A).  This will make the page
>sequence look like this:
>
>  title page
>  blank page
>  copyright page
>  blank page
>  table of contents (page i) ...
>
>6.  I commented out the line numbering on all the preliminary matter,
>including the table of contents; this is the way the Fortran 95
>document looks also.  It also had the nice side-effect of
>reintroducing the (roman numeral) page numbering on the preliminary
>pages, which had been suppressed by the line numbering.
>
>To do this consistently, I had to redefine the \chapter command in
>syntax-macs.tex, and introduce a LaTeX variable \linenumbers that is
>initially set to \FALSE, and then changed to \TRUE just before Section
>1 (Overview).  This variable is needed to control what happens on the
>first page of each chapter -- this is handled as a special case in
>syntax-macs.tex.  This variable is managed in hpf-report.tex.
>
>7.  I shortened the running head for Section 12 (Approved Extensions
>for the HPF Intrinsic and Library Procedures) so that it wouldn't hang out
>into the margin on each even-numbered page.  To do this correctly, I
>had to specify that the Section number in the running head should be
>typeset as \large.  This is because the document is being set in 11pt
>type.  Without \large, the Section number comes out in 10pt type,
>which is the default.  I don't know how to make the correct behavior
>happen automatically, so if the document were ever typeset in 10pt
>type, the \large would have to be taken out.
>
>8.  I made a few very minor changes in wording (no content changes,
>mostly just reordering words) in order to avoid having some lines
>stick out into the margins.  Other than putting in some explicit line
>breaks, however, I did nothing in the library chapters.  There are a
>lot of overlong lines in those chapters, but I didn't want to start
>messing with the wording of library routine specifications.
>
>9.  I noticed that a lot of the extra strange spacing around code
>examples was due to the placement of the \CODE and \EDOC macros.  I
>moved them all so that they are at the beginning of the line.  That
>took out the extra vertical spacing that was often inserted after
>these examples, and made the document much nicer, although the LaTeX
>source becomes arguably somewhat more difficult to read.
>
>10.  I changed the keywords in section headings for HPF_CRAFT and
>F77_LOCAL to be normal (Roman) font, rather than typewriter font.
>This is to be consistent with the usage of the rest of the document.
>I also suppressed the table of contents entries in the F77_LOCAL
>appendix, again in conformance with the rest of the document.  (I
>didn't put this on the same switch, however -- I just changed
>\subsection to \subsection*.)
>
>Other than that and a few very minor formatting fixups, I left those
>two sections alone.
>
>-------------------------------------------------------------------------
>
>In addition to the BNF fixing and the final pass by Guy, the following
>things have to be done:
>
>1.  copyright.tex needs to be put in its final (non-public-comment)
>form.
>
>2.  The Minloc directory should be deleted, since these functions are
>now in F95 and the files are no longer used in this report.
>
>Also, the following files in the Mapping directory should be deleted,
>since they are not included in this report:
>
>        hpf-distribution-extended.tex
>        hpf-mapping.tex
>        hpf-number.tex
>        mapping-inquiry.tex
>
>3.  The business about the right font for single quotation marks in
>the extrinsics chapters needs to be fixed.  Guy thought could do that
>by making single quote be an active character that is redefined in the
>\texttt environment.  Also, there are still some double quotes in
>those chapters that should be changed to single quotes.
>
>
>                --Carl Offner

>From here out, the schedule is:

Now to Jan 14 - Comment by HPFF attendees welcome.  For typos and small
edits, send e-mail to the chapter editor.   If you have major issues (e.g.
you think the ON clause is completely incorrect), send them to
[email-masked].  I *think* the current list of editors is:

% Chapter 1: Overview - terms and concepts - new document/language structure,
% Fortran language base, F95 features, HPF 1.1 deletions, etc.
	Mary and Saday

% Chapter 2: Notation - Base BNF for HPF 2.0 and Approved Extensions
	Saday

% Chapter 3: Mappings  - distribute, align, sequence, some of pointer.
	Piyush and Carl

% Chapter 4: Mapping across Subprogram Interface.
	Piyush and Carl

% Chapter 5:  Independent and Reduce
	Rob and Chuck

% Chapter 6:  Extrinsic
	???

% Chapter 6: HPF Library (plus sort-up and sort-down)
	Rob

% Chapter 7: More mappings (and related subprogram interface issues)
% GenBlock, indirect, range, shadow, subsets, derived type, more on pointers.
	Piyush and Carl

% Chapter 8: ON, TASK, RESIDENT
	Chuck and Rob

% Chapter 9: Async I/O
	Larry

% Chapter 10: HPF_LOCAL (extrinsic extensions)
	Carol ???

% Chapter 10: New Library - generalized transpose, extended inquiries,
% new mappings.
	Rob

% Appendix A - BNF
%\include{bnf-app}
	(not currently in the document, but Guy will generate/edit)

% Appendix B- Subset
	Mary

% Appendix C - Old Acknowledgments
	Mary

% Appendix D - Bibliography
	Carl

% Appendix E - Extrinsic Extrinsics - (policy, mechanism, HPF_CRAFT)
	???

% Appendix F - HPF_CRAFT
	Tom MacDonald

% Appendix G - FORTRAN__LOCAL
	Carol

Concurrently, Guy Steele will work on the BNF appendix and remaining
formatting issues, if any.  I will announce a new version when he is done.
(This was going to be the version announced on New Years Eve, but we had
some slippage.  I haven't heard from Guy, so no ETA; however, the changes
were expected to be very minor in any case.)

Jan 14 - All chapter editors have all suggested edits.

Jan 21 - All chapter editors send their final version to Chuck.

Jan 22 - Chuck installs final version

Jan 23-28 - Guy checks final document

Jan 28 - HPF 2.0 is announced to the world!

Thanks to all the people who vave gotten us this far.  Now, let's hear
those comments!

**********************************************************************
Charles Koelbel				CRPC, MS 132
Center for Research on Parallel Computation		Rice University
Rice University				6100 Main Street
[email-masked]				Houston, TX 77005
**********************************************************************

---------------------------------------------------------------------------
To (un)subscribe to this list, send mail to [email-masked].
Leave the subject line blank, and in the body put the line
(un)subscribe <email-address>
---------------------------------------------------------------------------