APDL Public Domain 1/APDL_PD1A.iso/textutil/jgpsuite/xmp/EXNOTE

Text File | 1992-01-13 | 11.7 KB | 270 lines

.cpi 10 1 60
.hd
/
.if \o
.col
Page \p|Notes|\s0
.else
.col
\s0|Notes|Page \p
.fi

/
.ft
:

.col
30/11/87|(C) JGLaski, 1988|29/7/89

:
.parind 0
.setst :\s1=38:
.setst ::
.ftnt
*.cpi 12 1 72
.sp 8       This will be ignored in JGDoc
.ht 8
.bar -
.setst :\t:
*\R\&\T *.nost
\&)\t*
.endnt
*.page
.bar -

Here is the beginning of the chapnotes

.bar -

.col
|Chapnotes|

.ht 8
.setst :\t:
*\R\#\T *
.nost
\#)*
.endno 10
.ftno a

.col
|Notes \(A demonstration that footnotes can be set from within the fields of
..cols; of course the opening and closing brackets must be in matched
positions, or chaos will ensue.\)|

This document serves as both documentation and example for Endnotes and
Footnotes. Moreover, they serve as a paradigm for any JGPrint job for which
notes are required, and I would strongly suggest that you start by using the
same directives as are used here, and then modify them to adapt to your specific
requirements. Indeed, I should be suprised if any modifications are needed
except for reseting the odd margins here, and possibly not using .ftno to move
away from numeric footnotes, for the vast majority of jobs.

The following directives set up the three strings and the base for the
footnotes in this document:
.nofj
..ftnt
*.cpi 12
..sp 8
..ht 8
..bar -
..setst :\\t:
*\\R\\&\\T *.nost
\\&)\\t*
..ftno a
.fj
Similarly, these directives set up the three strings and the base for the
endnotes and chapnotes in this document:
.nofj
..endnt
*.page
..bar  -

Here is the beginning of the chapnotes

..bar -

..col
|Endnotes|

..ht 8
..setst :\\t:
*\\R\\#\\T *
..nost
\\#)*
..endno 10
.fj
The actual footnotes and endnotes are taken from the \\(...\\) and \\[...\\]
brackets in the body of the text. When JGPrinting to screen, long footnotes
provoke prompts "Long footnote OK? / Enddoc" to enable missing \\) to be
caught. It is, of course, absurd to use these facilities on such a little
document other than for demonstration purposes. I find complicated uses of
note usage require checking, possibly printing testing texts made up of small
extracts, before a final print.

In each case, three strings are defined: the first specifies how the notes are
separated from the body of the text; the second specifies a string to be put in
the body at the point to which a note applies; the third specifies a string at
the beginning of the corresponding note.

Syntactically, the facilities for Endnotes and Footnotes are almost identical.
\[\tThe dotties .FTNT and .ENDNT each require three strings as an argument,
only the second of which is interpreted within the text where the note is
refered to; .FTNO takes a character, .ENDNO takes a numerical argument.\]
\(The dotties .FTNT and .ENDNT each require three strings as an argument, only
the second of which is interpreted within the text where the note is refered
to; .FTNO takes a character, .ENDNO  takes a numerical argument\) Admittedly
..CHAPNT has no analogue for footnotes and the configuration parameter
FtPgRestart has no analogue for endnotes, but these make available auxiliary
flexibilities that are not central to handling notes. \[\t}\\(, \\) and \\&
are analogous to \\[, \\] and \\#.\] \(\\(, \\) and \\& are analogous to \\[,
\\] and \\#.\)

How JGPrint deals with them, however, is very different, and this has
consequences for setting the strings in .FT/ENDNT and within the beginning of
the body of the note that is put out. This example produces, as closely as
appropriate, endnotes and footnotes with the same layout. Examining the body
of the text, you will see slight, but necessary \[\t}The positioning of the
tab (\\t) in the third string of .FTNT is more convenient than putting it at
the beginning of each footnote, but doing it as for the endnotes will work;
most importantly, putting the endnote tab in the third ..ENDNT string rather
than in the body will lead to chaos. Try it!\] \(The positioning of the tab
(\\t) in the third string of .FTNT is more convenient than putting it at the
beginning of each footnote, but doing it as for the endnotes will work; most
importantly, putting the endnote tab in the third .ENDNT string rather than in
the body will lead to chaos. Try it!\) differences to achieve this. The third
string of .ENDNT begins with a new line, whereas that for .FTNT does not. The
second string of .FTNT ends with a tab (\\t), whereas the analogous endnote
tab appears explicitly at the beginning of each note. The first strings
following .ENDNT and .FTNT are completely different, but, since they are
intended to produce different separations between the text and the notes, this
difference, though larger, is not significant.

The margins have been moved to the left since the footnotes have been set to
appear with the same width as the body but at 12 cpi, and as this cannot be
shown on the screen, the margins set avoid line overflow.

There are three differences between the treatment of endnotes and footnotes,
of which the first is by far the most important.

This first difference is between what happens to the body of the note, that
which is between \\[ and \\] or between \\( and \\). The endnote text is
simply copied through without interpretation to a file 'endnt~~'; the only
backslash that is looked for is the matching \\]. The footnote text has to be
interpreted before being copied through \[\t}it is held in vectors in the
store, and is therefore expensive in space\] \(it is held in vectors in the
store, and is therefore expensive in space\) since JGPrint needs to know the
depth on the page to leave for the footnotes. Consequently, the current line
and word are stored and restored, and, for each footnote starts again from the
leftmost column. The second difference follows from this; each footnote begins
on a new line.

