home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Misc / FTREE0.3.LHA / ftree / guide / RCS / ftree.guide,v
Encoding:
Text File  |  1994-04-30  |  33.5 KB  |  1,104 lines
  1. head    1.4;
  2. access;
  3. symbols;
  4. locks; strict;
  5. comment    @# @;
  6.  
  7.  
  8. 1.4
  9. date    94.04.30.12.19.58;    author peteric;    state Exp;
  10. branches;
  11. next    1.3;
  12.  
  13. 1.3
  14. date    94.03.26.11.36.32;    author peteric;    state Exp;
  15. branches;
  16. next    1.2;
  17.  
  18. 1.2
  19. date    94.03.02.22.00.48;    author peteric;    state Exp;
  20. branches;
  21. next    1.1;
  22.  
  23. 1.1
  24. date    94.03.02.00.14.59;    author peteric;    state Exp;
  25. branches;
  26. next    ;
  27.  
  28.  
  29. desc
  30. @Documentation in AmigaGuide format for the Ftree Family Tree
  31. Formatter program.
  32. @
  33.  
  34.  
  35. 1.4
  36. log
  37. @Most of the changes for V0.3 of the program; added more of the
  38. options for marriages. Still some left...
  39. @
  40. text
  41. @@@Database "ftree.guide"
  42. @@Remark $VER: ftree.guide 0.3 (28.04.94) $
  43. @@Node main "Ftree Documentation"
  44. @@Width 75
  45. @@Toc main
  46. Ftree is a program which reads a description of a group of people linked by
  47. marriage and writes out, in the PostScript language, a family tree diagram.
  48.  
  49. This document describes Ftree version 0.3.
  50.  
  51.     @@{"Contents" LINK contents}
  52.     @@{"Introduction" LINK intro}
  53.     @@{"Command line options" LINK options}
  54.     @@{"Input file structure" LINK input}
  55.     @@{"Output Options" LINK output-options}
  56.     @@{"Examples" LINK examples}
  57.  
  58. Ftree is Copyright (c) 1994 P. Ivimey-Cook.
  59.  
  60.  
  61. The installer and it's project icon have been developed by Commodore; the
  62. following are the copyright and legal messages required by Commodode-Amiga:
  63.  
  64.      Installer and Installer project icon
  65.      (c) Copyright 1991-93 Commodore-Amiga, Inc.  All Rights Reserved.
  66.      Reproduced and distributed under license from Commodore.
  67.  
  68.      The installer software is provided "as-is" and subject to change;
  69.      No warranties are made.  All use is at your own risk.  No liability
  70.      or responsibility is assumed.    
  71.  
  72.  
  73. @@EndNode
  74.  
  75. @@Node intro "Introduction"
  76. @@Next options
  77. @@Prev main
  78. @@{b}Introduction@@{ub}
  79. ============
  80.  
  81. Ftree is a utility to produce nice familiy tree plots with the minimum
  82. fuss. It has two aims; to allow arbitrary sized trees to be printed by
  83. using PostScript as the output language, and to avoid as far as possible
  84. having to specify the location, or attribute of any graphical element.
  85.  
  86. Using PostScript would normally have the limitation that only PostScript
  87. output devices such as the Apple LaserWriter could print the result;
  88. however there are two very good PostScript interpreters available; @@{"Post" LINK "post.guide/main"}
  89. and @@{"GhostScript" LINK "ghostscript.guide/main"}. See Output Options for more information.
  90.  
  91. The program operates on an input file or files containing three things;
  92. specifications such as fonts to use, titles and other such things,
  93. descriptions of people, and descriptions of marriages.
  94.  
  95. Please Note: In this document, and indeed in the program itself, no real
  96. distinction is made between a 'legal' marriage and other modes of living
  97. together.
  98. @@EndNode
  99.  
  100. @@Node options "Command Line Options"
  101. @@Next input
  102. @@Prev intro
  103. @@{b}Command Line Options@@{ub}
  104. ====================
  105.  
  106. Ftree accepts the following command line options:
  107.  
  108.       @@{b}-F font@@{ub}   - select font 'font' to write with
  109.       @@{b}-L size@@{ub}   - set maximum # generations to print
  110.       @@{"-P psize" link opt-papersize}  - set the paper size to 'psize'
  111.       @@{b}-h@@{ub}        - print the help message
  112.       @@{"-l" link opt-orientation}        - print in landscape mode
  113.       @@{"-o psfile" link opt-outputfile} - specify output file name ('-' == stdout)
  114.       @@{b}-p <size>@@{ub} - standard font point size
  115.       @@{b}-q@@{ub}        - quick mode format; approximate the text size
  116.       @@{"-s pers" link opt-root}   - specify 'root' person of tree
  117.       @@{b}-t ttl@@{ub}    - title string of tree
  118.       @@{b}-v@@{ub}        - comment more verbosely.
  119.       @@{b}-x@@{ub}        - do not print occupations
  120.  
  121. Font names are precisely the standard PostScript names; examples
  122. are:
  123.  
  124.     Times-Roman, Courier, Helvetica, Garamond-Light, ZapfChancery
  125.  
  126. but the exact list of available fonts will depend upon the PostScript
  127. device the file is sent to. Ftree never supplies font definitions itself. 
  128. Font names are always case sensitive.
  129.  
  130. Paper sizes are specified with the usual ISO and common-use names; again,
  131. they are case sensitive. The current list of supported sizes can be printed
  132. out with the command:
  133.  
  134.     @@{b}ftree -h@@{ub}
  135.  
  136. Examples currently include:
  137.  
  138.     a3, a4, a5, letter, legal, note
  139.  
  140. @@EndNode
  141.  
  142. @@Node input "Input file structure"
  143. @@Next output-options
  144. @@Prev options
  145. @@{b}Input file structure@@{ub}
  146. ====================
  147.  
  148. The Ftree input file consists of three major elements. The way in which
  149. these which may be arranged in an input file are specified in the section
  150. @@{"Basic file syntax" LINK "syntax"}.
  151.  
  152. The @@{"OPTION" LINK "options-stmt"} statement is a list of options, many of which mirror those
  153. available on the command line but also including others not available that
  154. way.
  155.  
  156. The @@{"PERSON" LINK "person-stmt"} statement is a definition of a person. It lists the known
  157. attributes of a single person.
  158.  
  159. The @@{"MARRIAGE" LINK "marriage-stmt"} statement is a definition of the marriage of two people.
  160. Marriage may be construed as any union of two people from which children
  161. are born. Marriages need not involve children, though. Marriage statements
  162. may be chained together with the 'then' construct, through which multiple
  163. marriages of one person may be specified.
  164.  
  165. In addition, the program may be instructed to include another file in it's
  166. entirety at a given point by the @@{"include" LINK "include-stmt"} statement.
  167.  
  168. @@EndNode
  169.  
  170. @@Node syntax "Basic Input File Syntax"
  171. @@Next person-stmt
  172. @@Prev input
  173. @@{b}Basic Input File Syntax@@{ub}
  174. =======================
  175.  
  176. Comment lines, which will be completely ignored by ftree during processing,
  177. are started by the semicolon (;) character and continue until the end of the
  178. line.
  179.  
  180. White space - spaces and tabs - are also ignored, but are necessary in
  181. order to split up other words in the input file. Strings and numbers are
  182. required by some of the operators and options: Strings are always
  183. surrounded by double quote (") characters. To incorporate a double quote
  184. into a string, just precede it by a backslash (\).
  185.  
  186. Numbers come in two forms. Floating point numbers are typically used to
  187. specify sizes - e.g. the point size of a font. These always contain a
  188. decimal point. If there is no whole-number part, this must be specified as
  189. being 0. If there is no fractional part, the fractional part may be
  190. omitted. Thus:
  191.  
  192.     0.1        is legal
  193.     10.45    is legal
  194.     5.        is legal
  195.     .3        is not legal
  196.     4e5        is not legal.
  197.  
  198. Things which fall outside this are interpreted character-by-character, and
  199. will usually cause a syntax error message to be printed:
  200.  
  201. <filename>: <lineno>: error: syntax error; character - h (104) unexpected.
  202.  
  203. In this case the program is complaining that it didn't understand a letter
  204. h in the input file. <filename> and <line number> are filled in whenever
  205. possible. 'error:' means that the program considers this to be a major
  206. problem; 'warning:' means that something which may be wrong has occurred;
  207. usually this is something which the user probably doesn't want but which
  208. may be perfectly correct. The program exits once five errors have been
  209. found. Any number of warnings may be tolerated.
  210.  
  211. @@EndNode
  212.  
  213. @@Node person-stmt "The Person Statement"
  214. @@Prev syntax
  215. @@Next marriage-stmt
  216. @@{b}The Person Statement@@{ub}
  217. ====================
  218.  
  219. The person statement defines all that the program needs to know about an
  220. individual person. Details concerning relationships with other people are
  221. kept in the Marriage statement. The basic form is:
  222.  
  223.     person <id>
  224.     {
  225.         <list of items>
  226.     }
  227.  
  228. The formatting, as with all aspects of the input file, is up to the user.
  229. The item <id> is a unique ID which is applied to the person. Names, and
  230. even the combination of names and other information, are in general
  231. insufficient to generate reliably unique identifiers. If <id> is omitted,
  232. an ID code will be calculated by Ftree for the person from the other
  233. information supplied. However, there is no easy way to find out what these
  234. are in order to reference them elsewhere!
  235.  
  236. The main body of the statement is the <list of items>. This consists of a
  237. number of words, some of which must have strings or numbers afterwards.
  238. Each word (word pair) may be followed by a comma, but this is optional.
  239.  
  240. An example of a definition might be:
  241.  
  242.     person A491 { firstname "Sally Ann" surname "Hodge"
  243.         born 4 May 1997 sex female
  244.     }
  245.  
  246. This follows probably the most common form, in which the full name and one
  247. or two other items about a person are known. In this case, the commas have
  248. been omitted.
  249.  
  250. The full list of possible options is:
  251.  
  252.     @@{"bapt <date>            - the date of baptism (not displayed)" LINK "pers-bapt"}
  253.     @@{"born <date>            - the date of birth" LINK "pers-born"}
  254.     @@{"dead                   - the person as being dead" LINK "pers-dead"}
  255.     @@{"died <date>            - the date of death" LINK "pers-died"}
  256.     @@{"living                 - the person as still being alive" LINK "pers-living"}
  257.     @@{"firstname <name>       - the first name(s) of the person" LINK "pers-firstname"}
  258.     @@{"surname <name>         - the family name of the person" LINK "pers-surname"}
  259.     @@{"occupation <str>       - arbirary text (not displayed)" LINK "pers-occupation"}
  260.     @@{"sex <male> or <female> - the sex of the person" LINK "pers-sex"}
  261.  
  262. @@EndNode
  263.  
  264. @@Node marriage-stmt "The Marriage Statement"
  265. @@{b}The Marriage Statement@@{ub}
  266. ====================
  267.  
  268. The marriage statement defines all the information the program needs to
  269. know about a given marriage. Because some people marry more than once they
  270. may be chained together with the 'then' keyword. Thus a simple marriage
  271. statement conforms to the template:
  272.  
  273.     marriage {
  274.         husband X wife Y <other details>
  275.         }
  276.  
  277. and more generally:
  278.  
  279.     marriage {
  280.         husband X wife Y <other details>
  281.         }
  282.     then {
  283.         husband X wife Z <other details>
  284.         }
  285.     then ...
  286.  
  287. The husband and wife clauses must be specified in a marriage; they are not
  288. optional. However, the order in which they are defined is not important. 
  289. Indeed, one might specify a marriage as 'marriage { <others> wife X husband
  290. Y}'. The marriage statement uses the ID codes previously assigned to people
  291. in order to remove ambiguity. Thus an example marriage statement might be:
  292.  
  293.     marriage {
  294.         husband A34 wife B97 married 4 Oct 78 children D65
  295.     }
  296.  
  297. In order to understand this in real terms, of course, the list of people
  298. and ID codes must be examined.
  299.  
  300. All the people mentioned in a marriage statement must have been previously
  301. defined with 'person' statements. Ftree uses this in order to check the
  302. marriage for, for example, selecting as the husband a person previously
  303. defined as being female. Conversely, Ftree will warn if a person who has
  304. not previously been defined as being male or female is assigned as the
  305. huband or wife of somebody.
  306.  
  307. Other checks will in future be performed; for example to make sure that the
  308. children were born after the parents.
  309.  
  310. The full list of keywords in a marriage statement is:
  311.  
  312.     @@{"husband <id>      - the husband (male partner)" LINK "marr-husbwife"}
  313.     @@{"wife <id>         - the wife (female partner)" LINK "marr-husbwife"}
  314.     @@{"married <date>    - date of marriage" LINK "marr-married"}
  315.     @@{"divorced          - marriage was annulled" LINK "marr-divorced"}
  316.     @@{"separated         - marriage 'died'" LINK "marr-separated"}
  317.     @@{"left              - hint to place children more to left" LINK "marr-left"}
  318.     @@{"right             - hint to place children more to right" LINK "marr-right"}
  319.     @@{"children <idlist> - list of children's ID's" LINK "marr-children"}
  320.  
  321. @@EndNode
  322.  
  323. @@Node options-stmt "The Options Statement"
  324. @@{b}The Options Statement@@{ub}
  325. ====================
  326.  
  327. The options statement defines certain program options and variables. It is
  328. hoped that this is a convenient way of specifying some of the more esoteric
  329. options. Because of this, in addition to the obvious use inside any given
  330. input file, Ftree looks for and if present loads the file 'ftree.options'
  331. from the 'S:' directory. It may be useful to note that the program does not
  332. limit the contents of this file to 'option' statements.
  333.  
  334. There may be more than one options statement per file.
  335.  
  336. The full list of options statements is:
  337.  
  338.     @@{"vspace <length>       - set the vertical spacing"    LINK "opt-vspace"}
  339.     @@{"hspace <length>       - set the horizontal spacing"    LINK "opt-hspace"}
  340.     @@{"root <person-id>      - set the initial marriage"    LINK "opt-root"}
  341.     @@{"outputfile <filename> - set the name of the output file"    LINK "opt-outputfile"}
  342.     @@{"notitlebox            - disable the box around the title"    LINK "opt-notitlebox"}
  343.     @@{"titlebox <level>      - set the grey level for the title box"    LINK "opt-titlebox"}
  344.     @@{"ident <fontspec>      - set the identifier font"    LINK "opt-ident"}
  345.     @@{"title <string>        - set the tree's title"    LINK "opt-title"}
  346.     @@{"title <fontspec>      - set the title font"    LINK "opt-title"}
  347.     @@{"symbol <fontspec>     - set the symbol font"    LINK "opt-symbol"}
  348.     @@{"date <fontspec>       - set the date font"    LINK "opt-date"}
  349.     @@{"person <fontspec>     - set the person font"    LINK "opt-person"}
  350.     @@{"pagesize <size>       - set the output page size (e.g. a4)"    LINK "opt-pagesize"}
  351.     @@{"ticklen <length>      - set the length of tick marks"    LINK "opt-ticklen"}
  352.     @@{"orientation <type>    - set the page orientation"    LINK "opt-orientation"}
  353.  
  354. An example might be:
  355.  
  356.     option
  357.     {
  358.         title "\"Clan\" Tree"
  359.         title font "ZapfChancery"
  360.         person pointsize 8.0
  361.         date pointsize 6.0
  362.         vspace 1.0
  363.         orientation landscape
  364.         root A85
  365.     }
  366.  
  367. This sets the title of the diagram to '"Clan" Tree' in the font
  368. ZapfChancery, the point size of the characters used to write people's names
  369. to 8 point (8/72nd inch) and that used for writing dates to 6 points. It
  370. also sets the vertical spacing between people to 1 inch and the orientation
  371. of the diagram on the page is set to landscape mode (long size horizontal).
  372. Finally, it sets the root person (the marriage from which the tree starts)
  373. to whoever A85 is.
  374.  
  375. @@EndNode
  376.  
  377. @@Node include-stmt "The Include Statement"
  378. @@{b}The Include Statement@@{ub}
  379. ====================
  380.  
  381. The include statement simply allows other ftree input files to be textually
  382. included at the point the include statement is found in the input file. For
  383. example, this may be used to include a specific options setup for a series
  384. of diagrams, or to include a database of people from which a subset is
  385. drawn.
  386.  
  387. The syntax is very simple:
  388.  
  389.     include "filename"
  390.  
  391. The quotes must be included. The filename may be relative or absolute; it
  392. will be interpreted relative to the current directory of ftree.
  393.  
  394. There is a limit of 10 on the number of times an included file may itself
  395. include another.
  396.  
  397. In theory the include statement may appear anywhere in the input file, even
  398. within other statements. However, this practice should probably be avoided.
  399.  
  400. Note that the include filename is interpreted relative to the current
  401. directory of the 'ftree' process. This may be changed in future. For the
  402. moment this means that included files are best kept in the same directory
  403. as the other files.
  404.  
  405. @@EndNode
  406.  
  407. @@Node output-options "Output Options"
  408. @@Prev input
  409. @@Next examples
  410. @@{b}Output Options@@{ub}
  411. ==============
  412.  
  413. Ftree produces an output file; no actual printing of an image is done
  414. by Ftree. The file produced will be called @@{b}tree.ps@@{ub} unless changed
  415. by the user with the '-o' command line option or @@{"outputfile" LINK opt-outputfile} options
  416. statement.
  417.  
  418. The file produced uses the language PostScript, which many laser printers
  419. and other output devices use as the way a program tells the device what to
  420. put on a page. For this reason PostScript is referred to as a Page
  421. Description Language. It was developed by Adobe Systems in the USA and is
  422. now widely used. Ftree also conforms to the Adobe Document Structuring
  423. Conventions, which means that programs which manipulate PostScript files,
  424. such as those which band-print a file or allow 2 or 4 'pages' to be printed
  425. on one real page, should be able to understand FTree output.
  426.  
  427. To get the output of FTree onto the page, therefore, you either need a
  428. printer which understand PostScript natively, such as the Apply LaserWriter
  429. series, or a conversion program - a piece of software which performs the
  430. translation within the main computer and writes the resulting bitmap to
  431. whatever printer is available.
  432.  
  433. One such program is called @@{"Post" LINK "post.guide/main"}, and is widely available in the Public
  434. Domain (e.g. Fish Disk ???). Another is @@{"GhostScript" LINK "ghostscript.guide/main"}, a program initially
  435. developed for Unix systems but later converted to run on the Amiga. Both
  436. should be able to either display the charts FTree produces on the screen or
  437. on a suitable printer.
  438.  
  439. For example, to print the default output file using the Amiga Printer
  440. Preferences driver using Post:
  441.  
  442. 1> post printer post:init.ps tree.ps
  443.  
  444. @@EndNode
  445.  
  446. @@Node examples "Examples"
  447. @@Prev output-options
  448. @@{b}Examples@@{ub}
  449. ========
  450.  
  451. No examples are available at present.
  452.  
  453. @@EndNode
  454.  
  455. @@Node opt-vspace "Vertical Space Setting"
  456. @@Prev options
  457. @@Next opt-hspace
  458. Vertical Space Setting
  459. ======================
  460.  
  461. The vertical space setting defines the distance between the generations, as
  462. printed on the page. By default the distance is measured in inches, and may
  463. be fractional.
  464.  
  465. The program considers the person to 'be' at a point which is at in the
  466. middle of the top of the first line (the name), as printed. The distance
  467. vspace measures is that between this point and the equivalent point for the
  468. children of this person.
  469.  
  470. However, it is easier to think of the distance as that separating the line
  471. for one generation's children and the next.
  472.  
  473. The vertical space includes the space required to print the information
  474. requested (name, dates etc) for the people. If Ftree is asked to print a
  475. chart with a vspace which is smaller than that required for the text, it
  476. prints a warning message and sets the spacing to the minimum possible.
  477.  
  478. Example:
  479.         option { vspace 0.8 }
  480.  
  481. @@EndNode
  482.  
  483. @@Node opt-hspace "Horizontal Space Setting"
  484. @@Prev opt-vspace
  485. @@Next opt-root
  486. Horizontal Space Setting
  487. ========================
  488.  
  489. The horizontal space setting defines the distance between the people who
  490. are next to each other, as printed on the page. By default the distance is
  491. measured in inches, and may be fractional.
  492.  
  493. This distance is in addition to the space the program has determined is
  494. necessary to prevent the people overlapping, and may be further
  495. supplemented by space required by younger generations. Thus:
  496.  
  497.                           |
  498.                +----------+---------+
  499.                |                    |
  500.            Hilma Smith         James Smith
  501.  
  502.            |<------->|         |<------->|
  503.               Text   |<------->|  Text
  504.              Space      hspace    Space
  505.  
  506.  
  507. Example:
  508.         option { hspace 0.1 }
  509.  
  510. @@EndNode
  511.  
  512. @@Node opt-root "Root or Initial Marriage Selection"
  513. @@Prev opt-hspace
  514. @@Next opt-outputfile
  515. Root or Initial Marriage Selection
  516. ==================================
  517.  
  518. The root person for the tree is the person who will eventually be printed
  519. at the top, as the oldest person present. Currently, FTree demands that
  520. this person married; if this were not true the tree would consist of just
  521. that person.
  522.  
  523. The root person is selected by specifying the identifier defined in a
  524. person statement which is reas in as part of a file presented to FTree. The
  525. search for the person is not carried out until all input sources have been
  526. read.
  527.  
  528. The tree which is printed is defined by this selection; it will include
  529. only the people who are (have been) married to this person, or who are or
  530. have been married to descendents of this person.
  531.  
  532. If not specified, this defaults to the @@{b}last@@{ub} person who was defined
  533. in a marriage statement, and a message is printed to say who this is.
  534.  
  535. Example:
  536.         option { root D46 }
  537.  
  538. @@EndNode
  539.  
  540. @@Node opt-outputfile "Output Filename Selection"
  541. @@Prev opt-root
  542. @@Next opt-notitlebox
  543. Output Filename Selection
  544. =========================
  545.  
  546. The output file name is the name of the PostScript file which is produced
  547. by FTree. If not otherwise specifed, the output file will be written to
  548. "tree.ps", a file in the current directory.
  549.  
  550. There are two ways to change this; the command line option '-o' and the
  551. options statement 'outputfile'. Both of the following examples define the
  552. output file name to be "t:postscript"
  553.  
  554. Example 1 (command line use):
  555.  
  556.         1> ftree -o t:postscript 
  557.  
  558. Example 2 (within a file):
  559.  
  560.         option { outputfile "t:postscript" }
  561.  
  562. @@EndNode
  563.  
  564. @@Node opt-notitlebox "Inhibit the Title Box"
  565. @@Prev opt-outputfile
  566. @@Next opt-titlebox
  567. Inhibit the Title Box
  568. =====================
  569.  
  570. FTree prints a title at the top of the chart which consists of two
  571. elements - a string and a grey area surrounding it. This option prevents
  572. FTree placing the grey background area around the title string.
  573.  
  574. This option may change to cause the removal of the outline box around the
  575. title as well; the current equivalent 'titlebox 1.0' will retain the
  576. current meaning.
  577.  
  578. The option 'notitlebox' is (currently) equivalent to 'titlebox 1.0'.
  579.  
  580. Example:
  581.         option { notitlebox }
  582.  
  583. @@EndNode
  584.  
  585. @@Node opt-titlebox "Specify the Grey level for the Title Box"
  586. @@Prev opt-notitlebox
  587. @@Next opt-ident
  588. Specify the Grey level for the Title Box
  589. ========================================
  590.  
  591. FTree prints a title at the top of the chart which consists of two
  592. elements - a string and a grey area surrounding it. This option defines the
  593. grey level which is used as the background for the string. The grey level
  594. is defined as a number between 0 and 1, with 0 being black and 1 being
  595. white. Thus a level of 0.5 is a mid grey. 
  596.  
  597. The option 'titlebox 1.0' is equivalent to 'notitlebox'.
  598.  
  599. Example:
  600.         option { titlebox 0.5 }
  601.  
  602. @@EndNode
  603.  
  604. @@Node opt-ident "Identifier Font Specification"
  605. @@Prev opt-titlebox
  606. @@Next opt-person
  607. Identifier Font Specification
  608. =========================
  609.  
  610. The Identifier font is selected whenever an identifier must be printed;
  611. this is however only done when the option 'printids' is in effect.
  612.  
  613. The selection of fonts in FTree follows a standard pattern; the font type
  614. first (e.g. ident), then the font name or size selector ('font' or
  615. 'pointsize') then the information.
  616.  
  617. Note that changing one does not imply a change to the other aspect of the
  618. font; thus one can change to a different font in the default pointsize, or
  619. change the pointsize without changing the name of the font.
  620.  
  621. Example:
  622.     options {
  623.     ident font "Bookman-Light"    ; sets name to Bookman-Light
  624.     ident pointsize 6.0        ; sets size to 6 point.
  625.     }
  626.  
  627. @@EndNode
  628.  
  629. @@Node opt-person "Person Font Specification"
  630. @@Prev opt-ident
  631. @@Next opt-date
  632. Person Font Specification
  633. =========================
  634.  
  635. The Person font is selected whenever a person's name must be printed. This
  636. font is used to print the names of all people in the chart, whether married
  637. or not.
  638.  
  639. The selection of fonts in FTree follows a standard pattern; the font type
  640. first (e.g. ident), then the font name or size selector ('font' or
  641. 'pointsize') then the information.
  642.  
  643. Note that changing one does not imply a change to the other aspect of the
  644. font; thus one can change to a different font in the default pointsize, or
  645. change the pointsize without changing the name of the font.
  646.  
  647. Example:
  648.     options {
  649.     person font "Bookman-Light"        ; sets name to Bookman-Light
  650.     person pointsize 7.5        ; sets size to 7.5 point.
  651.     }
  652.  
  653. @@EndNode
  654.  
  655. @@Node opt-symbol "Symbol Font Specification"
  656. @@Prev opt-person
  657. @@Next opt-date
  658. Symbol Font Specification
  659. =========================
  660.  
  661. The Symbol font is selected whenever a symbol (special character) must be
  662. printed. Currently, no symbols are required by the program and this font
  663. is not used.
  664.  
  665. The selection of fonts in FTree follows a standard pattern; the font type
  666. first (e.g. ident), then the font name or size selector ('font' or
  667. 'pointsize') then the information.
  668.  
  669. Note that changing one does not imply a change to the other aspect of the
  670. font; thus one can change to a different font in the default pointsize, or
  671. change the pointsize without changing the name of the font.
  672.  
  673. Example:
  674.     options {
  675.     symbol font "Symbol"        ; sets name to Symbol
  676.     symbol pointsize 6.5        ; sets size to 6.5 point.
  677.     }
  678.  
  679. @@EndNode
  680.  
  681. @@Node opt-date "Date Font Specification"
  682. @@Prev opt-symbol
  683. @@Next opt-title
  684. Date Font Specification
  685. =======================
  686.  
  687. The Date font is selected whenever a date must be printed. This font is
  688. used to print both the date of birth/death and date of marriage.
  689.  
  690. The selection of fonts in FTree follows a standard pattern; the font type
  691. first (e.g. ident), then the font name or size selector ('font' or
  692. 'pointsize') then the information.
  693.  
  694. Note that changing one does not imply a change to the other aspect of the
  695. font; thus one can change to a different font in the default pointsize, or
  696. change the pointsize without changing the name of the font.
  697.  
  698. Example:
  699.     options {
  700.     date font "Courier"        ; sets name to Courier
  701.     date pointsize 6.5        ; sets size to 6.5 point.
  702.     }
  703.  
  704. @@EndNode
  705.  
  706. @@Node opt-title "Title Font and String Specification"
  707. @@Prev opt-date
  708. @@Next opt-pagesize
  709. Title Font and String Specification
  710. ===================================
  711.  
  712. The title font is selected only to print the title of the chart. The Title
  713. will be printed centered at the top of the page, and unless changed is the
  714. string "Family Tree". The title font specification is similar to the other
  715. fonts - ident, person etc - but includes the ability to specify a string
  716. for the title itself.
  717.  
  718. The selection of fonts in FTree follows a standard pattern; the font type
  719. first (e.g. ident), then the font name or size selector ('font' or
  720. 'pointsize') then the information. As with all strings, a Quite character
  721. may be included by preceding it with a backslash.
  722.  
  723. Note that changing one does not imply a change to the other aspect of the
  724. font; thus one can change to a different font in the default pointsize, or
  725. change the pointsize without changing the name of the font.
  726.  
  727. Example:
  728.     options {
  729.     title "The \"Smith\" Family Tree" ; title: The "Smith" Family Tree
  730.     title font "ZapfChancery"    ; sets name to ZapfChancery
  731.     title pointsize 18.        ; sets size to 18 point.
  732.     }
  733.  
  734. @@EndNode
  735.  
  736. @@Node opt-pagesize "Destination Page Size Selection"
  737. @@Prev opt-title
  738. @@Next opt-ticklen
  739. Destination Page Size Selection
  740. ===============================
  741.  
  742. The size of the page bein printed is used internally by FTree to correctly
  743. place the chart on the page. In cases where the chart is too large to fit
  744. on one of the nominated pages, the multiple page option (-M) will modify
  745. the generated PostScript write the chart span several pages, with cut-marks
  746. at the page border.
  747.  
  748. The page size is determined in one of two ways. Either one of the standard
  749. sizes is specified directly - e.g. 'a4' - or the actual width & height of
  750. the page is specified. The main difference is that in the former case, the
  751. generated PostScript code attempts to select the correct page size, whilst
  752. in the latter case no such attempt is made; the printer is left to choose
  753. the paper to print on itself.
  754.  
  755. Currently available page sizes are:
  756.  
  757.  
  758. Example:
  759.     options {
  760.         pagesize "a4"
  761.     }
  762.  
  763. or:
  764.     1.Workbench:> ftree -P a4
  765.  
  766. @@EndNode
  767.  
  768. @@Node opt-ticklen "Child Tick Length Specification"
  769. @@Prev opt-pagesize
  770. @@Next opt-orientation
  771. Child Tick Length Specification
  772. ===============================
  773.  
  774. The child tick is the line joining the parent line (that joining all
  775. children) with the child's name. It's length helps to determine the overall
  776. height of the tree; longer ticks make taller trees.
  777.  
  778. It is suggested that this length is kept below 0.2 inches.
  779.  
  780. Example:
  781.     options {
  782.         ticklen 0.05
  783.     }
  784.  
  785. @@EndNode
  786.  
  787. @@Node opt-orientation "Page Orientation Specification"
  788. @@Prev opt-ticklen
  789. Page Orientation Specification
  790. ==============================
  791.  
  792. The pages output by FTree may be arranged short side horizontal (portrait)
  793. or long side horizontal (landscape). The way the chart is organised will
  794. dictate the best way of laying it out; if it is wide & shallow you probably
  795. want a landscape mode print; if narrow and deep a portrait print is
  796. probably best. For wide and deep prints portrait in multiple page mode
  797. usually gives good results.
  798.  
  799. The default mode is portrait.
  800.  
  801. Example:
  802.     options {
  803.         orientation portrait  ; sets portrait (short side horizontal)
  804.     }
  805.  
  806. or:
  807.     options {
  808.         orientation landscape ; sets landscape (long side horizontal)
  809.     }
  810.  
  811. or:
  812.     1.Workbench:> ftree -l    ; sets landscape (long side horizontal)
  813.  
  814. @@EndNode
  815.  
  816. @@Node marr-husbwife "Marriage Husband and Marriage Wife Identifiers"
  817. @@Next marr-divorced
  818. Marriage Husband and Marriage Wife Identifiers
  819. ==============================================
  820.  
  821. The marriage statement exists to join the two people involved in the
  822. marriage. It therefore muse define the husband & wife, and does this using
  823. two keywords; 'husband' and 'wife'. Both must be present, but the order in
  824. which they appear is not important.
  825.  
  826. The people who are to be married must have been defined in the input file
  827. before the marriage statement which joined them; this would therefore be
  828. incorrect:
  829.  
  830.     marriage { husband A01 wife A02 }  ; needs A01 & A02 defined before
  831.     person A01 {}
  832.     person A02 {}
  833.  
  834. Both keywords expect an identifier, assigned to the persons being joined
  835. when they were declared. FTree will assign identifiers if not present;
  836. however there is no easy way to find out what they are! Thus the expected
  837. system is to define the people involved (including any children) and then
  838. define the marriage which links them.
  839.  
  840. Example:
  841.  
  842.     person Z50 { surname "Smith" }
  843.     person R45 { surname "Jones" }
  844.  
  845.     marriage { wife Z50 husband R45 }
  846.  
  847. @@EndNode
  848.  
  849. @@Node marr-divorced "Marriage Divorce Flag"
  850. @@Prev marr-husbwife
  851. @@Next marr-separated 
  852. Marriage Divorce Flag
  853. =====================
  854.  
  855. Not currently used; this sets a flag indicating that a marriage failed due
  856. to the divorce of the partners. It is not displayed on the chart.
  857.  
  858. @@EndNode
  859.  
  860. @@Node marr-separated "Marriage Separated Flag"
  861. @@Prev marr-divorced
  862. @@Next marr-left
  863. Marriage Separated Flag
  864. =======================
  865.  
  866. Not currently used; this sets a flag indicating that a marriage failed due
  867. to the seperation of the partners. It is not displayed on the chart.
  868.  
  869. @@EndNode
  870.  
  871. @@Node marr-left "Marriage Left Shift Flag"
  872. @@Prev marr-separated
  873. @@Next marr-right
  874. Marriage Left Shift Flag
  875. ========================
  876.  
  877. Not currently implemented.
  878.  
  879. @@EndNode
  880.  
  881. @@Node marr-right "Marriage Right Shift Flag"
  882. @@Prev marr-children
  883. @@Next marr-left
  884. Marriage Right Shift Flag
  885. =========================
  886.  
  887. Not currently implemented.
  888.  
  889. @@EndNode
  890.  
  891. @@Node marr-children "Marriage Children Identifier List"
  892. @@Prev marr-right
  893. Marriage Children Identifier List
  894. =================================
  895.  
  896. The children of the marriage are specifed in this list. It defines the
  897. children of the marriage using identifier codes as for the parents. An
  898. absent children list is equivalent to an empty list.
  899.  
  900. Currently, if there are no children of a marriage specified, the program
  901. will insert the text "[no issue]" after the marriage details. This may
  902. change.
  903.  
  904. Example:
  905.  
  906.     marriage { wife Z50 husband R45 children E30 H37 H38 }
  907.     
  908. @@EndNode
  909.  
  910. @
  911.  
  912.  
  913. 1.3
  914. log
  915. @More of the options/keywords explained
  916. @
  917. text
  918. @d2 1
  919. a2 1
  920. @@Remark $VER: ftree.guide 1.0 (1 3 94))
  921. d5 1
  922. a5 1
  923. @@Toc contents
  924. d9 1
  925. a9 1
  926. This document describes Ftree version 0.2.
  927. a19 1
  928. @@EndNode
  929. d21 11
  930. a31 5
  931. @@Node contents "Contents"
  932. @@Prev main
  933. @@Next intro
  934. @@{b}Contents@@{ub}
  935. ========
  936. a32 1
  937.     
  938. d37 1
  939. a37 1
  940. @@Prev contents
  941. d73 1
  942. a73 1
  943.       @@{"-o psfile" link opt-outputfile} - specify output file name ('con' == stdout)
  944. d75 1
  945. d169 1
  946. a169 1
  947. found.
  948. d242 1
  949. a242 1
  950.     then marriage {
  951. d245 1
  952. a245 1
  953.     then marriage ...
  954. d272 2
  955. a273 2
  956.     @@{"husband <id>      - the husband (male partner)" LINK "marr-husband"}
  957.     @@{"wife <id>         - the wife (female partner)" LINK "marr-wife"}
  958. d299 1
  959. d360 5
  960. d411 1
  961. d417 1
  962. a417 1
  963. @@Next opt-root
  964. d443 29
  965. d473 1
  966. a473 1
  967. @@Prev opt-vspace
  968. d534 5
  969. a538 1
  970. The option 'notitlebox' is equivalent to 'titlebox 1'.
  971. d557 1
  972. a557 1
  973. The option 'titlebox 1' is equivalent to 'notitlebox'.
  974. d609 1
  975. a609 1
  976.     person font "Helvetica"        ; sets name to Bookman-Light
  977. d702 23
  978. d734 10
  979. d752 6
  980. d759 1
  981. a759 1
  982. @@EndNode
  983. d761 4
  984. a764 4
  985. @@Node marr-husband "Marriage Husband Identifier"
  986. @@Next marr-wife
  987. Marriage Husband Identifier
  988. ===========================
  989. d766 7
  990. d776 1
  991. a776 2
  992. @@Node marr-wife "Marriage Wife Identifier"
  993. @@Prev marr-husband
  994. d778 26
  995. a803 2
  996. Marriage Wife Identifier
  997. ========================
  998. d805 1
  999. d810 1
  1000. a810 1
  1001. @@Prev marr-wife
  1002. d815 2
  1003. d826 2
  1004. d837 1
  1005. d847 1
  1006. d856 7
  1007. d864 1
  1008. a864 23
  1009. @@EndNode
  1010.  
  1011. @@Node pers- ""
  1012. @@Prev pers-
  1013. @@Next pers-
  1014. =========================
  1015.  
  1016.  
  1017. @@EndNode
  1018.  
  1019. @@Node pers- ""
  1020. @@Prev pers-
  1021. @@Next pers-
  1022. =========================
  1023.  
  1024.  
  1025. @@EndNode
  1026.  
  1027. @@Node pers- ""
  1028. @@Prev pers-
  1029. @@Next pers-
  1030. =========================
  1031.  
  1032. d866 2
  1033. @
  1034.  
  1035.  
  1036. 1.2
  1037. log
  1038. @added more about the input file.
  1039. @
  1040. text
  1041. @d4 1
  1042. d11 1
  1043. d15 2
  1044. d23 2
  1045. d32 2
  1046. d45 1
  1047. a45 1
  1048. and @@{"GhostScript" LINK "ghostscript.guide/main"}.
  1049. d66 1
  1050. a66 1
  1051.       @@{b}-P psize@@{ub}  - set the paper size to 'psize'
  1052. d68 4
  1053. a71 4
  1054.       @@{b}-l@@{ub}        - print in landscape mode
  1055.       @@{b}-o psfile@@{ub} - specify output file name ('con' == stdout)
  1056.       @@{b}-p <siz@@{ub}   - standard font point size
  1057.       @@{b}-s pers@@{ub}   - specify 'root' person of tree
  1058. d98 1
  1059. a98 1
  1060. @@Next syntax
  1061. d207 9
  1062. a215 9
  1063.     @@{"bapt <date>            - the date of baptism (not displayed)" LINK "stmt-bapt"}
  1064.     @@{"born <date>            - the date of birth" LINK "stmt-born"}
  1065.     @@{"dead                   - the person as being dead" LINK "stmt-dead"}
  1066.     @@{"died <date>            - the date of death" LINK "stmt-died"}
  1067.     @@{"living                 - the person as still being alive" LINK "stmt-living"}
  1068.     @@{"firstname <name>       - the first name(s) of the person" LINK "stmt-firstname"}
  1069.     @@{"surname <name>         - the family name of the person" LINK "stmt-surname"}
  1070.     @@{"occupation <str>       - arbirary text (not displayed)" LINK "stmt-occupation"}
  1071.     @@{"sex <male> or <female> - the sex of the person" LINK "stmt-sex"}
  1072. d271 1
  1073. a271 1
  1074.     @@{"seperated         - marriage 'died'" LINK "marr-seperated"}
  1075. d353 406
  1076. @
  1077.  
  1078.  
  1079. 1.1
  1080. log
  1081. @Initial revision
  1082. @
  1083. text
  1084. @d19 4
  1085. d27 1
  1086. d52 1
  1087. d93 1
  1088. d95 3
  1089. a97 1
  1090. The Ftree input file consists of three major elements.
  1091. d99 1
  1092. a99 1
  1093. The @@{"OPTION" LINK "option-stmt"} statement is a list of options, many of which mirror those
  1094. d112 2
  1095. a113 2
  1096. The way in which these which may be arranged in an input file are specified
  1097. in the section @@{"Basic file syntax" LINK "syntax"}.
  1098. d118 1
  1099. a118 1
  1100. @@Next 
  1101. d121 1
  1102. d160 187
  1103. @
  1104.