APDL Public Domain 1

home *** CD-ROM | disk | FTP | other *** search

/ APDL Public Domain 1 / APDL_PD1A.iso / textutil / jgpsuite / Docs / JGDocDoc < prev next >

Wrap

Text File | 1993-04-23 | 42.1 KB | 1,054 lines

.// Source for JGDoc_Info Wed,15 Apr 1992 .gute 5 .ht 2 10 12 .// This sets tabs for the indented layouts below. .sp 0 Comment out if Pages wanted; default 66 lines (.sp 66) .setu 10 :arc: In/exclude archimedes only features. see .if/fi below .// .setu 10 :msdos: Ex/include msdos only features. .setu 11 :0: 1 for debug; 0 for production .if \u11 .hd /.col """""""""""""""""""""" / .fi .ft / .col |Page \p / .if \u11 eq 0 .hd : .if \o .col |JGDocumentation|Wed,15 Apr 1992 .else .col Wed,15 Apr 1992|JGDocumentation .fi : .fi .marg 16 68 .vbar | 0 52 .bar _ .vbsw + .nofj .\ \Q .// Cancels any proportional character setting from Configuration, since .// "JGDocument" looks wrong; restored, if applicable, by .usel base below. @ @@@@ @@@@@ @@@@ @@@@ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @@@@@ @ @ @@@ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @@@@ @@@@ @@@@@ @@@@ @@@@ @ @ @ @ @@@@@@ @ @ @@@@@ @ @ @@ @@ @ @@ @ @ @ @ @ @@ @ @@@@@ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @@ @ @@@@ @ @ @@@@@@ @ @ @ .bar _ .vbsw .usel base See Layouts below This document assumes you are in JGDoc mode, but is also valid for JGPrint mode. Shareware is distributed with JGDoc mode set. In JGPrint mode, more flexibility is available through use of the configuration files. This text is quasi\-tutorial, in the sense that directives are both explained and used; in particular an attempt is made to provide examples near explanations. .page This file is of type JGPrint, and when it is interpreted by JGDoc (!jgp.Tools.JG(Share)Pr), generates doc.jgdocdoc, a JGPCopy file. This file describes the formatting facilities available to the user and to the writer of documentation; this file itself serves as an example of how these facilities are provided, doc.jgdocdoc shows the results of their use. You should rename doc.jgpdocdoc to JGDocInfo. .col |Running JGDoc on "OK" files If the first character of !jgp.info.JGPStrings is '*', JGPrint runs in JGDoc mode. I distribute in this mode. The following information assumes desktop; if it is not there, analogous reports will appear on the screen. The documentation below discusses how to write or modify files for JGDoc and JGPrint. If you have a file <path>.foo of type JGPrint (a brown open book), applying JGDoc to it will produce a well\-laid out file <path>.doc.foo of type JGPCopy (a yellow open book). At the end you will get a report window telling you how long the file is; click on the OK button, and you will quit. You may get other report windows en route. The most common appears if <path>.doc.foo already exists, in which case, the report window asks if you want to overwrite it, and has an OK and a Quit button. Of course this applies to any output file, whether what you are JGPrint/Docing to, or any auxiliary file you may be writing. Suitable reports appear if any invalid directives appear in foo's text. If your text requests an index file (see below), the report buttons are Ignore, Choose, Quit: Ignore will cause later requests to be ignored; Choose will replace the report window with a To window. Put the file leafname you want to use in the window, and drag the icon to the directory window you want it to live in. If your text requests a merge file (see below), clicking the Find rather than the Quit button replaces the report window with a From window. You should drag the required merge file to this window. If a directive that only makes sense in JGPrint mode is in your text, you will get a report window with a message that it has been ignored. This will disappear after less than a second. There is also a choice you need to make, if you have used vertical bars, as to whether your output is intended for "Screen" or "Printer". If your text includes a request for a change of pitch, JGDoc ignores it without a report. This is all you need to know to run JGDoc on an existing unchanged file. I recommend you to do so now to the files in document'n.doc. The results will be much more agreeable to read. If you want to alter the layout of the file doc.foo, you'll have to read a little further. A trick: if you want to cancel opening a file from a to: window, give it a null name, or the same name as an existing file; from a from: window, drag a directory to the window. In each case you will get another report that quits the run. .col |JGPrint/Doc Directives Because this text has two purposes, formatting directives are more plentiful in this document than I would usually expect to find. It has, unfortunately, been necessary, sometimes, to use some before they have been explained. There are three classes of directive: dotties, which begin with a . in column 1; backslashes, which consist of \\ followed by a character; and hatties, which consist of a ^^ followed by a character. Two dots, backslashes or hats are JGPrinted as a single printed character rather than as the introduction to a directive. Certain dotty directives require as argument a bracketted string. The first character between byte 33 and byte 126 encountered after the dotty name is taken to be the bracket; it is my practice to use : or some other punctuation character. Any characters on the dotty line after those meaningful to the dotty will be swallowed; thus, as above, they can be used for comments. If the backslash \\<letter> is followed by the sign }, the } is swallowed; I find this } adds to the clarity of some source documents and avoids confusing spellcheckers; \\u<n> is an example of a few backslashes that are followed by a letter, then a number; a dot following this number will be swallowed similarly. Of course if you want a } in the first context or a . in the second, }} and .. give it to you. \\+ requires to be followed by a file name. In JG(Shar)Ed, f1 - 0 will type a list of JGPrint directives with brief descriptions to the screen. The syntax for certain advanced facilities is sometimes given without semantic explanation; users may care to experiment to see the effect. This file will also serve as input to JGPrint/JGSharePr in JGDoc or JGPrint mode. It can, of course, also be read 'as is', with a little noise from the JGP layout directives. See below for how to choose what mode JG(Share)Print runs in. .if \u10 eq arc .cp 6 .col |JGPrint and JGPCopy Files In the Desktop, provided you have seen !jgp, it is sufficient to double click on the file's icon in the filer. See !clickme for how to set a file's type to JGPrint. In the commandline, type the line JGPrint JGDocdoc. This assumes JGPrint and JGXists are in the library; alternatively <jgp$dir>.Tools.JG(Share)Pr(int) will enter directly. Doc.JGDocdoc will be a JGPCopy file, and double clicking on it will enable it to be read on the screen, dumped, or printed. See !JGPClick for a discussion of JGPCopy's options. (I find mode 12 the best to use to read or study a text, mode 20 better for writing one.) You should rename this file doc.JGDocInfo. .fi I shall speak of JGDoc rather than JGPrint in JGDoc(ument) mode. JGDoc runs entirely in the desktop; if none, it will run instead from the commandline. JGPrint can run either in the Desktop, or in the commandline. In the desktop, it starts with a dialogue in its own window, which covers the whole screen. Dependng on what you choose to JGPrint To, you can choose to continue either in the desktop (quicker), or in its own window (useful for checking out texts). For further details see JGPrintDoc/Info. .cp 6 .col \s1|The Reader's Needs Given a document with JGDoc's formatting directives, either the user can accept the formatting provided, or the user requires to be able to decide whether it is to be paginated, and if so, how it its pages are to be set out for length and width; she may also need to know what byte to provide her printer with, whenever the pound sign appears in the text on to the screen; this byte value will be found in her printer documentation. .cp 6 .col \s2|.sp <n> The .sp directive is followed by a number, which determines how many lines there are on each page. Allowable values are 0, 11-120. 0 implies no paging, <n> implies that the header, body and footer of each page make up precisely <n> lines. The default value is 66, i.e. 11" at 6 lines per inch. Note that the documenter may have put in paging or conditional paging directives to take back some control from JGDoc (see below). In JGDoc mode, the .sp directive is only effective within the prologue, the group of dotties at the top of the document interpreted before any printing is done; within the body of the text its use is reported, but its effect ignored. Thus, unlike JGPrinting to screen, page registration is preserved, in spite of the fact that the change is not effected on the printer. To emit codes to alter the physical distance between lines on particular printers, JGPrint itself is needed. This serves as an example of JGDoc's designed limitations. There can sometimes be rounding errors if only .sp is used. JGPrint/Doc has a fuller story involving both pagelength (.pl) and line spacing. For details see below. .cp 6 .col \s2|.Marg <l> {<r>} The .marg directive sets the lefthand column <l>, and the right hand column <r> between which characters are allowed. Column 1 is the leftmost the device can use. Thus the usual modes require 1\ <=\ <l>\ <\ <r>\ <=\ 80. In effect <r> specifies the width of the page. The default values are 7, 73 giving a left margin of 6 columns and a right margin of 7 columns on an 80 column device. NB .cpi <p> <l> <r> is a synonym which has extra effects on the character pitch used in JGPrint. In JGDoc, it will only have effects if margins, guttering or horizontal tab are already set. .cp 6 .col \s2|jgp$pound If the system variable jgp$pound is set to an integer .if \u10 eq arc (*seteval jgp$pound <n>), byte 163(£) .fi .if \u10 eq msdos (>set jgp$pound = <n>), byte 156(†) .fi is transformed to byte n, thus enabling the printer to get the value it requires when the JGDocced file is copied to the printer. If jgp$pound is unset, the £ byte is unchanged, as is required when the JGDocced file is looked at on the screen. (The Pound sign above will only come out correvtly on the screen on an Archimedes.) .cp 6 .col \s2|Newlines JGDoc sends precisely the combination of carriage returns(13) and newlines(10) it requires the printhead to move. Therefore, it requires its printer to perform a carriage return or linefeed if and only if it receives one. See Vbar below for some details. In JGPrint mode it is possible to set parameters in the configuration file to send <nl> rather than <cr><nl>. .cp 6 .col \s2|JGDoc's Queries In certain rare circumstances JGDoc will need to know whether the JGCopy file is intended to be copied to the screen or passed to the printer, and, if so, will enquire "Forscreen?(Y) :"; At the moment (1991), 'vertical bars' is the only documenter's directive that requires this cooperation from the user, but I do not exclude the possibility of adding more if needed. .col \s2|.Singlesheets JGDoc is set up for printers that do not require any extra characters, e.g. FormFeed between pages. If your printer is such, you will have to use JGPrint with a suitable configuration file. See below for guttering, allowing wider margins on alternate sides to make binding produce a better effect. .cp 12 .col \s1|The Documenter's needs A general word of advice: particularly if you are using the more advanced formatting facilities, getting it right first time is rare. Using JGDoc involves developing and debugging the layout of your documents. You will probably find JGPrint mode more convenient (see JGPrintDoc) if you are developing a complicated text. (To c or to <file>, so you can see the text on the screen as JGPrint lays it out.) .cp 6 .col \s2=0|Distribution Fees If you distribute software with documentation (prepared) using JGDoc/Print, a copy of the product and its documentation is to be sent to me with a free licence subject to your normal conditions for my full use of the product. On 'sale' of your 100th. copy you pay me as full and final fee the full normal end\-user charge for your product. Variations for odd circumstances are proposed in JGLiceDoc. .cp 6 .col \s2|Comments and Diagnostics When preparing a document for JGDoc, it will normally be the case that a partial document will be tried out several times on the way, and it may well be that various parts may need to be commented out, either because it is text that you are not sure whether or not to include, or directives whose effects you are not entirely sure of. Furthermore, JGDoc may not be able to understand the directives you have presented it with. Therefore, JGDoc provides:- .setst |\h3| see tabs and undented lines below .nost \t\s3 \t.//, which causes the line that follows it to be ignored in the target text doc.whatever, but to come out in JGDoc's screen window. Another use for this is to help locate a diagnostic report which has not given sufficient context to be recognised, by bracketting it between successively closer comments. (In the desktop it is ignored.) An alternative way to skip unwanted text is provided by .if/.fi (see below). .nost \t\s3 \t<Diagnostic Report>/Enddoc(Y/J) : or Report Window Report/Enddoc, with buttons Quit/Continue/Jot is put out whenever JGPrint/JGDoc suspects something is wrong. The message, derived usually from JGPStrings, should be self\-explanatory, but I may not always have been successful in pointing you to where the problem is. NB. Jot is not available in JGDoc. In JGPrint, Jot enables you to write to the Jotfile Jot>, so that you can check up on what went wrong. .cp 12 .cp 6 .col \s2|Running Heads .setst :: If JGDoc is not providing pages, there will be a header, and the body of the document will follow. Otherwise pages each begin with the header, end with the footer, and place the body of the text between these. If no header is specified, a default of 3 blank lines is provided; if no footer is specified, a default of 3 blank lines is provided. JGDoc may sometimes leave an extra line before or after the footer in order to make the page break sensible, and avoid widow or orphan lines. Although headers and footers are normally set in the prologue, there is no reason why they should not be reset in the body of a document, usually before a page\-break. This document is an example where this is done for the header, but not the footer. Therefore, JGDoc provides:- .setst |\h3| .nost \t\s3 \t.hd <Bracketted string>, which holds the bracketted string for use at the head of each page. .nost \t\s3 \t.ft <Bracketted string>, which holds the bracketted string for use at the foot of each page. .nost \t\s3 \t\\p outputs the current page number whenever it is encountered. It is most useful in running heads, but works just as well in the text body. The bracketted string is restricted to a maximum of 255 characters. The bracket is the first ink character (bytes 33-126) encountered after .hd/ft. It is my normal practice to use a punctuation character which I don't want in my header\/footer string; I also normally put these brackets on separate lines. Only blank lines, 'col'led lines or barred lines are allowed in running heads. Running heads are always put out in the base layout, ie. with the margins etc. that apply at the end of the prologue, ignoring later changes. The default Initial header and footer are put to 3 blank lines in JGDoc mode; if this is not convenient for your printer, you can always put in in what you need explicitly. See JGPrintDoc for the greater flexibility available in JGPrint mode. .cp 12 .cp 6 .col \s2|Barred and Colled Lines .setst :: It is useful to be able to draw horizontal and vertical lines on the page when setting out, say, a table; it is also useful to be able to centre, range left or range right some text on a line. JGDoc provides facilities for putting a bar of a given character across the page between the current margins, and of dividing up a line into three clumps of text, respectively ranged left, centred and ranged right. (For Vertical bars see below.) Therefore, JGDoc provides:- .setst |\h3| .nost \t\s3 \t.bar <ch> {<n1> <n2>} which spreads a line of <ch>s across the page. .nost \t\s3 \t.col <nl> <str1> {|<str2> {|<str3>{|}}} ranges <str1> left, centres <str2> and ranges <str3> right. NB {..} shows what parts can be left out, and very often are. See the examples of the various uses throughout this documentation. The third optional | in .col enables blanks to pad the right\-ranged string to the right. This is useful to provide a right ranged, left aligned address. (I did this at the bottom of Rdmedoc/!Clickme.) Strings may be, and often are, empty. If you want to put ranged left and ranged right strings on a line, you cannot use an empty centre string, since JGDoc construes || as a single | to be put in a string. A string consisting of a blank character as the centre string will produce the required effect. The optional integers in .bar allow a part-line from <n1> to <n2> char columns to be put out; thus these two optional numbers bar allow lines partway accross the screen; for an example see Exlongd. <ch> may be a hatty, and may be preceded by certain backslashes, eg underline or bold. The user is recommended to experiment to see whether what she wants is available. .cp 12 .col \s2|Tabs and Vertical Bars .setst :: It is useful to be able to set and effect tabs; it is also useful to be able to set positions for vertical bars to appear on a page, and then independently,switch this on and off. Therefore, JGDoc provides:- .setst |\h3| .nost \t\s3 \t.ht <n1> <n2>.... which sets tab positions at <n1>, <n2>,.... relative to the left margin. .nost \t\s3 \t\\t effects a tab to the first tab column to the right of where JGDoc is on the line. .nost \t\s3 \t\\<h<n> effects a tab to the nth. tab from the left margin. .nost \t\s3 \t.vbar <c> <n1> <n2>... set positions for the character <c> to be put on each line in addition to the text actually specified. .nost \t\s3 \t.vbsw {+} switches on and off printing in the current vertical bar positions. .nost \t\s3 \t.vt <n1> <n2>.... which sets vertical tab positions at <n1> <n2> relative to the top of the page (not top of text body). Units of lines (n<100> can be used. .nost \t\s3 \t\\v effects a vertical tab to the next setting. The <n1> <n2>... must be monotonically increasing. <n1> for tabs must be positive, but for vbar can be 0. It is often better to cancel filling and justification when using tabbing, since otherwise you will not know where JGDoc is on the line when you effect a tab. Colled lines are not vbarred; nor are empty lines. A trick for the latter is to put <ch>\\w on the line, since \\w signifies wipe out a character. \\w can also be useful for extending the range of effects produced by tabbing. The initial default has no tabs or vertical bars set. A problem can arise if the word following a tab is too wide to fit in before the right margin. In this case, one of my 'longstop' diagnostics catches the overflow with the report "Word/Line too long. Alleged...." where ... is the overlong line. This may contain one or more examples of \\}<n>, which are rightwards printhead-moving directives. You should either move your tabs or widen your margins. Note that changing the configuration file used, or changing cpi or to or from proportional spacing, will affect whether or not you encounter this problem. I think this is the only use made of my longstops that directly affects the user; they are principally provided for development purposes. Vertical bars are implemented by printing a barred line in two passes with <cr>(13) between them. Warning: typing to screen, editors and word\-processors may treat this as <cr><lf>, putting the two passes on separate lines. Look at a dumped doc-file to see what actually happens. If you use .vbar, as in this document, JGDoc will ask you whether or not your JGDocced file is "For Printer"; this enables it to put out the right bytes to move the 'printhead' without wiping out what was below it. JGDoc may sometimes output <13><10><10> for two or more newlines. This will produce correct results on printers set to accept literally the characters passed to them, and not to put in extra characters. Doc-files with vertical bars cannot be resubmitted to JGDoc. If the left margin is altered after a tab or vertical bar is set, the position of the tab or bar remains unaltered relative to the left edge, changing relative to the margin. \\a, \\c, \\r are other kinds of horizontal tabs: arithmetic, aligning a '.'; centre; aligning the centre of the next word; right, aligning the end of the next word. See ExTab for examples. .cp 12 .col \s2|Filling and Justification .setst :: It is useful to be able to choose either a vertically aligned or a ragged right margin. Sometimes, however, the source text should be set just as it is laid out. Sometimes an individual line split is needed at some particular place. Therefore, JGDoc provides:- .setst |\h3| .nost \t\s3 \t.nofj (no fill or justify) copies the source document verbatim save that, if there are too many words to put between current margins, the last word (or more if needed) is put on a new line, rather than allowing the new line to come in the middle of a word. .nost \t\s3 \t.fill copies successive words onto a line until the next one would cause an overflow. Extra spaces between words are ignored. .nost \t\s3 \t.fj fills, and justifies by scattering extra spaces between words in the line so that the right margin is right aligned. .nost \t\s3 \t\\| (Line split) cancels filling to force a short line. Filling and justifying are stopped by a blank line, most dotty commands or a line split. Tab bytes are construed as spaces, page throw bytes as new lines. The default condition is filling and justifying. Documents from JGPrint prepared with .fgfj or .jgfj (fairly good or jolly good fill and justification) will come out on JGDoc as though .fj were set. .cp 12 .col \s2|Paragraphs, Pagebreaks and Figures .setst :: Paragraphs are construed as being ended by a blank line. However, you may or may not want a blank line between the paragraphs of your final text, and you may want the first line of paragraphs to be indented some number of positions. You may want to force a page break at some point in your text, or to force it only if the next few lines would otherwise be split between two pages. You may want to leave a number of lines blank, and require that these lines are kept on one page. You may want to reset the page numbering or start with a page other than 1. Therefore, JGDoc provides:- .setst |\h3| .nost \t\s3 \t.parsep {<n>} with <n>=1 to put a blank line between paragraphs, with <n>=0 to put the first line of a paragraph hard below the last line of the preceeding paragraph. NB. if <n> > 3, then in JGPrint <n>/100 Line spacing will be provided; JGCopy will show at least a full extra line .nost \t\s3 \t.parind <n> to indent the first line of a paragraph by <n> character positions. .nost \t\s3 \t.page to force a page break. .nost \t\s3 \t.cp <n> to force a conditional page break if fewer than <n> lines remain on the page outside the running heads. .nost \t\s3 \t.fig <n> to leave <n> unbroken blank lines in the text. .nost \t\s3 \t.pgno <n> to reset the pagenumber after the next page break. The default condition is .parsep 1, .parind 0. If .sp is set to 0, .page and ..cp are ignored. There is a notional pagebreak before the first page. ..graph <n> <n1> {<n2> }* 256, where the <n1>, <n2> <= 255, is an extension of ..fig <n>, but ignores <n1> and passes the <n2> direct to the printer; it is the user's responsibility to see that the printhead moves down the required <n> lines. ..defch n {<n1> }* 256 is similar without moving the printhead, and could be used to send an initialising string to the printer. The extra number should be small, eg 1. These facilities are for printer buffs. .cp 12 .col \s2|Hard Spaces, Hyphens and Topset Bytes .setst :: You may not want two words to be split between lines, even though there is a space between them, or you may want to cancel the way fill eats up multiple spaces. You may be willing to split a pair of words with a hyphen if this will help to get well\-justified lines. You may want to send particular bytes to your printer outside the standard 33-127. Therefore, JGDoc provides:- .setst |\h3| .nost \t\s3 \t\\<sp>, a hard space that acts like an ink character as far as filling and justifying are concerned but actually puts no ink on the page. .nost \t\s3 \t\\- is the shown hyphen in that the - appears between the words whether they are split between two lines or not. .nost \t\s3 \t\\_ is the hidden hyphen, in that it does not appear if a split does not occur. .nost \t\s3 \t^^<c> sends to the output the byte 128 above the one which represents <c>. There is another shown hyphen \\/ for use in long alternation lists; the hatty ^^<c> is less convenient than JGPrint's where the configuration selected defines the hatty mapping for the individual printer; indeed I only included it to simplify my coding and cope, somehow, with hatties that may have been used in documents originally provided for JGPrint. JGDoc treats all 255 bytes, only interpreting <0>, <9>, <10>, <12>, <13> <127>, so that if your editor can produce these bytes directly, you have no need for the hatties. It is probably better to insert top-bit set, and indeed bytes 0-31 directly from the keyboard, but, remember, you will get the printers sign for these bytes, not what you will see on screen. JGPrint can accept all bytes directly except 0, which must be sent via a hatty, but JGEd, and probably other editors will probably have problems with some other control bytes. See JGPrint for further discussion of how to send VDU bytes to the printer. .cp 12 .col \s2|Undented lines .setst :: You may want your indented text's left margin to be to the right of the beginning of certain particular 'undented' lines, as is the case for the numbered list of JGDoc directives in this document. JGDoc does this by setting a 'startstring' at the beginning of every line that is not to be undented. This startstring will consist of a number of spaces, though there is nothing in the mechanism to prevent ink characters being used. Tabs may be used to set the blank space width required. Therefore, JGDoc provides:- .setst |\h3| .nost \t\s3 \t.setst <Bracketted string> to set the required 'startstring'. .nost \t\s3 \t.nost to cancel the use of the 'startstring' for the following line. Blank lines, barred lines and colled lines do not have the start\_string prepended to them. As with vbarring, <ch>\\w will give you a pseudo blank line to to which the start\_string will be prepended. This, of course, is only useful if the start\_string contains non\-blank characters. The indent is fixed relative to the left margin, even if margins or tabsets are changed between a setst and a line for which it is used. ..setend/.noend are analogous for the right margin. Undenting is not very useful, but the same mechanism can be used to mark certain paragraphs etc. .cp 12 .col \s2|Section numbers .setst :: It is useful, as here, to have a way of numbering sections to some depth, and restarting the numbers when required. Therefore, JGDoc provides:- .setst |\h3| .nost \t\s3 \t\\s<n> which increments the section number at level n, and then puts out the current section numbers from levels 1 to <n>-1, separated by dots, followed by a dot, followed by the section number at level <n>; it then 'zeroes' section numbers from <n>+1 to 9, the maximum available. .nost \t\s3 \t\\s<n>=<m> acts as above, but sets the section number at level n to the integer m. This solves the resetting problem (\\s1=1). The description above is slightly simplified. Section numbers other than the last printed cannot be zero, so if, say, an \\s3 appears without a preceeding \\s2 and \\s1, it will come out as 1.1.1 rather than 0.0.1. Also section numbers in running heads do not increment, but merely repeat the number. Initially, all section levels are zeroed. \\s0 means put out a section number to the level last specified. This partly solves the running head problem mentioned in the previous paragraph. \\s<n>+<m> and \\s<n>-<m>, .pushsect, .popsect and .setc a.A.1 etc. are also available. .cp 12 .col \s2|Conditionals .setst :: .setc 0.0.0.A It is useful to have a way of including or excluding sections of text according to local conditions. One such condition is whether one is on an odd or even page. Therefore, JGDoc provides:- .setst |\h3| .nost \t\s3 \t.if <truthvalue> introduces a conditionally included chunk of text. .nost \t\s3 \t.else swaps the truth\-value conditions (optional). .nost \t\s3 \t.fi ends the conditionally included text. .nost \t\s3 \t\\o outputs 1 on odd pages and 0 on even pages. .nost \t\s3 \t<truthvalue> is a string of characters construed as true or false according to the following rules:\| \s4 0 is false;\| \s4 A positive integer is true;\| \s4 y, yes, t, true are true, as are their upper case equivalents;\| \s4 all other strings are false. I used this in the header with \\o, but conditionals can appear anywhere. .if 0 ....... .fi is a useful alternative method of switching out a chunk of text; replacing the zero by one will, of course, put it back. Conditionals can be nested. .elseif <truthvalue> and .orif <truthvalue> are also available. Three\-string conditionals are available; the middle string must be one of eq, ne, lt, le, ge, gt relations, or their upper\-case equivalents. The comparison is arithmetic if both the first and third string are numerals, lexicographic, with lower\-case letters internally made upper\-case, otherwise. Conditional text beginning with a dot assumes what follows to be a dotty; otherwise the conditional text abuts what preceeds and follows it. See the use of .if etc in these documents for how to ensure that there is a space between what preceeds a .if and what follows it. .setst :: .makel intro .cp 12 \s2|Guttering If you are intending to bind what you are printing, it is useful to have a wider margin on the binding side of each page, an extra 2 or 3 characters width say. Therefore,jgdoc provides: .setst |\h3| .makel directvs .nost \t\s3 \t.gute {-}<n> which provides guttering of an extra <n> character widths on the left margin on even pages, -n on odd pages if the '-' is not present; if the '-' is present, the extra left margin comes on odd pages, with even pages having the narrower margin. I think this is the only place in JGPrint where the user may have to supply a negative number. My experience is that 2-3 character widths are suitable for most kinds of binding, but you should experiment this and left margin to get what you want. As mentioned above, this advanced facility may be helpful to readers using JGDoc eho want to bind the documentation theu print out. .usel intro .cp 12 .col \s2|layouts It is useful to have a way of saving and restoring the current layout, in order to achieve reliable consistency of style in big documents. Therefore, JGDoc provides:- .usel directvs .nost \t\s3 \t.makel <string> saves (most of) the current state of JGDoc. .nost \t\s3 \t.usel <string> reinstates the state that applied when the layout <string> was defined. The problem with this facility was the decision as to how much of JGDoc's state is to be saved as a layout. As common sense suggests, the current page\-number or section numbers obviously aren't, but margins, tabs, paragraph settings, justify settings and start- and end\-strings should be and are. The layout defined at the end of the prologue is made available under the name 'base'. ..pushl <string>, .popl are also available. HP style printers require font defining codes to be specified to the printer in a particular sequence, and the implementation of Usel has been tailored to provide this. The directive .font <n> only has an effect in JGPrint. .setu 1 'Therefore, JGDoc provides:-' .setm 2 *.nost \t\s3 \t* .usel intro .cp 12 .col \s2|User Variables In well\-structured documents, there is often a lot of repetition both of ordinary text, and of sequences of directives. It is nice to be able to define any of these once, and have a simple way of including it in the text. \u1 .usel directvs \u2..setu <n> <bracketted string> defines the user variable <n> to be the <bracketted string>, interpreting any directives within it as it does so. \u2..setm <n> <bracketted string> defines the user variable <n> to the <bracketted string>, copying without interpretation. \u2\\u<n> embeds the user variable string in the text being read, interpreting it as it does so for those set with .setm. The bracketted strings are restricted to 255 characters. Strings may be nested. \\u0 specifies a string to be inserted from the keyboard, which will be prompted for. I regard user strings as quite the most powerful tools of JGDoc. I have refrained from using them before here, since this documentation is also an introductory teaching document; but I do so now to exhibit their use; I would normally have moved the .setu and .setm up to the prologue, and used \\u1 and \\u2 throughout, both to avoid typing errors and to discipline regularity in the text. If you have defined user variables, JGPrint, but not JGDoc will, on exit, offer you the opportunity of saving them in a file you choose. Its format is quite transparent. JGPrint would enable you to input this file to preset user variables on another run, but JGDoc can't specify where to find this file. You could achieve cross\-reference within and between files by putting them in by hand but this is tedious... NB. Multi-lined user strings which include dotties require care in realising precisely how many newlines will in fact be present. It is good practice to put your brackets on two otherwise empty lines, which implies that the string will itself contain newlines at beginning and end. A '.' immediately following the first bracket will be treated as <nl> '.'; a dotty immediately preceeding the last bracket will, as everywhere else, 'swallow the new line following itself. ..rpt (see below) will probably need some fine tuning to get what you want. .usel intro .cp 6 .col \s2|Included Files For large documents, it is often convenient to divide them up into several files and call these from a driving file. Indeed, the specification of common layouts and user strings can conveniently be put into this driving file. Another approach is to have independent files, each of which calls on a common file to set its layouts and user strings. \u1 .usel directvs \u2\\+<filespec> includes the file <filespec> into the text being read. Include files can be nested to any reasonable level; the file should be specified as from the directory in which the original 'from' file was found. See JGEdDoc/JGEd1Doc for a simple example; ExTime/ExTimeLay for a another. .usel intro .cp 6 .col \s2|Merge Files It is useful to be able to have a text frame, into which can be slotted the fields from successive records, so that the same letter can be sent to a set of recipients etc. Two examples of possible use are provided by exmerge, with exmergm, and exlbl with exlblm in the XMP directory. There is some tutorial material after the body of each of these files. JGDoc reports, with the name of the descriptor, for you to specify a merge file from which records can then be drawn. In JGPrint mode, it is, alternatively, possible to specify the merge file during the initial dialogue. In the Own window, this file may be specified as from the directory in which the original 'from' file was found. \u1 .usel directvs \u2\\f<descriptor><t> includes the field corresponding, in the current record, to <descriptor>; the terminator <t> can be a space, a newline, or }. \u2\\g reads in the next record. If the last record of the merge file has not been read by the end of the text, the next record is read, and the text restarted. .usel intro .cp 6 .col \s2|Indexing It is useful to be able to mark phrases in the text, and obtain a list of whereabouts these are in the text, page, line, section number. \u1 .usel directvs \u2\\i....\\j brackets a phrase which is put out, with the current page, line, section in an index file. \u2\\k within these brackets causes what remains between \\k and \\j to go to the index file only. .usel intro .cp 6 .col \s2|Internal repetition If many copies of a short message are wanted, it is wasteful to put each on a separate sheet. If you simply put multiple copies in your text, the page end will usually cut the last one on each page in two. \u1 .usel directvs \u2..rpt <n> <b><text><b> will insert <text> as many times on a page as there is room for, and continue to do so until <n> copies have been printed. It may be useful to leave an empty line or two before the second <b> to facilitate cutting the copies apart. It is often useful to combine this with \\f and \\g from a merge file. JGDoc assumes that the next instance will be vertically as big as the preceeding instance. If <n> is 0, repetition will continue until the merge file is exhausted. See EXLBL/LBLM for how to use these facilities for printing labels. .cp 9 .col |Absence of Restriction .usel intro There was some discussion as to whether or not it was appropriate to allow merge files, index files and repetition in JGSharEd/Doc, on the grounds that these were unusually powerful and useful capabilities to provide in a public domain program. I thought to restrict their use numerically, but felt this to be inelegant. However, I do regard anyone who uses these facilities extensively without having bought a licence to JGPrint as a thieving knave. .cp 6 .col \s1|Epilogue I hope I have documented all the facilities I have used in this document, and used the majority of those listed under a section number. I know that only a very few of those also mentioned have been used, since I have wanted to keep this document relatively straightforward as an introduction to JGDoc. In the directory XMP, if present, are example documents from my JGPrint collection, where I have quite gone to town (OTT) on use of the facilities. The file EXNOTE covers endnotes and footnotes which have not been mentioned here but are documented in EXNOTE itself. Some contain underlining and italicising directives that are ignored by JGDoc. Some directives, e.g. .rpt are used and commented on. Certain of these, if JGPrinted to screen, are demanding in space, and may require mode 16 if their right margin is wider than 80 (EXTAB, EXLBL, EXLONGD etc.) EXLAYOUT and EXMERGE reset vertical spacing and cause warning reports in JGDoc mode. I have put, as oxdiary, a result of JGDOCcing EXDIARY Good luck with these; some are quite difficult to work out, and you may need to see the source and result together. .cp 6 .col \s2|The mouse The mouse can be clicked in response to JGDoc and JGPrint's dialogue prompts in JGPrint's own window. See JGPrintDoc for the rules of the game. .cp 6 \.col \s2|JGSharePr In order to convert JGDoc to JG(Share)Pr(int), remove the initial '*s' from the first line of !jgp.Info.JGPStrings. !JGCnfig, accessible from JGPrint's desktop menu, will edit the configuration files in !jgp.pa and !jgp.q needed by JGSharepr\/JGPrint. JGSharePr imposes restrictions outside JGDoc mode, except when JGPrinting to Screen. .cp 6 .col \s1|Funny .sp <n> I suggested above that JGDoc's story of configuring n lines per page was a simplification, and sometimes rounding errors can creep in. The truth is that JGDoc works in terms of 2160 internal units per vertical inch, and the default page length is set to 11" = 23760 units. A request for 66 lines per page works out a line spacing of 23760/66 = 360 units = 1/6". If a request were received for 65 or 67 there would be a rounding error since JGDoc's configuration does not allow part\-line vertical motion. Therefore, if you want to use such 'funny' numbers, it would be sensible to set a suitable pagelength which was a multiple of the number of lines you wanted on each page (eg. .pl 6500/.sp 65). Of course, in a file there is no absolute sense of distance between lines to aim for. The full story is:- .usel directvs .nost \t\s2 \t.pl <n> sets page length, where <n>\ <\ 20 is construed as inches, 20 and above as vertical units, i.e. small numbers are multiplied by 2160. .nost \t\s2 \t.sp <n> sets line spacing, where <n>\ <=\ 10 is construed as lines per inch i.e. 2160/<n>, 10\ <\ <n>\ <=\ 120 is construed as lines per page, i.\ e. <pagelength>/<n>; 120 and above are directly construed as vertical units. In JGPrint mode, .sp <n> affects the depth each line's spacing is deemed to occupy, so that the number of lines that fit on a page becomes changed whenever a .sp is encountered. On an 11" page, .cpi 6, .cpi 66, and .cpi 360 all set spacing to 6 lines per inch. .cp 6 .col \s1|Editor Choice .usel base Any editor capable of generating pure ascii text can be used to generate a JGPrint/Doc file. JG(Share)Print will cope with any method your editor may use to signify a line\-break, and will accept any byte greater than 13 as as a character to print. In JGPrint mode, using a suitable configuration file, all bytes can be used to print a character. JG(shar)Ed has the extended command fp (reformat for JGPrint) which does not affect lines beginning with '.', and provides online documentation for JGPrint directives; this is helpful, but is not a particularly important reason to use JG(Shar)Ed with JG(Shar)EPr. The better reason is that JG(Shar)Ed is a Jolly Good Editor.