This second difference is the reason why the .nost in the .ENDNT directive has
to begin on a newline, whereas in the .FTNT directive it can immediately
follow the seperator '*'\[\t}This note is put in to demonstrate that if a
footnote is so long that it would cause a page to overflow, it and the line it
belongs to are forced over to the next page. Another consequence is that you
can put footnotes into endnotes, but not Endnotes into footnotes. There is a
bad case of the pagebreak bug for \\p and \\m, thus \p, if the footnote is
forced over the page, but I expect the preceeding example is the only one that
will ever occur in practical use.
I have to make this long enough to force over, as you
can see by the space left above on the previous page (footnote only).\] \(This
note is put in to demonstrate that if a footnote is so long that it would
cause a page to overflow, it and the line it belongs to are forced over to the
next page. Another consequence is that you can put footnotes into endnotes,
but not Endnotes into footnotes. There is a bad case of the pagebreak bug for
\\p and \\m, thus \p, if the footnote is forcrd over the page, but I expect
the preceeding example is the only one that will ever occur in practical use.
I have to make this long enough to force over, as you can see by the space
left above on the previous page (footnote only).

I have had to go over into extra paragraphs and space consuming bars to manage
this as the text now stands.
.bar - 4 40
.bar -
.bar - 40 50
.col
|Long enough?|
\);  also the tab (\\t) in the second string would be interpreted in .ENDNT at
the line position where the note occurs, so that the tab would produce either
an apparantly random number of spaces or a confusing diagnostic.

.chapnt
*.hd
/

.col
|Endnotes|

/
.page
.ht 8
.setst :\t:
*\R\#\T *

.bar -

Here is the end of the chapnotes

.bar -
.fig 3

..ENDNO sets the next note nunber, and is restricted to be numeric \[\t}This
was the original for both kinds of notes. The change shows how how experience
informs imagination informs design.\] \(This was the original for both kinds
of notes. The change shows how experience informs imagination informs
design.\), whereas .FTNO sets the base from which numbering begins on each
page and the next note number, and is set by any character that follows.
\[\t}If the character is 0, the notes numbers are numeric starting from 1; 10
follows 9. Otherwise they are ascii; b follows a, + follows *. Special
characters can be defined by the user for this purpose, 'dagger', double dagger
etc. Note that these cannot be taken from the IBM standard extended character
sets, which does not provide them adjacently. Many\-charactered note numbers (*,
** or Roman numbers) cannot be provided via \\#/&; They can of course be
provided explicitly with null strings following .FTNT/ENDNT)\] \(If the
character is 1, the notes numbers are numeric; 10 follows 9. Otherwise they are
ascii; b follows a, + follows *. Special characters can be defined by the user
for this purpose, 'dagger', double dagger etc. Note that these cannot be taken
from the IBM standard extended character sets, which does not provide them
adjacently. Many\-charactered note numbers (*, ** or Roman numbers) cannot be
provided via \\#/&; They can of course be provided explicitly with null strings
following ..FTNT/ENDNT)\) There is a small bug in the design here, since a .FTNO
on a page on which there has already been a footnote will cause inconsistent
references: the numbers in the text are as specified above; the numbering of the
footnotes will begin with the number/character set by .FTNO. It is not a heavy
burden on the user to require .FTNO to be use only in the prologue, or at the
top of a page \(Code could be written to hold a FTNO reset to the top of the
next page, but this seemed more trouble than it was worth\) \[\t}Code could be
written to hold a FTNO reset to the top of the next page, but this seemed more
trouble than it was worth\].

Footnotes are good candidates for the title of  the most complicated part of JGPrint's
design \[\t}Rivals for complication are horizontal tabs and section numbers.\]
\(Rivals for complication are horizontal tabs and section numbers.\), keeping
track of the required layout, the residue depth on the page, the numbering of
the notes on the page, the vectors in which these are held. This example is
quite a comprehensive test, and other tests have been made. However, this is
an area in which I would not be suprised if I had overlooked some rare
condition.

Footnotes are held in store until they can be put out, and this is
space\-consuming; there is always the danger of running out of available space
if your footnote usage resembles the Variorum Edition of Shakespeare's plays.
Footnotes go through several stages af construction and analysis, and I reckon
I am close to the limit of the number of facilities in JGPrint before its
coding spirals out of control. But I had this idea in my bath last night......

Footnotes, endnotes, included files and strings and .IF directives can all be
properly nested and will work correctly. However if the nesting is invalid,
chaos will result. This is the major case in which I decided not to go to the
complication of keeping track and providing diagnostics. I reckoned that such
use would be sufficiently rare for users to take a great deal of care when
setting out texts that would require these facilities simultaneously, and that
nesting would not be deep and it would be easy to see that they did not get
knotted. On implementations for larger machines, I could put diagnostics in if
there was a genuine call for them; it would be space\-consuming. With my
fingers crossed, I now demonstrate a footnote in an endnote, and and endnote
from a footnote. \[\t}This endnote has a footnote \(This foootnote comes from
an endnote.\).\] \(This footnote refers to an endnote\[\t}This endnote
qualifies a footnote.\].\).